pair-channel

Pair Channel

Read procedure.md completely before creating or joining a channel. It carries the protocol; this file only tells you how to operate it.

The instrument is channel.py, beside this file. Every write to the channel and every wait goes through it. The protocol's only concurrency guard is "the session named by TURN: writes; the other waits." Written as a rule it was voluntary and it failed in another project on the first day; as a script it is checkable, and its mutating commands run under a lock.

PC=~/.claude/skills/pair-channel
[ -f "$PC/channel.py" ] || PC=~/.codex/skills/pair-channel

python3 "$PC/channel.py" init   <channel> --set CHANNEL_NAME=tempcom1 --set REVIEWER_HOST="Claude Code" ...
python3 "$PC/channel.py" state  <channel>                       # TURN / NEXT_SEQ / OPEN / ESCALATED
python3 "$PC/channel.py" append <channel> --role REVIEWER --message msg.md --flip-to IMPLEMENTER --set-open P1
python3 "$PC/channel.py" fill   <channel> --role IMPLEMENTER --set IMPLEMENTER_WORKTREE=/abs/path
python3 "$PC/channel.py" ledger <channel> --role IMPLEMENTER --id P1 --decision "…" --commit abc123
python3 "$PC/channel.py" watch  <channel> --role REVIEWER       # blocks; exit 0 = your turn, 2 = file gone
python3 "$PC/channel.py" check  <channel>                       # every invariant; run when anything looks odd

append refuses: an out-of-turn write, a wrong or duplicate sequence number, two messages in one file, an unbalanced code fence, and any thread line beginning with TURN: outside a fenced quote (TURN lives only in STATE). It stamps the timestamp, updates STATE, and re-verifies. fill (header tables only) and ledger are the rule-1 carve-outs with the same turn check. Every mutating command holds <channel>.lock. watch reads STATE, never the thread.

Starting a pairing (REVIEWER does this)

1. Both sessions already have their own worktrees (/start-worktree). The reviewer never writes a tracked file, so its worktree stays at zero commits.
2. Create the channel OUTSIDE both worktrees in a gitignored place both can reach — on this framework's repos, <repo>/.claude/worktrees/<name>.md, which .git/info/exclude hides. Confirm with git status in every worktree.
3. init with every placeholder you know; the implementer fills its own rows with fill when it holds the turn for message #2.
4. Write message #1 as a channel test (procedure.md §0), append it with --flip-to IMPLEMENTER --set-open P0, then watch --role REVIEWER in the background (Claude Code: run_in_background: true).
5. Give the human ONE prompt for the implementer session that points at the file (procedure.md §7). After that the human relays no content — the file carries it all. Establishing the pairing standing-authorizes ordinary channel messages and turn flips; neither role asks again per message. The V-016 cadence still limits review to four boundaries, not every choice.