| name | flow-code-brainstorm |
| description | Use when exploring requirements before planning. Pressure-tests ideas, generates approaches, and outputs a requirements doc for /flow-code:plan. |
| tier | 3 |
| user-invocable | false |
Flow brainstorm
Explore and pressure-test an idea before committing to a plan. Outputs a requirements doc that feeds directly into /flow-code:plan.
Pipeline auto-detection: If this skill is invoked as part of the /flow-code:go pipeline (detected by: epic already exists, or flow-code-run is the caller), ALWAYS use Auto mode — AI self-interview with zero human input. Do NOT use AskUserQuestion. The go pipeline has a zero-interaction contract.
IMPORTANT: This plugin uses .flow/ for ALL task tracking. Do NOT use markdown TODOs, plan files, TodoWrite, or other tracking methods. All task state must be read and written via flowctl.
CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Always use:
FLOWCTL="$HOME/.flow/bin/flowctl"
$FLOWCTL <command>
Pre-check: Local setup version
If .flow/meta.json exists and has setup_version, compare to plugin version:
SETUP_VER=$(jq -r '.setup_version // empty' .flow/meta.json 2>/dev/null)
PLUGIN_JSON="$HOME/.codex/plugin.json"
PLUGIN_VER=$(jq -r '.version' "$PLUGIN_JSON" 2>/dev/null || echo "unknown")
if [[ -n "$SETUP_VER" && "$PLUGIN_VER" != "unknown" ]]; then
[[ "$SETUP_VER" = "$PLUGIN_VER" ]] || echo "Plugin updated to v${PLUGIN_VER}. Run /flow-code:setup to refresh local scripts (current: v${SETUP_VER})."
fi
Continue regardless (non-blocking).
Role: product strategist, requirements explorer
Goal: pressure-test ideas before planning to avoid wasted implementation effort
Input
Full request: $ARGUMENTS
Accepts:
- Feature/bug description in natural language
- Empty: ask "What idea or problem should we brainstorm? Describe it in 1-5 sentences."
Examples:
/flow-code:brainstorm Add real-time collaboration to the editor/flow-code:brainstorm We keep getting auth token expiry bugs/flow-code:brainstorm migrate from REST to GraphQL
Phase 0: Complexity Assessment
Analyze the request and the codebase to gauge complexity:
FLOWCTL="$HOME/.flow/bin/flowctl"
Read relevant code, git log, and project structure to understand the scope.
Classify into one of three tiers:
Trivial (1-2 files, clear fix, well-understood change)
- Skip brainstorm entirely.
- Tell the user: "This looks straightforward — skip brainstorm and go directly to planning."
- Suggest:
Run /flow-code:plan <their request> and stop here.
Medium (clear feature, moderate scope)
- Run a quick brainstorm: ask only the 3 pressure-test questions (Phase 1), then jump to Phase 2 with 2 approaches.
Large (cross-cutting, vague requirements, multiple systems affected)
- Run the full brainstorm: all phases, 3 approaches.
Tell the user which tier you picked and why (one sentence).
Phase 1: Forcing Questions (with Pushback)
Ask questions one at a time via AskUserQuestion. After each answer, apply pushback — challenge vague/hypothetical responses.
Q1: Demand Reality
What's the strongest evidence this change is actually needed?
- Reject: "It would be nice" / "best practice says" / "users might want"
- Accept: Specific failure, measured waste, blocked workflow, production incident
- If answer is vague, reframe: "Let me restate what I think the core need is: [restate]. Is that right?"
Q2: Status Quo
How is this being handled RIGHT NOW without this change?
- Reject: "Nothing handles this" (if nobody works around it, pain isn't real)
- Accept: Specific workaround, manual steps, duct-tape solution
- If no workaround: "Who is suffering and how? If nobody, should we build this?"
Q3: Narrowest Wedge
What's the smallest version that delivers 80% of the value?
- Reject: "We need the full implementation"
- Accept: One function/file/config change that unblocks the core use case
- Push: "Can this ship in < 1 day? If not, can we cut more?"
Q4: Failure Pre-mortem
If this shipped and FAILED, what are the top 3 causes?
- Reject: Vague categories ("security issues", "performance")
- Accept: Specific scenarios ("token not refreshed after 1hr", "N+1 on list page")
After all 4 answers, summarize key insights in 2-3 bullets. Rate quality:
- All answers specific + evidence-backed → proceed
- Any answer still vague → flag as risk in requirements
Structured Deepening
After self-interview completes, apply 1-2 named reasoning methods to pressure-test the output:
Method Selection Guide
| Method | Best for | Prompt |
|---|
| Pre-mortem Analysis | Specs, plans, new features | "Assume this shipped and failed 6 months later. What are the 3 most likely causes?" |
| First Principles | Architecture, major refactors | "Strip all assumptions. What's the simplest possible solution from ground truth?" |
| Inversion | Risk assessment, refactoring | "How would you guarantee this fails? Now avoid those things." |
| Red Team | Security, APIs, public surfaces | "You're an attacker. How do you break this?" |
| Constraint Removal | Innovation, scope decisions | "Remove all constraints (time, tech, team). What changes? What stays the same?" |
| Stakeholder Mapping | Multi-user features | "Re-evaluate from each stakeholder's perspective. Who loses?" |
Auto-Selection Rules
- For spec/plan tasks → Pre-mortem (default)
- For architecture tasks → First Principles
- For refactoring tasks → Inversion
- For security-sensitive → Red Team
- For scope decisions → Constraint Removal
Execution
- Auto-select the most relevant method based on task type
- Apply the method's prompt to the current brainstorm output
- Append insights to requirements doc under "## Deepening Insights" section
- If insights reveal significant gaps, re-run self-interview for those specific areas
Phase 2: Approach Generation
Generate 2-3 concrete approaches based on the answers from Phase 1 and your codebase analysis.
For each approach, provide:
| Field | Format |
|---|
| Name | Short descriptive label |
| Summary | One sentence — what this approach does |
| Effort | S / M / L |
| Risk | Low / Med / High |
| Pros | 2-3 bullets |
| Cons | 2-3 bullets |
Present the approaches and ask the user (via AskUserQuestion):
Which approach do you prefer? (1/2/3, or "combine" to mix elements)
Phase 3: Requirements Output
Based on the chosen approach, write a requirements document:
SLUG=$(echo "$IDEA" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | head -c 40)
mkdir -p .flow/specs
Write to .flow/specs/${SLUG}-requirements.md with this format:
# Requirements: <Title>
## Problem
<1-2 sentences from pressure test answers>
## Users
<Who uses this, from Q1>
## Chosen Approach
<Name and summary of selected approach>
## Requirements
- [ ] <Requirement 1>
- [ ] <Requirement 2>
- [ ] <Requirement 3>
...
## Non-Goals
- <What this explicitly does NOT include>
## Constraints
- <Technical or business constraints identified during brainstorm>
## Open Questions
- <Anything unresolved that /flow-code:plan should address>
After writing the file, tell the user:
Requirements written to .flow/specs/<slug>-requirements.md
Next step: Run /flow-code:plan .flow/specs/<slug>-requirements.md
