docs: add multi-agent development paradigm README
This commit is contained in:
adlee-was-taken
138
docs/superpowers/MULTI-AGENT.md
Normal file
138
docs/superpowers/MULTI-AGENT.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# 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
|
||||
|
||||
```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 <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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user