brainstorm

<objective>

Turn unformed idea into branching exploration tree, then distill into spec. Idea mode = pure divergence — grow tree of directions, deepen promising branches, prune others, save result. No premature convergence. Run breakdown on tree when ready: asks distillation questions, writes spec section-by-section.

NOT for implementation or code-gen — see develop plugin (requires develop plugin).

HARD GATE: Do NOT take any implementation action — writing code, creating files, scaffolding — until user approves design (spec). Applies regardless of perceived simplicity. Simple idea can have short tree and spec, but process never skipped.

</objective>

<inputs>

• $ARGUMENTS: required — fuzzy idea, goal, or feature request in any form; one sentence enough

• --tight — reduced-ceremony mode: see per-step caps below — 5/5/1 bounds vs default 10/10/2. Good for well-scoped ideas where problem already understood.

• --deep — extended-ceremony mode: 15/15/3 bounds vs default 10/10/2. Good for genuinely ambiguous problems where more exploration valuable.

• Default (no flag): behaviour unchanged — 10/10/2 bounds.

• --type <type> — optional type hint for idea mode. One of: application (app/service with users/endpoints), workflow (automation, pipeline, script), utility (helper library, tool, CLI), config (.claude/ agents/skills/rules), research (investigation, survey, experiment design). Affects Step 1 scan patterns and Step 2 question framing. Omit if unsure — skill works without it.

• breakdown <tree-or-spec-file> — breakdown mode: read already-saved tree (Status: tree) or spec (Status: draft). For tree: ask distillation questions, write spec section-by-section. For spec: scan for blocking open questions then generate ordered action plan. Skips Steps 1–6 entirely.

</inputs>

<workflow>

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): \--<token>\. Supported: \--tight\, \--deep\, \--type\. then invoke AskUserQuestion — (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"

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):

```bash

_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-defi