/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.
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, Skill
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).
• Terminal path: Step 6 option (a) approval — suggest breakdown and stop.

</compaction>

<workflow>

**Task hygiene**: load and follow the protocol below.

# loads: compaction-contract.md
# audit-skip: resilience-replication
python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_foundry}/bin/load_shared_doc.py" foundry skills/_shared task-hygiene.md  # timeout: 5000

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

export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_foundry}/bin/extract-keep-flag.py" brainstorm-state "$ARGUMENTS"  # timeout: 5000 — parses --keep, clears stale contract
eval "$(python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_foundry}/bin/parse-skill-flags.py" --flags tight,deep --value-flags type "$ARGUMENTS")"  # timeout: 5000
ARGUMENTS="$CLEAN_ARGS"

Step 1: Context scan

**Unsupported flag check** — after all supported flags extracted (`--tight`, `--deep`, `--type`, `--keep`), scan `$ARGUMENTS` for remaining `--<token>` tokens. If found: print `` ! Unknown flag(s): `--<token>`. Supported: `--tight`, `--deep`, `--type`, `--keep`. `` 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 follow established patterns unless idea explicitly requires changing them. Where existing code has problems affecting work (e.g., file grown too large, unclear boundaries), note as open threads — do not propose unrelated refactoring, but flag targeted improvements serving current goal.

Goal: understand constraints so questions targeted, not generic. If idea already exists or 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