Claude-Code-Workflow/.claude/commands/workflow/brainstorm-with-file.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
brainstorm-with-file	Interactive brainstorming with multi-CLI collaboration, idea expansion, and documented thought evolution	[-y|--yes] [-c|--continue] [-m|--mode creative|structured] "idea or topic"	TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)

Auto Mode

When --yes or -y: Auto-confirm decisions, use recommended roles, balanced exploration mode.

Workflow Brainstorm Command

Quick Start

# Basic usage
/workflow:brainstorm-with-file "如何重新设计用户通知系统"

# With options
/workflow:brainstorm-with-file --continue "通知系统"              # Continue existing
/workflow:brainstorm-with-file -y -m creative "创新的AI辅助功能"   # Creative auto mode
/workflow:brainstorm-with-file -m structured "优化缓存策略"       # Goal-oriented mode

Context Source: cli-explore-agent + Multi-CLI perspectives (Gemini/Codex/Claude or Professional Roles) Output Directory: .workflow/.brainstorm/{session-id}/ Core Innovation: Diverge-Converge cycles with documented thought evolution

Output Artifacts

Phase	Artifact	Description
1	brainstorm.md	Complete thought evolution timeline (initialized)
1	Session variables	Dimensions, roles, exploration vectors
2	exploration-codebase.json	Codebase context from cli-explore-agent
2	perspectives.json	Multi-CLI perspective findings (creative/pragmatic/systematic)
2	Updated brainstorm.md	Round 2 multi-perspective exploration
3	ideas/{idea-slug}.md	Deep-dive analysis for selected ideas
3	Updated brainstorm.md	Round 3-6 refinement cycles
4	synthesis.json	Final synthesis with top ideas, recommendations
4	Final brainstorm.md	Complete thought evolution with conclusions

Output Structure

.workflow/.brainstorm/BS-{slug}-{date}/
├── brainstorm.md                  # ⭐ Complete thought evolution timeline
├── exploration-codebase.json      # Phase 2: Codebase context
├── perspectives.json              # Phase 2: Multi-CLI findings
├── synthesis.json                 # Phase 4: Final synthesis
└── ideas/                         # Phase 3: Individual idea deep-dives
    ├── idea-1.md
    ├── idea-2.md
    └── merged-idea-1.md

┌─────────────────────────────────────────────────────────────────────────┐
│                    INTERACTIVE BRAINSTORMING WORKFLOW                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Phase 1: Seed Understanding                                             │
│     ├─ Parse initial idea/topic                                          │
│     ├─ Identify dimensions (technical, UX, business, etc.)               │
│     ├─ Select roles (professional or simple perspectives)                │
│     ├─ Initial scoping questions                                         │
│     ├─ Expand into exploration vectors                                   │
│     └─ Initialize brainstorm.md                                          │
│                                                                          │
│  Phase 2: Divergent Exploration                                          │
│     ├─ cli-explore-agent: Codebase context (FIRST)                       │
│     ├─ Multi-CLI Perspectives (AFTER exploration)                        │
│     │   ├─ Creative (Gemini): Innovation, cross-domain                   │
│     │   ├─ Pragmatic (Codex): Implementation, feasibility                │
│     │   └─ Systematic (Claude): Architecture, structure                  │
│     └─ Aggregate diverse viewpoints                                      │
│                                                                          │
│  Phase 3: Interactive Refinement (Multi-Round)                           │
│     ├─ Present multi-perspective findings                                │
│     ├─ User selects promising directions                                 │
│     ├─ Actions: Deep dive | Generate more | Challenge | Merge            │
│     ├─ Update brainstorm.md with evolution                               │
│     └─ Repeat diverge-converge cycles (max 6 rounds)                     │
│                                                                          │
│  Phase 4: Convergence & Crystallization                                  │
│     ├─ Synthesize best ideas                                             │
│     ├─ Resolve conflicts between perspectives                            │
│     ├─ Generate actionable conclusions                                   │
│     ├─ Offer next steps (plan/issue/analyze/export)                      │
│     └─ Final brainstorm.md update                                        │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Implementation

Session Initialization

1. Extract idea/topic from $ARGUMENTS

2. Generate session ID: BS-{slug}-{date} (slug: lowercase, alphanumeric + Chinese, max 40 chars; date: YYYY-MM-DD UTC+8)

3. Define session folder: .workflow/.brainstorm/{session-id}

4. Parse command options:

   • -c or --continue for session continuation
   • -m or --mode for brainstorm mode (creative/structured/balanced)
   • -y or --yes for auto-approval mode

5. Auto-detect mode: If session folder + brainstorm.md exist → continue mode

6. Create directory structure: {session-folder}/ideas/

7. Create Progress Tracking (TodoWrite — MANDATORY):

   TodoWrite([
     { id: "phase-1", title: "Phase 1: Seed Understanding", status: "in_progress" },
     { id: "phase-2", title: "Phase 2: Divergent Exploration", status: "pending" },
     { id: "phase-3", title: "Phase 3: Interactive Refinement", status: "pending" },
     { id: "phase-4", title: "Phase 4: Convergence & Crystallization", status: "pending" },
     { id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
   ])
   

   • Update status to "in_progress" when entering each phase, "completed" when done
   • next-step is a terminal gate — workflow is NOT complete until this todo is "completed"

Session Variables: sessionId, sessionFolder, brainstormMode (creative|structured|balanced), autoMode (boolean), mode (new|continue)

Phase 1: Seed Understanding

1. Parse Seed & Identify Dimensions

   • Match topic keywords against Brainstorm Dimensions table
   • Default dimensions based on brainstormMode if no match

2. Role Selection

   • Recommend roles based on topic keywords (see Role Selection tables)
   • Professional roles: system-architect, product-manager, ui-designer, ux-expert, data-architect, test-strategist, subject-matter-expert, product-owner, scrum-master
   • Simple perspectives (fallback): creative/pragmatic/systematic
   • Auto mode: Select top 3 recommended professional roles
   • Manual mode: AskUserQuestion with recommended roles + "Use simple perspectives" option

3. Initial Scoping Questions (if new session + not auto mode)

   • Direction: Multi-select from directions generated by detected dimensions
   • Depth: Single-select from quick/balanced/deep (15-20min / 30-60min / 1-2hr)
   • Constraints: Multi-select from existing architecture, time, resources, or no constraints

4. Expand Seed into Exploration Vectors

Bash({
  command: `ccw cli -p "
Given the initial idea: '${idea_or_topic}'
User focus areas: ${userFocusAreas.join(', ')}
Constraints: ${constraints.join(', ')}

Generate 5-7 exploration vectors (questions/directions) to expand this idea:
1. Core question: What is the fundamental problem/opportunity?
2. User perspective: Who benefits and how?
3. Technical angle: What enables this technically?
4. Alternative approaches: What other ways could this be solved?
5. Challenges: What could go wrong or block success?
6. Innovation angle: What would make this 10x better?
7. Integration: How does this fit with existing systems/processes?

Output as structured exploration vectors for multi-perspective analysis.
" --tool gemini --mode analysis --model gemini-2.5-flash`,
  run_in_background: false
})

5. Initialize brainstorm.md with session metadata, initial context (user focus, depth, constraints), seed expansion (original idea + exploration vectors), empty thought evolution timeline sections

TodoWrite: Update phase-1 → "completed", phase-2 → "in_progress"

Phase 2: Divergent Exploration

1. Primary Codebase Exploration via cli-explore-agent (⚠️ FIRST)

Agent({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  description: `Explore codebase for brainstorm: ${topicSlug}`,
  prompt: `
## Brainstorm Context
Topic: ${idea_or_topic}
Dimensions: ${dimensions.join(', ')}
Mode: ${brainstormMode}
Session: ${sessionFolder}

## MANDATORY FIRST STEPS
1. Run: ccw tool exec get_modules_by_depth '{}'
2. Search for code related to topic keywords
3. Read: .workflow/project-tech.json (if exists)

## Exploration Focus
- Identify existing implementations related to the topic
- Find patterns that could inspire solutions
- Map current architecture constraints
- Locate integration points

## Output
Write findings to: ${sessionFolder}/exploration-codebase.json

Schema:
{
  "relevant_files": [{"path": "...", "relevance": "high|medium|low", "rationale": "..."}],
  "existing_patterns": [],
  "architecture_constraints": [],
  "integration_points": [],
  "inspiration_sources": [],
  "_metadata": { "exploration_type": "brainstorm-codebase", "timestamp": "..." }
}
`
})

2. Multi-CLI Perspective Analysis (⚠️ AFTER exploration)

Build shared context from exploration results:

const explorationContext = `
PRIOR EXPLORATION CONTEXT (from cli-explore-agent):
- Key files: ${explorationResults.relevant_files.slice(0,5).map(f => f.path).join(', ')}
- Existing patterns: ${explorationResults.existing_patterns.slice(0,3).join(', ')}
- Architecture constraints: ${explorationResults.architecture_constraints.slice(0,3).join(', ')}
- Integration points: ${explorationResults.integration_points.slice(0,3).join(', ')}`

Launch 3 parallel CLI calls (run_in_background: true each), one per perspective:

Perspective	Tool	PURPOSE	Key TASK bullets	EXPECTED	CONSTRAINTS
Creative	gemini	Generate innovative ideas	Challenge assumptions, cross-domain inspiration, moonshot + practical ideas	5+ creative ideas with novelty/impact ratings	structured mode: keep feasible
Pragmatic	codex	Implementation reality	Evaluate feasibility, estimate complexity, identify blockers, incremental approach	3-5 practical approaches with effort/risk ratings	Current tech stack
Systematic	claude	Architectural thinking	Decompose problems, identify patterns, map dependencies, scalability	Problem decomposition, 2-3 approaches with tradeoffs	Existing architecture

// Each perspective uses this prompt structure (launch all 3 in parallel):
Bash({
  command: `ccw cli -p "
PURPOSE: ${perspective} brainstorming for '${idea_or_topic}' - ${purposeFocus}
Success: ${expected}

${explorationContext}

TASK:
• Build on explored ${contextType} - how to ${actionVerb}?
${perspectiveSpecificBullets}

MODE: analysis
CONTEXT: @**/* | Topic: ${idea_or_topic}
EXPECTED: ${expected}
CONSTRAINTS: ${constraints}
" --tool ${tool} --mode analysis`,
  run_in_background: true
})
// ⚠️ STOP POINT: Wait for hook callback to receive all results before continuing

3. Aggregate Multi-Perspective Findings

   • Convergent themes (all agree), conflicting views (need resolution), unique contributions
   • Write to perspectives.json

4. Update brainstorm.md with Round 2 multi-perspective exploration and synthesis

Phase 3: Interactive Refinement

Guideline: Delegate complex tasks to agents (cli-explore-agent, code-developer, universal-executor) or CLI calls. Avoid direct analysis/execution in main process.

1. Present Current State: Extract top ideas from perspectives.json with title, source, description, novelty/feasibility ratings

2. Gather User Direction (AskUserQuestion)

   • Q1: Which ideas to explore (multi-select from top ideas)
   • Q2: Next step (single-select):
     • 深入探索: Deep dive on selected ideas
     • 继续发散: Generate more ideas
     • 挑战验证: Devil's advocate challenge
     • 合并综合: Merge multiple ideas
     • 准备收敛: Begin convergence (exit loop)

3. Execute User-Selected Action

Action	Tool	Output	Key Tasks
Deep Dive	Gemini CLI	ideas/{slug}.md	Elaborate concept, requirements, challenges, POC approach, metrics, dependencies
Generate More	Selected CLI	Updated perspectives.json	New angles from unexplored vectors
Challenge	Codex CLI	Challenge results	3 objections per idea, challenge assumptions, failure scenarios, survivability (1-5)
Merge	Gemini CLI	ideas/merged-{slug}.md	Complementary elements, resolve contradictions, unified concept

Deep Dive CLI Call:

Bash({
  command: `ccw cli -p "
PURPOSE: Deep dive analysis on idea '${idea.title}'
Success: Comprehensive understanding with actionable next steps

TASK:
• Elaborate the core concept in detail
• Identify implementation requirements
• List potential challenges and mitigations
• Suggest proof-of-concept approach
• Define success metrics
• Map related/dependent features

MODE: analysis
CONTEXT: @**/*
Original idea: ${idea.description}
Source perspective: ${idea.source}

EXPECTED: Detailed concept, technical requirements, risk matrix, MVP definition, success criteria, recommendation (pursue/pivot/park)
CONSTRAINTS: Focus on actionability
" --tool gemini --mode analysis`,
  run_in_background: false
})

Devil's Advocate CLI Call:

Bash({
  command: `ccw cli -p "
PURPOSE: Devil's advocate - rigorously challenge these brainstorm ideas
Success: Uncover hidden weaknesses and strengthen viable ideas

IDEAS TO CHALLENGE:
${ideas.map((idea, i) => `${i+1}. ${idea.title}: ${idea.brief}`).join('\n')}

TASK:
• For each idea, identify 3 strongest objections
• Challenge core assumptions
• Identify scenarios where this fails
• Consider competitive/alternative solutions
• Rate survivability after challenge (1-5)

MODE: analysis
EXPECTED: Per-idea challenge report, critical weaknesses, survivability ratings, modified/strengthened versions
CONSTRAINTS: Be genuinely critical, not just contrarian
" --tool codex --mode analysis`,
  run_in_background: false
})

Merge Ideas CLI Call:

Bash({
  command: `ccw cli -p "
PURPOSE: Synthesize multiple ideas into unified concept
Success: Coherent merged idea that captures best elements

IDEAS TO MERGE:
${selectedIdeas.map((idea, i) => `
${i+1}. ${idea.title} (${idea.source})
   ${idea.description}
   Strengths: ${idea.strengths.join(', ')}
`).join('\n')}

TASK:
• Identify complementary elements
• Resolve contradictions
• Create unified concept preserving key strengths
• Assess viability of merged idea

MODE: analysis
EXPECTED: Merged concept, elements from each source, contradictions resolved, implementation considerations
CONSTRAINTS: Don't force incompatible ideas together
" --tool gemini --mode analysis`,
  run_in_background: false
})

4. Update brainstorm.md with Round N findings
5. Repeat or Converge: Continue loop (max 6 rounds) or exit to Phase 4

TodoWrite: Update phase-2 → "completed" (after first round enters Phase 3), phase-3 → "in_progress" TodoWrite (on exit loop): Update phase-3 → "completed", phase-4 → "in_progress"

Phase 4: Convergence & Crystallization

1. Generate Final Synthesis → Write to synthesis.json
   • Top ideas: Filter active, sort by score, top 5 with title, description, source_perspective, score, novelty, feasibility, strengths, challenges, next_steps
   • Parked ideas: With reason and future trigger
   • Key insights: Process discoveries, challenged assumptions, unexpected connections
   • Recommendations: Primary, alternatives, not recommended
   • Follow-up: Implementation/research/validation summaries

synthesis.json Schema: session_id, topic, completed (timestamp), total_rounds, top_ideas[], parked_ideas[], key_insights[], recommendations (primary/alternatives/not_recommended), follow_up[]

2. Final brainstorm.md Update: Executive summary, top ideas ranked, primary recommendation with rationale, alternative approaches, parked ideas, key insights, session statistics (rounds, ideas generated/survived, duration)

3. MANDATORY GATE: Next Step Selection — workflow MUST NOT end without executing this step.

   TodoWrite: Update phase-4 → "completed", next-step → "in_progress"

   CRITICAL: This AskUserQuestion is a terminal gate. The workflow is INCOMPLETE if this question is not asked. After displaying synthesis (step 2), you MUST immediately proceed here.

   Call AskUserQuestion (single-select, header: "Next Step"):

   • 创建实施计划 (Recommended if top idea has high feasibility): "基于最佳创意启动 workflow-plan 制定实施计划"
   • 创建Issue: "将 Top 3 创意转化为 issue 进行跟踪管理"
   • 深入分析: "对最佳创意启动 analyze-with-file 深入技术分析"
   • 完成: "头脑风暴已足够，无需进一步操作"

   Handle user selection:

   "创建实施计划" → MUST invoke Skill tool:

   1. Build taskDescription from top idea in synthesis.json (title + description + next_steps)
   2. Assemble context: ## Prior Brainstorm ({sessionId}) + summary + top idea details + key insights (up to 5)
   3. Invoke Skill tool immediately:

      Skill({ skill: "workflow-plan", args: `${taskDescription}\n\n${contextLines}` })
      

      If Skill invocation is omitted, the workflow is BROKEN.
   4. After Skill invocation, brainstorm-with-file is complete

   "创建Issue" → Convert top ideas to issues:

   1. For each idea in synthesis.top_ideas (top 3):
      • Build issue JSON: {title: idea.title, context: idea.description + '\n' + idea.next_steps.join('\n'), priority: idea.score >= 8 ? 2 : 3, source: 'brainstorm', labels: dimensions}
      • Create via: Skill({ skill: "issue:from-brainstorm", args: "${sessionFolder}/synthesis.json" })
   2. Display created issue IDs

   "深入分析" → Launch analysis on top idea:

   1. Build analysis topic from top idea title + description
   2. Invoke Skill tool immediately:

      Skill({ skill: "workflow:analyze-with-file", args: `${topIdea.title}: ${topIdea.description}` })
      

   "完成" → No further action needed.

   TodoWrite: Update next-step → "completed" after user selection is handled

Configuration

Brainstorm Dimensions

Dimension	Keywords
technical	技术, technical, implementation, code, 实现, architecture
ux	用户, user, experience, UX, UI, 体验, interaction
business	业务, business, value, ROI, 价值, market
innovation	创新, innovation, novel, creative, 新颖
feasibility	可行, feasible, practical, realistic, 实际
scalability	扩展, scale, growth, performance, 性能
security	安全, security, risk, protection, 风险

Role Selection

Professional Roles:

Role	CLI Tool	Focus Area	Keywords
system-architect	Claude	Architecture, patterns	架构, architecture, system, 系统, design pattern
product-manager	Gemini	Business value, roadmap	产品, product, feature, 功能, roadmap
ui-designer	Gemini	Visual design, interaction	UI, 界面, interface, visual, 视觉
ux-expert	Codex	User research, usability	UX, 体验, experience, user, 用户
data-architect	Claude	Data modeling, storage	数据, data, database, 存储, storage
test-strategist	Codex	Quality, testing	测试, test, quality, 质量, QA
subject-matter-expert	Gemini	Domain knowledge	领域, domain, industry, 行业, expert
product-owner	Codex	Priority, scope	优先, priority, scope, 范围, backlog
scrum-master	Gemini	Process, collaboration	敏捷, agile, scrum, sprint, 迭代

Simple Perspectives (fallback):

Perspective	CLI Tool	Focus
creative	Gemini	Innovation, cross-domain
pragmatic	Codex	Implementation, feasibility
systematic	Claude	Architecture, structure

Selection Strategy: Auto mode → top 3 professional roles | Manual mode → recommended roles + "Use simple perspectives" option | Continue mode → roles from previous session

Error Handling

Error	Resolution
cli-explore-agent fails	Continue with empty exploration context
CLI timeout	Retry with shorter prompt, or skip perspective
No good ideas	Reframe problem, adjust constraints, try new angles
User disengaged	Summarize progress, offer break point with resume
Perspectives conflict	Present as tradeoff, let user decide
Max rounds reached	Force synthesis, highlight unresolved questions
All ideas fail challenge	Return to divergent phase with new constraints

---

Now execute brainstorm-with-file for: $ARGUMENTS