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-11 02:33:51 +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/workflows/cli-templates/planning-roles/synthesis-role.md
+++ b/.claude/workflows/cli-templates/planning-roles/synthesis-role.md
@@ -1,4 +1,25 @@
-# Synthesis Role Template
+# ⚠️ DEPRECATED: Synthesis Role Template
+
+## DEPRECATION NOTICE
+
+**This template is DEPRECATED and no longer used.**
+
+### Why Deprecated
+The `/workflow:brainstorm:synthesis` command has been redesigned:
+- **Old behavior**: Generated synthesis-specification.md consolidating all role analyses
+- **New behavior**: Performs cross-role analysis, identifies ambiguities, interacts with user for clarification, and updates role analysis.md files directly
+
+### Migration
+- **Role analyses are the source of truth**: Each role's analysis.md file is updated directly
+- **Planning reads role documents**: The planning phase dynamically reads all role analysis.md files
+- **No template needed**: The clarification workflow doesn't require a document template
+
+### Historical Context
+This template was used to guide the generation of synthesis-specification.md from multiple role perspectives. It is preserved for historical reference but should not be used in the new architecture.
+
+---
+
+# Original Template (Historical Reference)

 ## Purpose
 Generate comprehensive synthesis-specification.md that consolidates all role perspectives from brainstorming into actionable implementation specification.
@@ -18,7 +39,7 @@ Generate comprehensive synthesis-specification.md that consolidates all role per
 ```markdown
 # [Topic] - Integrated Implementation Specification

-**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
+**Framework Reference**: @guidance-specification.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
 **Source Integration**: All brainstorming role perspectives consolidated
 **Document Type**: Requirements & Design Specification (WHAT to build)

@@ -344,7 +365,7 @@ Document known constraints that affect planning:

 ### Cross-Role Synthesis Process

-1. **Load All Role Analyses**: Read topic-framework.md and all discovered */analysis.md files
+1. **Load All Role Analyses**: Read guidance-specification.md and all discovered */analysis.md files
 2. **Extract Key Insights**: Identify main recommendations, concerns, and innovations from each role
 3. **Identify Consensus Areas**: Find common themes across multiple roles
 4. **Document Disagreements**: Capture controversial points where roles differ
@@ -371,7 +392,7 @@ Document known constraints that affect planning:
 Use @ references to link back to source role analyses:
 - `@role/analysis.md` - Reference entire role analysis
 - `@role/analysis.md#section` - Reference specific section
- `@topic-framework.md#point-3` - Reference framework discussion point
+- `@guidance-specification.md#point-3` - Reference framework discussion point

 ### Dynamic Role Handling

--- a/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt
+++ b/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt
@@ -187,8 +187,8 @@ Generate ANALYSIS_RESULTS.md with comprehensive solution design and technical an

 ### Analysis Priority Sources
 1. **PRIMARY**: Individual role analysis.md files (system-architect, ui-designer, etc.) - technical details, ADRs, decision context
-2. **SECONDARY**: synthesis-specification.md - integrated requirements, cross-role alignment
-3. **REFERENCE**: topic-framework.md - discussion context
+2. **SECONDARY**: role analysis documents - multi-perspective requirements and design specs
+3. **REFERENCE**: guidance-specification.md - discussion context

 ### Focus Areas
 - **SOLUTION IMPROVEMENTS**: How to enhance current design
--- a/.claude/workflows/cli-templates/prompts/workflow/gemini-solution-design.txt
+++ b/.claude/workflows/cli-templates/prompts/workflow/gemini-solution-design.txt
@@ -15,12 +15,12 @@ Analyze and design optimal solution with comprehensive architecture evaluation a
   - Architecture Decision Records (ADRs)
   - Design decision context and rationale

-2. **SECONDARY**: synthesis-specification.md
+2. **SECONDARY**: role analysis documents
   - Integrated requirements across roles
   - Cross-role alignment and dependencies
   - Unified feature specifications

-3. **REFERENCE**: topic-framework.md
+3. **REFERENCE**: guidance-specification.md
   - Discussion context and background
   - Initial problem framing

@@ -104,8 +104,8 @@ For each target:
 ### Brainstorm Context
 If brainstorming artifacts exist:
 - Prioritize individual role analysis.md files
- Use synthesis-specification.md for integrated view
- Reference topic-framework.md for context
+- Use role analysis documents for integrated view
+- Reference guidance-specification.md for context

 ### Codebase Context
 - Identify similar patterns in existing code
--- a/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt
+++ b/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt
@@ -35,10 +35,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 generated)
 - ✅ 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 ({X} clarifications answered, role analyses updated | skipped)
 - ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)

 **Quality Gates**:
@@ -76,12 +76,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 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
@@ -96,17 +96,17 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence

 ### Integrated Specifications (Highest Priority)
- **synthesis-specification.md**: Comprehensive implementation blueprint
+- **role analyses**: Comprehensive implementation blueprint
  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment

 ### Supporting Artifacts (Reference)
- **topic-framework.md**: Role-specific discussion points and analysis framework
+- **guidance-specification.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)
+1. role analyses (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)
@@ -126,7 +126,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**:
@@ -218,7 +218,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 analyses implemented
 - [ ] All acceptance criteria from task.json files met

 **Technical Quality**:
@@ -232,7 +232,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]

 ## Template Usage Guidelines

@@ -269,7 +269,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
   - Create dependency graph visualization

 7. **Set Success Criteria**:
-   - Extract from synthesis-specification.md
+   - Extract from role analyses
   - Include measurable metrics
   - Define quality gates

--- a/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt
+++ b/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt
@@ -34,8 +34,8 @@ Task JSON Schema - Agent Mode (No Command Field)
  "flow_control": {
    "pre_analysis": [
      {
-        "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification",
+        "step": "load_role_analyses_specification",
+        "action": "Load consolidated role analyses",
        "commands": [
          "Read({synthesis_spec_path})"
        ],
@@ -62,16 +62,16 @@ Task JSON Schema - Agent Mode (No Command Field)
    "implementation_approach": [
      {
        "step": 1,
-        "title": "Implement task following synthesis specification",
-        "description": "Implement '{title}' following [synthesis_specification] requirements and [context_pkg] patterns. Use synthesis-specification.md as primary source, consult artifacts for technical details.",
+        "title": "Implement task following role analyses",
+        "description": "Implement '{title}' following [synthesis_specification] requirements and [context_pkg] patterns. Use role analyses as primary source, consult artifacts for technical details.",
        "modification_points": [
-          "Apply consolidated requirements from synthesis-specification.md",
+          "Apply consolidated requirements from role analyses",
          "Follow technical guidelines from synthesis",
          "Consult artifacts for implementation details when needed",
          "Integrate with existing patterns"
        ],
        "logic_flow": [
-          "Load synthesis specification and context package",
+          "Load role analyses and context package",
          "Analyze existing patterns from [codebase_structure]",
          "Implement following specification",
          "Consult artifacts for technical details when needed",