Refactor planning workflow documentation and enhance UI designer role template

- Updated the `/workflow:plan` command description to clarify its orchestration of a 4-phase planning workflow. - Revised the execution flow and core planning principles for improved clarity and structure. - Removed the `ANALYSIS_RESULTS.md` file as it is no longer needed in the workflow. - Enhanced the `concept-enhanced` tool documentation to specify mandatory first steps and output requirements. - Expanded the `ui-designer` role template to include detailed design workflows, output requirements, and collaboration strategies. - Introduced new design phases with clear outputs and user approval checkpoints in the UI designer template.
2026-02-13 02:41:50 +08:00 · 2025-09-30 13:37:37 +08:00
parent 04876c80bd
commit 7775cb3b0a
9 changed files with 929 additions and 956 deletions
--- a/.claude/commands/workflow/brainstorm/artifacts.md
+++ b/.claude/commands/workflow/brainstorm/artifacts.md
@@ -1,12 +1,12 @@
 ---
 name: artifacts
-description: Generate structured topic-framework.md for role-based brainstorming analysis
-usage: /workflow:brainstorm:artifacts "<topic>"
+description: Generate role-specific topic-framework.md dynamically based on selected roles
+usage: /workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
 argument-hint: "topic or challenge description for framework generation"
 examples:
  - /workflow:brainstorm:artifacts "Build real-time collaboration feature"
-  - /workflow:brainstorm:artifacts "Optimize database performance for millions of users"
-  - /workflow:brainstorm:artifacts "Implement secure authentication system"
+  - /workflow:brainstorm:artifacts "Optimize database performance" --roles "system-architect,data-architect,security-expert"
+  - /workflow:brainstorm:artifacts "Implement secure authentication system" --roles "ui-designer,security-expert,user-researcher"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---

@@ -14,11 +14,17 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)

 ## Usage
 ```bash
-/workflow:brainstorm:artifacts "<topic>"
+/workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
 ```

 ## Purpose
-**Specialized command for generating structured topic-framework.md documents** that provide discussion frameworks for role-based brainstorming analysis. Creates the foundation document that all role agents will reference.
+**Generate dynamic topic-framework.md tailored to selected roles**. Creates role-specific discussion frameworks that address relevant perspectives. If no roles specified, generates comprehensive framework covering common analysis areas.
+
+## Role-Based Framework Generation
+
+**Dynamic Generation**: Framework content adapts based on selected roles
+- **With roles**: Generate targeted discussion points for specified roles only
+- **Without roles**: Generate comprehensive framework covering all common areas

 ## Core Workflow

@@ -30,22 +36,28 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 - **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists
 - **Framework check**: Check if `topic-framework.md` exists (update vs create mode)

-**Phase 2: Interactive Topic Analysis**
+**Phase 2: Role Analysis** ⚠️ NEW
+- **Parse roles parameter**: Extract roles from `--roles "role1,role2,role3"` if provided
+- **Role validation**: Verify each role is valid (matches available role commands)
+- **Store role list**: Save selected roles to session metadata for reference
+- **Default behavior**: If no roles specified, use comprehensive coverage
+
+**Phase 3: Dynamic Topic Analysis**
 - **Scope definition**: Define topic boundaries and objectives
- **Stakeholder identification**: Identify key users and stakeholders
- **Requirements gathering**: Extract core requirements and constraints
- **Context collection**: Gather technical and business context
+- **Stakeholder identification**: Identify key users and stakeholders based on selected roles
+- **Requirements gathering**: Extract requirements relevant to selected roles
+- **Context collection**: Gather context appropriate for role perspectives

-**Phase 3: Structured Framework Generation**
- **Discussion points creation**: Generate 5 key discussion areas
- **Role-specific questions**: Create tailored questions for each relevant role
- **Framework document**: Generate structured `topic-framework.md`
- **Validation check**: Ensure framework completeness and clarity
+**Phase 4: Role-Specific Framework Generation**
+- **Discussion points creation**: Generate 3-5 discussion areas **tailored to selected roles**
+- **Role-targeted questions**: Create questions specifically for chosen roles
+- **Framework document**: Generate `topic-framework.md` with role-specific sections
+- **Validation check**: Ensure framework addresses all selected role perspectives

-**Phase 4: Update Mechanism**
- **Existing framework detection**: Check for existing framework
- **Incremental updates**: Add new discussion points if requested
- **Version tracking**: Maintain framework evolution history
+**Phase 5: Metadata Storage**
+- **Save role assignment**: Store selected roles in session metadata
+- **Framework versioning**: Track which roles framework addresses
+- **Update tracking**: Maintain role evolution if framework updated

 ## Implementation Standards

@@ -83,68 +95,181 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 └── workflow-session.json               # Framework metadata and role assignments
 ```

-**Topic Framework Template**:
+## Framework Template Structures

-### topic-framework.md Structure
+### Dynamic Role-Based Framework
+
+Framework content adapts based on `--roles` parameter:
+
+#### Option 1: Specific Roles Provided
 ```markdown
 # [Topic] - Discussion Framework

 ## Topic Overview
- **Scope**: [Clear topic boundaries and scope definition]
- **Objectives**: [Primary goals and expected outcomes]
- **Context**: [Relevant background and constraints]
- **Stakeholders**: [Key users, roles, and affected parties]
+- **Scope**: [Topic boundaries relevant to selected roles]
+- **Objectives**: [Goals from perspective of selected roles]
+- **Context**: [Background focusing on role-specific concerns]
+- **Target Roles**: ui-designer, system-architect, security-expert

-## Key Discussion Points
+## Role-Specific Discussion Points

-### 1. Core Requirements
+### For UI Designer
+1. **User Interface Requirements**
+   - What interface components are needed?
+   - What user interactions must be supported?
+   - What visual design considerations apply?
+
+2. **User Experience Challenges**
+   - What are the key user journeys?
+   - What accessibility requirements exist?
+   - How to balance aesthetics with functionality?
+
+### For System Architect
+1. **Architecture Decisions**
+   - What architectural patterns fit this solution?
+   - What scalability requirements exist?
+   - How does this integrate with existing systems?
+
+2. **Technical Implementation**
+   - What technology stack is appropriate?
+   - What are the performance requirements?
+   - What dependencies must be managed?
+
+### For Security Expert
+1. **Security Requirements**
+   - What are the key security concerns?
+   - What threat vectors must be addressed?
+   - What compliance requirements apply?
+
+2. **Security Implementation**
+   - What authentication/authorization is needed?
+   - What data protection mechanisms are required?
+   - How to handle security incidents?
+
+## Cross-Role Integration Points
+- How do UI decisions impact architecture?
+- How does architecture constrain UI possibilities?
+- What security requirements affect both UI and architecture?
+
+## Framework Usage
+**For Role Agents**: Address your specific section + integration points
+**Reference Format**: @../topic-framework.md in your analysis.md
+**Update Process**: Use /workflow:brainstorm:artifacts to update
+
+---
+*Generated for roles: ui-designer, system-architect, security-expert*
+*Last updated: [timestamp]*
+```
+
+#### Option 2: No Roles Specified (Comprehensive)
+```markdown
+# [Topic] - Discussion Framework
+
+## Topic Overview
+- **Scope**: [Comprehensive topic boundaries]
+- **Objectives**: [All-encompassing goals]
+- **Context**: [Full background and constraints]
+- **Stakeholders**: [All relevant parties]
+
+## Core Discussion Areas
+
+### 1. Requirements & Objectives
 - What are the fundamental requirements?
 - What are the critical success factors?
 - What constraints must be considered?
- What acceptance criteria define success?

-### 2. Technical Considerations
+### 2. Technical & Architecture
 - What are the technical challenges?
 - What architectural decisions are needed?
- What technology choices impact the solution?
 - What integration points exist?

-### 3. User Experience Factors
+### 3. User Experience & Design
 - Who are the primary users?
 - What are the key user journeys?
 - What usability requirements exist?
- What accessibility considerations apply?

-### 4. Implementation Challenges
- What are the main implementation risks?
- What dependencies exist?
+### 4. Security & Compliance
+- What security requirements exist?
+- What compliance considerations apply?
+- What data protection is needed?
+
+### 5. Implementation & Operations
+- What are the implementation risks?
 - What resources are required?
- What timeline constraints apply?
+- How will this be maintained?

-### 5. Success Metrics
- How will success be measured?
- What are the acceptance criteria?
- What performance requirements exist?
- What monitoring and analytics are needed?
-
-## Role-Specific Analysis Points
- **System Architect**: Architecture patterns, scalability, technology stack
- **Product Manager**: Business value, user needs, market positioning
- **UI Designer**: User experience, interface design, usability
- **Security Expert**: Security requirements, threat modeling, compliance
- **Data Architect**: Data modeling, processing workflows, analytics
- **Business Analyst**: Process optimization, cost-benefit, change management
-
-## Framework Usage Instructions
-**For Role Agents**: Address each discussion point from your role perspective
-**Reference Format**: Use @../topic-framework.md in your analysis.md
-**Update Process**: Use /workflow:brainstorm:artifacts to update framework
+## Available Role Perspectives
+Framework supports analysis from any of these roles:
+- system-architect, ui-designer, security-expert
+- user-researcher, product-manager, business-analyst
+- data-architect, innovation-lead, feature-planner

 ---
-*Generated by /workflow:brainstorm:artifacts*
+*Comprehensive framework - adaptable to any role*
 *Last updated: [timestamp]*
 ```

+## Role-Specific Content Generation
+
+### Available Roles and Their Focus Areas
+
+**Technical Roles**:
+- `system-architect`: Architecture patterns, scalability, technology stack, integration
+- `data-architect`: Data modeling, processing workflows, analytics, storage
+- `security-expert`: Security requirements, threat modeling, compliance, protection
+
+**Product & Design Roles**:
+- `ui-designer`: User interface, visual design, interaction patterns, accessibility
+- `user-researcher`: User needs, behavior analysis, usability testing, personas
+- `product-manager`: Business value, feature prioritization, market positioning, roadmap
+
+**Business Roles**:
+- `business-analyst`: Process optimization, requirements analysis, cost-benefit, ROI
+- `innovation-lead`: Emerging technologies, competitive advantage, transformation, trends
+- `feature-planner`: Feature specification, user stories, acceptance criteria, dependencies
+
+### Dynamic Discussion Point Generation
+
+**For each selected role, generate**:
+1. **2-3 core discussion areas** specific to that role's perspective
+2. **3-5 targeted questions** per discussion area
+3. **Cross-role integration points** showing how roles interact
+
+**Example mapping**:
+```javascript
+// If roles = ["ui-designer", "system-architect"]
+Generate:
+- UI Designer section: UI Requirements, UX Challenges
+- System Architect section: Architecture Decisions, Technical Implementation
+- Integration Points: UI↔Architecture dependencies
+```
+
+### Framework Generation Examples
+
+#### Example 1: Architecture-Heavy Topic
+```bash
+/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,security-expert"
+```
+**Generated framework focuses on**:
+- Service architecture and communication patterns
+- Data flow and storage strategies
+- Security boundaries and authentication
+
+#### Example 2: User-Focused Topic
+```bash
+/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,user-researcher,product-manager"
+```
+**Generated framework focuses on**:
+- Onboarding flow and UI components
+- User behavior and pain points
+- Business value and success metrics
+
+#### Example 3: Comprehensive Analysis
+```bash
+/workflow:brainstorm:artifacts "Build real-time collaboration feature"
+```
+**Generated framework covers** all aspects (no roles specified)
+
 ## Session Management ⚠️ CRITICAL
 - **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before processing
 - **Multiple sessions support**: Different Claude instances can have different active sessions
--- a/.claude/commands/workflow/brainstorm/auto-parallel.md
+++ b/.claude/commands/workflow/brainstorm/auto-parallel.md
@@ -40,7 +40,9 @@ bash($(cat "~/.claude/workflows/cli-templates/planning-roles/ui-designer.md"))
 The command follows a structured three-phase approach with dedicated document types:

 **Phase 1: Framework Generation** ⚠️ COMMAND EXECUTION
- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}"` using SlashCommand tool
+- **Role selection**: Auto-select 2-3 roles based on topic keywords (see Role Selection Logic)
+- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"` using SlashCommand tool
+- **Role-specific framework**: Generate framework with sections tailored to selected roles

 **Phase 2: Role Analysis Execution** ⚠️ PARALLEL AGENT ANALYSIS
 - **Parallel execution**: Multiple roles execute simultaneously for faster completion
@@ -58,15 +60,15 @@ The command follows a structured three-phase approach with dedicated document ty
 Auto command coordinates independent specialized commands:

 **Command Sequence**:
-1. **Generate Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}"`
-2. **Role Selection**: Auto-select 2-3 relevant roles based on topic keywords
-3. **Role Analysis**: Execute selected role commands in parallel
+1. **Role Selection**: Auto-select 2-3 relevant roles based on topic keywords
+2. **Generate Role-Specific Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"`
+3. **Parallel Role Analysis**: Execute selected role agents in parallel, each reading their specific framework section
 4. **Generate Synthesis**: Use SlashCommand to execute `/workflow:brainstorm:synthesis`

 **SlashCommand Integration**:
-1. **artifacts command**: Called via SlashCommand tool for framework generation
-2. **role commands**: Each role command operates in parallel with framework reference
-3. **synthesis command**: Called via SlashCommand tool for final integration
+1. **artifacts command**: Called via SlashCommand tool with `--roles` parameter for role-specific framework generation
+2. **role agents**: Each agent reads its dedicated section in the role-specific framework
+3. **synthesis command**: Called via SlashCommand tool for final integration with role-targeted insights
 4. **Command coordination**: SlashCommand handles execution and validation

 **Role Selection Logic**:
@@ -211,14 +213,14 @@ TodoWrite({
      activeForm: "Initializing brainstorming session"
    },
    {
-      content: "Execute artifacts command using SlashCommand for framework generation",
+      content: "Select roles based on topic keyword analysis",
      status: "pending",
-      activeForm: "Executing artifacts command for topic framework"
+      activeForm: "Selecting roles for brainstorming analysis"
    },
    {
-      content: "Select roles and create workflow-session.json with framework references",
+      content: "Execute artifacts command with selected roles for role-specific framework",
      status: "pending",
-      activeForm: "Selecting roles and creating session metadata"
+      activeForm: "Generating role-specific topic framework"
    },
    {
      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
--- a/.claude/commands/workflow/brainstorm/auto-squeeze.md
+++ b/.claude/commands/workflow/brainstorm/auto-squeeze.md
@@ -1,6 +1,6 @@
 ---
 name: auto-squeeze
-description: Sequential command coordination for brainstorming workflow commands
+description: Orchestrate 3-phase brainstorming workflow by executing commands sequentially
 usage: /workflow:brainstorm:auto-squeeze "<topic>"
 argument-hint: "topic or challenge description for coordinated brainstorming"
 examples:
@@ -10,187 +10,249 @@ examples:
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*)
 ---

-# Sequential Auto Brainstorming Coordination Command
+# Workflow Brainstorm Auto-Squeeze Command

-## Usage
-```bash
-/workflow:brainstorm:auto-squeeze "<topic>"
-```
+## Coordinator Role

-## Purpose
-**Sequential command coordination for brainstorming workflow** by calling existing brainstorm commands using SlashCommand tool. This command orchestrates the complete brainstorming workflow from framework generation to synthesis in sequential order.
+**This command is a pure orchestrator**: Execute brainstorming commands in sequence (artifacts → roles → synthesis), auto-select relevant roles, and ensure complete brainstorming workflow execution.

-## Command Coordination Workflow
+**Execution Flow**:
+1. Initialize TodoWrite → Execute Phase 1 (artifacts) → Validate framework → Update TodoWrite
+2. Select 2-3 relevant roles → Display selection → Execute Phase 2 (role analyses) → Update TodoWrite
+3. Execute Phase 3 (synthesis) → Validate outputs → Return summary
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
+2. **Auto-Select Roles**: Analyze topic keywords to select 2-3 most relevant roles (max 3)
+3. **Display Selection**: Show selected roles to user before execution
+4. **Sequential Execution**: Execute role commands one by one, not in parallel
+5. **Complete All Phases**: Do not return to user until synthesis completes
+6. **Track Progress**: Update TodoWrite after every command completion
+
+## 3-Phase Execution

 ### Phase 1: Framework Generation
-1. **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}"`
-2. **Verify framework creation**: Check for topic-framework.md existence
-3. **Session validation**: Ensure active session continuity

-### Phase 2: Role Analysis Coordination
-1. **Role selection**: Auto-select 2-3 relevant roles based on topic keywords
-2. **Display selected roles**: Clearly list the chosen roles before execution
-   ```
-   Selected roles for analysis:
-   - ui-designer (UI/UX perspective)
-   - system-architect (Technical architecture)
-   - security-expert (Security considerations)
-   ```
-3. **Sequential execution**: Call each role command using SlashCommand
-4. **Progress monitoring**: Track completion of each role analysis
-5. **Role execution order**:
-   - `/workflow:brainstorm:ui-designer` - UI/UX perspective
-   - `/workflow:brainstorm:system-architect` - Technical architecture
-   - `/workflow:brainstorm:security-expert` - Security considerations
+**Step 1.1: Role Selection**
+Auto-select 2-3 roles based on topic keywords (see Role Selection Logic below)

-### Phase 3: Synthesis Coordination
-1. **Completion verification**: Ensure all role analyses are complete
-2. **Call synthesis command**: Execute `/workflow:brainstorm:synthesis`
-3. **Final validation**: Verify synthesis document creation
+**Step 1.2: Generate Role-Specific Framework**
+**Command**: `SlashCommand(command="/workflow:brainstorm:artifacts \"[topic]\" --roles \"[role1,role2,role3]\"")`

-## Role Selection Logic
+**Input**: Selected roles from step 1.1

-### Keyword-Based Role Mapping
- **Technical & Architecture**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert
- **Product & UX**: `user|ui|ux|interface|design|product|feature` → ui-designer, user-researcher, product-manager
- **Business & Process**: `business|process|workflow|cost|innovation` → business-analyst, innovation-lead
- **Default fallback**: ui-designer if no clear match
+**Parse Output**:
+- Verify topic-framework.md created with role-specific sections

-### Auto-Selection Rules
- **Maximum 3 roles**: Select most relevant based on topic analysis
- **Priority ordering**: Most relevant role first
- **Coverage ensure**: Include complementary perspectives
+**Validation**:
+- File `.workflow/[session]/.brainstorming/topic-framework.md` exists
+- Contains sections for each selected role
+- Includes cross-role integration points

-## Implementation Protocol
+**TodoWrite**: Mark phase 1 completed, mark "Display selected roles" as in_progress

-### Sequential Command Execution
-```bash
-# Phase 1: Generate framework
-SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\"")
+---

-# Display selected roles
-echo "Selected roles for analysis:"
-echo "- ui-designer (UI/UX perspective)"
-echo "- system-architect (Technical architecture)"
-echo "- security-expert (Security considerations)"
+### Phase 2: Role Analysis Execution

-# Phase 2: Execute selected roles sequentially
-SlashCommand(command="/workflow:brainstorm:ui-designer")
-SlashCommand(command="/workflow:brainstorm:system-architect")
-SlashCommand(command="/workflow:brainstorm:security-expert")
+**Step 2.1: Role Selection**
+Use keyword analysis to auto-select 2-3 roles:

-# Phase 3: Generate synthesis
-SlashCommand(command="/workflow:brainstorm:synthesis")
+**Role Selection Logic**:
+- **Technical/Architecture keywords**: `architecture|system|performance|database|api|backend|scalability`
+  → system-architect, data-architect, security-expert
+- **UI/UX keywords**: `user|ui|ux|interface|design|frontend|experience`
+  → ui-designer, user-researcher
+- **Product/Business keywords**: `product|feature|business|workflow|process|customer`
+  → product-manager, business-analyst
+- **Security keywords**: `security|auth|permission|encryption|compliance`
+  → security-expert
+- **Innovation keywords**: `innovation|new|disrupt|transform|emerging`
+  → innovation-lead
+- **Default**: ui-designer (if no clear match)
+
+**Selection Rules**:
+- Maximum 3 roles
+- Select most relevant role first based on strongest keyword match
+- Include complementary perspectives (e.g., if system-architect selected, also consider security-expert)
+
+**Step 2.2: Display Selected Roles**
+Show selection to user before execution:
+```
+Selected roles for analysis:
+- ui-designer (UI/UX perspective)
+- system-architect (Technical architecture)
+- security-expert (Security considerations)
 ```

-### Progress Tracking
+**Step 2.3: Execute Role Commands Sequentially**
+Execute each selected role command one by one:
+
+**Commands**:
+- `SlashCommand(command="/workflow:brainstorm:ui-designer")`
+- `SlashCommand(command="/workflow:brainstorm:system-architect")`
+- `SlashCommand(command="/workflow:brainstorm:security-expert")`
+- `SlashCommand(command="/workflow:brainstorm:user-researcher")`
+- `SlashCommand(command="/workflow:brainstorm:product-manager")`
+- `SlashCommand(command="/workflow:brainstorm:business-analyst")`
+- `SlashCommand(command="/workflow:brainstorm:data-architect")`
+- `SlashCommand(command="/workflow:brainstorm:innovation-lead")`
+- `SlashCommand(command="/workflow:brainstorm:feature-planner")`
+
+**Validation** (after each role):
+- File `.workflow/[session]/.brainstorming/[role]/analysis.md` exists
+- Contains role-specific analysis
+
+**TodoWrite**: Mark each role task completed after execution, start next role as in_progress
+
+---
+
+### Phase 3: Synthesis Generation
+**Command**: `SlashCommand(command="/workflow:brainstorm:synthesis")`
+
+**Validation**:
+- File `.workflow/[session]/.brainstorming/synthesis-report.md` exists
+- Contains cross-references to role analyses using @ notation
+
+**TodoWrite**: Mark phase 3 completed
+
+**Return to User**:
+```
+Brainstorming complete for topic: [topic]
+Framework: .workflow/[session]/.brainstorming/topic-framework.md
+Roles analyzed: [role1], [role2], [role3]
+Synthesis: .workflow/[session]/.brainstorming/synthesis-report.md
+```
+
+## TodoWrite Pattern
+
 ```javascript
-TodoWrite({
-  todos: [
-    {
-      content: "Generate topic framework using artifacts command",
-      status: "in_progress",
-      activeForm: "Generating topic framework"
-    },
-    {
-      content: "Display selected roles: ui-designer, system-architect, security-expert",
-      status: "pending",
-      activeForm: "Displaying selected roles for analysis"
-    },
-    {
-      content: "Execute ui-designer role analysis",
-      status: "pending",
-      activeForm: "Executing ui-designer analysis"
-    },
-    {
-      content: "Execute system-architect role analysis",
-      status: "pending",
-      activeForm: "Executing system-architect analysis"
-    },
-    {
-      content: "Execute security-expert role analysis",
-      status: "pending",
-      activeForm: "Executing security-expert analysis"
-    },
-    {
-      content: "Generate synthesis report",
-      status: "pending",
-      activeForm: "Generating synthesis report"
-    }
-  ]
-});
+// Initialize (before Phase 1)
+TodoWrite({todos: [
+  {"content": "Generate topic framework", "status": "in_progress", "activeForm": "Generating topic framework"},
+  {"content": "Display selected roles", "status": "pending", "activeForm": "Displaying selected roles"},
+  {"content": "Execute ui-designer analysis", "status": "pending", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
+  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
+]})
+
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Generate topic framework", "status": "completed", "activeForm": "Generating topic framework"},
+  {"content": "Display selected roles", "status": "in_progress", "activeForm": "Displaying selected roles"},
+  {"content": "Execute ui-designer analysis", "status": "pending", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
+  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
+]})
+
+// After displaying roles
+TodoWrite({todos: [
+  {"content": "Generate topic framework", "status": "completed", "activeForm": "Generating topic framework"},
+  {"content": "Display selected roles", "status": "completed", "activeForm": "Displaying selected roles"},
+  {"content": "Execute ui-designer analysis", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
+  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
+]})
+
+// Continue pattern for each role and synthesis...
 ```

-### Verification Steps
-Between each phase:
-1. **Check command completion**: Verify previous command finished successfully
-2. **Validate outputs**: Ensure expected files were created
-3. **Update progress**: Mark current task complete, start next task
-4. **Error handling**: Stop workflow if any command fails
+## Data Flow
+
+```
+User Input (topic)
+    ↓
+Role Selection (analyze topic keywords)
+    ↓ Output: 2-3 selected roles (e.g., ui-designer, system-architect, security-expert)
+    ↓
+Phase 1: artifacts "topic" --roles "role1,role2,role3"
+    ↓ Input: topic + selected roles
+    ↓ Output: role-specific topic-framework.md
+    ↓
+Display: Show selected roles to user
+    ↓
+Phase 2: Execute each role command sequentially
+    ↓ Role 1 → reads role-specific section → analysis.md
+    ↓ Role 2 → reads role-specific section → analysis.md
+    ↓ Role 3 → reads role-specific section → analysis.md
+    ↓
+Phase 3: synthesis
+    ↓ Input: role-specific framework + all role analyses
+    ↓ Output: synthesis-report.md with role-targeted insights
+    ↓
+Return summary to user
+```
+
+**Session Context**: All commands use active brainstorming session, sharing:
+- Role-specific topic framework
+- Role-targeted analyses
+- Cross-role integration points
+- Synthesis with role-specific insights
+
+**Key Improvement**: Framework is generated with roles parameter, ensuring all discussion points are relevant to selected roles
+
+## Role Selection Examples
+
+### Example 1: UI-Focused Topic
+**Topic**: "Redesign user authentication interface"
+**Keywords detected**: user, interface, design
+**Selected roles**:
+- ui-designer (primary: UI/UX match)
+- user-researcher (secondary: user experience)
+- security-expert (complementary: auth security)
+
+### Example 2: Architecture Topic
+**Topic**: "Design scalable microservices architecture"
+**Keywords detected**: architecture, scalable, system
+**Selected roles**:
+- system-architect (primary: architecture match)
+- data-architect (secondary: scalability/data)
+- security-expert (complementary: system security)
+
+### Example 3: Business Process Topic
+**Topic**: "Optimize customer onboarding workflow"
+**Keywords detected**: workflow, process, customer
+**Selected roles**:
+- business-analyst (primary: process match)
+- product-manager (secondary: customer focus)
+- ui-designer (complementary: user experience)

 ## Error Handling

-### Command Failure Recovery
- **Framework generation fails**: Stop workflow, report error
- **Role analysis fails**: Continue with remaining roles, note failure
- **Synthesis fails**: Attempt retry once, then report partial completion
+- **Framework Generation Failure**: Stop workflow, report error, do not proceed to role selection
+- **Role Analysis Failure**: Log failure, continue with remaining roles, note in final summary
+- **Synthesis Failure**: Retry once, if still fails report partial completion with available analyses
+- **Session Error**: Report session issue, prompt user to check session status

-### Session Management
- **Active session required**: Use existing session or create new one
- **Session continuity**: Maintain same session throughout workflow
- **Multi-session handling**: Prompt user if multiple active sessions
-
-## Expected Output Structure
+## Output Structure

 ```
-.workflow/WFS-{session}/.brainstorming/
-├── topic-framework.md          # Generated by artifacts command
-├── ui-designer/
-│   └── analysis.md            # Generated by ui-designer command
-├── system-architect/
-│   └── analysis.md            # Generated by system-architect command
-├── security-expert/
-│   └── analysis.md            # Generated by security-expert command
-└── synthesis-report.md        # Generated by synthesis command
+.workflow/[session]/.brainstorming/
+├── topic-framework.md          # Phase 1 output
+├── [role1]/
+│   └── analysis.md            # Phase 2 output (role 1)
+├── [role2]/
+│   └── analysis.md            # Phase 2 output (role 2)
+├── [role3]/
+│   └── analysis.md            # Phase 2 output (role 3)
+└── synthesis-report.md        # Phase 3 output
 ```

-## Test Scenarios
+## Coordinator Checklist

-### Test Case 1: UI/UX Focus Topic
-**Topic**: "Redesign user authentication interface"
-**Expected roles**: ui-designer, user-researcher, security-expert
-**Validation**: Check UI-focused analysis in each role output
-
-### Test Case 2: Technical Architecture Topic
-**Topic**: "Design scalable microservices architecture"
-**Expected roles**: system-architect, data-architect, security-expert
-**Validation**: Check technical depth in architecture analysis
-
-### Test Case 3: Business Process Topic
-**Topic**: "Optimize customer onboarding workflow"
-**Expected roles**: business-analyst, product-manager, ui-designer
-**Validation**: Check business process focus in analysis
-
-## Quality Assurance
-
-### Command Integration Verification
- **All commands execute independently**: Each command handles its own validation
- **No direct dependencies**: Commands work with framework reference
- **Consistent session usage**: All commands use same session directory
- **Proper error propagation**: Failed commands don't break workflow
-
-### Output Quality Checks
- **Framework completeness**: topic-framework.md has all required sections
- **Role analysis depth**: Each role provides substantial analysis
- **Synthesis integration**: synthesis-report.md references all role analyses
- **Cross-references work**: @ notation links function correctly
-
-## Success Criteria
-1. **Complete workflow execution**: All phases complete without errors
-2. **Proper file generation**: All expected output files created
-3. **Content quality**: Each document contains substantial, relevant analysis
-4. **Integration validation**: Synthesis properly references all role analyses
-5. **Session consistency**: All outputs in correct session directory
-
---
-*Sequential command coordination for brainstorming workflow*
+✅ Initialize TodoWrite with framework + display + N roles + synthesis tasks
+✅ Execute Phase 1 (artifacts) immediately
+✅ Validate topic-framework.md exists
+✅ Analyze topic keywords for role selection
+✅ Auto-select 2-3 most relevant roles (max 3)
+✅ Display selected roles to user with rationale
+✅ Execute each role command sequentially
+✅ Validate each role's analysis.md after execution
+✅ Update TodoWrite after each role completion
+✅ Execute Phase 3 (synthesis) after all roles complete
+✅ Validate synthesis-report.md exists
+✅ Return summary with all generated files