/brainstorm

name: brainstorm
description: 'Iterative brainstorming skill for turning fuzzy ideas into approved tree documents. Diverges into branches, deepens and prunes them over many rounds, saves a tree doc. Run breakdown on the tree to distill it into a spec via guided questions. SKIP: a content outline to co-create, or one already approved and awaiting finished content (use foundry:create — create co-creates the outline, foundry:creator writes the finished artifact; brainstorm is for idea generation before an outline exists); a code-level implementation plan derived from an existing spec (use develop:plan (requires `develop` plugin)).'
argument-hint: <fuzzy idea or feature goal> [--tight|--deep] [--type <type>] [--keep "<items>"] | breakdown <tree-or-spec-file>
disable-model-invocation: true
allowed-tools: Read, Write, Bash, Grep, Agent, TaskCreate, TaskUpdate, TaskList, AskUserQuestion
effort: medium

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

<compaction>

• Key boundary 1: end of Step 4 (tree doc saved to .plans/blueprint/), before Step 5 tree review.
• Preserve at boundary 1: tree file path (.plans/blueprint/YYYY-MM-DD-<slug>.md), sidecar path (if viewer active), report run dir (.reports/brainstorm/<ts>/).
• Terminal path: Step 6 option (a) approval — suggest breakdown and stop.

</compaction>

<workflow>

**Task hygiene** — task tools may be deferred; load before first use: `ToolSearch(query="select:TaskList,TaskCreate,TaskUpdate,TaskGet", max_results=4)`. Call `TaskList` first and triage each task it returns: `completed` if work clearly done, `deleted` if orphaned, keep `in_progress` only if genuinely continuing. Never spend a turn on bookkeeping alone — every `TaskCreate`/`TaskUpdate` ships in the same response as the next substantive tool call; one exception, `TaskUpdate(completed)` immediately before a long output block (`rules/task-lifecycle.md`).

**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 0: Parse flags

PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name foundry) || exit $?; export PLUGIN_ROOT
export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
python "$PLUGIN_ROOT/bin/parse-skill-flags.py" --flags tight,deep --value-flags type --keep-state brainstorm-state -- "$ARGUMENTS" >/dev/null  # timeout: 5000 — no eval; brainstorm-state-<flag>-${CSID} sentinels + keep-items, clears stale contract
IFS= read -r ARGUMENTS < "${TMPDIR:-/tmp}/brainstorm-state-clean-args-${CSID}" 2>/dev/null || ARGUMENTS=""
REPORT_DIR=".reports/brainstorm/$(date -u +%Y-%m-%dT%H-%M-%SZ)"
echo "$REPORT_DIR" > "${TMPDIR:-/tmp}/brainstorm-state-report-dir-${CSID}"
echo "report dir: $REPORT_DIR/"

**Report run dir**: every `.reports/brainstorm/<ts>/` artifact below (breakdown mode included) uses the one `<ts>` persisted above for this invocation — rounds within a run replace their copy; a later run never overwrites an earlier run's files. Before a later Bash block uses the report directory, re-read it with `IFS= read -r REPORT_DIR < "${TMPDIR:-/tmp}/brainstorm-state-report-dir-${CSID}"`; if missing or empty, stop rather than derive a new timestamp, unless Step 4 recovers the existing run directory from this run's branch report as described below.

Step 1: Context scan

**Unsupported flag check** — after all supported flags extracted (`--tight`, `--deep`, `--type`, `--keep`), scan `$ARGUMENTS` for remaining `--<token>` tokens. If found: invoke `AskUserQuestion` with question text `` ! Unknown flag(s): `--<token>`. Supported: `--tight`, `--deep`, `--type`, `--keep`. `` — (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
• Ident