/brainstorming

name: brainstorming
description: Designs new software features and multi-component changes for the current repo into implementation-ready BDD specs via autonomous codebase research, then commits the design for review (runs to completion without mid-design questions). Scope covers new features, greenfield design, and multi-component changes. Not for hardware/physical-system design, out-of-repo questions, single-file refactors, or known-root-cause bugs (those go to direct edits or systematic-debugging).
user-invocable: true
disable-model-invocation: true
allowed-tools: ["Read", "Write", "Glob", "Grep", "Agent", "Bash(git-agent:*)", "Bash(git:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/seed-checklists.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh:*)"]

Brainstorming Ideas Into Designs

Turn rough ideas into implementation-ready designs through structured codebase-grounded research. The full pipeline (parallel research sub-agents + evaluator) is calibrated for **open-ended multi-component problems**. Trivial work bypasses via the bail-out check below. This is substantial multi-phase work — **the recommended way to run it is wrapped in Claude Code's built-in `/goal`** (see below).

Recommended: run wrapped in `/goal`

Brainstorming does open-ended, multi-turn research. **Launch it under Claude Code's built-in `/goal`** (v2.1.139+) so a fresh evaluator drives it to completion across turns instead of stopping mid-pipeline:

/goal "Claude has narrated a successful design commit (with commit hash) and the evaluator's verdict is PASS" /superpowers:brainstorming "<problem>"

`/goal` is a **user-typed outer wrapper** (a skill cannot enable it for itself mid-run), and its evaluator judges only what Claude narrates in the transcript — phrase the condition against narrated output (the commit hash, the literal evaluator verdict line), never filesystem state. Full semantics, condition phrasing, and bail-out interaction: `../../skills/references/goal-wrapper.md`.

CRITICAL: Bail-Out Check (run before Initialization)

**Classify `$ARGUMENTS` into one of three buckets. Do NOT default to "proceed when in doubt" — that biases the agent single-direction toward over-engineering.**

**Bucket A — Strong trivial-scope signals (bail out: do NOT write design files, do NOT spawn evaluator):**

• Names a single file or single-line change ("change X to Y", "rename foo to bar", "log level to DEBUG")
• Mechanical refactor ("extract helper", "reorder imports", "update deprecated API call")
• Bug with a named root cause ("cookie domain is wrong, fix it") — route to `/superpowers:systematic-debugging`
• One-shot script / config tweak / dependency bump
• User explicitly said "just patch" / "no plan" / "terse fix"

**Bucket B — Strong open-ended signals (proceed to Initialization):**

• Multi-component design naming explicit subsystems (e.g., "design a notification system supporting email + SMS + push")
• Ambiguous requirements that the user expects to be clarified through dialogue
• Greenfield feature with explicit "design first" / "brainstorm" framing

**Bucket C — Ambiguous (default to Bucket B, do NOT pause to ask):**

• `$ARGUMENTS` is brief and could go either way (e.g., a single sentence with no scope cues)
• Mixes trivial signals with open-ended language
• Names an outcome but not a scope (e.g., "improve performance", "make it faster")

For Bucket A, output the bail-out response below and stop. For Bucket B (including all Bucket C cases), proceed to Initialization. The `--force` token is preserved for backward compatibility and now no-ops (the bail-out is per-invocation); a later scope pivot is absorbed by Phase 1's mid-stream pivot handling.

**Bail-out response (Bucket A, output verbatim, then proceed with direct edit OR hand off):**

> Detected trivial-scope work. Skipping the brainstorming pipeline (calibrated for open-ended multi-component problems). To force the full pipeline, re-invoke as `/superpowers:brainstorming --force "<task>"`.

Initialization

1. **Capture the problem statement**: Reduce `$ARGUMENTS` to a single declarative sentence under ~150 chars — the problem to brainstorm, in the user's own framing. Do NOT paraphrase, summarize away constraints, or introduce vocabulary the user did not use. Strip a leading `--force` token if present (already consumed by the bail-out check). If `$ARGUMENTS` is empty, use the open problem the user just described in conversation. 2. **Read project context**: Read `CLAUDE.md` and `README.md` to understand project constraints. Then consult the docs index — run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind design --status active` and `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --status expired`. Treat any `expired:` design's conclusions as non-authoritative — create a fresh design rather than extending an expired one. If an `active` design on the same topic already exists, surface it in the Phase 1 sprint contract and either extend it (preferred) or supersede it via the Phase 3 wrap-up. Then consult memory: run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active` and Read the 3-5 topically-relevant rows' files before Phase 1 exploration. 3. **Proceed to Phase 1** in the same turn.

Core Principles

1. **Context First**: Explore codebase before asking questions 2. **YAGNI Ruthlessly**: Only include what's explicitly needed 3. **Test-First Mindset**: Always include BDD specifications -- load `superpowers:behavior-driven-development` skill 4. **Incremental Validation**: Validate each phase exit before proceeding 5. **Context Reset by Design**: Research and QA happen in fresh sub-agent contexts (Anthropic harness-design principle 1) — the main agent only synthesizes.

Phase 1: Scope Alignment

Explore codebase, lock the approach inline, proceed to Phase 2 in the same iteration.

**Actions**:

1. **Explore codebase**: Use Read/Grep/Glob to find relevant files, patterns, docs, recent commit