Refactor workflow to replace synthesis-specification.md with role analysis documents

- Updated references in various workflow commands to utilize role analysis documents instead of synthesis-specification.md. - Modified CLI templates and command references to reflect the new architecture and document structure. - Introduced conflict-resolution command to analyze and resolve conflicts between implementation plans and existing codebase. - Deprecated synthesis role template and provided migration guidance for transitioning to the new role analysis approach.
2026-02-12 02:37:45 +08:00 · 2025-10-24 11:08:15 +08:00
parent ef187d3a4b
commit 57fa379e45
35 changed files with 1835 additions and 1271 deletions
--- a/.claude/commands/workflow/tools/concept-enhanced.md
+++ b/.claude/commands/workflow/tools/concept-enhanced.md
@@ -1,38 +1,37 @@
 ---
 name: concept-enhanced
-description: Enhanced intelligent analysis with parallel CLI execution and design blueprint generation
+description: Architecture validation and implementation enhancement with CLI-powered analysis
 argument-hint: "--session WFS-session-id --context path/to/context-package.json"
 examples:
  - /workflow:tools:concept-enhanced --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
  - /workflow:tools:concept-enhanced --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
 ---

-# Enhanced Analysis Command (/workflow:tools:concept-enhanced)
+# Architecture Validation Command (/workflow:tools:concept-enhanced)

 ## Overview
-Advanced solution design and feasibility analysis engine with parallel CLI execution. Processes standardized context packages to produce ANALYSIS_RESULTS.md focused on solution improvements, key design decisions, and critical insights.
+Architecture validation and implementation enhancement engine with CLI-powered analysis. Validates existing architectural approaches and enhances implementation details through Gemini/Codex analysis.

-**Scope**: Solution-focused technical analysis only. Does NOT generate task breakdowns or implementation plans.
+**Scope**: Validation and enhancement only. Does NOT generate new designs, task breakdowns, or implementation plans.

-**Usage**: Standalone command or integrated into `/workflow:plan`. Accepts context packages and orchestrates Gemini/Codex for comprehensive analysis.
+**Usage**: Optional enhancement in `/workflow:plan` (requires `--cli-enhance` flag). Accepts context packages and validates architectural soundness.

 ## Core Philosophy & Responsibilities
- **Agent Coordination**: Delegate analysis execution to specialized agent (cli-execution-agent)
- **Solution-Focused Analysis**: Emphasize design decisions, architectural rationale, and critical insights (exclude task planning)
- **Context-Driven**: Parse and validate context-package.json for precise analysis
- **Agent-Driven Tool Selection**: Agent autonomously selects Gemini/Codex based on task complexity
- **Solution Design**: Evaluate architecture, identify key design decisions with rationale
- **Feasibility Assessment**: Analyze technical complexity, risks, implementation readiness
- **Optimization Recommendations**: Performance, security, and code quality improvements
+- **Agent Coordination**: Delegate validation execution to specialized agent (cli-execution-agent)
+- **Validation-Focused**: Verify architectural soundness, identify risks and quality issues
+- **Context-Driven**: Parse and validate context-package.json for precise validation
+- **Agent-Driven Tool Selection**: Agent autonomously selects Gemini/Codex based on validation needs
+- **Architecture Validation**: Verify design decisions, assess technical feasibility and risks
+- **Implementation Enhancement**: Identify optimization opportunities for performance, security, and quality
 - **Output Validation**: Verify ANALYSIS_RESULTS.md generation and quality
- **Single Output**: Generate only ANALYSIS_RESULTS.md with technical analysis
+- **Single Output**: Generate only ANALYSIS_RESULTS.md with validation findings and enhancement recommendations

 ## Analysis Strategy Selection

 **Agent-Driven Strategy**: cli-execution-agent autonomously determines tool selection based on:
 - **Task Complexity**: Number of modules, integration scope, technical depth
 - **Tech Stack**: Frontend (Gemini-focused), Backend (Codex-preferred), Fullstack (hybrid)
- **Analysis Focus**: Architecture design (Gemini), Feasibility validation (Codex), Performance optimization (both)
+- **Validation Focus**: Architecture validation (Gemini), Feasibility verification (Codex), Quality assessment (both)

 **Complexity Tiers** (Agent decides internally):
 - **Simple (≤3 modules)**: Gemini-only analysis
@@ -140,16 +139,16 @@ Generate final ANALYSIS_RESULTS.md and report completion status:

 **Template Reference**: `~/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt`

-Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design decisions, and critical insights** (NOT task planning).
+Generated ANALYSIS_RESULTS.md focuses on **validation findings, quality assessment, and enhancement recommendations** (NOT new designs or task planning).

 ### Required Structure (7 Sections)

-1. **Executive Summary**: Analysis focus, tools used, overall assessment (X/5), recommendation status
+1. **Executive Summary**: Validation focus, tools used, overall assessment (X/5), recommendation status
 2. **Current State Analysis**: Architecture overview, compatibility/dependencies, critical findings
-3. **Proposed Solution Design**: Core principles, system design, key decisions with rationale, technical specs
-4. **Implementation Strategy**: Development approach, code modification targets, feasibility assessment, risk mitigation
-5. **Solution Optimization**: Performance, security, code quality recommendations
-6. **Critical Success Factors**: Technical requirements, quality metrics, success validation
+3. **Architecture Validation**: Verify design soundness, assess feasibility, identify risks with rationale
+4. **Implementation Enhancement**: Code quality improvements, optimization opportunities, risk mitigation
+5. **Quality Optimization**: Performance, security, code quality recommendations
+6. **Critical Success Factors**: Technical requirements, quality metrics, validation criteria
 7. **Reference Information**: Tool analysis summary, context & resources

 ### Key Requirements
@@ -159,11 +158,11 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec
 - New files: `file` only (e.g., `src/auth/PasswordReset.ts`)
 - Unknown lines: `file:function:*`

-**Key Design Decisions** (minimum 2):
- Decision statement
- Rationale (why this approach)
- Alternatives considered (tradeoffs)
- Impact (implications on architecture)
+**Validation Findings** (minimum 2):
+- Finding statement (what was validated/discovered)
+- Assessment (risks, quality issues, improvement opportunities)
+- Recommendations (specific actions to address findings)
+- Impact (implications on implementation)

 **Assessment Scores** (1-5 scale):
 - Conceptual Integrity, Architectural Soundness, Technical Feasibility, Implementation Readiness
@@ -171,10 +170,11 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec
 - Final Recommendation: PROCEED | PROCEED_WITH_MODIFICATIONS | RECONSIDER | REJECT

 ### Content Focus
- ✅ Solution improvements and architectural decisions
- ✅ Design rationale, alternatives, and tradeoffs
- ✅ Risk assessment with mitigation strategies
- ✅ Optimization opportunities (performance, security, quality)
+- ✅ Validation findings and quality assessment
+- ✅ Enhancement opportunities with specific recommendations
+- ✅ Risk identification and mitigation strategies
+- ✅ Optimization recommendations (performance, security, quality)
+- ❌ New design proposals or architectural changes
 - ❌ Task lists or implementation steps
 - ❌ Code examples or snippets
 - ❌ Project management timelines
@@ -213,11 +213,11 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec
 **Quality Checks**: Completeness, consistency, feasibility validation

 **Success Criteria**:
- ✅ Solution-focused analysis (design decisions, critical insights, NO task planning)
+- ✅ Validation-focused analysis (quality assessment, enhancement recommendations, NO new designs or task planning)
 - ✅ Single output file only (ANALYSIS_RESULTS.md)
- ✅ Design decision depth with rationale/alternatives/tradeoffs
- ✅ Feasibility assessment (complexity, risks, readiness)
- ✅ Optimization strategies (performance, security, quality)
+- ✅ Validation findings depth with assessment/recommendations/impact
+- ✅ Quality assessment (risks, improvement opportunities, readiness)
+- ✅ Enhancement strategies (performance, security, quality optimization)
 - ✅ Agent-driven tool selection (autonomous Gemini/Codex execution)
 - ✅ Robust error handling (validation, retry, graceful degradation)
 - ✅ Confidence scoring with clear recommendation status
@@ -225,5 +225,5 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec

 ## Related Commands
 - `/context:gather` - Generate context packages required by this command
- `/workflow:plan` - Call this command for analysis
- `/task:create` - Create specific tasks based on analysis results
+- `/workflow:plan --cli-enhance` - Optionally call this command for validation enhancement
+- `/task:create` - Create specific tasks based on validation results
--- a/.claude/commands/workflow/tools/conflict-resolution.md
+++ b/.claude/commands/workflow/tools/conflict-resolution.md
@@ -0,0 +1,365 @@
+---
+name: conflict-resolution
+description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis
+argument-hint: "--session WFS-session-id --context path/to/context-package.json"
+examples:
+  - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
+  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
+---
+
+# Conflict Resolution Command (/workflow:tools:conflict-resolution)
+
+## Overview
+Analyzes potential conflicts between implementation plan and existing codebase, generating multiple resolution strategies for user selection.
+
+**Trigger Condition**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
+
+**Scope**: Conflict detection and resolution strategy generation only. Does NOT modify code or generate tasks.
+
+**Usage**: Automatically triggered in `/workflow:plan` Phase 3 when conflict risk detected.
+
+## Core Philosophy & Responsibilities
+- **Conflict Detection**: Analyze plan vs existing code architecture inconsistencies
+- **Multi-Strategy Generation**: Generate 2-4 resolution options per conflict
+- **CLI-Powered Analysis**: Use Gemini/Qwen/Codex for deep code analysis
+- **Graceful Fallback**: Use Claude analysis if CLI tools unavailable
+- **User Decision**: Present strategies for user selection, never auto-apply
+- **Single Output**: Generate CONFLICT_RESOLUTION.md with findings and options
+
+## Conflict Detection Categories
+
+**Architecture Conflicts**:
+- New architecture incompatible with existing patterns
+- Module structure changes affecting existing components
+- Design pattern migrations required
+
+**API & Interface Conflicts**:
+- Breaking changes to existing API contracts
+- Function signature modifications
+- Public interface changes affecting dependents
+
+**Data Model Conflicts**:
+- Database schema modifications
+- Data type changes breaking compatibility
+- Migration requirements for existing data
+
+**Dependency Conflicts**:
+- Version conflicts with existing dependencies
+- New dependencies incompatible with current setup
+- Breaking changes in dependency updates
+
+## Execution Lifecycle
+
+### Phase 1: Validation & Trigger Check
+1. **Session Validation**: Verify `.workflow/{session_id}/` exists
+2. **Context Package Loading**: Read and parse context-package.json
+3. **Conflict Risk Check**:
+   ```javascript
+   if (context_package.conflict_detection.conflict_risk in ["none", "low"]) {
+     SKIP: "No significant conflicts detected"
+     EXIT
+   }
+   ```
+4. **Agent Preparation**: Prepare agent task prompt with conflict analysis requirements
+
+### Phase 2: Agent-Delegated Conflict Analysis
+
+**Agent Invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Detect and analyze code conflicts",
+  prompt=`
+## Execution Context
+
+**Session ID**: {session_id}
+**Mode**: Conflict Detection and Resolution Strategy Generation
+**Conflict Risk**: {conflict_risk}
+
+## Input Context
+
+**Context Package**: {context_path}
+**Existing Files**: {existing_files_list}
+**Affected Modules**: {affected_modules}
+
+## Analysis Task
+
+### Step 1: Load Existing Codebase Context
+1. **Load Existing Files** (from context package existing_files)
+   - Read all files listed in conflict_detection.existing_files
+   - Analyze current architecture patterns
+   - Identify current API contracts and interfaces
+
+2. **Load Plan Requirements** (from session context)
+   - Read .workflow/{session_id}/.brainstorming/*/analysis.md (if exists)
+   - Extract requirements and design decisions
+   - Identify planned changes
+
+### Step 2: CLI-Powered Conflict Analysis
+Execute conflict analysis using CLI tools:
+
+**Primary Tool - Gemini Analysis**:
+\`\`\`bash
+cd {project_root} && gemini -p "
+PURPOSE: Analyze conflicts between plan and existing code
+TASK:
+• Compare existing architecture with planned changes
+• Identify API contract breaking changes
+• Detect data model incompatibilities
+• Assess dependency conflicts
+MODE: analysis
+CONTEXT: @{existing_files_pattern} @.workflow/{session_id}/**/*
+EXPECTED: Conflict list with severity and affected areas
+RULES: Focus on breaking changes and migration complexity
+"
+\`\`\`
+
+**Fallback - Qwen Analysis** (if Gemini unavailable):
+Same prompt structure, replace 'gemini' with 'qwen'
+
+**Fallback - Claude Analysis** (if CLI unavailable):
+- Manual file reading and comparison
+- Pattern matching for common conflict types
+- Heuristic-based conflict detection
+
+### Step 3: Generate Resolution Strategies
+For each detected conflict, generate 2-4 resolution options:
+
+**Strategy Template**:
+```markdown
+### Conflict: {conflict_name}
+**Severity**: Critical | High | Medium
+**Category**: Architecture | API | Data Model | Dependency
+**Affected Files**: {file_list}
+**Impact**: {impact_description}
+
+#### Option 1: {strategy_name}
+**Approach**: {brief_description}
+**Pros**:
+- {advantage_1}
+- {advantage_2}
+**Cons**:
+- {disadvantage_1}
+- {disadvantage_2}
+**Effort**: Low | Medium | High
+**Risk**: Low | Medium | High
+
+#### Option 2: {strategy_name}
+...
+
+**Recommended**: Option {N} - {rationale}
+```
+
+### Step 4: Generate CONFLICT_RESOLUTION.md
+Create comprehensive conflict resolution document:
+
+**Output Location**: \`.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md\`
+
+**Required Structure**:
+1. **Executive Summary**: Total conflicts, severity distribution, overall risk
+2. **Conflict Analysis**: Detailed per-conflict analysis with categories
+3. **Resolution Strategies**: Multiple options per conflict with pros/cons
+4. **Recommended Actions**: Prioritized recommendations with rationale
+5. **Migration Considerations**: Data/API migration requirements if any
+
+### Output Requirements
+
+**Quality Standards**:
+- Minimum 2 resolution options per conflict
+- Clear pros/cons for each strategy
+- Effort and risk estimates included
+- Recommended strategy with clear rationale
+- Actionable migration steps if required
+
+## Output
+Generate CONFLICT_RESOLUTION.md and report completion status:
+- Conflicts detected: {count}
+- Severity distribution: Critical: {N}, High: {N}, Medium: {N}
+- Resolution strategies: {total_options}
+- Output location: .workflow/{session_id}/.process/CONFLICT_RESOLUTION.md
+\`
+)
+```
+
+**Agent Execution Flow** (Internal to cli-execution-agent):
+1. Parse session ID and context path, load context-package.json
+2. Check conflict_risk, exit if none/low
+3. Load existing codebase files from conflict_detection.existing_files
+4. Load plan requirements from session brainstorming artifacts
+5. Execute CLI tool analysis (Gemini/Qwen/Claude fallback)
+6. Parse conflict findings from CLI output
+7. Generate resolution strategies (2-4 options per conflict)
+8. Create CONFLICT_RESOLUTION.md with structured findings
+9. Verify output file exists at correct path
+10. Return execution log path
+
+**Command Execution**: Launch agent via Task tool, wait for completion
+
+### Phase 3: Output Validation
+1. **File Verification**: Confirm `.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md` exists
+2. **Content Validation**: Verify required sections present
+3. **Strategy Quality**: Ensure minimum 2 options per conflict
+4. **Agent Log**: Retrieve agent execution log from `.workflow/{session_id}/.chat/`
+5. **Success Criteria**: File exists, contains all required sections, strategies actionable
+
+## CONFLICT_RESOLUTION.md Format
+
+**Template Reference**: Resolution document focuses on **conflict identification, impact analysis, and strategic options** (NOT implementation).
+
+### Required Structure
+
+```markdown
+# Conflict Resolution Report
+
+**Session**: WFS-{session-id}
+**Generated**: {timestamp}
+**Conflict Risk**: {medium|high}
+**Total Conflicts**: {count}
+
+## Executive Summary
+
+**Overall Assessment**: {summary_paragraph}
+
+**Severity Distribution**:
+- Critical: {count} - Blocking issues requiring immediate resolution
+- High: {count} - Significant issues affecting core functionality
+- Medium: {count} - Moderate issues with workarounds available
+
+**Recommended Priority**: {conflict_id_1}, {conflict_id_2}, ...
+
+---
+
+## Conflict Analysis
+
+### Conflict 1: {conflict_name}
+**ID**: CON-001
+**Severity**: Critical | High | Medium
+**Category**: Architecture | API | Data Model | Dependency
+**Affected Files**:
+- {file_1}
+- {file_2}
+
+**Description**: {detailed_conflict_description}
+
+**Impact Analysis**:
+- **Scope**: {which_modules_affected}
+- **Backward Compatibility**: {yes/no/partial}
+- **Migration Required**: {yes/no}
+- **Estimated Effort**: {person-days}
+
+#### Resolution Strategies
+
+##### Option 1: {strategy_name}
+**Approach**: {implementation_approach}
+
+**Pros**:
+- {advantage_1}
+- {advantage_2}
+
+**Cons**:
+- {disadvantage_1}
+- {disadvantage_2}
+
+**Implementation Complexity**: Low | Medium | High
+**Risk Level**: Low | Medium | High
+**Estimated Effort**: {time_estimate}
+
+##### Option 2: {strategy_name}
+...
+
+**Recommended Strategy**: Option {N}
+**Rationale**: {why_this_option_is_best}
+
+---
+
+## Recommended Actions
+
+### Priority 1: Address Critical Conflicts
+1. {conflict_id}: {brief_action} - {recommended_strategy}
+2. ...
+
+### Priority 2: Resolve High-Severity Issues
+1. {conflict_id}: {brief_action} - {recommended_strategy}
+2. ...
+
+### Priority 3: Handle Medium Issues
+1. {conflict_id}: {brief_action} - {recommended_strategy}
+2. ...
+
+## Migration Considerations
+
+**Data Migration**:
+- {migration_task_1}
+- {migration_task_2}
+
+**API Versioning**:
+- {versioning_strategy}
+
+**Rollback Strategy**:
+- {rollback_plan}
+
+---
+
+## Next Steps
+
+**Before Implementation**:
+1. Review and select resolution strategies
+2. Update IMPL_PLAN.md with conflict resolution decisions
+3. Validate migration requirements
+
+**Proceed to**:
+- /workflow:plan continue → Proceed with task generation
+```
+
+### Content Focus
+- ✅ Conflict detection with severity classification
+- ✅ Multiple resolution strategies per conflict
+- ✅ Pros/cons analysis for each strategy
+- ✅ Effort and risk estimates
+- ✅ Migration considerations
+- ❌ Direct code changes or patches
+- ❌ Implementation details (save for IMPL_PLAN)
+- ❌ Task breakdowns (handled by task generation)
+
+## Execution Management
+
+### Error Handling & Recovery
+1. **Pre-execution**: Verify conflict_risk warrants execution
+2. **Agent Monitoring**: Track agent execution status via Task tool
+3. **Validation**: Check CONFLICT_RESOLUTION.md generation on completion
+4. **Error Recovery**:
+   - Agent execution failure → report error, check agent logs
+   - Missing output file → retry agent execution once
+   - CLI tool failure → fallback to Claude analysis
+5. **Graceful Degradation**: If all analysis methods fail, generate basic conflict report from heuristics
+
+## Integration & Success Criteria
+
+### Input/Output Interface
+**Input**:
+- `--session` (required): Session ID (e.g., WFS-auth)
+- `--context` (required): Context package path
+- Context package must have conflict_risk ≥ medium
+
+**Output**:
+- Single file: `CONFLICT_RESOLUTION.md` at `.workflow/{session_id}/.process/`
+- No code modifications
+
+### Quality & Success Validation
+**Quality Checks**: Completeness, strategy diversity, actionability
+
+**Success Criteria**:
+- ✅ Conflict detection complete (all categories scanned)
+- ✅ Minimum 2 resolution strategies per conflict
+- ✅ Clear pros/cons for each strategy
+- ✅ Effort and risk estimates provided
+- ✅ Recommended strategy with rationale
+- ✅ Migration considerations documented
+- ✅ CLI-powered analysis (with fallback handling)
+- ✅ Robust error handling (validation, retry, degradation)
+- ✅ Agent execution log saved to session chat directory
+
+## Related Commands
+- `/context:gather` - Generates conflict_detection data required by this command
+- `/workflow:plan` - Automatically calls this command when conflict_risk ≥ medium
+- `/task:create` - Creates tasks based on selected resolution strategies
--- a/.claude/commands/workflow/tools/context-gather.md
+++ b/.claude/commands/workflow/tools/context-gather.md
@@ -158,6 +158,36 @@ Task(
 #### Step 4: Context Packaging
 Generate standardized context-package.json following the format below

+#### Step 5: Conflict Detection & Risk Assessment
+**Purpose**: Analyze existing codebase to determine conflict risk level
+
+1. **Existing Code Detection**
+   - Count relevant existing source files discovered in Step 2
+   - Identify modules that overlap with task scope
+   - Flag existence of implementations related to task keywords
+
+2. **Architecture Analysis**
+   - Compare task requirements with existing architecture patterns
+   - Identify potential architectural changes required
+   - Detect breaking changes to current structure
+
+3. **API & Dependency Analysis**
+   - Check for existing API endpoints/contracts that may change
+   - Identify shared dependencies and interface changes
+   - Detect potential breaking changes to public APIs
+
+4. **Data Model Analysis**
+   - Identify existing data models/schemas in task scope
+   - Check for schema modification requirements
+   - Detect potential data migration needs
+
+5. **Risk Level Calculation**
+   Calculate conflict_risk based on:
+   - **none**: No existing code, new feature/module
+   - **low**: < 5 existing files, minimal changes
+   - **medium**: 5-15 existing files OR architectural changes OR API changes
+   - **high**: >15 existing files OR data model changes OR breaking changes
+
 ### Required Output

 **Output Location**: \`.workflow/{session-id}/.process/context-package.json\`
@@ -222,6 +252,23 @@ Generate standardized context-package.json following the format below
    "docs_files": 4,
    "config_files": 2,
    "test_files": 1
+  },
+  "conflict_detection": {
+    "conflict_risk": "medium",
+    "existing_files": [
+      "src/auth/AuthService.ts",
+      "src/models/User.ts",
+      "src/middleware/auth.ts"
+    ],
+    "has_existing_code": true,
+    "affected_modules": ["auth", "user-model"],
+    "detection_criteria": {
+      "existing_code_count": 8,
+      "architecture_changes": false,
+      "api_changes": true,
+      "data_model_changes": false
+    },
+    "risk_rationale": "Medium risk due to existing auth code and potential API changes"
  }
 }
 \`\`\`
--- a/.claude/commands/workflow/tools/task-generate-agent.md
+++ b/.claude/commands/workflow/tools/task-generate-agent.md
@@ -301,7 +301,7 @@ Before completion, verify:

 Generate all three documents and report completion status:
 - Task JSON files created: N files
- Artifacts integrated: synthesis-spec, topic-framework, N role analyses
+- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
 - MCP enhancements: code-index, exa-research
 - Session ready for execution: /workflow:execute
 `
--- a/.claude/commands/workflow/tools/task-generate-tdd.md
+++ b/.claude/commands/workflow/tools/task-generate-tdd.md
@@ -79,7 +79,7 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
 3. **Artifact Discovery**
   - If artifact inventory in memory → Skip scanning
   - Else: Scan `.workflow/{session_id}/.brainstorming/` directory
-   - Detect: synthesis-specification.md, topic-framework.md, role analyses
+   - Detect: role analysis documents, guidance-specification.md, role analyses

 ### Phase 2: TDD Task JSON Generation

@@ -283,7 +283,7 @@ tdd_workflow: true

 ## 3. Brainstorming Artifacts Reference
 - Artifact Usage Strategy
-  - synthesis-specification.md (primary reference)
+  - role analysis documents (primary reference)
  - test-context-package.json (test patterns)
  - context-package.json (smart context)
  - ANALYSIS_RESULTS.md (technical analysis)
--- a/.claude/commands/workflow/tools/task-generate.md
+++ b/.claude/commands/workflow/tools/task-generate.md
@@ -38,7 +38,7 @@ When the `--cli-execute` flag is used, each step in `implementation_approach` **
 This command is built on a set of core principles to ensure efficient and reliable task generation.

 - **Analysis-Driven**: All generated tasks originate from `ANALYSIS_RESULTS.md`, ensuring a direct link between analysis and implementation
- **Artifact-Aware**: Automatically detects and integrates brainstorming outputs (`synthesis-specification.md`, role analyses) to enrich task context
+- **Artifact-Aware**: Automatically detects and integrates brainstorming outputs (role analyses, guidance-specification.md) to enrich task context
 - **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
 - **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task
 - **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
@@ -53,7 +53,7 @@ The command follows a streamlined, three-step process to convert analysis into e
 The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory.
 1.  **Session Validation**: Loads and validates the session from `.workflow/{session_id}/workflow-session.json`.
 2.  **Analysis Loading**: Reads the primary input, `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`.
-3.  **Artifact Discovery**: Scans the `.workflow/{session_id}/.brainstorming/` directory to find `synthesis-specification.md`, `topic-framework.md`, and various role analyses.
+3.  **Artifact Discovery**: Scans the `.workflow/{session_id}/.brainstorming/` directory to find `guidance-specification.md` and various role analyses ([role]/analysis*.md).

 ### Step 2: Task Decomposition & Grouping
 Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
@@ -188,9 +188,9 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
    "shared_context": {"tech_stack": [], "conventions": []},
    "artifacts": [
      {
-        "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
+        "path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis*.md",
        "priority": "highest",
-        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
+        "usage": "Role-specific insights and requirements from brainstorming (may have multiple files per role: analysis.md OR analysis-1/2/3.md). Common roles: product-manager (user stories, business requirements), system-architect (ADRs, APIs, architecture), ui-designer (design tokens, layouts), data-architect (data models, schemas), ux-expert (user journeys)"
      },
      {
        "path": ".workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md",
@@ -203,13 +203,8 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
        "usage": "Smart context with focus paths, module structure, dependency graph, existing patterns. Use for: environment setup, dependency resolution, pattern discovery"
      },
      {
-        "path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis*.md",
-        "priority": "high",
-        "usage": "Technical/design/business details from specific roles (may have multiple files: analysis.md OR analysis-1/2/3.md). Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)"
-      },
-      {
-        "path": ".workflow/WFS-[session]/.brainstorming/topic-framework.md",
-        "priority": "low",
+        "path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md",
+        "priority": "medium",
        "usage": "Discussion context and framework structure"
      }
    ]
@@ -217,19 +212,20 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
  "flow_control": {
    "pre_analysis": [
      {
-        "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification",
+        "step": "load_role_analyses",
+        "action": "Load role analysis documents from brainstorming",
        "commands": [
-          "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'not found')",
-          "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)"
+          "bash(ls .workflow/WFS-[session]/.brainstorming/*/analysis*.md 2>/dev/null || echo 'not found')",
+          "Glob(.workflow/WFS-[session]/.brainstorming/*/analysis*.md)",
+          "Read(each discovered role analysis file)"
        ],
-        "output_to": "synthesis_specification",
+        "output_to": "role_analyses",
        "on_error": "skip_optional"
      },
      {
        "step": "load_role_analysis_artifacts",
        "action": "Load role-specific analysis documents for technical details (supports multiple files per role)",
-        "note": "These artifacts contain implementation details not in synthesis. Consult when needing: API schemas, caching configs, design tokens, ADRs, performance metrics. Each role may have analysis.md OR analysis-1/2/3.md.",
+        "note": "These artifacts contain role-specific implementation details. Consult when needing: API schemas, caching configs, design tokens, ADRs, performance metrics. Each role may have analysis.md OR analysis-1/2/3.md.",
        "commands": [
          "bash(find .workflow/WFS-[session]/.brainstorming/ -name 'analysis*.md' 2>/dev/null | sort | head -24)",
          "Read(.workflow/WFS-[session]/.brainstorming/system-architect/analysis.md)",
@@ -265,7 +261,7 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
        "action": "Analyze existing code patterns and identify modification targets",
        "commands": [
          "bash(cd \"[focus_paths]\")",
-          "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")"
+          "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")"
        ],
        "output_to": "task_context_with_targets",
        "on_error": "fail"
@@ -274,23 +270,23 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
    "implementation_approach": [
      {
        "step": 1,
-        "title": "Implement task following synthesis specification",
-        "description": "Implement '[title]' following this priority: 1) synthesis-specification.md (primary requirements), 2) ANALYSIS_RESULTS.md (technical guidance and risk mitigation from planning phase), 3) context-package.json (smart context and patterns), 4) role artifacts (detailed specs). Consult ANALYSIS_RESULTS.md for optimization strategies, performance considerations, and architecture review insights before implementation.",
+        "title": "Implement task following role analyses and technical guidance",
+        "description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements and design specs from brainstorming), 2) ANALYSIS_RESULTS.md (technical guidance and risk mitigation from planning phase), 3) context-package.json (smart context and patterns). Consult ANALYSIS_RESULTS.md for optimization strategies, performance considerations, and architecture review insights before implementation.",
        "modification_points": [
-          "Apply consolidated requirements from synthesis-specification.md",
+          "Apply requirements from role analysis documents",
          "Follow technical guidelines from ANALYSIS_RESULTS.md",
          "Use context-package.json for focus paths and dependency resolution",
-          "Consult role artifacts for implementation details when needed",
+          "Consult specific role artifacts for implementation details when needed",
          "Integrate with existing patterns"
        ],
        "logic_flow": [
-          "Load synthesis specification (requirements baseline)",
+          "Load role analyses (requirements and design decisions from brainstorming)",
          "Load ANALYSIS_RESULTS.md (technical guidance and risk mitigation strategies)",
          "Load context-package.json (smart context: focus paths, dependencies, existing patterns)",
-          "Extract requirements and design decisions",
+          "Extract requirements and design decisions from role documents",
          "Review technical analysis and optimization strategies from ANALYSIS_RESULTS.md",
          "Identify modification targets using context package",
-          "Implement following specification and technical guidance",
+          "Implement following role requirements and technical guidance",
          "Apply optimization patterns from ANALYSIS_RESULTS.md",
          "Consult role artifacts for detailed specifications when needed",
          "Validate against acceptance criteria"
@@ -337,10 +333,10 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).

 ### CCW Workflow Context
 **Phase Progression**:
- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
+- ✅ Phase 1: Brainstorming (role analyses clarified and refined)
 - ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
 - ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
+- ✅ Phase 4: Concept Verification (integrated in brainstorming phase | skipped)
 - ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)

 **Quality Gates**:
@@ -378,12 +374,12 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 ## 3. Brainstorming Artifacts Reference

 ### Artifact Usage Strategy
-**Primary Reference (synthesis-specification.md)**:
- **What**: Comprehensive implementation blueprint from multi-role synthesis
- **When**: Every task references this first for requirements and design decisions
- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
+**Primary Reference (Role Analyses)**:
+- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights
+- **When**: Every task references relevant role analyses for requirements and design decisions
+- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
+- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
+- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning

 **Context Intelligence (context-package.json)**:
 - **What**: Smart context gathered by CCW's context-gather phase
@@ -393,25 +389,27 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).

 **Technical Analysis (ANALYSIS_RESULTS.md)**:
 - **What**: Gemini/Qwen/Codex parallel analysis results
- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
+- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns, cross-role synthesis
 - **Usage**: Referenced in task planning for technical guidance and risk mitigation
- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
+- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence and cross-role integration

-### Integrated Specifications (Highest Priority)
- **synthesis-specification.md**: Comprehensive implementation blueprint
-  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
+### Role Analysis Documents (Highest Priority)
+Role analyses provide specialized perspectives on the implementation:
+- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies
+- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns
+- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements
+- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics
+- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies
+- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns

 ### Supporting Artifacts (Reference)
 - **topic-framework.md**: Role-specific discussion points and analysis framework
- **system-architect/analysis.md**: Detailed architecture specifications
- **ui-designer/analysis.md**: Layout and component specifications
- **product-manager/analysis.md**: Product vision and user stories

 **Artifact Priority in Development**:
-1. synthesis-specification.md (primary reference for all tasks)
-2. context-package.json (smart context for execution environment)
-3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
-4. Role-specific analyses (fallback for detailed specifications)
+1. Role analysis.md files (primary requirements and design specs from brainstorming)
+2. ANALYSIS_RESULTS.md (technical analysis, optimization strategies, and cross-role synthesis from planning)
+3. context-package.json (smart context for execution environment)
+4. topic-framework.md (discussion framework structure)

 ## 4. Implementation Strategy

@@ -428,7 +426,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).

 ### Architectural Approach
 **Key Architecture Decisions**:
- [ADR references from synthesis]
+- [ADR references from role analyses]
 - [Justification for architecture patterns]

 **Integration Strategy**:
@@ -520,7 +518,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 ## 8. Success Criteria

 **Functional Completeness**:
- [ ] All requirements from synthesis-specification.md implemented
+- [ ] All requirements from role analysis documents implemented
 - [ ] All acceptance criteria from task.json files met

 **Technical Quality**:
@@ -534,7 +532,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - [ ] Documentation complete

 **Business Metrics**:
- [ ] [Key business metrics from synthesis]
+- [ ] [Key business metrics from role analyses]
 ```

 ### 6.3. TODO_LIST.md Structure
@@ -567,10 +565,9 @@ The command organizes outputs into a standard directory structure.
 │   ├── IMPL-1.json                  # Container task
 │   ├── IMPL-1.1.json                # Leaf task with flow_control
 │   └── IMPL-1.2.json                # Leaf task with flow_control
-├── .brainstorming/                  # Input artifacts
-│   ├── synthesis-specification.md
+├── .braguidance-specification              # Input artifacts
 │   ├── topic-framework.md
-│   └── {role}/analysis.md
+│   └── {role}/analysis*.md          # Role analyses (may have multiple files per role)
 └── .process/
    ├── ANALYSIS_RESULTS.md          # Input from concept-enhanced
    └── context-package.json         # Input from context-gather
@@ -580,28 +577,28 @@ The command organizes outputs into a standard directory structure.
 The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.

 #### Artifact Priority
-1.  **synthesis-specification.md** (highest): Comprehensive implementation blueprint from brainstorming synthesis
-2.  **ANALYSIS_RESULTS.md** (critical): Technical analysis, risk assessment, and optimization strategies from planning phase (generated by concept-enhanced)
-3.  **context-package.json** (critical): Smart context with focus paths, module structure, and dependency graph from planning phase (generated by context-gather)
+1.  **role/analysis*.md** (highest): Role-specific requirements and design specs from brainstorming (product-manager, system-architect, ui-designer, etc.)
+2.  **ANALYSIS_RESULTS.md** (critical): Technical analysis, risk assessment, optimization strategies, and cross-role synthesis from planning phase (generated by concept-enhanced)
+3.  **guidance-specification.json** (critical): Smart context with focus paths, module structure, and dependency graph from planning phase (generated by context-gather)
 4.  **topic-framework.md** (medium): Discussion framework structure from brainstorming
-5.  **role/analysis.md** (low): Individual role-based analyses for detailed specifications

 #### Artifact-Task Mapping
 Artifacts are mapped to tasks based on their relevance to the task's domain.
- **synthesis-specification.md**: Included in all tasks as the primary reference.
- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks.
- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks.
- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards.
- **data-architect/analysis.md**: Mapped to tasks involving data models or APIs.
+- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type
+- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components
+- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns
+- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards
+- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs
+- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories

-This ensures that each task has access to the most relevant and detailed specifications, from the high-level synthesis down to the role-specific details.
+This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.

 ## 8. CLI Execute Mode Details
 When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command.

 **Key Points**:
 - **Sequential Steps**: Steps execute in order defined in `implementation_approach` array
- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{.workflow/{session}/.process/context-package.json}` and `@{.workflow/{session}/.brainstorming/synthesis-specification.md}`
+- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{.workflow/{session}/.process/context-package.json}` and role analysis files from `.brainstorming/*/analysis*.md`
 - **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity
 - **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field

@@ -623,10 +620,10 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
  "flow_control": {
    "pre_analysis": [
      {
-        "step": "load_synthesis",
-        "action": "Load synthesis specification for requirements",
-        "commands": ["Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)"],
-        "output_to": "synthesis_spec",
+        "step": "load_role_analyses",
+        "action": "Load role analyses for requirements",
+        "commands": ["Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)"],
+        "output_to": "role_analyses",
        "on_error": "fail"
      },
      {
@@ -641,7 +638,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
      {
        "step": 1,
        "title": "Implement JWT-based authentication",
-        "description": "Create authentication module using JWT following [synthesis_spec] requirements and [context_pkg] patterns",
+        "description": "Create authentication module using JWT following [role_analyses] requirements and [context_pkg] patterns",
        "modification_points": [
          "Create auth service with JWT generation",
          "Implement login endpoint with credential validation",
@@ -676,10 +673,10 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
  "flow_control": {
    "pre_analysis": [
      {
-        "step": "load_synthesis",
-        "action": "Load synthesis specification",
-        "commands": ["Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)"],
-        "output_to": "synthesis_spec",
+        "step": "load_role_analyses",
+        "action": "Load role analyses",
+        "commands": ["Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)"],
+        "output_to": "role_analyses",
        "on_error": "fail"
      }
    ],
@@ -688,7 +685,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
        "step": 1,
        "title": "Implement authentication with Codex",
        "description": "Create JWT-based authentication module",
-        "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/synthesis-specification.md} EXPECTED: Complete auth module with tests RULES: Follow synthesis specification\" --skip-git-repo-check -s danger-full-access)",
+        "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/*/analysis*.md} EXPECTED: Complete auth module with tests RULES: Follow role analyses\" --skip-git-repo-check -s danger-full-access)",
        "modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"],
        "logic_flow": ["Validate credentials", "Generate JWT", "Return token"],
        "depends_on": [],
@@ -715,10 +712,10 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
    "pre_analysis": [
      {
        "step": "load_context",
-        "action": "Load context and synthesis",
+        "action": "Load context and role analyses",
        "commands": [
          "Read(.workflow/WFS-session/.process/context-package.json)",
-          "Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)"
+          "Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)"
        ],
        "output_to": "full_context",
        "on_error": "fail"
@@ -729,7 +726,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
        "step": 1,
        "title": "Create RBAC models",
        "description": "Define role and permission data models",
-        "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/synthesis-specification.md} EXPECTED: Models with migrations RULES: Follow synthesis spec\" --skip-git-repo-check -s danger-full-access)",
+        "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/*/analysis*.md} EXPECTED: Models with migrations RULES: Follow role analyses\" --skip-git-repo-check -s danger-full-access)",
        "modification_points": ["Define role model", "Define permission model", "Create migrations"],
        "logic_flow": ["Design schema", "Implement models", "Generate migrations"],
        "depends_on": [],