Brainstorm

Unified brainstorming skill combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis into a single entry point with two operational modes.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐ │ /brainstorm │ │ Unified Entry Point + Interactive Routing │ └───────────────────────┬─────────────────────────────────────┘ │ ┌─────────┴─────────┐ ↓ ↓ ┌─────────────────┐ ┌──────────────────┐ │ Auto Mode │ │ Single Role Mode │ │ (自动模式) │ │ (单角色分析模式) │ └────────┬────────┘ └────────┬─────────┘ │ │ ┌────────┼────────┐ │ ↓ ↓ ↓ ↓ Phase 2 Phase 3 Phase 4 Phase 3 Artifacts N×Role Synthesis 1×Role (7步) Analysis (8步) Analysis 并行 (4步)

Data Flow:

Auto Mode: Phase 2 (artifacts) → guidance-specification.md + selected_roles[] → Phase 3 (N × role-analysis) → {role}/analysis*.md (immutable) → Phase 4 (synthesis) → feature-specs/ + feature-index.json + synthesis-changelog.md

Single Role Mode: Phase 3 (1 × role-analysis) → {role}/analysis*.md

Key Design Principles

• Dual-Mode Routing: Interactive mode selection via AskUserQuestion, with parameter-based auto-detection

• Progressive Phase Loading: Phase files loaded on-demand via Ref: markers, not all at once

• Task Attachment/Collapse: Sub-tasks attached during phase execution, collapsed after completion

• Session Continuity: All phases share session state via workflow-session.json

• Auto-Continue Execution: Phases chain automatically without user intervention between them

• SPEC.md Quality Alignment: Guidance specification and role analysis follow SPEC.md standards (Concepts & Terminology, Non-Goals, Data Model, State Machine, RFC 2119 constraints)

• Template-Driven Analysis: Role-specific templates (e.g., system-architect) ensure consistent, high-quality outputs

• Quality Gates: Automated validation of guidance specification and role analysis against quality standards

Auto Mode

When --yes or -y : Auto-select auto mode, skip interactive routing question, auto-select recommended roles, skip all clarification questions, use default answers.

Execution Flow

Phase 1: Mode Detection & Interactive Routing

Ref: phases/01-mode-routing.md

Parse arguments, detect mode from flags/parameters, or ask user via AskUserQuestion.

Mode Detection Rules:

• If --yes or -y flag present → Auto Mode (no question asked)

• If first arg matches a known role name → Single Role Mode (no question asked)

• If --session flag present without role name → Ask user

• Otherwise → Ask user via AskUserQuestion

Output: execution_mode ("auto" | "single-role"), parsed parameters

Auto Mode Execution (execution_mode = "auto")

Phase 1.5: Terminology & Boundary Definition

• Extract 5-10 core domain terms from user input and Phase 1 context

• Generate terminology table (term, definition, aliases, category)

• Collect Non-Goals via AskUserQuestion (明确排除的范围)

• Store to session.terminology and session.non_goals

Phase 2: Interactive Framework Generation

Ref: phases/02-artifacts.md

Seven-phase interactive workflow: Context collection → Topic analysis → Role selection → Role questions → Conflict resolution → Final check → Generate specification.

Input: topic description, --count N, --yes flag Output: guidance-specification.md (with Concepts & Terminology, Non-Goals, RFC 2119 constraints), workflow-session.json (selected_roles[], session_id)

TodoWrite: Attach 7 sub-tasks (Phase 0-5), execute sequentially, collapse on completion.

Phase 3: Parallel Role Analysis

Ref: phases/03-role-analysis.md

Execute role analysis for EACH selected role in parallel.

Input: selected_roles[] from Phase 2, session_id, guidance-specification.md Output: {role}/analysis*.md for each role

Parallel Execution: Launch N role-analysis calls simultaneously (one message with multiple Skill invokes). Each role with --skip-questions flag.

For ui-designer: append --style-skill {package} if provided.

Template-Driven Analysis:

• Load role-specific template if exists (e.g., templates/role-templates/system-architect-template.md )

• Inject template into agent prompt as required structure

• For system-architect: MUST include Data Model, State Machine, Error Handling, Observability, Configuration Model, Boundary Scenarios

Quality Validation:

• After analysis generation, invoke role-analysis-reviewer-agent to validate against template

• Check MUST have sections (blocking), SHOULD have sections (warning), quality checks (RFC keywords, valid diagrams)

• Output validation report with score and recommendations

TodoWrite: Attach N parallel sub-tasks, execute concurrently, collapse on completion.

Phase 4: Synthesis Integration

Ref: phases/04-synthesis.md

Six-phase synthesis: Discovery → File discovery → Cross-role analysis → User interaction → Spec generation (single agent, sequential) + Conditional review → Finalization. Role analysis files are read-only (never modified). Spec is the final synthesis artifact.

Input: session_id from Phase 2, all role analysis files from Phase 3 (read-only) Output: feature-specs/, feature-index.json, synthesis-changelog.md

TodoWrite: Attach synthesis sub-tasks, execute sequentially, collapse on completion.

Single Role Mode Execution (execution_mode = "single-role")

Phase 3: Single Role Analysis

Ref: phases/03-role-analysis.md

Execute role analysis for ONE specified role with optional interactive context gathering.

Input: role_name, --session, --update, --include-questions, --skip-questions, --style-skill Output: {role}/analysis*.md

TodoWrite: Attach 4 sub-tasks (Detection → Context → Agent → Validation), execute sequentially.

Phase Reference Documents (read on-demand when phase executes):

Phase Document Purpose Used By

1 phases/01-mode-routing.md Parameter parsing, mode detection, interactive routing Both modes

2 phases/02-artifacts.md Interactive framework generation (7 phases) Auto mode only

3 phases/03-role-analysis.md Role-specific analysis generation Both modes

4 phases/04-synthesis.md Cross-role synthesis and feature specs Auto mode only

Core Rules

• Start with Mode Detection: First action is Phase 1 (parse args + detect mode)

• Interactive Routing: If mode cannot be determined from args, ASK user via AskUserQuestion

• No Preliminary Analysis: Do not analyze topic before Phase 2 - artifacts handles all analysis

• Parse Every Output: Extract selected_roles from workflow-session.json after Phase 2

• Auto-Continue via TodoList: Check TodoList status to execute next pending phase automatically

• Task Attachment Model: Skill and Task executes attach sub-tasks to current workflow

• ⚠️ CRITICAL: DO NOT STOP: Continuous multi-phase workflow in auto mode. After executing all attached tasks, immediately collapse them and execute next phase

• Parallel Execution: Auto mode Phase 3 attaches multiple agent tasks simultaneously for concurrent execution

• Single Role Independence: Single role mode operates independently without requiring artifacts or synthesis

Input Processing

Parameter Parsing

// Parse from user input (argument string) const args = parseArguments(user_input);

// Flags const auto_yes = args.includes('--yes') || args.includes('-y'); const count = extractFlag(args, '--count', 3); // default 3, max 9 const session_id = extractFlag(args, '--session', null); const update_mode = args.includes('--update'); const include_questions = args.includes('--include-questions'); const skip_questions = args.includes('--skip-questions'); const style_skill = extractFlag(args, '--style-skill', null);

// Role detection const VALID_ROLES = [ 'data-architect', 'product-manager', 'product-owner', 'scrum-master', 'subject-matter-expert', 'system-architect', 'test-strategist', 'ui-designer', 'ux-expert' ]; const first_arg = args[0]; // first non-flag argument const is_role = VALID_ROLES.includes(first_arg);

// Mode detection if (auto_yes) { execution_mode = 'auto'; topic = extractTopic(args); } else if (is_role) { execution_mode = 'single-role'; role_name = first_arg; } else { execution_mode = null; // Ask user topic = extractTopic(args); }

Usage Examples

Auto mode - full pipeline

/brainstorm "Build real-time collaboration platform" --count 3 /brainstorm -y "GOAL: Build platform SCOPE: 100 users" --count 5 /brainstorm "Design payment system" --style-skill material-design

Single role mode - individual analysis

/brainstorm system-architect --session WFS-xxx /brainstorm ux-expert --include-questions /brainstorm ui-designer --session WFS-xxx --update --style-skill material-design /brainstorm product-manager --skip-questions

Ambiguous - will ask interactively

/brainstorm --session WFS-xxx /brainstorm

Data Flow

Phase 1 (Mode Routing): Input: user arguments Output: execution_mode, parsed_params ↓ ┌───────┴───────┐ Auto Single Role ↓ ↓ Phase 2: Phase 3: Input: topic, count, auto_yes Output: session_id ─────────────→ Input: role_name, session_id selected_roles[] skip/include questions guidance-specification.md style_skill ↓ Output: {role}/analysis*.md Phase 3: Input: selected_roles[], session_id guidance-specification.md style_skill (for ui-designer) Output: {role}/analysis*.md (N files, immutable after this point) ↓ Phase 4: Input: session_id, all analysis files (read-only) Output: feature-specs/F-{id}-{slug}.md feature-index.json synthesis-changelog.md

TodoWrite Pattern

Auto Mode Lifecycle

Initial → Phase 1 Mode Routing (completed) → Phase 2 Artifacts (in_progress) → 7 sub-tasks ATTACHED (Phase 0-5) → Execute sequentially → Sub-tasks COLLAPSED → Phase 3 Parallel Role Analysis (in_progress) → N role sub-tasks ATTACHED simultaneously → Execute concurrently → Sub-tasks COLLAPSED → Phase 4 Synthesis (in_progress) → 8 sub-tasks ATTACHED → Execute sequentially → Sub-tasks COLLAPSED → All completed

Single Role Mode Lifecycle

Initial → Phase 1 Mode Routing (completed) → Phase 3 Role Analysis (in_progress) → 4 sub-tasks ATTACHED (Detection → Context → Agent → Validation) → Execute sequentially → Sub-tasks COLLAPSED → Completed

Initial TodoWrite (Auto Mode)

[ {"content": "Phase 1: Mode detection and parameter parsing", "status": "in_progress", "activeForm": "Detecting mode"}, {"content": "Phase 2: Interactive Framework Generation", "status": "pending", "activeForm": "Generating framework"}, {"content": "Phase 3: Parallel Role Analysis", "status": "pending", "activeForm": "Executing parallel analysis"}, {"content": "Phase 4: Synthesis Integration", "status": "pending", "activeForm": "Executing synthesis"} ]

Initial TodoWrite (Single Role Mode)

[ {"content": "Phase 1: Mode detection and parameter parsing", "status": "in_progress", "activeForm": "Detecting mode"}, {"content": "Phase 3: Single role analysis for {role_name}", "status": "pending", "activeForm": "Executing role analysis"} ]

Session Management

⚡ FIRST ACTION: Check .workflow/active/ for existing sessions

Multiple Sessions Support:

• Different Claude instances can have different brainstorming sessions

• If multiple sessions found, prompt user to select

• If single session found, use it

• If no session exists:

• Auto mode: Create WFS-[topic-slug]

• Single role mode: ERROR if no session (must run auto mode first)

Session Continuity: All phases share session state via workflow-session.json

Available Roles

Role ID Title Focus Area

data-architect

数据架构师 Data models, storage strategies, data flow

product-manager

产品经理 Product strategy, roadmap, prioritization

product-owner

产品负责人 Backlog management, user stories, acceptance criteria

scrum-master

敏捷教练 Process facilitation, impediment removal

subject-matter-expert

领域专家 Domain knowledge, business rules, compliance

system-architect

系统架构师 Technical architecture, scalability, integration

test-strategist

测试策略师 Test strategy, quality assurance

ui-designer

UI设计师 Visual design, mockups, design systems

ux-expert

UX专家 User research, information architecture, journey

Role Selection: Auto mode → handled by artifacts (Phase 2). Single role mode → user specifies directly.

Output Structure

.workflow/active/WFS-{topic}/ ├── workflow-session.json # Session metadata ONLY ├── .process/ │ └── context-package.json # Phase 0 output (auto mode) └── .brainstorming/ ├── guidance-specification.md # Framework (Phase 2, auto mode) ├── feature-index.json # Feature index (Phase 4, auto mode, feature_mode) ├── synthesis-changelog.md # Synthesis decisions audit trail (Phase 4, auto mode) ├── feature-specs/ # Feature specs (Phase 4, auto mode, feature_mode) │ ├── F-001-{slug}.md │ └── F-00N-{slug}.md ├── specs/ │ └── terminology-template.json # Terminology schema ├── templates/ │ └── role-templates/ │ └── system-architect-template.md # System architect analysis template ├── agents/ │ └── role-analysis-reviewer-agent.md # Role analysis validation agent ├── {role}/ # Role analyses (IMMUTABLE after Phase 3) │ ├── {role}-context.md # Interactive Q&A responses │ ├── analysis.md # Main/index document │ ├── analysis-cross-cutting.md # Cross-feature (feature_mode) │ └── analysis-F-{id}-{slug}.md # Per-feature (feature_mode) └── synthesis-specification.md # Integration (Phase 4, non-feature_mode only)

Error Handling

Error Recovery Mode

Invalid role name Show valid roles list, ask again Single Role

No active session Auto mode: create new. Single role: error with guidance Both

Role selection failure Default to product-manager Auto

Agent execution failure Agent-specific retry with minimal dependencies Both

Template loading issues Graceful degradation Both

Synthesis conflicts Highlight disagreements without forced resolution Auto

Context overflow (>100KB) Read only analysis.md index files Auto

Context Overflow Protection:

• Per-role limits: < 3000 words main, < 2000 words sub-docs, max 5 sub-docs

• Synthesis protection: If total > 100KB, read only analysis.md (not sub-documents)

• Recovery: reduce scope (--count 2) → use --summary-only → manual synthesis

Coordinator Checklist

Pre-Phase Actions:

• Read Phase document via Ref: marker

• Verify prerequisites (session exists, required files present)

• Mark phase as in_progress in TodoWrite

• Attach sub-tasks if applicable

Post-Phase Actions:

• Validate phase outputs exist

• Collapse sub-tasks to phase summary

• Mark phase as completed in TodoWrite

• Auto-continue to next pending phase (auto mode)

• Report completion (single role mode)

Related Commands

Prerequisites:

• /workflow:session:start
• Start a new workflow session (optional, brainstorm creates its own)

Follow-ups (after brainstorm completes):

• /workflow-plan --session {sessionId}

• Generate implementation plan

• /workflow:brainstorm:synthesis --session {sessionId}

• Run synthesis standalone (if skipped)

Reference Information

Template Source: ~/.ccw/workflows/cli-templates/planning-roles/

Style SKILL Packages: .claude/skills/style-{package-name}/