# 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/-plan-a-*` | Implement Plan A tasks in their own worktree | | Dev-B | 3 | `feature/-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 ```bash # 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 ` 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: ```bash tools/relay/start.sh ``` In-flight messages are lost on restart. Any agent with unread messages should re-post them. --- ## Generating kickoff prompts ### Full workflow (spec → plans → kickoff) **Step 1 — Write a spec** Run the `superpowers:brainstorming` skill. At the end it invokes `superpowers:writing-plans` for each dev stream. Each stream gets its own plan file in `docs/superpowers/plans/`. The spec lives in `docs/superpowers/specs/`. **Step 2 — Invoke the kickoff skill** Say anything like: - "kick off the multi-agent thing for v0.6.0" - "spin up PM and devs for this release" - "set up the three-terminal paradigm" The `multi-agent-kickoff` skill auto-triggers on those phrases. It will: 1. Auto-discover the spec and plans by date/release label (asks to confirm if ambiguous) 2. Generate `docs/superpowers/coordination/-pm-prompt.md` and one `-dev--prompt.md` per plan 3. Inject the relay paragraph, branch names, worktree paths, test commands, and scope partitioning automatically from the plans and `CLAUDE.md` 4. Commit the prompts and print launch instructions N>2 devs works automatically — 3 plans produces PM + Dev-A/B/C prompts. **Step 3 — Launch** ```bash tools/relay/start.sh # prints prompt file paths, starts relay server # open N+1 terminals, paste each prompt below its '---' line ``` The skill reminder: run `tools/relay/start.sh` **before** opening the Claude Code sessions — the MCP tools need the server up when each session initializes. --- ## Ending a lift 1. PM emits `REVIEW-COMPLETE` and `MERGE-APPROVED` for each dev's PR 2. User merges each PR (the PM session does `gh pr merge` with user authorization) 3. PM tags the release (only after explicit user `yes`) 4. 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.