docs(spec): add top-level README section to relay server design

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
2026-05-02 16:38:30 -04:00
parent 5e8e617a4d
commit 0443f6a3b4

View File

@@ -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 ## What this is not
- Not a product feature — never bundled with the extension or CLI - Not a product feature — never bundled with the extension or CLI