# 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

### 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**

```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.
