diff --git a/docs/superpowers/specs/2026-05-02-relay-server-design.md b/docs/superpowers/specs/2026-05-02-relay-server-design.md index b38a425..d88b83a 100644 --- a/docs/superpowers/specs/2026-05-02-relay-server-design.md +++ b/docs/superpowers/specs/2026-05-02-relay-server-design.md @@ -192,6 +192,24 @@ No integration test against the MCP SSE transport — that is the SDK's responsi --- +## Top-level README (`docs/superpowers/MULTI-AGENT.md`) + +A durable reference document covering the whole development paradigm — not the relay server specifically, but the entire three-terminal workflow that the relay server enables. Lives in `docs/superpowers/` alongside the specs and plans it describes. + +**Contents:** + +1. **Overview** — the PM/Dev-A/Dev-B pattern: why three terminals, what each role owns, what the user's job is (authorize merges, resolve escalations) +2. **Starting a lift** — prerequisites checklist, then: `tools/relay/start.sh` → three sessions → paste kickoff prompts +3. **Coordination protocol reference** — the four message kinds (`status`, `question`, `directive`, `free`), when each is used, what a well-formed body looks like +4. **Using the relay tools** — `post_message`, `read_messages`, `list_pending` with one-liner examples +5. **If the relay server isn't running** — fallback to manual copy-paste; the coordination protocol still works, just with the user as bus +6. **Generating kickoff prompts** — point to the `multi-agent-kickoff` skill; note that the skill injects the relay paragraph automatically +7. **Ending a lift** — PM emits MERGE-APPROVED, devs push branches, user authorizes merges, Ctrl-C the relay terminal + +This README is written for future-you opening the repo six months from now, not for the current lift. + +--- + ## What this is not - Not a product feature — never bundled with the extension or CLI