brainstorm

Task hygiene:

# audit-skip: resilience-replication
_FS=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/foundry}/bin/resolve_shared_path.py" foundry skills/_shared 2>/dev/null || echo "plugins/foundry/skills/_shared")  # timeout: 5000

Read $_FS/task-hygiene.md — follow task hygiene protocol.

Task tracking: Before Step 1, create TaskCreate entries for all 6 steps (context scan, clarifying questions, build tree, save tree, tree review, present + gate). Then print session plan to user:

Brainstorming: <goal from $ARGUMENTS> Plan: context scan → clarifying questions → build tree → save tree doc → review → approval gate. Starting with a codebase scan...

Step 1: Context scan

Unsupported flag check — after all supported flags extracted (--tight, --deep, --type), scan $ARGUMENTS for remaining --<token> tokens. If found: print ! Unknown flag(s): \--`. Supported: `--tight`, `--deep`, `--type`.then invokeAskUserQuestion` — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown flags, proceed). On Abort: stop.

Gather project context before asking anything:

• Read README.md and relevant files under docs/
• Grep for keywords from $ARGUMENTS across src/ or project root
• Identify: related code that already exists, stated non-goals in docs, prior design decisions

Type-aware scan patterns (when --type declared):

• application: look for existing routes, controllers, components, API endpoints, auth middleware
• workflow: look for existing scripts, pipelines, CI configs, scheduled jobs, automation files
• utility: look for existing utils/, helpers/, lib/ directories and similar functions
• config: look for .claude/ agents, skills, rules, and settings.json entries
• research: look for existing notes, benchmarks, prior experiment results, and related papers/tickets

When no --type declared, perform generic scan.

Existing codebase guidance: when project has existing code, note patterns in use (naming, architecture, data flow) — Step 3 branches should follow established patterns unless idea explicitly requires changing them. Where existing code has problems affecting the work (e.g., file grown too large, unclear boundaries), note as open threads — do not propose unrelated refactoring, but flag targeted improvements that serve current goal.

Goal: understand constraints so questions targeted, not generic. If idea already exists or clearly out of scope, say so immediately and stop.

Scope check: before asking clarifying questions, assess request size. If idea describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag immediately — do not spend questions refining details of oversized scope. Help user decompose into sub-ideas: what are independent pieces, how do they relate, what order to tackle them? Then proceed with first sub-idea through normal idea mode flow.

Live viewer init: ask user whether to create live viewer before proceeding. Call AskUserQuestion:

• question: "Create live tree viewer for this session?"
• (a) label: Yes — create viewer — description: create JSON sidecar and serve tree viewer in browser
• (b) label: No — skip viewer — description: proceed without viewer; tree still saved to disk at Step 4

On (b): skip viewer creation and the print launch note below; set SIDECAR="" and skip all Write-to-sidecar steps throughout (Steps 3–4).

On (a):

# timeout: 3000
mkdir -p .plans/blueprint
SIDECAR=".plans/blueprint/brainstorm-$(date -u +%Y-%m-%dT%H-%M-%SZ).json"
echo "$SIDECAR" > "${TMPDIR:-/tmp}/brainstorm-state-sidecar"
echo "$SIDECAR"

Persistence note: shell variables do NOT persist across separate Bash calls. The echo "$SIDECAR" > "${TMPDIR:-/tmp}/brainstorm-state-sidecar" step above writes the path to a state file. At the top of every subsequent Bash block that references $SIDECAR (Steps 3–4), re-read it:

SIDECAR=$(cat "${TMPDIR:-/tmp}/brainstorm-state-sidecar" 2>/dev/null || echo "")

If $SIDECAR is empty after re-read, treat as viewer opt-out and skip all sidecar Write steps.

Record $SIDECAR path — referenced in Steps 3 and 4. Write initial JSON to that path using the Write tool:

{
  "schema_version": 1,
  "session_status": "active",
  "updated_at": "<current ISO timestamp>",
  "session": { "title": "<raw $ARGUMENTS text>", "slug": "", "started_at": "<current ISO timestamp>" },
  "tree": { "id": "root", "label": "<raw $ARGUMENTS text>", "status": "open", "core_idea": "", "tension": "", "trades_away": "", "skill_lean": "", "children": [] },
  "ui": { "active_node_id": null, "last_error": null }
}

On write failure: log > Viewer write failed: <reason> inline and continue.

Print launch note:

Live tree viewer: resolve scripts dir (works both pre- and post-install — $CLAUDE_PLUGIN_ROOT points at the installed cache when the plugin is installed; the fallback supports development against the source tree):

_BRAINSTORM_SCRIPTS="${CLAUDE_PLUGIN_ROOT:-plugins/foundry}/skills/brainstorm/scripts"
echo "Viewer HTML: $_BRAINSTORM_SCRIPTS/tree-viewer.html"

Because the viewer lives under the plugin cache (read-only) while $SIDECAR lives under the project's .plans/blueprint/, the static server's document root must cover both paths. Easiest reliable option: serve from $HOME with python -m http.server 8080 --directory "$HOME" (or npx serve "$HOME"), then open http://localhost:8080/<relative-path-from-HOME-to-tree-viewer.html>?state=<absolute-or-HOME-relative-sidecar-path>. If you prefer serving from the project root, copy or symlink the viewer HTML into a project-local directory first so the URL path resolves under the same document root as $SIDECAR.

Step 2: Clarifying questions

Use AskUserQuestion for every clarifying question — renders interactive prompt inline, not plain text.

Rules:

• Ask one question at a time — call AskUserQuestion once, wait for answer, then decide if another question needed
• Always use multiple-choice options in AskUserQuestion: list lettered choices so user can reply with just "a", "b", or "c"; mark recommended option with ★ (e.g., a) Option A ★ recommended) so user has sensible default
• Maximum 10 questions (5 in --tight mode, 15 in --deep mode) — after limit, proceed to Step 3 with what you have
• After question 3 (and every subsequent question), always include escape hatch option: x) Enough questions — let's start building the tree so user can move on if problem already well-defined
• No solution proposals during this step — only gather information
• After each answer, briefly restate updated problem understanding in 1–2 sentences before asking next question or proceeding — simple acknowledgment ("Got it", "Understood") does not count; restatement must name what is now known about problem (e.g., "So the goal is X and the constraint is Y.")
• After restatement, add skill's own perspective in blockquote labelled Skill's read: — 1–2 sentences on what directions this answer opens up, what it makes more or less likely, or what tension it surfaces. Active hypothesis, not neutral summary (e.g., > **Skill's read:** This makes me think the core challenge is X, which points toward approaches like Y). Write as skill speaking.

Gate: do not proceed to Step 3 until problem well-defined or maximum question count reached. Aim for at least 3 questions to build enough context for rich tree.

Type-aware question framing (when --type declared): lead with type-appropriate questions first:

• application: ask about users (who uses it?), scale, and integration points before general questions
• workflow: ask about triggers (what starts it?), inputs, outputs, and failure handling first
• utility: ask about callers (who uses this library/tool?), interface shape, and scope of responsibility
• config: ask whether this targets existing agent/skill or is new, and what gap it fills in current setup
• research: ask about hypothesis or question being investigated, and what constitutes useful finding

Step 3: Build the tree

Full creative session — grow, deepen, and prune tree of directions. Tree is output; convergence happens later in breakdown. Runs as loop of tree operations.

Pre-seeding exchange

Before presenting formal branches, run brief free-form idea exchange — 2–3 rapid rounds. Goal: surface intuitions about direction before committing to structure. Like tennis rally — Claude serves first, user returns, branches emerge from what lands.

1. State skill's opening hypothesis: 1–2 sentences on where problem looks most interesting or tricky. Not a branch — just a read.
2. Immediately present 3–5 initial branches (see Seeding the tree below) in the same message — no separate round-trip. Each branch is numbered (1, 2, 3, …) and ★ on the most promising one.
3. Call a single AskUserQuestion for the reaction choice (≤4 options per call per AQQ cap): "How does this look?" with exactly four options: (a) ★ recommended — pick branches to focus on (reply naming 1–3 branch numbers in free text) · (b) Not quite — let me redirect (reply describing the redirect) · (c) add more branches first · (d) skip focus selection — start tree ops with all branches open. The branch list is in the message body for reference; users name branches by number rather than by sub-option letter so the AQQ stays at 4 options regardless of branch count.
4. Proceed to Tree operations loop:
   • (a) picked: user's free-text reply names 1–3 branches → set those as ▶️ focus; others remain 💭 open
   • (b) picked: regenerate 2–3 fresh branches reflecting the redirect and re-enter step 3 (one re-entry allowed; second redirect proceeds with whatever branches exist)
   • (c) picked: generate 2–3 additional branches with different framing and re-enter step 3
   • (d) picked: enter tree ops with all branches 💭 open and no initial focus

Skip on re-entry: when looping back from Step 6 (b) "Needs more exploration", skip BOTH the pre-seeding exchange AND the Seeding the tree section — go straight to the Tree operations loop with existing branches as starting state. Do NOT re-seed (do NOT present new top-level branches as if starting fresh); user's previous tree is the operand for re-entry operations (add, close, deepen, etc.).

Seeding the tree

Present 3–5 initial branches (top-level directions) in the same message as the opening hypothesis (see pre-seeding exchange step 2 above). For each include:

• Name: short label
• Core idea: 2–3 sentences — what makes this branch distinct
• Tension it resolves: which aspect of problem this branch prioritises
• What it trades away: what gets harder or left unsolved
• Skill's lean: short honest opinion — what makes branch interesting or worth exploring, and any reservation skill has about it (e.g., "Interesting because it sidesteps the auth problem entirely, but risky if the data model isn't flexible.")

YAGNI filter: when generating branches, actively prune speculative "we might need this later" directions — include only branches that directly address stated problem. Flag any branch requiring features or scale not mentioned in clarifying questions as "speculative" in its What it trades away line.

Write Opening framing paragraph (2–3 sentences): skill's initial read on problem space — core tension, which branch(es) most promising and why, one thing it's uncertain about. Not recommendation to converge — divergence still goal — but honest perspective to spark reaction.

The reaction AskUserQuestion is defined in pre-seeding exchange above (4 options: focus / redirect / more branches / skip). When the reaction is (b) redirect: generate 2–3 new branches incorporating the described direction. When (c) add more: generate 2–3 fresh branches with genuinely different framing.

User may select 1–3 branches to mark as initial focus via the free-text reply to option (a). All other branches start as 💭 open too — not closed yet, just not initial focus.

After user selects initial focus, write sidecar immediately with all branch details populated — set core_idea, tension, and trades_away on every branch node before first tree operation begins. Do not wait for first operation to write branch content into sidecar.

Tree operations loop

After seeding, enter operations loop. Each iteration:

1. Show current tree summary (see format below)

2. Write Skill's moment — 2–3 sentences of skill's current read: which open branches look most interesting and why, what closed branches revealed about problem, and what skill would explore next if it had a vote. Make specific to current tree state (refer to actual branch names by their labels). Gives user something to react to before choosing operation.

3. Call AskUserQuestion with four operation-category options (AQQ cap is 4 per call — pick a category here; if the category needs a specific operation, ask one follow-up AQQ enumerating the operations within it):

   • (a) per-branch operation — deepen, reject, accept, or merge a branch (follow-up AQQ enumerates the four per-branch operations and asks which branch)
   • (b) tree-level operation — add a new top-level branch, or reopen a closed one (follow-up AQQ enumerates the two tree-level operations)
   • (c) back to idea stacking — free-form exchange, then return here (no follow-up needed)
   • (d) ready — save tree and proceed to Step 4

   When (a) is picked, the follow-up AQQ (still capped at 4 options) lists:

   • a) deepen [branch name] — add sub-directions
   • b) reject [branch name] — close with a reason
   • c) accept [branch name] — mark as the chosen direction
   • d) merge [branch name] + [branch name] — combine into one

   When (b) is picked, the follow-up AQQ lists:

   • a) add a new top-level branch — explore a fresh angle
   • b) reopen [branch name] — revisit a closed branch

   For per-branch operations that need a branch name, ask the user for the branch number/name in the follow-up AQQ's free-text reply rather than enumerating each branch as a separate option (keeps every AQQ ≤ 4).

4. Write viewer state (after any operation except Ready; skip entirely if $SIDECAR is empty — viewer opt-out): overwrite $SIDECAR with current full tree state using Write tool; set ui.active_node_id to just-operated node's id; update updated_at to current ISO timestamp; update session.title to current brainstorm title. All branch objects in JSON — regardless of status (open, rejected, merged, resolved) — must retain core_idea, tension, and trades_away fields; these are set at seeding time and must not be dropped when branch status changes. On write failure: log > Viewer write failed: <reason> inline and continue; on next successful write, set ui.last_error: "<reason>".

Operations:

• Deepen (a): generate 2–3 sub-branches under named branch. Sub-branches use same format as top-level branches. Ask which one(s) to focus on. After executing, write 1–2 sentences reacting to what deepening this branch opens up — what new tensions or opportunities sub-branches reveal.
• Reject (b): mark named branch as ⛔ (rejected) with user's reason shown after —. Add one-line entry to pruning log. Ask if reason captures it correctly before proceeding. After executing, write 1–2 sentences reacting to what rejecting this branch reveals — what it tells us about where exploration is actually headed.
• Accept (c): mark named branch as ✅ (resolved) with note explaining why it was chosen as the direction. Do NOT add to pruning log (it's accepted, not pruned). After executing, write 1–2 sentences on what this choice commits to — what it confirms and what it implicitly rules out.
• Merge (d): synthesise two named branches into single hybrid branch; present merged description; mark originals as 🔗 with [merged -> <number>: <new-branch-name>] immediately in tree summary shown after merge, and in all subsequent tree summaries. When writing merged branch state to sidecar, use field name merged_into_id with value equal to target branch's id field (e.g., "b6"), not a label string. After executing, write 1–2 sentences on what merge suggests about where idea is heading — what synthesis makes clearer or harder.
• Add (e): generate 1–2 fresh top-level branches with directions not yet represented in tree. After executing, write 1–2 sentences on why new angle matters — what gap it fills or what it challenges in existing branches.
• Reopen (f): change ⛔ (rejected) or ✅ (resolved) back to 💭 (open) on named branch; note re-opening reason. After executing, write 1–2 sentences on what reopening this branch might change — what it puts back on table.
• Idea stacking (g): pause tree operations and enter brief free-form exchange — same format as pre-seeding exchange (2–3 rounds max). Useful when exploration feels stuck or new angle just surfaced but isn't fully formed yet. After exchange, return to tree operations loop with any new angles incorporated as branches or sub-branches. Does NOT consume an operation slot — counter unchanged.
• Ready (h): exit loop, proceed to Step 4.

Tree summary format

Always show tree summary before calling AskUserQuestion:

Tree: <title>
├─ ▶️ Branch 1: <name>
│  ├─ 💭 1.1: <name>
│  └─ ⛔ 1.2: <name> — <reason>
├─ 💭 Branch 2: <name>
│  ├─ ▶️ 2.1: <name>
│  │  ├─ 💭 2.1.1: <name>
│  │  └─ ⛔ 2.1.2: <name> — <reason>
│  └─ ⛔ 2.2: <name> — <reason>
├─ ✅ Branch 3: <name> — <reason chosen>
└─ 🔗 Branch 4: <name> [merged -> <number>: <new-branch-name>]
Open: N · Rejected: N · Resolved: N · Merged: N
Legend: ▶️ active focus · 💭 open · ⛔ rejected · ✅ resolved/accepted · 🔗 merged

Use ├─, │ ├─, └─ for tree rendering. Show sub-branches indented one level per depth. Sub-branches use hierarchical dot notation: branch 2 splits into 2.1, 2.2, …; those split further into 2.1.1, 2.1.2, … Prefix each branch with status emoji: ▶️ for branch currently operated on (most recently deepened, or selected as initial focus during seeding), 💭 for all other open branches, ⛔ for rejected branches (show reason after —), ✅ for resolved/accepted branches (show reason after —), 🔗 for merged branches (show merge target as [merged -> <number>: <new-branch-name>]). Legend line always last.

Loop bounds

• Maximum 10 operations (5 in --tight mode, 15 in --deep mode) (round = one operation; idea stacking (g) does not count)
• After limit: show tree state, call AskUserQuestion with: a) Save tree as-is ★ recommended / b) Do 2 more operations then save
• Gate: do not proceed to Step 4 until user selects "Ready" or max reached with at least 2 rejected branches (1 in --tight, 3 in --deep); resolved/accepted branches do not count toward this minimum (they are the goal, not waste); if fewer than required rejected branches exist, prompt: "The tree has few rejected branches — consider rejecting 1–2 that are clearly not the right direction before saving."

Step 4: Save tree

Assemble tree state and write to .plans/blueprint/YYYY-MM-DD-<slug>.md using Write tool (creates directory if absent). Slug derived from title (kebab-case, max 5 words). If file already exists at target path (e.g., same day, same slug after restart), append counter suffix (-2, -3, etc.) rather than overwriting.

# <title>

**Date**: YYYY-MM-DD
**Status**: tree

## Root idea

[The original user input and the refined problem understanding built up during Step 2 — 2–3 sentences.]

## Branches

[For each branch in the tree, using this structure:]

### Branch N: <name> [open | rejected — <reason> | resolved — <reason> | merged into <name>]

**Core idea**: ...
**Tension it resolves**: ...
**What it trades away**: ...

[Sub-branches nested as H4 headings if present:]

#### N.1: <sub-branch name> [open | rejected — <reason> | resolved — <reason>]

**Core idea**: ...

[Deeper splits nest as H5 headings, e.g. `##### N.1.1: <name>`]

## Pruning log

- Branch N rejected: <reason>
- Sub-branch N.1 rejected: <reason>
[One bullet per rejected or merged branch (NOT resolved/accepted), in the order they were closed.]

## Resolved branches

- Branch N accepted: <reason/decision note>
[One bullet per ✅ resolved branch.]

## Open threads

[Unanswered questions, untested combinations, and constraints that surfaced during Step 3. Each thread is a one-line bullet.]

Gate: do not proceed to Step 5 until file written and path confirmed.

Sidecar finalise (skip if $SIDECAR is empty — viewer opt-out): using Write tool, write full current JSON content (same as $SIDECAR) with session_status: "complete" to .plans/blueprint/<final-slug>.json (same slug as .md file, .json extension). Then also overwrite $SIDECAR with session_status: "complete". Do NOT move or rename $SIDECAR — open browser tabs keep polling original timestamp-slug path.

Step 5: Tree review

Before spawning, pre-compute output path:

# timeout: 3000
BRANCH=$(timeout 3 git branch --show-current 2>/dev/null | tr '/' '-' || echo 'main')
mkdir -p .reports/brainstorm
OUTPUT_PATH=".reports/brainstorm/review-$BRANCH-$(date +%Y-%m-%d).md"

Spawn foundry:curator with tree-focused prompt. Substitute $OUTPUT_PATH value (pre-computed above) for <output-path> template slot and the actual tree file path for <tree-file> before passing prompt — do NOT pass literal $OUTPUT_PATH variable name or the bare <output-path> / <tree-file> placeholder strings in the prompt string. Example substitutions: <output-path> → .reports/brainstorm/review-main-2026-05-20.md; <tree-file> → .plans/blueprint/2026-05-20-my-idea.md:

Read .plans/blueprint/<tree-file>. Audit for tree quality only (do NOT audit `.claude/` config files — scope is the brainstorm tree only):
- Root idea: is the original problem clearly stated in the "Root idea" section?
- Branch depth: do open branches have enough detail (not just a name)?
- Closure quality: are closure reasons substantive (not just "not chosen" or "skipped")?
- Coverage: are there obvious high-level directions completely missing from the tree?
- Open threads: are there unresolved questions worth capturing?
Write your full findings to <output-path> using the Write tool. The file must begin with a YAML metadata block:
---
Brainstorm Review — [tree topic]
Date:     [YYYY-MM-DD]
Verdict:  READY | NEEDS_REFINEMENT | BLOCKED
Findings: [N]
Confidence: [score] — [key gaps]
Next steps: /foundry:manage create | /develop:feature (requires `develop` plugin)
Path:       → .reports/brainstorm/review-<branch>-<date>.md
---
Then the full findings below.
Return ONLY a compact JSON envelope: {"status":"done","findings":N,"file":"<path>","confidence":0.N,"summary":"<one-line>"}

Passive health monitoring: Agent tool is synchronous — Claude awaits curator's response natively. If foundry:curator does not return within 15 min, surface any partial output already written to $OUTPUT_PATH (under .reports/brainstorm/) with ⏱ marker and continue to Step 6 with incomplete review noted. The path is the same $OUTPUT_PATH computed in the pre-spawn block above; do not poll .temp/ — brainstorm review output lives in .reports/brainstorm/.

Note: synchronous Agent calls do not support mid-call extensions per CLAUDE.md §6 — simplified monitoring is intentional for synchronous spawns.

If findings > 0: add missing details, improve closure reasons, or add open threads as needed — loop back to Step 5 (max 2 revision cycles per Step 6 approval cycle; counter resets each time Step 3 re-entry is triggered from Step 6 option b). After 2 cycles with remaining findings, surface unresolved issues to user and proceed to Step 6 anyway.

Gate: do not proceed to Step 6 until findings == 0 or 2 revision cycles exhausted.

Step 6: Present and gate

Show tree file path and compact tree summary (same format as Step 3). Then call AskUserQuestion tool — do NOT write options as plain text first. Map options directly into tool call arguments:

• question: "How does the exploration tree look?"
• (a) label: Tree looks good — ready to distill — description: proceed to distillation (★ recommended)
• (b) label: Needs more exploration — description: describe what to add or close; loop back to Step 5
• (c) label: Start over — description: back to clarifying questions

Gate: do not exit until user approves.

On (b): return to Step 3 with existing tree state — add requested branches or close specified ones, then loop back to Step 5. Use reduced cap of 3 additional operations for this re-entry (not fresh full budget reset); cap resets only at start of Step 3, not on re-entry. On (c): loop back to Step 2. (Max 3 approval cycles as guideline — track in context; if 3 cycles pass without convergence, surface unresolved concerns to user.)

On approval, suggest: /brainstorm breakdown .plans/blueprint/<file> to distill tree into spec.

Tree file is durable record of exploration. Share with teammates or use as context for future /brainstorm sessions on related ideas.

Mode: Breakdown

Triggered when $ARGUMENTS starts with breakdown followed by file path.

Read file at given path. Check **Status**: field:

• Status: tree → Distillation mode (Steps D1–D4 below)
• Status: draft → Action plan mode (Steps B1–B3 below)

Distillation mode (Status: tree)

Step D1: Present tree summary

Read all open branches from file. Show compact tree summary (same format as Step 3) and one-sentence description of each open branch. State count of open and closed branches.

Step D2: Distillation questions

Ask up to 5 distillation questions to narrow open branches into single direction — batch into AskUserQuestion calls of up to 3 questions each (max 2 calls):

Start with these (adapt based on tree content):

1. "Which open branch best captures the core direction you want to pursue?" — list each open branch as lettered option. Note: if tree was saved and this branch does not already have ✅ status in file, it should be updated to resolved — chosen in distillation in tree file; do not re-save file here — spec file written in D3 will reflect accepted direction.
2. "Should any remaining open branches be combined with chosen direction, or are they separate concerns?"
3. "What is the single most important success criterion for this idea?" 4–5. Ask additional questions based on gaps in open threads section or unresolved tensions between branches

After questions, briefly restate distilled direction in 2–3 sentences — synthesis of what was just decided.

Step D3: Write spec

Build spec section by section, showing each section inline. Write nothing to disk until full draft assembled.

Write all 6 sections inline, then invoke a single AskUserQuestion for the full spec:

• a) Spec looks good — write to disk ★ recommended
• b) Revise [section name(s)] — [describe what to change]
• c) A section sparks a new thought — [add context]

On (b): revise named sections inline, re-present those sections, re-offer. Max 2 revisions per section. On (c): incorporate context, revise if needed, re-offer.

Sections:

Section 1 — Goal (1 paragraph: what problem this solves and for whom) Derive from distilled direction from D2. Reference open branches that fed into it.

Section 2 — Non-goals (explicit list) Derive from closed branches and open branches not chosen in D2.

Section 3 — Proposed design (distilled direction with enough detail to implement) Break into sub-points. Describe what, not how. If direction is merge of multiple open branches, name each part.

Section 4 — Open questions (unresolved decisions) Seed from "Open threads" section of tree. For each, note blocking vs non-blocking and recommended default if possible.

Section 5 — Success criteria (observable, testable outcomes) Include criterion identified in D2 question 3. Each criterion must be concrete enough to write pass/fail check.

Section 6 — Exploration notes (summary of closed branches and why) Draw from Pruning log in tree. Context for future readers — what was considered and rejected.

Gate: do not write to disk until all 6 sections drafted and individually approved.

Graduation checklist — verify before writing to disk:

• Goal (Section 1) is concrete and names who benefits
• Proposed design (Section 3) has at least 3 distinct sub-points
• Success criteria (Section 5) are observable/testable — not vague ("it works") but checkable ("running X produces Y")
• At least one non-goal stated (Section 2 not empty)

If any item fails, call AskUserQuestion with:

• a) Revise failing section(s) now — return to that section in D3 ★ recommended
• b) Proceed anyway — I accept spec may be underspecified

On (a): jump back to failing section in D3 (max 1 extra revision per section). On (b): proceed to write.

After all sections approved: write to .plans/blueprint/YYYY-MM-DD-<slug>.md (new file; use tree's slug with -spec suffix if writing alongside tree):

# <title>

**Date**: YYYY-MM-DD
**Status**: draft

## Goal
[Section 1]

## Non-goals
[Section 2]

## Proposed design
[Section 3]

## Open questions
[Section 4]

## Success criteria
[Section 5]

## Exploration notes
[Section 6]

Step D4: Suggest next step

After writing spec, suggest:

• Spec targets .claude/ config: /foundry:manage update <name> .plans/blueprint/<spec-file> or /foundry:manage create <type> <name> "description"
• Spec targets application code or mixed changes: /brainstorm breakdown .plans/blueprint/<spec-file> to generate action plan (action plan may emit /develop:feature and /develop:fix invocations — these require the develop plugin)

Action plan mode (Status: draft)

Step B1: Scan for blocking open questions

Read spec's "Open questions" section. For each question, determine whether blocking (no recommended option stated, answer genuinely unknown) or non-blocking (spec states recommended option or answer inferable).

For each blocking question: call AskUserQuestion — one at a time, in order. Non-blocking questions go into plan table footnote.

Step B2: Generate the action plan

Idempotency pre-check: before generating plan, call TaskList and scan for active /develop:feature tasks naming this spec's slug. If found, surface existing task to user and ask whether to re-generate plan (which will not re-dispatch — see Step B3) or skip; do not silently double-dispatch.

1. Parse spec into discrete action items from "Proposed design" and "Success criteria"
2. For each item, write ready-to-run invocation:
   • .claude/ config change → /foundry:manage create <type> <name> "description" or /foundry:manage update <name> <spec-file>
   • System install or shell setup → full shell command
   • Application code change → /develop:feature "<goal>" or /develop:fix "<symptom>" (requires develop plugin)
   • Documentation → /develop:feature "<doc goal>" (requires develop plugin)
   • Verification/testing → /develop:feature "<test goal>" (requires develop plugin) or manual check command
3. Output ordered task table:

Note: /develop:feature and /develop:fix require the develop plugin. If not installed, replace those commands with appropriate manual workflow.

## Action Plan: <spec title>

Spec: <file path>

| # | Task | Invocation |
|---|------|------------|
| 1 | [first action item] | `/develop:feature "<goal>"` |

### Non-blocking open questions (resolve during implementation)
- [list, or "None"]

Step B3: Post-plan prompt

Call AskUserQuestion tool — do NOT write options as plain text first. Map options directly into tool call arguments:

• question: "Plan ready. What next?"
• (a) label: Start task 1 now — description: proceed immediately with task 1 invocation (★ recommended)
• (b) label: Copy plan — description: output plan table as clean markdown block, then stop
• (c) label: Revise spec first — description: stop; revise spec and re-run /brainstorm breakdown <spec>

On (a) (requires develop plugin): before dispatching, verify no active /develop:feature task for this spec already exists in TaskList — call TaskList and scan for tasks naming the spec slug or referencing /develop:feature against same spec file; if found, surface existing task to user and skip dispatch (prevents double-dispatch on re-entry). Otherwise proceed immediately with invocation from task 1. On (b): output plan table as clean markdown block, then stop. On (c): stop and tell user to revise spec and re-run /brainstorm breakdown <spec>.

End with ## Confidence block per CLAUDE.md output standards.