brainstorm

头脑风暴

将交互式框架生成、多角色并行分析和跨角色综合整合为一个统一入口，并提供两种运行模式。

架构概览

┌─────────────────────────────────────────────────────────────┐
│                    /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步)

数据流：

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

核心设计原则

1. 双模式路由：通过 AskUserQuestion 交互式选择模式，并根据参数自动检测
2. 渐进式阶段加载：通过 Ref: 标记按需加载阶段文件，而非一次性全部加载
3. 任务附加／折叠：在阶段执行期间附加子任务，完成后折叠
4. 会话连续性：所有阶段通过 workflow-session.json 共享会话状态
5. 自动继续执行：各阶段自动衔接，无需用户在阶段之间介入
6. SPEC.md 质量对齐：指导规范和角色分析遵循 SPEC.md 标准（概念与术语、非目标、数据模型、状态机、RFC 2119 约束）
7. 模板驱动分析：特定角色的模板（如 system-architect）确保输出一致且高质量
8. 质量关卡：根据质量标准自动验证指导规范和角色分析

自动模式

当使用 --yes 或 -y 时：自动选择自动模式，跳过交互式路由问题，自动选择推荐角色，跳过所有澄清问题，并使用默认答案。

执行流程

阶段 1：模式检测与交互式路由

Ref: phases/01-mode-routing.md

解析参数，根据标志／参数检测模式，或通过 AskUserQuestion 询问用户。

模式检测规则：

1. 如果存在 --yes 或 -y 标志 → 自动模式（不提问）
2. 如果第一个参数与已知角色名称匹配 → 单角色模式（不提问）
3. 如果存在 --session 标志但没有角色名称 → 询问用户
4. 否则 → 通过 AskUserQuestion 询问用户

输出：execution_mode（"auto" | "single-role"）、已解析的参数

---

自动模式执行（execution_mode = "auto"）

阶段 1.5：术语与边界定义

• 从用户输入和阶段 1 上下文中提取 5-10 个核心领域术语
• 生成术语表（术语、定义、别名、类别）
• 通过 AskUserQuestion 收集非目标（明确排除的范围）
• 保存至 session.terminology 和 session.non_goals

阶段 2：交互式框架生成

Ref: phases/02-artifacts.md

七阶段交互式工作流：收集上下文 → 分析主题 → 选择角色 → 提出角色问题 → 解决冲突 → 最终检查 → 生成规范。

输入：主题描述、--count N、--yes 标志 输出：guidance-specification.md（包含概念与术语、非目标、RFC 2119 约束）、workflow-session.json（selected_roles[]、session_id）

TodoWrite：附加 7 个子任务（阶段 0-5），按顺序执行，完成后折叠。

阶段 3：并行角色分析

参考：phases/03-role-analysis.md

并行对每个选定角色执行角色分析（不包括 ui-designer，该角色将在阶段 3.5 中按顺序执行）。

输入：Phase 2 中的 selected_roles[]、session_id、guidance-specification.md 输出：每个角色对应的 {role}/analysis*.md

并行执行：同时启动 N 个角色分析调用（在一条消息中调用多个 Skill）。每个角色都使用 --skip-questions 标志。注意：ui-designer 不包含在此并行批次中；它将在阶段 3.5 中执行，并可访问所有文本角色分析。

对于 ui-designer：如果提供了样式技能，则附加 --style-skill {package}。

模板驱动分析：

• 如果存在角色专属模板，则加载该模板（例如，templates/role-templates/system-architect-template.md）
• 将模板注入 Agent 提示词，作为必需结构
• 对于 system-architect：必须包含 Data Model、State Machine、Error Handling、Observability、Configuration Model、Boundary Scenarios

质量验证：

• 生成分析后，调用 role-analysis-reviewer-agent，根据模板进行验证
• 检查必须包含的章节（阻断项）、应包含的章节（警告）以及质量检查（RFC 关键词、有效图表）
• 输出包含评分和建议的验证报告

TodoWrite：添加 N 个并行子任务，并发执行，完成后折叠。

阶段 3.5：UI 设计探索

参考：phases/03a-ui-design-exploration.md

在文本角色分析完成后按顺序执行的阶段。根据项目类型检测结果生成具体的 UI 产物（HTML 原型、ASCII 原型图或 API 草图）。

输入：阶段 3 的所有角色分析（只读）、guidance-specification.md、style_skill（可选） 输出：包含 feature-index.json 的 html-prototypes/、ascii-mockups/ 或 api-sketches/ 目录

跳过条件：项目类型为库/服务、所选角色中没有 ui-designer，或在未指定 --ui-explore 的 --yes 模式下

可选评审：如果有 2 个或更多原型且未启用 --yes，则加载 Ref: ~/.ccw/workflows/brainstorm-visualize.md，进行多轮交互式评审，并智能分组。

TodoWrite：添加包含子任务的单个任务（检测 → 生成 → 验证 → 评审 → 反馈），完成后折叠。

阶段 4：综合集成

参考：phases/04-synthesis.md

六阶段综合流程：发现 → 文件发现 → 跨角色分析 → 用户交互 → 规格生成（单个 Agent，按顺序执行）+ 条件式评审 → 最终确定。角色分析文件为只读文件（绝不修改）。规格是最终综合产物。

输入：Phase 2 的 session_id、Phase 3 的所有角色分析文件（只读） 输出：feature-specs/、feature-index.json、synthesis-changelog.md

TodoWrite：添加综合子任务，按顺序执行，完成后折叠。

---

单角色模式执行（execution_mode = "single-role"）

阶段 3：单角色分析

参考：phases/03-role-analysis.md

针对一个指定角色执行角色分析，并可选择交互式收集上下文。

输入：role_name、--session、--update、--include-questions、--skip-questions、--style-skill 输出：{role}/analysis*.md

TodoWrite：添加 4 个子任务（检测 → 上下文 → Agent → 验证），并按顺序执行。

---

阶段参考文档（在阶段执行时按需读取）：

阶段	文档	用途	使用方
1	phases/01-mode-routing.md	参数解析、模式检测、交互式路由	两种模式
2	phases/02-artifacts.md	交互式框架生成（7 个阶段）	仅自动模式
3	phases/03-role-analysis.md	生成角色专项分析	两种模式
3.5	phases/03a-ui-design-exploration.md	UI 原型生成与评审	仅自动模式
4	phases/04-synthesis.md	跨角色综合分析与功能规格	仅自动模式

核心规则

1. 从模式检测开始：第一个操作是阶段 1（解析参数 + 检测模式）
2. 交互式路由：如果无法从参数确定模式，则通过 AskUserQuestion 询问用户
3. 不做初步分析：阶段 2 之前不要分析主题，所有分析由 artifacts 负责
4. 解析每项输出：阶段 2 之后，从 workflow-session.json 中提取 selected_roles
5. 通过 TodoList 自动继续：检查 TodoList 状态，自动执行下一个待处理阶段
6. 任务附加模型：Skill 和 Task 将子任务附加到当前工作流
7. ⚠️ 关键：不要停止：自动模式下持续执行多阶段工作流。完成所有已附加任务后，立即将其折叠并执行下一阶段
8. 并行执行：自动模式的阶段 3 会同时附加多个 Agent 任务，以便并发执行
9. 单角色独立性：单角色模式独立运行，不需要 artifacts 或综合分析

输入处理

参数解析

// 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);
}

使用示例

# 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

数据流

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 3.5:
  Input:  all analysis*.md (read-only), guidance-specification.md, style_skill
  Output: html-prototypes/ OR ascii-mockups/ OR api-sketches/
          feature-index.json, review_decisions (optional)
          ↓
Phase 4:
  Input:  session_id, all analysis files (read-only)
  Output: feature-specs/F-{id}-{slug}.md
          feature-index.json
          synthesis-changelog.md

TodoWrite 模式

自动模式生命周期

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 (excluding ui-designer)
           → Execute concurrently
           → Sub-tasks COLLAPSED
       → Phase 3.5 UI Design Exploration (in_progress)
           → Sub-tasks: Detection → Generate → Validate → Review → Feedback
           → Execute sequentially
           → Sub-tasks COLLAPSED
       → Phase 4 Synthesis (in_progress)
           → 8 sub-tasks ATTACHED
           → Execute sequentially
           → Sub-tasks COLLAPSED
       → All completed

单角色模式生命周期

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

初始 TodoWrite（自动模式）

[
  {"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 3.5: UI Design Exploration", "status": "pending", "activeForm": "Generating UI prototypes"},
  {"content": "Phase 4: Synthesis Integration", "status": "pending", "activeForm": "Executing synthesis"}
]

初始 TodoWrite（单角色模式）

[
  {"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"}
]

会话管理

⚡ 首要操作：检查 .workflow/active/ 中是否存在现有会话

支持多个会话：

• 不同的 Claude 实例可以拥有不同的头脑风暴会话
• 如果找到多个会话，则提示用户选择
• 如果找到一个会话，则使用该会话
• 如果不存在会话：
  • 自动模式：创建 WFS-[topic-slug]
  • 单角色模式：若无会话则报错（必须先运行自动模式）

会话连续性：所有阶段通过 workflow-session.json 共享会话状态

可用角色

角色 ID	职称	关注领域
data-architect	数据架构师	数据模型、存储策略、数据流
product-manager	产品经理	产品策略、路线图、优先级排序
product-owner	产品负责人	待办事项管理、用户故事、验收标准
scrum-master	敏捷教练	流程协调、消除障碍
subject-matter-expert	领域专家	领域知识、业务规则、合规性
system-architect	系统架构师	技术架构、可扩展性、集成
test-strategist	测试策略师	测试策略、质量保证
ui-designer	UI 设计师	视觉设计、模型图、设计系统
ux-expert	UX 专家	用户研究、信息架构、用户旅程

角色选择：自动模式 → 由 artifacts 处理（阶段 2）。单角色模式 → 由用户直接指定。

输出结构

.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
    ├── html-prototypes/               # Phase 3.5 (web/mobile/desktop-gui)
    │   ├── README.md                  # Prototype summary
    │   ├── feature-index.json         # File-to-feature mapping
    │   └── {feature-slug}.html        # Self-contained prototypes
    ├── ascii-mockups/                 # Phase 3.5 (cli projects)
    │   └── {feature-slug}.md
    ├── api-sketches/                  # Phase 3.5 (library/service projects)
    │   └── {feature-slug}.md
    ├── {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)

错误处理

错误	恢复方式	模式
角色名称无效	显示有效角色列表，并重新询问	单角色
没有活动会话	自动模式：创建新会话。单角色模式：显示错误并提供指导	两者
角色选择失败	默认使用 product-manager	自动
Agent 执行失败	针对 Agent 进行重试，并尽量减少依赖项	两者
模板加载问题	优雅降级	两者
综合分析出现冲突	突出显示分歧，不强行解决	自动
上下文溢出（>100KB）	仅读取 analysis.md 索引文件	自动

上下文溢出保护：

• 每个角色的限制：主要文档 < 3000 字，子文档 < 2000 字，最多 5 个子文档
• 综合分析保护：如果总量 > 100KB，仅读取 analysis.md（不读取子文档）
• 恢复方式：缩小范围（--count 2）→ 使用 --summary-only → 手动综合分析

协调者检查清单

阶段前操作：

• 通过 Ref: 标记读取阶段文档
• 验证前置条件（会话存在、必需文件齐全）
• 在 TodoWrite 中将阶段标记为 in_progress
• 如适用，附加子任务

阶段后操作：

• 验证阶段输出是否存在
• 将子任务汇总为阶段摘要
• 在 TodoWrite 中将阶段标记为 completed
• 自动继续下一个待处理阶段（自动模式）
• 报告完成情况（单角色模式）

相关命令

前置条件：

• /workflow:session:start - 启动新的工作流会话（可选，brainstorm 会自行创建会话）

后续操作（brainstorm 完成后）：

• /workflow-plan --session {sessionId} - 生成实施计划
• /workflow:brainstorm:synthesis --session {sessionId} - 单独运行综合分析（如果已跳过）

参考信息

模板来源：~/.ccw/workflows/cli-templates/planning-roles/ 样式 SKILL 包：.claude/skills/style-{package-name}/