Multi-Agent Development Paradigm

This repo uses a three-terminal workflow for large development lifts: one Claude Code session acts as PM and two act as senior developers (Dev-A, Dev-B), each working in their own git worktree on a parallel feature branch.

A local relay MCP server eliminates manual message copying between terminals — agents call post_message/read_messages instead of asking the user to copy-paste.

Overview

Role	Terminal	Branch	Responsibilities
PM	1	`main` (read-only)	Drive doc-audit follow-ups, review PRs, write CHANGELOG, authorize merges and tagging
Dev-A	2	`feature/<release>-plan-a-*`	Implement Plan A tasks in their own worktree
Dev-B	3	`feature/<release>-plan-b-*`	Implement Plan B tasks in their own worktree
Relay server	4	—	Message bus; Ctrl-C to stop at end of lift

User's job: authorize merges (the PM asks), resolve escalations the PM can't handle, and watch the streams. You are no longer the message bus.

Starting a lift

Prerequisites

Kickoff prompts exist in docs/superpowers/coordination/ (generate with the multi-agent-kickoff skill if not)
No uncommitted changes in main that would confuse the devs
tools/relay/ is present (run ls tools/relay/ to confirm)

Launch sequence

# 1. Start the relay server (this terminal becomes the relay log)
tools/relay/start.sh           # prints copy-paste instructions, then starts server

# Optional: use a multiplexer to auto-open all four terminals
tools/relay/start.sh --tmux    # creates tmux session "relay-lift" with 4 windows
tools/relay/start.sh --kitty   # creates kitty tab "relay" + 3 windows

start.sh prints the paths to the three kickoff prompt files. In each Claude Code terminal, run cat <path> and paste everything below the --- line as the first message.

Coordination protocol

Agents communicate by posting structured blocks to each other's inboxes. Four message kinds:

Kind	Block header	When used
`status`	`## STATUS UPDATE — DEV-*`	After completing a task, getting blocked, or reaching a review-ready state
`question`	`## QUESTION TO PM — DEV-*`	When a dev needs PM input mid-task
`directive`	`## DIRECTIVE TO DEV-*`	When PM instructs a dev to proceed, hold, rescope, or approve a PR
`free`	(none)	Ad-hoc messages not covered by the above

A well-formed status block:

## STATUS UPDATE — DEV-B
Time: 2026-05-02T14:30:00-07:00
Branch: feature/v0.5.0-plan-b-extension-ux
Task: P4 / error-copy map
Status: DONE
Last commit: abc1234 feat(extension): centralize ERROR_COPY map
Tests: green
Notes: No issues. Ready for PM review of P4 before starting B1.

Using the relay tools

All three Claude Code sessions have these tools available when the relay server is running:

post_message(from, to, kind, body)   → { id }
read_messages(for)                   → RelayMessage[]   (drains inbox)
list_pending(for)                    → { count, kinds } (non-destructive)

Typical dev flow per task:

1. read_messages(for="dev-b")           # check for directives before starting
2. ... do the work ...
3. post_message(from="dev-b", to="pm", kind="status", body="## STATUS UPDATE...")

Typical PM flow:

1. read_messages(for="pm")             # see what devs posted
2. ... review ...
3. post_message(from="pm", to="dev-b", kind="directive", body="## DIRECTIVE TO DEV-B...")

If the relay server isn't running

Claude Code will show a yellow MCP connection warning for the relay server. The tools will be unavailable.

Agents fall back to the manual protocol: they emit the structured blocks as text and ask the user to copy-paste them to the relevant terminal. This is slower but fully functional — the coordination protocol works either way.

To restart a crashed server mid-lift:

tools/relay/start.sh

In-flight messages are lost on restart. Any agent with unread messages should re-post them.

Generating kickoff prompts

Use the multi-agent-kickoff skill (in the superpowers plugin). It auto-discovers the spec and plans for the release, substitutes all placeholders including the relay paragraph, and writes files to docs/superpowers/coordination/.

The skill reminder: run tools/relay/start.sh before opening the three Claude Code sessions — the MCP tools need the server to be up when each session initializes.

Ending a lift

PM emits REVIEW-COMPLETE and MERGE-APPROVED for each dev's PR
User merges each PR (the PM session does gh pr merge with user authorization)
PM tags the release (only after explicit user yes)
Ctrl-C the relay terminal — all in-memory messages are discarded

Roles and boundaries (quick reference)

PM must not: write feature code, merge without user authorization, tag without user approval, run git push --force / git reset --hard without asking.

Devs must not: merge their branch to main, push --force, run git reset --hard without asking.

User must: authorize all merges and the release tag. Everything else is delegated.

5.2 KiB Raw Blame History