[J-T-McC]

First of three PRs from feedback on running 9 peers with one coordinator. This one covers Orca coordination: items 1–3 and 5–9, plus the peer-side rules.

What changes

• bin/peer, the coordinator's helper:
  • dispatch adds the role line, runs /clear before a new task (or starts a new terminal when /clear can't work), applies the Role models line, and records the home.
  • tell sends the message and types a nudge into the peer's terminal, because an idle peer never reads its inbox.
  • watch is a background wait that costs no tokens. It wakes on any peer message except heartbeats, a peer over the size limit (SIZE), a terminal quiet for 20 min (STALL), or the time limit.
  • pending, sizes, list and release cover the rest.
• workflow/orca.md:
  • Named homes (dt-dev-1, dt-reviewer, …) with the worktree chosen per dispatch, and one Run for the whole team.
  • A fresh session for every task; --keep only for follow-ups on the same change.
  • The unacked batch is the list of unhandled reports, so there's no separate ledger file.
  • A new § Peers: a request for a go is an ask, never a status message.
  • The runtime line's Peer clear threshold setting becomes Peer size limit (default 400k).
• workflow/handoffs.md: a hand-over note (done / state / left, marked partial) when a session ends mid-work.

Design notes

• Homes are slots, not worktrees. Giving each role its own worktree only works when the workspace is uncommitted and shared by every worktree.
• /clear is the default. A new terminal is used for --restart, a different worktree, or a chat-mode worker; restart on purpose for new MCP servers or after an Orca update.
• Transcripts are found by a home marker in the role line, since Orca exposes no session ID.
• Reviewer change: a delta re-review may now run --keep in the reviewer session that wrote the review (what worked in practice). Before, the reviewer was cleared before every review.

Testing

• claude plugin validate . passes; its 5 warnings are the same as on main. tests/*.sh pass.
• peer sizes, list, project-line parsing and argument errors were run against a throwaway registry pointing at real peer transcripts. The sizes match a separate transcript-size script exactly.
• tests/peer.sh runs bin/peer against a fake orca CLI (tests/fake-orca) and checks the exact Orca calls each command makes. Its 31 checks cover:
  • the dispatch modes (new, fresh with /clear, --keep, restart for a new worktree or a chat-mode worker, --restart) and every refusal;
  • the role line, and model and effort from Role models;
  • the three tell outcomes (delivered, queued, unconfirmed) and --reply;
  • pending and watch: heartbeat-only batches acked automatically, a status message waking watch, SIZE once per session, STALL;
  • finding the right transcript when two homes share a worktree;
  • release.
• Not proven by tests: that real Orca's JSON matches the fake's. The fake's fields come from real worker-list / worker-show output; a live run on a real project is still the last check.

Not in this PR

• PR 2: the Owner board (template, /dev-team:board, bin/board-drift).
• PR 3: general rules (Owner words verbatim, re-review after approval, the mic/camera floor, cleanup, …) and a sync drift check beyond standards/. That drift check is also what will tell existing projects about the Peer size limit rename.

🤖 Generated with Claude Code