# Relay Server Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build a local MCP SSE server that gives PM, Dev-A, and Dev-B Claude Code sessions native `post_message`/`read_messages`/`list_pending` tools, eliminating manual copy-paste during multi-agent development lifts.

**Architecture:** A single Node.js process hosts an HTTP server with SSE transport for the MCP protocol. Three named in-memory FIFO queues (one per role) hold consume-once messages. A `start.sh` launcher prints copy-paste instructions (default) or spawns a tmux/kitty layout (flags). The multi-agent-kickoff skill templates get a `<<RELAY_PARAGRAPH>>` placeholder injected so every future lift prompt auto-includes relay instructions.

**Tech Stack:** Node.js v25, `@modelcontextprotocol/sdk` (MCP + SSE transport), `tsx` (dev dep, runs TypeScript directly), Node built-in `node:test` runner. No Express, no Hono, no Zod as a direct dep.

---

## File map

| Action | Path | Responsibility |
|--------|------|----------------|
| Create | `tools/relay/package.json` | npm metadata, scripts, single runtime dep + tsx devDep |
| Create | `tools/relay/tsconfig.json` | TypeScript config for ESM Node target |
| Create | `tools/relay/queue.ts` | `RelayQueue` class — in-memory FIFO, `post`/`read`/`pending`, `isRole` guard |
| Create | `tools/relay/queue.test.ts` | Node `node:test` unit tests for queue (5 cases) |
| Create | `tools/relay/server.ts` | MCP `Server` + `SSEServerTransport` HTTP server on port 7331 |
| Create | `tools/relay/start.sh` | Launcher: `--manual` (default), `--tmux`, `--kitty` |
| Modify | `.gitignore` | Add `tools/relay/node_modules/` |
| Modify | `.claude/settings.json` | Add `mcpServers.relay` SSE entry |
| Create | `docs/superpowers/MULTI-AGENT.md` | Paradigm reference README |
| Modify | `~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md` | Add `<<RELAY_PARAGRAPH>>` section |
| Modify | `~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md` | Add `<<RELAY_PARAGRAPH>>` section |
| Modify | `~/.claude/skills/multi-agent-kickoff/SKILL.md` | Placeholder ref + step 8 update + `<<DEV_ROLE>>` placeholder |

---

## Task 1: Scaffold `tools/relay/`

**Files:**
- Create: `tools/relay/package.json`
- Create: `tools/relay/tsconfig.json`
- Modify: `.gitignore`

- [ ] **Step 1: Create `tools/relay/package.json`**

```json
{
  "name": "@relicario/relay",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "npx tsx server.ts",
    "test": "node --import=tsx/esm --test queue.test.ts"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.10.0"
  },
  "devDependencies": {
    "tsx": "^4.19.0",
    "@types/node": "^22.0.0"
  }
}
```

- [ ] **Step 2: Create `tools/relay/tsconfig.json`**

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true
  },
  "include": ["*.ts"]
}
```

- [ ] **Step 3: Add to root `.gitignore`**

Open `/home/alee/Sources/relicario/.gitignore` and append:

```
tools/relay/node_modules/
```

- [ ] **Step 4: Install dependencies and verify**

```bash
cd tools/relay && npm install
```

Expected: `node_modules/` created, no errors. Verify with:

```bash
ls node_modules/@modelcontextprotocol/sdk && ls node_modules/tsx
```

Expected: both directories exist.

- [ ] **Step 5: Commit scaffold**

```bash
git add tools/relay/package.json tools/relay/tsconfig.json tools/relay/package-lock.json .gitignore
git commit -m "chore(relay): scaffold tools/relay with MCP SDK dep"
```

---

## Task 2: `queue.ts` — TDD

**Files:**
- Create: `tools/relay/queue.ts`
- Create: `tools/relay/queue.test.ts`

- [ ] **Step 1: Write the failing tests**

Create `tools/relay/queue.test.ts`:

```typescript
import { describe, it, beforeEach } from "node:test";
import assert from "node:assert/strict";
import { RelayQueue, isRole } from "./queue.ts";

describe("RelayQueue", () => {
  let q: RelayQueue;

  beforeEach(() => {
    q = new RelayQueue();
  });

  it("post + read roundtrip returns the message with correct fields", () => {
    q.post("dev-b", "pm", "status", "Task P4 DONE");
    const msgs = q.read("pm");
    assert.equal(msgs.length, 1);
    assert.equal(msgs[0].from, "dev-b");
    assert.equal(msgs[0].to, "pm");
    assert.equal(msgs[0].kind, "status");
    assert.equal(msgs[0].body, "Task P4 DONE");
    assert.ok(typeof msgs[0].id === "string" && msgs[0].id.length > 0);
    assert.ok(typeof msgs[0].ts === "string");
  });

  it("consume-once: second read returns empty", () => {
    q.post("dev-a", "pm", "question", "Should I use approach A?");
    q.read("pm");
    const second = q.read("pm");
    assert.deepEqual(second, []);
  });

  it("list_pending does not drain inbox", () => {
    q.post("dev-b", "pm", "directive", "PROCEED");
    const before = q.pending("pm");
    assert.equal(before.count, 1);
    const after = q.read("pm");
    assert.equal(after.length, 1);
  });

  it("FIFO ordering across multiple senders", () => {
    q.post("dev-a", "pm", "status", "first");
    q.post("dev-b", "pm", "status", "second");
    q.post("dev-a", "pm", "question", "third");
    const msgs = q.read("pm");
    assert.equal(msgs.length, 3);
    assert.equal(msgs[0].body, "first");
    assert.equal(msgs[1].body, "second");
    assert.equal(msgs[2].body, "third");
  });

  it("isRole rejects unknown strings", () => {
    assert.ok(isRole("pm"));
    assert.ok(isRole("dev-a"));
    assert.ok(isRole("dev-b"));
    assert.ok(!isRole("dev-c"));
    assert.ok(!isRole(""));
    assert.ok(!isRole("PM"));
  });
});
```

- [ ] **Step 2: Run tests to confirm they fail**

```bash
cd tools/relay && node --import=tsx/esm --test queue.test.ts
```

Expected: fails with `Cannot find module './queue.ts'` or similar. If it fails with a different error, investigate before continuing.

- [ ] **Step 3: Write `queue.ts`**

Create `tools/relay/queue.ts`:

```typescript
import { randomUUID } from "node:crypto";

export type Role = "pm" | "dev-a" | "dev-b";
export type MessageKind = "status" | "question" | "directive" | "free";

export interface RelayMessage {
  id: string;
  from: Role;
  to: Role;
  kind: MessageKind;
  body: string;
  ts: string;
}

const KNOWN_ROLES = new Set<string>(["pm", "dev-a", "dev-b"]);

export function isRole(s: string): s is Role {
  return KNOWN_ROLES.has(s);
}

export class RelayQueue {
  private readonly queues = new Map<Role, RelayMessage[]>([
    ["pm", []],
    ["dev-a", []],
    ["dev-b", []],
  ]);

  post(from: Role, to: Role, kind: MessageKind, body: string): RelayMessage {
    const msg: RelayMessage = {
      id: randomUUID(),
      from,
      to,
      kind,
      body,
      ts: new Date().toISOString(),
    };
    this.queues.get(to)!.push(msg);
    return msg;
  }

  read(forRole: Role): RelayMessage[] {
    const inbox = this.queues.get(forRole)!;
    const messages = [...inbox];
    inbox.length = 0;
    return messages;
  }

  pending(forRole: Role): { count: number; kinds: MessageKind[] } {
    const inbox = this.queues.get(forRole)!;
    return {
      count: inbox.length,
      kinds: inbox.map((m) => m.kind),
    };
  }
}
```

- [ ] **Step 4: Run tests to confirm they pass**

```bash
cd tools/relay && node --import=tsx/esm --test queue.test.ts
```

Expected output (all 5 passing):
```
▶ RelayQueue
  ✔ post + read roundtrip returns the message with correct fields
  ✔ consume-once: second read returns empty
  ✔ list_pending does not drain inbox
  ✔ FIFO ordering across multiple senders
  ✔ isRole rejects unknown strings
▶ RelayQueue (Xms)
ℹ tests 5
ℹ pass 5
ℹ fail 0
```

If any test fails, fix `queue.ts` before proceeding.

- [ ] **Step 5: Commit**

```bash
git add tools/relay/queue.ts tools/relay/queue.test.ts
git commit -m "feat(relay): in-memory queue with consume-once semantics"
```

---

## Task 3: `server.ts`

**Files:**
- Create: `tools/relay/server.ts`

- [ ] **Step 1: Write `server.ts`**

Create `tools/relay/server.ts`:

```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import http from "node:http";
import { RelayQueue, isRole } from "./queue.ts";

const PORT = 7331;
const queue = new RelayQueue();

const mcpServer = new Server(
  { name: "relay", version: "0.1.0" },
  { capabilities: { tools: {} } }
);

const TOOLS = [
  {
    name: "post_message",
    description:
      "Push a message to a recipient's inbox. Returns the assigned message id.",
    inputSchema: {
      type: "object" as const,
      properties: {
        from: {
          type: "string",
          enum: ["pm", "dev-a", "dev-b"],
          description: "Your role name",
        },
        to: {
          type: "string",
          enum: ["pm", "dev-a", "dev-b"],
          description: "Recipient role name",
        },
        kind: {
          type: "string",
          enum: ["status", "question", "directive", "free"],
          description: "Message type matching the coordination protocol",
        },
        body: {
          type: "string",
          description: "Message body — freeform markdown, typically the full formatted block",
        },
      },
      required: ["from", "to", "kind", "body"],
    },
  },
  {
    name: "read_messages",
    description:
      "Pop and return all pending messages for this recipient. Inbox is empty after this call (consume-once).",
    inputSchema: {
      type: "object" as const,
      properties: {
        for: {
          type: "string",
          enum: ["pm", "dev-a", "dev-b"],
          description: "Your role name",
        },
      },
      required: ["for"],
    },
  },
  {
    name: "list_pending",
    description:
      "Return count and kinds of pending messages without consuming them.",
    inputSchema: {
      type: "object" as const,
      properties: {
        for: {
          type: "string",
          enum: ["pm", "dev-a", "dev-b"],
          description: "Your role name",
        },
      },
      required: ["for"],
    },
  },
];

mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));

mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  const a = args as Record<string, string>;

  if (name === "post_message") {
    if (!isRole(a.from)) {
      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.from}"` }], isError: true };
    }
    if (!isRole(a.to)) {
      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.to}"` }], isError: true };
    }
    const kind = a.kind as "status" | "question" | "directive" | "free";
    const msg = queue.post(a.from, a.to, kind, a.body);
    const ts = new Date(msg.ts).toTimeString().slice(0, 8);
    const preview = a.body.slice(0, 60).replace(/\n/g, " ");
    const ellipsis = a.body.length > 60 ? "..." : "";
    process.stdout.write(`[${ts}] ${a.from} → ${a.to}  [${kind}]  "${preview}${ellipsis}"\n`);
    return { content: [{ type: "text" as const, text: JSON.stringify({ id: msg.id }) }] };
  }

  if (name === "read_messages") {
    if (!isRole(a.for)) {
      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.for}"` }], isError: true };
    }
    const messages = queue.read(a.for);
    return { content: [{ type: "text" as const, text: JSON.stringify(messages) }] };
  }

  if (name === "list_pending") {
    if (!isRole(a.for)) {
      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.for}"` }], isError: true };
    }
    const result = queue.pending(a.for);
    return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
  }

  return {
    content: [{ type: "text" as const, text: `Error: unknown tool "${name}"` }],
    isError: true,
  };
});

const transports = new Map<string, SSEServerTransport>();

const httpServer = http.createServer(async (req, res) => {
  try {
    if (req.method === "GET" && req.url === "/sse") {
      const transport = new SSEServerTransport("/message", res);
      transports.set(transport.sessionId, transport);
      transport.onclose = () => transports.delete(transport.sessionId);
      await mcpServer.connect(transport);
    } else if (req.method === "POST" && req.url?.startsWith("/message")) {
      const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
      const sessionId = url.searchParams.get("sessionId") ?? "";
      const transport = transports.get(sessionId);
      if (transport) {
        await transport.handlePostMessage(req, res);
      } else {
        res.writeHead(404, { "Content-Type": "application/json" });
        res.end(JSON.stringify({ error: "session not found" }));
      }
    } else {
      res.writeHead(404).end("not found");
    }
  } catch (err) {
    console.error("[relay] error:", err);
    if (!res.headersSent) res.writeHead(500).end(String(err));
  }
});

httpServer.listen(PORT, "127.0.0.1", () => {
  console.log(`[relay] server ready on :${PORT}`);
  console.log(`[relay] tools: post_message, read_messages, list_pending`);
  console.log(`[relay] waiting for connections — Ctrl-C to stop`);
});
```

- [ ] **Step 2: Smoke-test server startup**

In one terminal:
```bash
cd tools/relay && npx tsx server.ts
```

Expected output:
```
[relay] server ready on :7331
[relay] tools: post_message, read_messages, list_pending
[relay] waiting for connections — Ctrl-C to stop
```

In a second terminal, verify the port is listening:
```bash
curl -s --max-time 2 http://127.0.0.1:7331/sse | head -3
```

Expected: SSE `data:` stream begins (it won't complete — the connection stays open). Ctrl-C both.

If the server errors on startup, check that `@modelcontextprotocol/sdk` is installed and review any TypeScript errors by running `npx tsc --noEmit` in `tools/relay/`.

- [ ] **Step 3: Commit**

```bash
git add tools/relay/server.ts
git commit -m "feat(relay): MCP SSE server with post_message/read_messages/list_pending"
```

---

## Task 4: `start.sh`

**Files:**
- Create: `tools/relay/start.sh`

- [ ] **Step 1: Write `start.sh`**

Create `tools/relay/start.sh`:

```bash
#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel)"
PORT=7331
MODE="manual"

for arg in "$@"; do
  case "$arg" in
    --tmux)   MODE="tmux"   ;;
    --kitty)  MODE="kitty"  ;;
    --manual) MODE="manual" ;;
    *) echo "Unknown option: $arg" >&2; echo "Usage: $0 [--manual|--tmux|--kitty]" >&2; exit 1 ;;
  esac
done

# Port check
if lsof -ti:"$PORT" &>/dev/null; then
  echo "Error: port $PORT is already in use."
  echo "Relay already running? Kill it with: kill \$(lsof -ti:$PORT)"
  exit 1
fi

# Install deps (no-op if node_modules current)
cd "$SCRIPT_DIR"
npm install --silent

# Discover latest coordination prompts for instructions
COORD_DIR="$REPO_ROOT/docs/superpowers/coordination"
PM_PROMPT="$(ls -t "$COORD_DIR"/*-pm-prompt.md 2>/dev/null | head -1 || echo "(none found — run multi-agent-kickoff skill first)")"
DEV_A_PROMPT="$(ls -t "$COORD_DIR"/*-dev-a-prompt.md 2>/dev/null | head -1 || echo "(none found)")"
DEV_B_PROMPT="$(ls -t "$COORD_DIR"/*-dev-b-prompt.md 2>/dev/null | head -1 || echo "(none found)")"

print_manual_instructions() {
  echo ""
  echo "╔══════════════════════════════════════════════════════════════╗"
  echo "║          RELAY SERVER — MULTI-AGENT LIFT LAUNCHER            ║"
  echo "╚══════════════════════════════════════════════════════════════╝"
  echo ""
  echo "Open 3 new terminals. In each, start Claude Code and paste"
  echo "the content BELOW the '---' line from the corresponding file."
  echo ""
  echo "  Terminal 1 (PM):    cat '$PM_PROMPT'"
  echo "  Terminal 2 (Dev A): cat '$DEV_A_PROMPT'"
  echo "  Terminal 3 (Dev B): cat '$DEV_B_PROMPT'"
  echo ""
  echo "This terminal becomes the relay log. Keep it open."
  echo ""
  echo "══════════════════════════════════════════════════════════════"
}

launch_tmux() {
  SESSION="relay-lift"
  tmux new-session -d -s "$SESSION" -n "relay" \
    "cd '$SCRIPT_DIR' && npx tsx server.ts"
  tmux new-window -t "$SESSION:" -n "pm" "cd '$REPO_ROOT' && claude"
  tmux new-window -t "$SESSION:" -n "dev-a" "cd '$REPO_ROOT' && claude"
  tmux new-window -t "$SESSION:" -n "dev-b" "cd '$REPO_ROOT' && claude"
  echo ""
  echo "[relay] Opened tmux session '$SESSION' with 4 windows: relay, pm, dev-a, dev-b."
  echo "[relay] Paste the kickoff prompt into each Claude window."
  echo "        Prompts:"
  echo "          PM:    $PM_PROMPT"
  echo "          Dev A: $DEV_A_PROMPT"
  echo "          Dev B: $DEV_B_PROMPT"
  echo ""
  tmux attach-session -t "$SESSION"
}

launch_kitty() {
  kitty @ launch --new-tab --tab-title "relay" -- \
    bash -c "cd '$SCRIPT_DIR' && npx tsx server.ts"
  kitty @ launch --new-window --window-title "PM" -- \
    bash -c "cd '$REPO_ROOT' && claude"
  kitty @ launch --new-window --window-title "Dev-A" -- \
    bash -c "cd '$REPO_ROOT' && claude"
  kitty @ launch --new-window --window-title "Dev-B" -- \
    bash -c "cd '$REPO_ROOT' && claude"
  echo ""
  echo "[relay] Opened kitty tab 'relay' + 3 windows (PM, Dev-A, Dev-B)."
  echo "        Paste the kickoff prompts into each Claude window."
  echo "          PM:    $PM_PROMPT"
  echo "          Dev A: $DEV_A_PROMPT"
  echo "          Dev B: $DEV_B_PROMPT"
}

case "$MODE" in
  manual)
    print_manual_instructions
    exec npx tsx "$SCRIPT_DIR/server.ts"
    ;;
  tmux)
    launch_tmux
    ;;
  kitty)
    launch_kitty
    ;;
esac
```

- [ ] **Step 2: Make executable**

```bash
chmod +x tools/relay/start.sh
```

- [ ] **Step 3: Smoke-test `--manual` mode**

```bash
cd /home/alee/Sources/relicario && tools/relay/start.sh
```

Expected: prints the launch box with prompt paths, then server starts and shows `[relay] server ready on :7331`. Ctrl-C to stop.

- [ ] **Step 4: Commit**

```bash
git add tools/relay/start.sh
git commit -m "feat(relay): start.sh launcher with --manual/--tmux/--kitty modes"
```

---

## Task 5: Claude Code MCP configuration

**Files:**
- Modify: `.claude/settings.json`

- [ ] **Step 1: Read current `.claude/settings.json`**

```bash
cat .claude/settings.json
```

- [ ] **Step 2: Add the relay MCP server entry**

The file currently has `{ "enabledPlugins": { ... } }`. Add `"mcpServers"` at the top level:

```json
{
  "mcpServers": {
    "relay": {
      "type": "sse",
      "url": "http://localhost:7331/sse"
    }
  },
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true
  }
}
```

Preserve whatever is already in `enabledPlugins` — only add the `mcpServers` key.

- [ ] **Step 3: Commit**

```bash
git add .claude/settings.json
git commit -m "chore(relay): add relay MCP server to project Claude config"
```

---

## Task 6: `docs/superpowers/MULTI-AGENT.md`

**Files:**
- Create: `docs/superpowers/MULTI-AGENT.md`

- [ ] **Step 1: Write the paradigm README**

Create `docs/superpowers/MULTI-AGENT.md`:

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

- [ ] **Step 2: Commit**

```bash
git add docs/superpowers/MULTI-AGENT.md
git commit -m "docs: add multi-agent development paradigm README"
```

---

## Task 7: Update `multi-agent-kickoff` skill

**Files:**
- Modify: `~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md`
- Modify: `~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md`
- Modify: `~/.claude/skills/multi-agent-kickoff/SKILL.md`

- [ ] **Step 1: Read current templates**

```bash
cat ~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md
cat ~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md
```

Note where the "Setup" section ends in each template. The relay paragraph goes right after it (before "Required reading").

- [ ] **Step 2: Add `<<RELAY_PARAGRAPH>>` to `pm-prompt.md`**

In `~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md`, find the "## Setup" section and add the placeholder block immediately after it (before the "## Required reading" heading):

```markdown
<<RELAY_PARAGRAPH>>
```

The generated output for this placeholder (substituted by the skill at generation time) is:

```markdown
## Relay server

A message-bus MCP server is running on `localhost:7331`. You have three native tools:

- `post_message(from, to, kind, body)` — push a message; `from` is always `"pm"` for you
- `read_messages(for)` — drain your inbox; call with `for="pm"` before each action
- `list_pending(for)` — check inbox count without consuming

Recipients: `pm`, `dev-a`, `dev-b`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-a", kind="directive", body="...")`.
```

- [ ] **Step 3: Add `<<RELAY_PARAGRAPH>>` to `dev-prompt.md`**

In `~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md`, find the "## Setup" section and add immediately after it (before "## Required reading"):

```markdown
<<RELAY_PARAGRAPH>>
```

The generated output for this placeholder is role-specific (uses `<<DEV_ROLE>>`):

```markdown
## Relay server

A message-bus MCP server is running on `localhost:7331`. You have three native tools:

- `post_message(from, to, kind, body)` — push a message; your `from` is always `"<<DEV_ROLE>>"`
- `read_messages(for)` — drain your inbox; call with `for="<<DEV_ROLE>>"` before each task
- `list_pending(for)` — check inbox count without consuming

Recipients: `pm`, `dev-a`, `dev-b`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="<<DEV_ROLE>>")`. After emitting any status/question block: `post_message(from="<<DEV_ROLE>>", to="pm", kind="status"|"question", body="...")`.
```

- [ ] **Step 4: Update `SKILL.md` — add two entries to the placeholder reference table**

In `~/.claude/skills/multi-agent-kickoff/SKILL.md`, find the "### Common to all prompts" section of the Placeholder reference and add:

```markdown
- `<<RELAY_PARAGRAPH>>` — the relay server instruction block (substituted from the template above). For the PM prompt, `from` is hardcoded to `"pm"`. For dev prompts, uses `<<DEV_ROLE>>`.
```

In the "### Per-dev" section, add:

```markdown
- `<<DEV_ROLE>>` — lowercase relay role name, e.g. `dev-a`, `dev-b`. Derived from `<<DEV_LETTER>>` by lowercasing and prepending `dev-`. Set when `<<DEV_LETTER>>` is set.
```

- [ ] **Step 5: Update `SKILL.md` — step 8 (kickoff instructions)**

Find step 8 in the Process section ("Print kickoff instructions") and prepend a bullet:

```markdown
8. **Print kickoff instructions.** Tell the user exactly what to do:
   - **Start the relay server first:** `tools/relay/start.sh` (or `--tmux`/`--kitty` for auto-layout). The server must be running before the sessions open so the MCP tools initialize correctly.
   - Open three terminal windows (or panes — their choice of multiplexer)
   ...rest of existing bullets unchanged...
```

Also update the "After generation" section — change bullet 4 ("From that point on, they're the message bus...") to:

```markdown
4. The relay server handles message routing — agents call `post_message`/`read_messages` directly. The user only needs to step in for escalations the PM can't resolve, or if the relay server is down (manual fallback: copy-paste the block to the relevant terminal as before)
```

- [ ] **Step 6: Commit skill changes**

The skill files live outside the git repo, so no git commit needed. Verify the changes look right:

```bash
grep -n "RELAY_PARAGRAPH\|DEV_ROLE\|relay server" ~/.claude/skills/multi-agent-kickoff/SKILL.md | head -10
grep -n "RELAY_PARAGRAPH" ~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md
grep -n "RELAY_PARAGRAPH" ~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md
```

Expected: each grep returns at least one match.

---

## Final verification

- [ ] **Run queue tests one more time from repo root**

```bash
cd tools/relay && node --import=tsx/esm --test queue.test.ts
```

Expected: 5 passing, 0 failing.

- [ ] **Start server and verify it binds**

```bash
tools/relay/start.sh &
sleep 1
curl -s --max-time 1 http://127.0.0.1:7331/sse | head -1 || true
kill %1
```

Expected: `data:` line appears (SSE stream started), then server killed cleanly.

- [ ] **Verify MCP config is present**

```bash
python3 -c "import json; d=json.load(open('.claude/settings.json')); print(d['mcpServers']['relay'])"
```

Expected: `{'type': 'sse', 'url': 'http://localhost:7331/sse'}`

- [ ] **Verify skill placeholders were added**

```bash
grep "RELAY_PARAGRAPH" ~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md \
                       ~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md
```

Expected: one match per file.