Menu
Explore ideas and design before committing to a spec. Invoke with /flow-brainstorm when requirements are still fuzzy.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | flow-brainstorm |
| description | Explore ideas and design before committing to a spec. Invoke with /flow-brainstorm when requirements are still fuzzy. |
| disable-model-invocation | true |
| metadata | {"flow":{"command":"/flow-brainstorm"}} |
Triggered by: /flow-brainstorm
Explore intent, options, and design before formal requirements. No production code. No implementation plan.
Use when the idea is fuzzy, large, or needs decomposing. When direction is clear and approved, hand off to /flow-patch when scope is small and bounded; /flow-spec when multi-step or multi-concern.
Use /flow-brainstorm | Skip to |
|---|---|
| "I'm not sure how to build this" | — |
| Multiple valid approaches | — |
| Large initiative needing decomposition | — |
| Fuzzy but resolves to small bounded change | /flow-patch (after lightweight brainstorm) |
| Scope already clear, multi-step feature | /flow-spec |
| Single bounded fix | /flow-patch |
| Bug or failing test | /flow-debug |
Do not write production code, scaffold features, or create an implementation plan in this skill.
Read relevant files, docs, recent commits. Understand existing patterns and constraints.
Ask until you understand purpose, constraints, and success criteria at a directional level — not every spec detail.
Prefer multiple-choice when possible. One question per message.
Multiple-choice format: Label options A/B/C/D (and E if needed). Mark exactly one option with (Recommended) based on codebase context, stated constraints, and MVP scope. Add one sentence after the options explaining why you recommend it — do not hide the recommendation only in prose after the list.
Example:
How should draft vs. published work in the MVP?
A) Always live — saving makes chapters visible immediately
B) Fic-level publish — whole fic hidden until author publishes
C) **(Recommended)** Chapter-level publish — per-chapter draft/publish, plus "publish all"
D) Writer-only — no public reading yet
Recommend C: matches your writer-first goal and allows flexible publish workflow without fic-level lock-in.
If the user already stated a preference, skip recommending a different option — confirm their choice instead.
If the request spans multiple independent subsystems, help decompose: what are the pieces, how do they relate, what order?
After clarifying purpose and constraints, evaluate scope using the same criteria as /flow-patch:
Route to /flow-patch | Route to /flow-spec |
|---|---|
| ≤3 files, one concern | >3 files or multiple concerns |
| Clear success criteria | Multi-step / multi-subsystem |
| Design direction settled | Needs formal plan with many tasks |
/flow-patch — skip the brainstorm brief; the micro-spec in patch replaces it.Re-assess scope before handoff. If scope grew during brainstorm, recommend spec on the gate; if small and bounded, recommend patch.
Present 2–3 options with trade-offs. Mark one (Recommended) and explain why in one sentence.
Small-scope exception: When routing to /flow-patch and only one sensible approach exists, skip artificial alternatives — present one recommended approach and get user approval.
Scale to complexity — a few sentences for simple topics, more for nuanced ones. Cover as needed:
Get user approval on the design direction. Revise until aligned.
Read and follow flow-shared/references/session-gate.md (resolve via path resolver in flow/SKILL.md).
Before saving the brief or updating docs/flow/STATE.md: if STATE shows active unrelated work, send the session gate message and stop. Do not save the brief or write STATE in the same turn as the gate.
After gate passes (same topic, empty STATE, or user confirmed worktree for new topic): proceed to §6.
Save to:
docs/flow/brainstorms/YYYY-MM-DD-<topic>.md
Use the Next Step that matches scope assessment — pick one, not both:
Small bounded scope → patch:
# [Topic] — Brainstorm
## Problem / Goal
## Constraints
## Decisions Made
<!-- Each row: question → chosen answer -->
## Approaches Considered
## Recommended Direction
## Design Summary
## Out of Scope (for now)
## Open Questions
## Next Step
→ Handoff gate: continue to **patch** (recommended) or spec — agent sends §7 menu after save; use this brief for the micro-spec if patch
Multi-step or multi-concern → spec:
# [Topic] — Brainstorm
## Problem / Goal
## Constraints
## Decisions Made
<!-- Each row: question → chosen answer -->
## Approaches Considered
## Recommended Direction
## Design Summary
## Out of Scope (for now)
## Open Questions
## Next Step
→ Handoff gate: continue to **spec** (recommended) or patch — agent sends §7 menu after save; lock requirements and plan if spec
Self-review the brief before saving: no contradictions, open questions resolved or listed explicitly.
Update docs/flow/STATE.md: phase: brainstorm, add brief path.
After the brief is saved and STATE.md is updated, send only the handoff gate below — do not combine with micro-spec, spec writing, branch/workspace ask, session gate, STATE updates, or code.
Small bounded scope (patch criteria met):
Brainstorm saved to `docs/flow/brainstorms/...`.
What's next?
1. **(Recommended)** Continue to patch — I'll write the micro-spec from this brief
2. Continue to spec instead — full spec from this brief
3. Stop — no patch or spec yet
Multi-step or multi-concern (spec criteria met):
Brainstorm saved to `docs/flow/brainstorms/...`.
What's next?
1. **(Recommended)** Continue to spec — I'll write the spec from this brief
2. Continue to patch instead — smaller change with a micro-spec
3. Stop — no spec or patch yet
User-facing handoff menus — no skill file paths (SKILL.md), (no code …), inline TDD, or internal gate names in the fenced templates above.
Orchestrator after pick 1 or 2: read the matching skill via path resolver in flow/SKILL.md; no production code until downstream gates (micro-spec, design, spec, branch); do not tell the user to invoke /flow-patch or /flow-spec manually.
Stop until the user picks 1, 2, or 3. Option 3 ends brainstorm handoff. Continuation happens in this session after they pick.
"Yes" / "approve" / "proceed" / "1" after this gate counts as that handoff pick only — a single-word reply without a number means option 1 (recommended). Not micro-spec approval, spec approval, plan writing, branch/workspace confirmation, or code.
| User picks | You do |
|---|---|
| 1 (recommended path) | Read the matching skill via path resolver in flow/SKILL.md (flow-patch/SKILL.md or flow-spec/SKILL.md). Same-topic handoff from this brief → session gate does not re-fire. Follow that skill from the top — micro-spec and spec gates still apply; brainstorm design approval does not skip them. |
| 2 (alternate path) | Read the other skill (flow-spec if they chose patch→spec, or flow-patch if spec→patch). Same rules as above. |
| 3 | Stop. Do not start patch or spec work. |
At handoff, mark (Recommended) on option 1 for the path that matches scope assessment (patch when small/bounded; spec when multi-step or multi-concern).
(Recommended) on multiple-choice optionsdocs/flow/patches//flow-patch or /flow-spec instead of the handoff gate — use §7 numbered menu; continue in-session after they pickShared prompts and references for flow-* skills. Not invoked directly.
Execute an approved plan with subagents, TDD, and two-stage review. Invoke with /flow-execute to resume or when plan exists without an active spec session.
Router for the flow development workflow. Invoke with /flow to triage and suggest the right /flow-* command.
Create an approved spec and self-reviewed implementation plan. Invoke with /flow-spec before multi-step work.
Small bounded changes with micro-spec, inline TDD, and per-task review. Invoke with /flow-patch.
Final verification gate before claiming work complete. Invoke with /flow-verify.