| name | brainstorm |
| description | Dual-mode brainstorming pipeline. Auto mode: framework generation → parallel role analysis
(spawn_agents_on_csv) → cross-role synthesis. Single role mode: individual role analysis.
CSV-driven parallel coordination with NDJSON discovery board.
|
| argument-hint | [-y|--yes] [--count N] [--session ID] [--skip-questions] [--style-skill PKG] "topic" | <role-name> [--session ID] |
| allowed-tools | spawn_agents_on_csv, spawn_agent, wait_agent, send_message, followup_task, close_agent, request_user_input, Read, Write, Edit, Bash, Glob, Grep |
Auto Mode
When --yes or -y: Auto-select auto mode, auto-select recommended roles, skip all clarification questions, use defaults. This skill is brainstorming-only — it produces analysis and feature specs but NEVER executes code or modifies source files.
Brainstorm
Usage
$brainstorm "Build real-time collaboration platform" --count 3
$brainstorm -y "Design payment system" --count 5
$brainstorm "Build notification system" --style-skill material-design
$brainstorm system-architect --session WFS-xxx
$brainstorm ux-expert --include-questions
Flags:
-y, --yes: Skip all confirmations (auto mode)--count N: Number of roles to select (default: 3, max: 9)--session ID: Use existing session--skip-questions / --include-questions: Control interactive Q&A per role--style-skill PKG: Style skill package for ui-designer--update: Update existing role analysis
Overview
Dual-mode brainstorming with CSV-driven parallel role analysis. Auto mode runs a full pipeline; single role mode runs one role analysis independently.
┌──────────────────────────────────────────────────────────────────┐
│ BRAINSTORM PIPELINE │
├──────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: Mode Detection & Routing │
│ ├─ Parse flags and arguments │
│ └─ Route to Auto Mode or Single Role Mode │
│ │
│ ═══ Auto Mode ═══ │
│ │
│ Phase 2: Interactive Framework Generation │
│ ├─ Context collection → Topic analysis → Role selection │
│ ├─ Generate guidance-specification.md │
│ ├─ Generate roles.csv (1 row per selected role) │
│ └─ User validates (skip if -y) │
│ │
│ Phase 3: Wave Role Analysis (spawn_agents_on_csv) │
│ ├─ spawn_agents_on_csv(role instruction template) │
│ ├─ Each role agent produces analysis.md + sub-documents │
│ └─ discoveries.ndjson shared across role agents │
│ │
│ Phase 4: Synthesis Integration │
│ ├─ Read all role analyses (read-only) │
│ ├─ Cross-role analysis → conflict detection │
│ ├─ Feature spec generation │
│ └─ Output: feature-specs/ + feature-index.json │
│ │
│ ═══ Single Role Mode ═══ │
│ │
│ Phase 3S: Single Role Analysis (spawn_agent) │
│ ├─ spawn_agent(conceptual_planning_agent) │
│ └─ Output: {role}/analysis*.md │
│ │
└──────────────────────────────────────────────────────────────────┘
Context Flow
roles.csv feature-specs/
┌──────────────┐ ┌──────────────────┐
│ R1: sys-arch │──findings───→│ F-001-auth.md │
│ analysis.md │ │ (cross-role spec) │
├──────────────┤ ├──────────────────┤
│ R2: ui-design│──findings───→│ F-002-ui.md │
│ analysis.md │ │ (cross-role spec) │
├──────────────┤ ├──────────────────┤
│ R3: test-str │──findings───→│ F-003-test.md │
│ analysis.md │ │ (cross-role spec) │
└──────────────┘ └──────────────────┘
Two context channels:
1. Directed: role findings → synthesis → feature specs
2. Broadcast: discoveries.ndjson (append-only shared board)
CSV Schema
roles.csv
id,role,title,focus,deps,wave,status,findings,output_files,error
"R1","system-architect","系统架构师","Technical architecture, scalability","","1","pending","","",""
"R2","ui-designer","UI设计师","Visual design, mockups","","1","pending","","",""
"R3","test-strategist","测试策略师","Test strategy, quality","","1","pending","","",""
Columns:
| Column | Phase | Description |
|---|
id | Input | Role ID: R1, R2, ... |
role | Input | Role identifier (e.g., system-architect) |
title | Input | Role display title |
focus | Input | Role focus areas and keywords |
deps | Input | Dependency IDs (usually empty — all wave 1) |
wave | Computed | Wave number (usually 1 for all roles) |
status | Output | pending → completed / failed |
findings | Output | Key discoveries (max 800 chars) |
output_files | Output | Generated analysis files (semicolon-separated) |
error | Output | Error message if failed |
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 |
Session Structure
.workflow/active/WFS-{topic}/
├── workflow-session.json # Session metadata
├── .process/
│ └── context-package.json # Phase 0 context
├── roles.csv # Role analysis state (Phase 2-3)
├── discoveries.ndjson # Shared discovery board
└── .brainstorming/
├── guidance-specification.md # Framework (Phase 2)
├── feature-index.json # Feature index (Phase 4)
├── synthesis-changelog.md # Synthesis audit trail (Phase 4)
├── feature-specs/ # Feature specs (Phase 4)
│ ├── F-001-{slug}.md
│ └── F-00N-{slug}.md
└── {role}/ # Role analyses (Phase 3, immutable)
├── {role}-context.md # Interactive Q&A
├── analysis.md # Main/index document
├── analysis-cross-cutting.md # Cross-feature
└── analysis-F-{id}-{slug}.md # Per-feature
Implementation
Session Initialization
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const countMatch = $ARGUMENTS.match(/--count\s+(\d+)/)
const roleCount = countMatch ? Math.min(parseInt(countMatch[1]), 9) : 3
const sessionMatch = $ARGUMENTS.match(/--session\s+(\S+)/)
const existingSessionId = sessionMatch ? sessionMatch[1] : null
const skipQuestions = $ARGUMENTS.includes('--skip-questions')
const includeQuestions = $ARGUMENTS.includes('--include-questions')
const styleSkillMatch = $ARGUMENTS.match(/--style-skill\s+(\S+)/)
const styleSkill = styleSkillMatch ? styleSkillMatch[1] : null
const updateMode = $ARGUMENTS.includes('--update')
const VALID_ROLES = [
'data-architect', 'product-manager', 'product-owner', 'scrum-master',
'subject-matter-expert', 'system-architect', 'test-strategist',
'ui-designer', 'ux-expert'
]
const cleanArgs = $ARGUMENTS
.replace(/--yes|-y|--count\s+\d+|--session\s+\S+|--skip-questions|--include-questions|--style-skill\s+\S+|--update/g, '')
.trim()
const firstArg = cleanArgs.split(/\s+/)[0]
const isRole = VALID_ROLES.includes(firstArg)
let executionMode
if (AUTO_YES) {
executionMode = 'auto'
} else if (isRole) {
executionMode = 'single-role'
} else if (cleanArgs) {
executionMode = 'auto'
} else {
executionMode = null
}
const topic = isRole
? cleanArgs.replace(firstArg, '').trim()
: cleanArgs.replace(/^["']|["']$/g, '')
Phase 1: Mode Detection & Routing
Objective: Parse arguments, determine execution mode, prepare session.
Steps:
-
Detect Mode
if (executionMode === null) {
const modeAnswer = functions.request_user_input({
questions: [{
question: "Choose brainstorming mode:",
header: "Mode",
options: [
{ label: "Auto Mode (Recommended)", description: "Full pipeline: framework → parallel roles → synthesis" },
{ label: "Single Role", description: "Run one role analysis independently" }
]
}]
})
executionMode = modeAnswer.Mode.startsWith('Auto') ? 'auto' : 'single-role'
}
-
Session Setup
let sessionId, sessionFolder
if (existingSessionId) {
sessionId = existingSessionId
sessionFolder = `.workflow/active/${sessionId}`
} else if (executionMode === 'auto') {
const slug = topic.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 40)
sessionId = `WFS-${slug}`
sessionFolder = `.workflow/active/${sessionId}`
Bash(`mkdir -p "${sessionFolder}/.brainstorming" "${sessionFolder}/.process"`)
Write(`${sessionFolder}/workflow-session.json`, JSON.stringify({
session_id: sessionId,
topic: topic,
status: 'brainstorming',
execution_mode: executionMode,
created_at: getUtc8ISOString()
}, null, 2))
} else {
const existing = Bash(`ls -d .workflow/active/WFS-* 2>/dev/null | head -1`).trim()
if (!existing) {
console.log('ERROR: No active session found. Run auto mode first to create a session.')
return
}
sessionId = existing.split('/').pop()
sessionFolder = existing
}
Route:
executionMode === 'auto' → Phase 2executionMode === 'single-role' → Phase 3S
Phase 2: Interactive Framework Generation (Auto Mode)
Objective: Analyze topic, select roles, generate guidance-specification.md and roles.csv.
Steps:
-
Analyze Topic & Select Roles
Bash({
command: `ccw cli -p "PURPOSE: Analyze brainstorming topic and recommend ${roleCount} expert roles for multi-perspective analysis. Success = well-matched roles with clear focus areas.
TASK:
• Analyze topic domain, complexity, and key dimensions
• Select ${roleCount} roles from: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
• For each role: define focus area, key questions, and analysis scope
• Identify potential cross-role conflicts or synergies
• Generate feature decomposition if topic has distinct components
MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON: {analysis: {domain, complexity, dimensions[]}, roles: [{id, role, title, focus, key_questions[]}], features: [{id, title, description}]}
CONSTRAINTS: Select exactly ${roleCount} roles | Each role must have distinct perspective | Roles must cover topic comprehensively
TOPIC: ${topic}" --tool gemini --mode analysis --rule planning-breakdown-task-steps`,
run_in_background: true
})
// Wait for CLI completion → { analysis, roles[], features[] }
2. **User Validation** (skip if AUTO_YES)
```javascript
if (!AUTO_YES) {
console.log(`\n## Brainstorm Framework\n`)
console.log(`Topic: ${topic}`)
console.log(`Domain: ${analysis.domain} | Complexity: ${analysis.complexity}`)
console.log(`\nSelected Roles (${roles.length}):`)
roles.forEach(r => console.log(` - [${r.id}] ${r.title}: ${r.focus}`))
if (features.length > 0) {
console.log(`\nFeatures (${features.length}):`)
features.forEach(f => console.log(` - [${f.id}] ${f.title}`))
}
const answer = functions.request_user_input({
questions: [{
question: "Approve brainstorm framework?",
header: "Validate",
options: [
{ label: "Approve", description: "Proceed with role analysis" },
{ label: "Modify Roles", description: "Change role selection" },
{ label: "Cancel", description: "Abort" }
]
}]
})
if (answer.Validate === "Cancel") return
if (answer.Validate === "Modify Roles") {
// Allow user to adjust via request_user_input
const roleAnswer = functions.request_user_input({
questions: [{
question: "Select roles for analysis:",
header: "Roles",
options: VALID_ROLES.map(r => ({
label: r,
description: roles.find(sel => sel.role === r)?.focus || ''
}))
}]
})
// Rebuild roles[] from selection
}
}
-
Generate Guidance Specification
const guidanceContent = `# Guidance Specification
Topic
${topic}
Analysis
- Domain: ${analysis.domain}
- Complexity: ${analysis.complexity}
- Dimensions: ${analysis.dimensions.join(', ')}
Selected Roles
${roles.map(r => `### ${r.title} (${r.role})
- Focus: ${r.focus}
- Key Questions: ${r.key_questions.join('; ')}`).join('\n\n')}
Features
${features.map(f => - **[${f.id}] ${f.title}**: ${f.description}).join('\n')}
Write(${sessionFolder}/.brainstorming/guidance-specification.md`, guidanceContent)
4. **Generate roles.csv**
```javascript
const header = 'id,role,title,focus,deps,wave,status,findings,output_files,error'
const rows = roles.map(r =>
[r.id, r.role, r.title, r.focus, '', '1', 'pending', '', '', '']
.map(v => `"${String(v).replace(/"/g, '""')}"`)
.join(',')
)
Write(`${sessionFolder}/roles.csv`, [header, ...rows].join('\n'))
Update workflow-session.json with selected_roles.
Phase 3: Wave Role Analysis (spawn_agents_on_csv) — Auto Mode
Objective: Execute parallel role analysis via spawn_agents_on_csv. Each role agent produces analysis documents.
Steps:
-
Role Analysis Wave
const rolesCSV = parseCsv(Read(`${sessionFolder}/roles.csv`))
console.log(`\n## Phase 3: Parallel Role Analysis (${rolesCSV.length} roles)\n`)
spawn_agents_on_csv({
csv_path: `${sessionFolder}/roles.csv`,
id_column: "id",
instruction: buildRoleInstruction(sessionFolder, topic, features),
max_concurrency: Math.min(rolesCSV.length, 4),
max_runtime_seconds: 600,
output_csv_path: `${sessionFolder}/roles-results.csv`,
output_schema: {
type: "object",
properties: {
id: { type: "string" },
status: { type: "string", enum: ["completed", "failed"] },
findings: { type: "string" },
output_files: { type: "array", items: { type: "string" } },
error: { type: "string" }
},
required: ["id", "status", "findings"]
}
})
const roleResults = parseCsv(Read(`${sessionFolder}/roles-results.csv`))
for (const result of roleResults) {
updateMasterCsvRow(`${sessionFolder}/roles.csv`, result.id, {
status: result.status,
findings: result.findings || '',
output_files: Array.isArray(result.output_files) ? result.output_files.join(';') : (result.output_files || ''),
error: result.error || ''
})
console.log(` [${result.id}] ${result.status === 'completed' ? '✓' : '✗'} ${rolesCSV.find(r => r.id === result.id)?.role}`)
}
Bash(`rm -f "${sessionFolder}/roles-results.csv"`)
-
Role Instruction Template
function buildRoleInstruction(sessionFolder, topic, features) {
const featureList = features.length > 0
? features.map(f => `- [${f.id}] ${f.title}: ${f.description}`).join('\n')
: 'No feature decomposition — analyze topic holistically.'
return `
ROLE ANALYSIS ASSIGNMENT
MANDATORY FIRST STEPS
- Read guidance specification: ${sessionFolder}/.brainstorming/guidance-specification.md
- Read shared discoveries: ${sessionFolder}/discoveries.ndjson (if exists)
- Read project context: .workflow/project-tech.json (if exists)
Your Role
Role ID: {id}
Role: {role}
Title: {title}
Focus: {focus}
Topic
${topic}
Features to Analyze
${featureList}
Analysis Protocol
- Read guidance: Load guidance-specification.md for full context
- Read discoveries: Load discoveries.ndjson for shared findings from other roles
- Analyze from your perspective: Apply your role expertise to the topic
- Per-feature analysis (if features exist):
- Create `${sessionFolder}/.brainstorming/{role}/analysis-{feature-id}-{slug}.md` per feature
- Create `${sessionFolder}/.brainstorming/{role}/analysis-cross-cutting.md` for cross-feature concerns
- Create index document: `${sessionFolder}/.brainstorming/{role}/analysis.md`
- Summary of all findings
- Links to sub-documents
- Key recommendations
- Share discoveries: Append findings to shared board:
```bash
echo '{"ts":"","worker":"{id}","type":"","data":{...}}' >> ${sessionFolder}/discoveries.ndjson
```
- Report result: Return JSON via report_agent_job_result
Document Constraints
- Main analysis.md: < 3000 words
- Sub-documents: < 2000 words each, max 5
- Total per role: < 15000 words
Discovery Types to Share
- `design_pattern`: {name, rationale, applicability} — recommended patterns
- `risk`: {area, severity, mitigation} — identified risks
- `requirement`: {title, priority, source} — derived requirements
- `constraint`: {type, description, impact} — discovered constraints
- `synergy`: {roles[], area, description} — cross-role opportunities
Output (report_agent_job_result)
Return JSON:
{
"id": "{id}",
"status": "completed" | "failed",
"findings": "Key insights from {role} perspective (max 800 chars)",
"output_files": ["path/to/analysis.md", "path/to/analysis-F-001.md"],
"error": ""
}
`
}
---
### Phase 3S: Single Role Analysis (spawn_agent) — Single Role Mode
**Objective**: Run one role analysis via spawn_agent with optional interactive Q&A.
```javascript
if (executionMode === 'single-role') {
const roleName = firstArg
const roleDir = `${sessionFolder}/.brainstorming/${roleName}`
Bash(`mkdir -p "${roleDir}"`)
const agentId = spawn_agent({
agent_type: "conceptual_planning_agent",
instruction: `
Perform a ${roleName} analysis for the brainstorming session.
**Session**: ${sessionFolder}
**Role**: ${roleName}
**Topic**: Read from ${sessionFolder}/.brainstorming/guidance-specification.md
${includeQuestions ? '**Mode**: Interactive — ask clarification questions before analysis' : ''}
${skipQuestions ? '**Mode**: Skip questions — proceed directly to analysis' : ''}
${styleSkill ? `**Style Skill**: ${styleSkill} — load .claude/skills/style-${styleSkill}/ for design reference` : ''}
${updateMode ? '**Update Mode**: Read existing analysis and enhance/update it' : ''}
**Output**: Create analysis documents in ${roleDir}/
- ${roleDir}/analysis.md (main index)
- ${roleDir}/analysis-*.md (sub-documents as needed)
Follow the same analysis protocol as wave role analysis but with interactive refinement.
`
})
wait_agent({ timeout_ms: 1800000 })
close_agent({ target: agentId })
console.log(`\n✓ ${roleName} analysis complete: ${roleDir}/analysis.md`)
}
Phase 4: Synthesis Integration (Auto Mode)
Objective: Read all role analyses, cross-reference, generate feature specs.
Steps:
-
Collect Role Findings
const rolesCSV = parseCsv(Read(`${sessionFolder}/roles.csv`))
const completedRoles = rolesCSV.filter(r => r.status === 'completed')
const roleAnalyses = {}
for (const role of completedRoles) {
const indexPath = `${sessionFolder}/.brainstorming/${role.role}/analysis.md`
const content = Read(indexPath)
if (content) roleAnalyses[role.role] = content
}
const discoveriesPath = `${sessionFolder}/discoveries.ndjson`
const discoveries = Read(discoveriesPath) || ''
-
Synthesis via Agent
const synthesisAgent = spawn_agent({
agent_type: "conceptual_planning_agent",
instruction: `
SYNTHESIS ASSIGNMENT
Synthesize ${completedRoles.length} role analyses into unified feature specifications.
Session: ${sessionFolder}
Role Analyses: ${completedRoles.map(r => ${sessionFolder}/.brainstorming/${r.role}/analysis.md).join(', ')}
Discoveries: ${discoveriesPath}
Synthesis Protocol
- Read all role analyses (analysis.md files only — these are index documents)
- Cross-reference findings: Identify agreements, conflicts, and unique insights
- Generate feature specs: For each feature in guidance-specification.md:
- Create ${sessionFolder}/.brainstorming/feature-specs/F-{id}-{slug}.md
- Consolidate perspectives from all relevant roles
- Note conflicts and recommended resolutions
- Generate feature index: ${sessionFolder}/.brainstorming/feature-index.json
- Array of {id, title, slug, roles_contributing[], conflict_count, priority}
- Generate changelog: ${sessionFolder}/.brainstorming/synthesis-changelog.md
- Decisions made, conflicts resolved, trade-offs accepted
Complexity Assessment
Evaluate complexity score (0-8):
- Feature count (≤2: 0, 3-4: 1, ≥5: 2)
- Unresolved conflicts (0: 0, 1-2: 1, ≥3: 2)
- Participating roles (≤2: 0, 3-4: 1, ≥5: 2)
- Cross-feature dependencies (0: 0, 1-2: 1, ≥3: 2)
Output Files
-
feature-specs/F-{id}-{slug}.md (one per feature)
-
feature-index.json
-
synthesis-changelog.md
`
})
wait_agent({ timeout_ms: 1800000 })
close_agent({ target: synthesisAgent })
-
Completion Summary
const featureIndex = JSON.parse(Read(`${sessionFolder}/.brainstorming/feature-index.json`) || '[]')
console.log(`
Brainstorm Complete
Session: ${sessionId}
Roles analyzed: ${completedRoles.length}
Features synthesized: ${featureIndex.length}
Feature Specs
${featureIndex.map(f => - [${f.id}] ${f.title} (${f.roles_contributing?.length || 0} roles, ${f.conflict_count || 0} conflicts)).join('\n')}
Next Steps
Brainstorming complete. To continue, run one of:
- /workflow-plan --session ${sessionId} → Generate implementation plan
- Review: ${sessionFolder}/.brainstorming/feature-specs/
`)
Utility Functions
CSV Parser
function parseCsv(content) {
const lines = content.trim().split('\n')
if (lines.length < 2) return []
const headers = parseCSVLine(lines[0])
return lines.slice(1).map(line => {
const values = parseCSVLine(line)
const row = {}
headers.forEach((h, i) => row[h] = values[i] || '')
return row
})
}
CSV Row Updater
function updateMasterCsvRow(csvPath, id, updates) {
const content = Read(csvPath)
const lines = content.trim().split('\n')
const headers = parseCSVLine(lines[0])
const idIdx = headers.indexOf('id')
for (let i = 1; i < lines.length; i++) {
const values = parseCSVLine(lines[i])
if (values[idIdx]?.replace(/"/g, '') === id) {
Object.entries(updates).forEach(([key, val]) => {
const idx = headers.indexOf(key)
if (idx >= 0) values[idx] = `"${String(val).replace(/"/g, '""')}"`
})
lines[i] = values.join(',')
break
}
}
Write(csvPath, lines.join('\n'))
}
Error Handling
| Error | Recovery |
|---|
| Invalid role name | Show valid roles list, prompt again |
| No active session (single role) | Guide user to run auto mode first |
| Role agent failure | Mark failed in roles.csv, continue with remaining |
| Synthesis overflow (>100KB) | Read only analysis.md index files |
| Context compression | Re-read guidance-specification.md and roles.csv |
Compact Protection
COMPACT DIRECTIVE: If context compression occurs mid-execution, re-read the current phase's state:
- Phase 2: Re-read
guidance-specification.md
- Phase 3: Re-read
roles.csv for progress state
- Phase 4: Re-read
feature-index.json and roles.csv
