layered-soul/skills/colibri-development/references/multiagent-handoff.md

Colibri Multi-Agent Handoff Pattern

Protocol

All agents (Hermes, Claude, Codex) coordinate through .agent-handoff.md in the Colibri repo. The file is the single source of truth for cross-agent context transfer. Commit messages cite it; agents read it on startup.

Entry format

Each handoff entry follows this shape:

### YYYY-MM-DDTHH:MM:SSZ - Short descriptor
- **Agent From**: name (host/platform)
- **Agent To**: name (host/platform)
- **Focus Area**: one-line scope
- **Context**: 2-3 sentences of what changed / why this handoff exists
- **Steps**: numbered, copy-pasteable commands with expected output
- **Context Files**: list of files the receiving agent should read first

Verification rules

• Test counts: always from cargo test --workspace output, never --list
• Clippy: cargo clippy --workspace --all-targets -- -D warnings must be clean
• Platform: Codex (osa/FreeBSD) owns FreeBSD validation. Hermes/Claude (Linux) push for it.
• Baseline: record exact commit hash, test count, crate count

Relay pattern

Agent A (build + push)
  → Agent B (pull, verify, act, push)
    → Agent C (pull, verify, act, push)
      → back to A

Each relay includes:

1. Pull latest: git pull --ff-only origin main
2. Verify: cargo fmt --check && cargo clippy && cargo test --workspace
3. Act on the handoff steps
4. Push results
5. Update .agent-handoff.md with outcome

Platform split

Agent	Host	OS	Role
Hermes	debby	Debian 13	Build, code, push
Claude	domedog	Ubuntu 24.04	Build, code, review
Codex	osa	FreeBSD 15	FreeBSD validation, ISO builds

Codex is the only agent that can run FreeBSD-specific commands (pkg, service, kldload), validate cargo test on real FreeBSD, and build ISOs.

ISO build handoff (specific pattern)

When Codex needs to build Colibri for ISO consumption:

1. Hermes/Claude push Colibri changes to main
2. Handoff entry with exact build steps: cargo build --workspace --release
3. Codex pulls, builds, verifies 4 binaries (daemon, colibri, smoke-agent, tui)
4. Codex runs ISO preflight: FEATURE_COLIBRI=YES ./build.sh --skip-fetch
5. cargo clean only AFTER ISO build consumes the binaries
6. Codex reports: commit hash, binary sizes, FreeBSD version, ISO preflight result

Pitfalls

• SSH agent dies on tmux restart: ssh-add ~/.ssh/codeberg-clawdie before push
• Codeberg SSH drops: retry, don't assume push failed
• Test count inflation: --list overcounts; use cargo test --workspace output
• Bash heredoc corruption: use write_file for function definitions with command names
• DaemonConfig field additions: grep DaemonConfig { to find all constructors