relicario/docs/superpowers/MULTI-AGENT.md

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

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/<release>-pm-prompt.md and one -dev-<letter>-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

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.