Coordinator Running Brainstorm Cycles

---
name: coordinator-running-brainstorm-cycles
description:
  "Use when starting a brainstorm for a bug fix, feature, or architectural
  decision the coordinator can't trivially decide alone — spawns a researcher in
  an isolated worktree, runs the brainstorm interactively with the user,
  iterates dual-review cycles to ready-to-merge, optionally drives an
  overarching coherence pass when multiple sibling brainstorms close, then hands
  off to project-setup. Saves coordinator context by isolating brainstorm work
  in a sub-agent worktree rather than burning main-context tokens on Q-by-Q
  dialog."
# source: claude-plugin/skills/coordinator-running-brainstorm-cycles/SKILL.md
---

## Coordinator: Running Brainstorm Cycles

### When to use

A coordinator-orchestrated brainstorm is the right shape when:

- The user wants to settle the **architecture / design** of a non-trivial bug
  fix or feature before any code is written.
- The decision space has **multiple defensible options** and the user wants to
  explore them dialectically rather than just be told "I picked X."
- The coordinator would otherwise be running the Q-by-Q dialog directly, burning
  main-context tokens that should stay reserved for coordination.
- Multiple parallel brainstorms are valuable (one researcher per topic) and the
  coordinator needs to keep them moving without serializing on its own
  attention.

**Don't use when:**

- The decision is small and the coordinator can just decide and act
  (single-paragraph note, no protocol changes).
- The user explicitly wants the coordinator to do the brainstorm in main context
  (rare; respect it).
- The work is mid-implementation and a researcher would just slow it down — use
  the `adversarial-critique` skill for in-flight design forks instead.

### What this skill does (and what it hands off)

This skill owns the **entire researcher-side design pipeline** with review gates
at every stage:

1. Spawn researcher → 2. Brainstorm interactively with user → 3. **Dual-review
   the brainstorm** → 4. Iterate to LOCK → 5. (Optional) Overarching coherence
   pass when sibling brainstorms close → 6. Researcher writes plan +
   **dual-review the plan** → 7. Researcher runs `project-setup` + **dual-review
   the impl prompt** → 8. Hand off to coord for implementer dispatch.

**Three explicit review gates** at stages 3, 6, and 7 — same dual-axis pattern
each time (`verify-against-source` + a prose-quality reviewer, sub-agents (model
per `choosing-subagent-models`) in parallel — see "Review-loop mechanics"
below). Skipping any review gate is a documented anti-pattern. The brainstorm
review catches design issues; the plan review is the SOLE quality gate on the
plan doc — the researcher authors the plan directly (no external tool with its
own internal reviewer sits upstream of this gate); the prompt review catches
plan→prompt translation errors before the implementer executes against them.

### Subagent model selection

> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and
> effort per the `choosing-subagent-models` skill (read `runtime.role_models` at
> the moment of use). Never let a sub-agent inherit your own model.

#### Prefer `efficient-multi-agent-research` for multi-part research

When a research or investigation task has independent parts, reach for the
`efficient-multi-agent-research` skill FIRST — it partitions the work across
many cheap parallel subagents (cheap gatherers, judgment-tier synthesizers)
instead of one expensive serial subagent. It is the preferred research path:
cheaper, faster, and it keeps each subagent's context tight.

### Review-loop mechanics (applies to Phases 3, 6, 7)

Every prose gate uses the SAME machinery. Define it once here; each phase below
names only its stage-specific source.

#### The two reviewers (parallel, per gate)

| Axis            | Reviewer                                                                                                                                                 | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Conformance** | `verify-against-source` (thrum-owned skill)                                                                                                              | Does the artifact honor its INPUT(s)? Replaces `verify-against-plan` at prose gates — `verify-against-plan` BAILS without a code diff + a File-Structure table, so it cannot run on a brainstorm/plan/prompt. `verify-against-source` accepts a prose artifact + source doc with neither.                                                                                                                                                                                                                                                              |
| **Quality**     | general-purpose sub-agent (model per `choosing-subagent-models`) + prose-quality rubric (PRIMARY) ∥ `superpowers:requesting-code-review` (SUPPLEMENTARY) | The general-purpose prose-quality pass (internal consistency, gaps, contradiction, ambiguity, scope creep) is AUTHORITATIVE. `requesting-code-review` runs on a DIFF, so point it at the artifact's own commit range (`HEAD~1..HEAD`) — gated on the skill being resolvable; skip gracefully if absent. ⚠️ **That is the diff of the `.md` file, NOT a diff against the production code the artifact describes** — this row does NOT cover the code axis. Prose-vs-code is Conformance's job (see `verify-against-source` § "Second comparison unit"). |

Both are `general-purpose`, `model: <per choosing-subagent-models>`,
`run_in_background: true`. Wait for BOTH before consolidating. Verify each
BLOCKING against source before forwarding.

#### Footer → commit → stamp (per stage)

1. After the artifact is written, append the gate footer:
   `<!-- THRUM-GATE: stage=<brainstorm|plan|prompt> next=<dual-review|plan|project-setup|dispatch> -->`
2. **Commit the artifact (WIP) including the footer** — this gives the
   supplementary `requesting-code-review` pass a real `HEAD~1..HEAD` range.
3. Run the dual review against that range; each fix cycle commits its changes
   (giving the supplementary reviewer a fresh diff).
4. On terminate, append the verdict stamp. Use the **canonical, fixed-key-order
   form** (keys always in the order `stage=`, `verdict=`, `cycle=`, `date=`,
   `verify=`, optional `by=`/`reason=`; **case-sensitive** — exactly `Ready:Yes`
   / `OVERRIDE`; never `grep -i`) so the readers' **anchored**
   `grep -E '…verdict=Ready:Yes([[:space:]]|-->|$)'` matches — the gates no
   longer use `grep -F`, because a bare substring accepts
   `verdict=Ready:Yes-with-residual`:
   `<!-- THRUM-REVIEW: stage=<S> verdict=<Ready:Yes|OVERRIDE> cycle=<N> date=<YYYY-MM-DD> verify=<Ready:Yes|OVERRIDE|PREDATES> [by=<agent> reason="..."] -->`

   **`verify=` is REQUIRED (not optional) for `stage=plan` stamps going
   forward** — it records whether `verify-against-source` specifically ran this
   cycle (as opposed to some other reviewer stamping the artifact), and it must
   be PRESENT with one of exactly three values:
   - `Ready:Yes` — `verify-against-source` ran this cycle and came back clean.
   - `OVERRIDE` — a coordinator deliberately waived `verify-against-source` for
     THIS specific cycle (an active, in-the-moment decision, with a reason, same
     as the outer stamp's `OVERRIDE`).
   - `PREDATES` — this plan/stamp predates the `verify=` convention entirely;
     the legacy case. This is NOT the same as omitting the field — omission
     still fails `project-setup` Phase 0's mechanical gate. A plan from before
     this convention must be RE-STAMPED with `verify=PREDATES` (an explicit,
     checkable claim) to pass, not silently pass by having no `verify=` key at
     all.

   For other stages (`brainstorm`, `prompt`) `verify=` remains optional until
   those gates grow their own mechanical enforcement.

5. **Authored-against stamp (required, top of every artifact):** Before writing
   a brainstorm.md or plan.md, derive and emit the stamp per the
   $thrum:stamp-protocol skill § "Stamp format" — the canonical format,
   derivation commands, and never-type rule.

#### Soft pre-flight greps (the SOFT enforcement tier)

Before writing the plan (Phase 6) and before `project-setup` (Phase 7), grep the
prior artifact for `THRUM-REVIEW: stage=<S> verdict=Ready:Yes` (or
`verdict=OVERRIDE`); absent → STOP and run the review first. Anchor the match —
`grep -E '...verdict=Ready:Yes([[:space:]]|-->|$)'`, never `grep -F` — or an
invented `verdict=Ready:Yes-with-residual` passes as a substring. This is a
STRONG BEHAVIORAL guardrail, NOT a mechanical gate — an agent can ignore it. The
only structurally-enforceable gate is `project-setup` Phase 0 (it hard-bails).

#### Loop semantics

- `Ready:Yes` = ZERO BLOCKING findings remain. IMPORTANT/MINOR may be
  acknowledged-and-deferred without another cycle via a footer line:
  `<!-- THRUM-DEFER: stage=<S> cycle=<N> item="IMPORTANT #2" reason="<why + tracking ref>" -->`
  (any THRUM-DEFER still present at `project-setup` is surfaced in its Phase 0 /
  override audit).
- **Per-stage cap = 3 cycles**, independent per stage (max 9 across the
  pipeline) — a hard brainstorm does not starve the plan's budget.
- Cap hit with BLOCKINGs still open → STOP and escalate to the coordinator, who
  logs an override (stamp `verdict=OVERRIDE … reason="…"`) or redirects.
- **FEASIBILITY findings escalate, they do not reshape.** A FEASIBILITY finding
  (see Severity criteria, `verify-against-source/SKILL.md`) records that a
  reviewer judged a requirement too hard — NOT that the requirement should be
  dropped. The researcher may NOT resolve a FEASIBILITY finding by folding it
  inline into the next plan version as a silent scope cut. STOP and escalate to
  the coordinator as an explicit decision; only the coordinator (on the
  intent-owner's behalf) may rule "so we will not do it." The outcome — keep,
  cut, or weaken — is written into the `## Deviations from Source` block with
  attribution `owner decision`, never silently absorbed.

#### No external plugin drives this pipeline (D6)

Neither the brainstorm stage (Phase 2) nor the plan stage (Phase 6) invokes an
external skill — the researcher writes both artifacts directly, governed by this
skill's own protocol block (Phase 2) and structure/stamp/deviations requirements
(Phase 6). There is nothing to pre-flight-check or bail on for either stage, and
no `/plugin install` path: no such plugin is declared anywhere in this repo's
`.claude-plugin/marketplace.json`.

The one genuinely optional external supplement is `requesting-code-review`
(Review-loop mechanics, "Quality" row) — not resolvable → SKIP the supplementary
quality pass gracefully; the loop still runs on the general-purpose primary,
which is authoritative regardless.

`verify-against-source` and the general-purpose prose-quality pass carry no
external-plugin dependency and always work.

### Phase 1 — Set up the worktree, branch, and agent

#### Reuse an existing relevant brainstormer before spawning a new one

Before creating a new worktree, branch, or researcher agent, check whether an
existing brainstorm researcher is (a) **genuinely idle** — its prior brainstorm
is fully closed and handed off — AND (b) **domain-relevant** to the new topic. A
warm idle researcher carries accumulated codebase context that a fresh spawn
doesn't; reusing it is cheaper and faster when it fits.

**Probe (two commands, run in parallel):**

```bash
thrum team                   # list active agents; inspect intent + last_seen
git worktree list            # identify *-brainstorm worktrees still open
```

For each `*-brainstorm` worktree that looks relevant, inspect:

- The agent's `--intent` field (from `thrum team`) — does it overlap the new
  topic?
- `<worktree>/.thrum/agents/<name>/State.md` — one-sentence current status (idle
  / mid-brainstorm / standing-by)?
- The brainstorm doc in `dev-docs/brainstorms/` — is it stamped
  `verdict=Ready:Yes` or explicitly closed?

**Decision:**

| Condition                               | Action                                                                                                         |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Idle + domain-relevant researcher found | **REUSE** — send the Phase 2 briefing to the existing agent in its current worktree. Skip the rest of Phase 1. |
| No idle relevant researcher             | Fall through → proceed with "Pick the base branch" below.                                                      |

When reusing, have the agent itself run
`thrum session set-intent "<new one-line topic>"` so `thrum team` output stays
accurate (there is no command to set ANOTHER agent's intent — `set-intent` acts
on the caller), then send the Phase 2 briefing as normal. The existing worktree
and branch carry over; the agent is already primed.

**Scope of reuse:** adjacent topics in the same domain (e.g., a researcher who
handled scheduler-persistence brainstorm is a good candidate for a
scheduler-backpressure brainstorm). Cross-domain reuse is not worth the context
noise — start fresh.

> **Clarification vs the "Renaming brainstorm researchers" anti-pattern** (see
> Anti-patterns below): that anti-pattern forbids _renaming or rebinding_ a
> researcher to an _unrelated topic_ — especially while it is still busy on
> active work — because identity is bound to the worktree and mid-flight
> rebinding loses audit coherence. Reusing a **genuinely idle, domain-relevant**
> researcher for an adjacent topic in its **own existing worktree** is the
> ENCOURAGED path; no rename happens, no in-flight work is interrupted. The two
> rules are complementary: reuse when idle + relevant; tear down and start fresh
> when unrelated or still busy.

#### Pick the base branch

| Topic shape                                                          | Base branch                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bug fix, hardening, infra cleanup belonging to the current line      | The configured merge target — `CONFIG=.thrum/config.json; [ -f .thrum/redirect ] && CONFIG="$(cat .thrum/redirect)/config.json"; jq -r '.orchestration.merge_target' "$CONFIG"` (a worktree's `.thrum/` holds only a `redirect` file, not its own `config.json`) |
| Work belonging to a multi-epic version program                       | The version's long-lived branch                                                                                                                                                                                                                                  |
| Work tied to an existing feature epic with its own long-lived branch | That branch                                                                                                                                                                                                                                                      |

When in doubt, ask the user. Don't branch from `upstream/*` (per the global
git-safety rule).

#### Pick a name and module slug

- **Worktree dir name:** `<topic>-brainstorm` — kebab-case, descriptive of the
  topic, ends with `-brainstorm` so it's instantly recognizable in
  `git worktree list`. Examples: `auth-flow-brainstorm`, `cache-ttl-brainstorm`,
  `log-rotation-brainstorm`.
- **Branch name:** `feature/<topic>-brainstorm` (or `fix/<topic>-brainstorm` if
  the topic is a bug fix).
- **Agent name:** `researcher_<topic_underscore>` — matches the
  `<role>_<module>` convention. Examples: `researcher_auth_flow`,
  `researcher_cache_ttl`.
- **Module slug:** `<topic_underscore>` — short, lowercase, underscored.

#### Create branch + worktree + agent + launch runtime

```bash
# One command: branch + worktree + redirect + agent registration + tmux session + runtime launch
thrum worktree create <topic>-brainstorm \
  --branch feature/<topic>-brainstorm \
  --base <base-branch> \
  --name researcher_<topic_underscore> \
  --role researcher \
  --module <topic_underscore> \
  --intent "Brainstorm: <one-line topic description>" \
  --runtime claude
```

Never `git worktree add` an agent worktree: it leaves no `.thrum/redirect` and
lands outside `worktrees.base_path`. `thrum worktree create` wires both.

The runtime auto-primes via the SessionStart hook. Do NOT manually inject
`$thrum:thrum-prime` via send-keys (per `coordinator-dispatching-work`
discipline).

### Phase 2 — Send the briefing message

The briefing message is a structured handoff. Always send it via `thrum send`,
not `tmux send-keys` (per `coordinator-dispatching-work`).

#### The interactive-with-user brainstorm protocol

**Always include this verbatim block at the top of the briefing.** It encodes a
hard-won lesson, but a NARROW one: the failure mode is a researcher who
pre-commits the brainstorm's RESOLVED CHOICES (decisions/rulings) without the
user — those become confident-but-wrong and cost a full review cycle to undo.
The lesson is NOT "don't research." Brainstorming IS researching all aspects so
that when the questions come, they are sharp — and most brainstorms exist
precisely because there is a lot to research. Separate **pre-research (do it
hard)** from **pre-decision (don't)**: the researcher should aggressively survey
the landscape, enumerate options + tradeoffs, gather evidence with file:line
citations, surface the real open questions, and prepare a MEATY working draft of
the design space BEFORE the user joins — that is design-mode prep, exactly what
the user wants to walk into. They hold only the final DECISION-LOCK for the
user.

```text
═══ INTERACTIVE BRAINSTORM PROTOCOL ═══

Research aggressively + prepare MEATY groundwork BEFORE <user> joins:
survey the landscape, enumerate options + tradeoffs, gather evidence with
file:line citations, surface the real open questions, and draft a working
brainstorm doc of the design SPACE. The goal is that when <user> joins,
the questions are sharp and there is substance to work on.

<user> drives the DECISIONS Q-by-Q. Do NOT pre-commit or pre-write the
RESOLVED-CHOICES sections ahead of <user> — research + propose, but hold
the final rulings for them; capture their decisions verbatim. The
`interactive-brainstorm` role rule applies (search: `thrum memory search
"interactive-brainstorm"`).

Exception: a succinct, well-scoped brainstorm with little to research can
run capture-mostly; default to aggressive pre-research otherwise.
```

(Replace `<user>` with the actual user's name. The `interactive-brainstorm` role
rule (kind `agent_rule`, scope `role`) persists across researcher restarts —
find it with `thrum memory search "interactive-brainstorm"`, or browse all role
rules with `thrum memory list --kind agent_rule --scope role`.)

#### Briefing structure

Every briefing should include these sections (use `═══` headers for visual
distinction in the inbox display):

1. **Identity reminder** — agent name, worktree, branch, base branch (and that
   it's outside any larger version program if applicable). **Include an explicit
   "you run thrum commands from THIS worktree, not from the main repo or any
   other worktree" instruction** (see "Where the researcher runs thrum" below).
2. **Interactive brainstorm protocol** (verbatim block above)
3. **The problem** — one paragraph of the user-visible symptom or the feature
   gap
4. **What we already diagnosed / decided** — to prevent relitigation. Be
   explicit: "don't relitigate these; start from here."
5. **Design space to explore** — bulleted list of the open decisions the user
   will drive Q-by-Q
6. **Context to research up front** — concrete file paths + brief relevance
   notes. Tell them to read these AND research the space aggressively (code,
   beads, episodic memory, surveys) so they arrive with grounded options +
   evidence + sharp questions, not generic ones.
7. **Deliverable** — exact path the brainstorm doc lands at; convention:
   `dev-docs/brainstorms/<YYYY-MM-DD>-<topic>-brainstorm.md`. Include the
   "Decision Summary table at the bottom is canonical" framing. A meaty
   options/evidence/questions draft IS wanted up front; **explicitly say NOT to
   pre-commit the RESOLVED decisions** ahead of the user (those wait for the
   Q-by-Q + review feedback).
8. **Go-deep-then-ready instruction** — one sentence telling them to confirm
   readiness, research aggressively, and have meaty material ready when the user
   joins (not to sit idle waiting).
9. **Stop-at-the-artifact instruction** — tell the researcher explicitly: once
   the brainstorm design doc is drafted, STOP there. It goes through the Phase 3
   review gate before anything else happens; the plan doc is a separate,
   deliberate Phase 6 step after the brainstorm is LOCKED.

Send the whole thing as one `thrum send` call. The recipient's runtime will
display it as a single inbox message; structure beats brevity here.

#### Where the researcher runs thrum (do not let them inherit the wrong rule)

Some users have a global `~/.claude/CLAUDE.md` rule that reads "always run thrum
commands from the main repo directory." That rule is correct for the
main-repo-resident coordinator agent — but **it inverts for worktree-resident
researchers.** A researcher running thrum from the main repo path resolves
identity to the coordinator's name (e.g. `@your_coordinator`) and sends every
message under the coordinator's identity, polluting audit trails.

The correct rule is: **agents run thrum commands from their OWN home
directory.** Coordinator from main repo. Researcher from their worktree. **Never
run thrum from a worktree that isn't yours** (that's the underlying intent the
buggy global rule was reaching for).

Always include an explicit instruction in the Identity-Reminder section of the
briefing, e.g.:

```text
⚠ Run thrum commands from THIS worktree
(/Users/<you>/.thrum/worktrees/thrum/<topic>-brainstorm), not from the
main repo or any other worktree. The global CLAUDE.md "main repo only"
rule is correct for coordinators but inverts for worktree-resident
agents — your identity file lives in this worktree, and running thrum
from anywhere else will impersonate whoever owns that path.
```

Project-local capture: run
`thrum memory search --kind agent_rule --scope role --tag thrum-from-own-home`
to see the canonical version of this rule. If your project doesn't have it, the
researcher's first restart may re-inherit the buggy global rule.

### Phase 3 — Dual-review when the brainstorm closes

When the researcher reports the brainstorm is ready for review, run the
**two-reviewer dual review** per "Review-loop mechanics" above.

- **Conformance:** `verify-against-source` — artifact = the brainstorm doc;
  **source(s)** = parent decisions, the feature request, the ticket, and any
  sibling brainstorms.

  **Code side (REQUIRED):** for every decision naming a field, struct, column,
  table, RPC parameter, config key, or stored value, also hand the reviewer the
  ACTUAL definition at the authored-against SHA. Prose sources alone cannot
  catch an artifact that is wrong about the code. A gap there is a MISSING-STEP
  in the artifact, never a defect in the source — `IMPOSSIBLE` is not a verdict.

- **Quality:** general-purpose prose-quality PRIMARY ∥ `requesting-code-review`
  SUPPLEMENTARY (internal consistency, technical soundness, anti-patterns,
  gaps).

Both `general-purpose`, `model: <per choosing-subagent-models>`,
`run_in_background: true`. **Have the researcher append the gate footer and
commit (in their own worktree) BEFORE you spawn the dual-review sub-agents** —
the brainstorm lives in the researcher's branch, and the supplementary
`requesting-code-review` pass needs a real `HEAD~1..HEAD` diff. Wait for BOTH
before consolidating; verify each BLOCKING against source before forwarding.
Apply the footer → commit → stamp protocol and the loop semantics (Ready:Yes = 0
BLOCKING, per-stage 3-cap, override) from "Review-loop mechanics". On terminate,
the researcher stamps the brainstorm:
`<!-- THRUM-REVIEW: stage=brainstorm verdict=Ready:Yes cycle=<N> date=<YYYY-MM-DD> -->`.

#### Consolidated findings format

Send ONE numbered list to the researcher per `thrum send`, ordered:

1. BLOCKINGs in detail (severity, location, finding, suggestion)
2. IMPORTANTs as one-paragraph each
3. MINORs as condensed one-liners

Include "no-action positive tick-offs" at the bottom — this gives the researcher
confidence about what's already correct and prevents over-editing.

### Phase 4 — Iteration cycles

When the researcher reports their fixes are done:

- Run a **targeted verification sub-agent** (one sub-agent, model per
  `choosing-subagent-models`) that reads the updated doc and confirms each
  prescribed fix landed correctly. Do NOT re-derive the original findings —
  that's done.
- For tiny cosmetic fixes (one-line format updates, missing citations), ask
  in-place and spot-verify with a Bash grep — don't run a full verification
  cycle for single-line changes.
- For a researcher's design refinements that diverged from the literal
  recommendation: evaluate on substance, not literal compliance. Smart
  alternatives that close the original concern AND respect prior decisions
  better are coordinator-accepted territory; flag them for the user only if they
  materially change the user-visible shape.

When the verification passes, send the researcher an explicit "APPROVED — ready
to merge" with stand-down instructions.

### Phase 5 — Overarching coherence pass (when sibling brainstorms close)

If the topic is part of a larger program with multiple parallel brainstorms,
once **all sibling brainstorms reach ready-to-merge**, fire a deep-review (model
per `choosing-subagent-models`) coherence + implementability pass over the
corpus before specs are written.

Two parallel passes (background, a deeper tier per `choosing-subagent-models` —
escalate because this is genuinely cross-cutting reasoning over a large corpus):

| Pass                             | Focus                                                                                                                                                                                        |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Coherence / Contradiction**    | Direct contradictions between brainstorms, hidden cross-doc assumptions, vocabulary drift, reserved-field collisions, lifecycle composition, end-to-end event flows, cumulative parent-honor |
| **Implementability / Execution** | Realistic ship-cost, critical-path bottlenecks, capability assumptions that may not hold, test surface, operator-experience journeys, sub-epics needing split, sequencing risk               |

Both passes read the full brainstorm corpus + parent decisions + roadmap + any
existing companion specs. Their job is NOT to re-derive single-brainstorm
findings — it's to surface integration-layer issues that no single review could
see.

Findings from this pass go back to the relevant researchers (or to a follow-up
brainstorm if the issue spans multiple). Do not skip this pass when ≥ 3
brainstorms close in the same program — the integration layer is where the most
expensive footguns hide.

### Phase 6 — Researcher writes the plan (with dual-review gate)

Once the brainstorm is LOCKED (and any companion design spec is LOCKED), the
researcher writes the implementation plan doc directly, converting the
brainstorm + spec into concrete steps. (First, the soft pre-flight grep:
`grep -F` the brainstorm for its
`THRUM-REVIEW: stage=brainstorm verdict=Ready:Yes` (or `OVERRIDE`) stamp —
absent → STOP and finish the brainstorm review.) The plan feeds `project-setup`
— there is no other downstream path.

**The plan doc gets the SAME dual-review treatment as the brainstorm.** This
review step is mandatory: there is no internal reviewer upstream of it, so this
gate is the plan's only quality check. Independent review catches contract-drift
and quality issues a single author would miss.

**The researcher (not coord) dispatches the dual-review** in their own worktree:

1. Researcher writes plan v1 directly.
2. Researcher authors the `## Deviations from Source` block per the
   $thrum:deviations-protocol skill, diffing plan v1 against the brainstorm +
   design spec — BEFORE dual-review, so `verify-against-source` validates it as
   part of conformance. Required even when empty ("No deviations from source.").
3. Researcher runs the two-reviewer dual review (Review-loop mechanics):
   - **Conformance:** `verify-against-source` — artifact = the plan;
     **source(s)** = the brainstorm + the design spec. Verifies the plan honors
     every LOCKED decision AND that the Deviations block is present and
     accurate; flags missing scope, silent deviation, over-scoping, or an
     absent/inaccurate Deviations block. **Code side (REQUIRED):** for every
     requirement naming a field, struct, column, table, RPC parameter, config
     key, or stored value, hand the reviewer the ACTUAL definition at the
     authored-against SHA and require an enumerated SATISFIED / PARTIAL /
     MISSING-STEP / NOT-ADDRESSED verdict per requirement. `IMPOSSIBLE` is not a
     verdict — absent substrate is a MISSING-STEP in the plan, so the plan must
     ADD it.
   - **Quality:** general-purpose prose-quality PRIMARY ∥
     `requesting-code-review` SUPPLEMENTARY — per-task acceptance-criteria
     precision, anti-pattern enumeration, risk-register completeness, sequencing
     logic.
4. Researcher consolidates findings into ONE numbered list (all findings, all
   severities, per the same format Phase 3 uses).
5. Researcher folds findings inline → plan v2; applies footer → commit → stamp.
   Any FEASIBILITY finding (see Loop semantics) routes to the coordinator
   instead of being folded inline.
6. Researcher repeats only if cycle-1 introduces new design surface (rare for
   bounded mechanical plans); otherwise v2 LOCKED. Before stamping, compute
   `plan_obj`/`src_lock` per `stamp-protocol.md` § "Review-object binding"
   (strip-then-hash the plan against itself for `plan_obj`; plain-hash the
   LOCKED source for `src_lock`), then stamp
   `<!-- THRUM-REVIEW: stage=plan verdict=Ready:Yes cycle=<N> date=<YYYY-MM-DD> verify=Ready:Yes plan_obj=<blob> src_lock=<blob> -->`.
7. Researcher signals plan LOCKED back to coord, citing both review passes and
   the Deviations block.

If the researcher skips this step, send them back. Before Phase 7, the soft
pre-flight grep (Review-loop mechanics) confirms the plan carries the
`stage=plan verdict=Ready:Yes` (or `OVERRIDE`) stamp. Don't let them proceed to
`project-setup` until the plan has passed dual-review.

### Phase 7 — Researcher runs project-setup (with dual-review gate)

Plan LOCKED → researcher runs `thrum:project-setup` to produce the bundled
output: bd tickets + implementer prompt + cross-references.

**The implementer-prompt doc gets the SAME dual-review treatment as the plan.**
The prompt is the artifact the implementer executes against turn-by-turn; errors
propagate. The plan dual-review caught contract-drift in the plan; the prompt
review catches translation errors (plan → prompt) plus prompt-specific quality
(instructions clarity, anti-pattern enumeration, dispatch-readiness).

**The researcher (not coord) dispatches the post-setup dual-review**:

1. Researcher runs `project-setup` skill (bd tickets + prompt land together).
   Note: `project-setup` Phase 0 hard-bails unless the plan carries its
   `stage=plan verdict=Ready:Yes`/`OVERRIDE` stamp — Phase 6 must have stamped
   it.
2. Researcher runs the two-reviewer dual review on the impl prompt:
   - **Conformance:** `verify-against-source` — artifact = the impl prompt;
     **source(s)** = the LOCKED plan + the bead task descriptions (dump
     `bd show` to a temp file so the sub-agent can read the per-task ACs).
     Verifies the prompt faithfully translates per-task content + ACs + risk
     callouts; flags missing scope, divergent wording, dropped anti-patterns.
     **Code side (REQUIRED):** for every AC naming a field, struct, column,
     table, RPC parameter, config key, or stored value, hand the reviewer the
     ACTUAL definition at the authored-against SHA. An AC the current code
     cannot satisfy is a MISSING-STEP in the prompt/plan — the substrate must be
     ADDED. `IMPOSSIBLE` is not a verdict.
   - **Quality:** general-purpose prose-quality PRIMARY ∥
     `requesting-code-review` SUPPLEMENTARY — clarity, scope language,
     dispatch-readiness, sub-agent model guidance, DONE-shape spec.
3. Researcher consolidates → folds inline → re-issues prompt; `project-setup`
   OWNS and applies the prompt-stage stamps — the gate footer, the binding-bound
   verdict stamp, and the hard completion requirement that it not exist without
   one — per that skill's canonical contract (`project-setup` SKILL.md § "Step
   5: Stamp the prompt for the review loop" + Phase 0). This step does not
   restate that mechanics; it exists only to confirm the stamp is applied within
   the same project-setup session, before signaling back.
4. Researcher signals "project-setup complete + post-setup dual-review applied"
   back to coord, citing both review passes + final artifact paths.

Reaffirmation (at the prompt stage): `project-setup` is the only downstream path
for the implementer prompt.

If the researcher signals "project-setup complete" WITHOUT mentioning the
post-setup reviews, ASK explicitly: "did the post-setup dual-review run on the
impl prompt?" Send them back if not. The artifact the implementer executes must
be reviewed.

### Phase 8 — Hand off to coord

With plan LOCKED + reviewed AND project-setup complete + reviewed:

1. Researcher provides coord: plan path, prompt path, bd-epic ID, bd-task ID
   list, prereq verifications (philosophy.md, bd version, etc.).
2. Coord verifies the artifacts briefly + proceeds to Phase 0 implementer
   dispatch (worktree creation, hard-freeze if applicable, impl dispatch).
3. Stand the researcher down at-pane (or keep on standby for impl-time Q&A if
   the user explicitly requests continuity). Don't leave brainstorm researchers
   spinning idle indefinitely; they consume tmux sessions.

### Anti-patterns

❌ **Pre-emptive autonomous DECISIONS.** Researcher pre-commits the brainstorm's
RESOLVED choices/rulings without the user driving them — those become
confident-but-wrong and cost a full review cycle to undo. The sin is committing
DECISIONS, NOT researching: aggressive pre-research + a meaty
options/evidence/questions draft is wanted (see the brainstorm protocol). The
`interactive-brainstorm` role memory rule (kind `agent_rule`, scope `role`)
encodes this; include the verbatim protocol block in every briefing.

❌ **Half-batched findings.** Sending review findings before BOTH dual reviews
complete. Researcher fixes batch 1 and never sees batch 2.

❌ **Skipping the post-plan dual-review.** Proceeding directly to
`project-setup` without an independent review of the plan doc — there is no
internal reviewer upstream of it to lean on. The plan and the impl prompt MUST
get the same dual-axis review treatment the brainstorm gets — Phase 6 + Phase 7
explicit.

❌ **Skipping the post-project-setup dual-review on the impl prompt.** The
prompt is the artifact the implementer executes against turn-by-turn. Errors in
it propagate into every task. `project-setup` runs the bundle (bd + prompt)
mechanically; the prompt content is the implementer's spec. Treat it as such and
review it before dispatch.

❌ **Misread BLOCKINGs forwarded as gospel.** Reviewers (sub-agents) sometimes
misread cited code or stretch citations. Spot-verify any BLOCKING that names a
specific file/line/symbol before forwarding.

❌ **`thrum message read --all --force` mid-brainstorm without checking the
report.** `--all` alone is a dry run (marks nothing); `--force` only drains what
THAT dry-run listing named, and reports any later arrival as excluded rather
than silently sweeping it in — so the old "B arrives mid-read and gets silently
marked" timing bomb no longer applies. Still prefer
`thrum message read <id> [<id>...]` with specific IDs when juggling multiple
researchers — it's simpler to reason about than tracking a listing's 10-minute
validity window.

❌ **Sub-agents into the researcher's worktree.** For code research in the
brainstorm worktree, ask the researcher; for broader codebase exploration, spawn
an `Explore` sub-agent in the main repo path, not the worktree path.

❌ **Skipping the coherence pass.** When ≥ 3 sibling brainstorms close in the
same program, integration-layer issues that no single review can see are
virtually guaranteed. Fire the deep-review pass; it's worth the cost.

❌ **Renaming brainstorm researchers between topics.** Identity is bound to the
worktree. If a topic is done, kill the tmux session and tear down the worktree;
don't rebind the agent name to a different topic in place.

### See also

- `coordinator-plan-reconcile-gate` — when ≥2 plans for one program were
  authored in parallel (Phase 6 output) and must be verified to compose before
  `project-setup` (shared seams, no double-build, no gap).

### Project-specific rules (already loaded)

Load the $thrum:project-rules-protocol skill and follow it.

If you accumulate a new rule mid-session about brainstorm orchestration, capture
it via the Memory section of your role preamble — it references the
`thrum-memory` skill for the canonical `thrum memory create` shape. Use a
`brainstorm-<slug>` tag to keep brainstorm-orchestration rules grouped.