catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: enhance workflow documentation with role analysis and conflict resolution details

Browse Source
This commit is contained in:
catlog22
2025-10-24 11:56:50 +08:00
parent 1f070638b4
commit ee7ffdae67
9 changed files with 210 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
.claude/agents/code-developer.md
View File

@@ -33,6 +33,14 @@ You are a code execution specialist focused on implementing high-quality, produc
- User-provided task description and context - User-provided task description and context
- Existing documentation and code examples - Existing documentation and code examples
- Project CLAUDE.md standards - Project CLAUDE.md standards
- **context-package.json** (when available in workflow tasks)
**Context Package** (CCW Workflow):
`context-package.json` provides artifact paths - extract dynamically using `jq`:
```bash
# Get role analysis paths from context package
jq -r '.brainstorm_artifacts.role_analyses[].files[].path' context-package.json
```
**Pre-Analysis: Smart Tech Stack Loading**: **Pre-Analysis: Smart Tech Stack Loading**:
```bash ```bash

6
.claude/agents/conceptual-planning-agent.md
View File

@@ -14,11 +14,11 @@ description: |
Examples: Examples:
- Context: Auto brainstorm assigns system-architect role - Context: Auto brainstorm assigns system-architect role
auto.md: Assigns dedicated agent with ASSIGNED_ROLE: system-architect auto.md: Assigns dedicated agent with ASSIGNED_ROLE: system-architect
agent: "I'll execute system-architect analysis for this topic, creating architecture-focused conceptual analysis in .brainstorming/system-architect/ directory" agent: "I'll execute system-architect analysis for this topic, creating architecture-focused conceptual analysis in OUTPUT_LOCATION"
- Context: Auto brainstorm assigns ui-designer role - Context: Auto brainstorm assigns ui-designer role
auto.md: Assigns dedicated agent with ASSIGNED_ROLE: ui-designer auto.md: Assigns dedicated agent with ASSIGNED_ROLE: ui-designer
agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in .brainstorming/ui-designer/ directory" agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in OUTPUT_LOCATION"
color: purple color: purple
--- ---
@@ -166,7 +166,7 @@ When called, you receive:
- **User Context**: Specific requirements, constraints, and expectations from user discussion - **User Context**: Specific requirements, constraints, and expectations from user discussion
- **Output Location**: Directory path for generated analysis files - **Output Location**: Directory path for generated analysis files
- **Role Hint** (optional): Suggested role or role selection guidance - **Role Hint** (optional): Suggested role or role selection guidance
- **GEMINI_ANALYSIS_REQUIRED** (optional): Flag to trigger Gemini CLI analysis - **context-package.json** (CCW Workflow): Artifact paths catalog - extract using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
- **ASSIGNED_ROLE** (optional): Specific role assignment - **ASSIGNED_ROLE** (optional): Specific role assignment
- **ANALYSIS_DIMENSIONS** (optional): Role-specific analysis dimensions - **ANALYSIS_DIMENSIONS** (optional): Role-specific analysis dimensions

1
.claude/agents/test-fix-agent.md
View File

@@ -68,6 +68,7 @@ When task JSON contains implementation_approach array:
### 1. Context Assessment & Test Discovery ### 1. Context Assessment & Test Discovery
- Analyze task context to identify test files and source code paths - Analyze task context to identify test files and source code paths
- Load test framework configuration (Jest, Pytest, Mocha, etc.) - Load test framework configuration (Jest, Pytest, Mocha, etc.)
- **context-package.json** (CCW Workflow): Extract artifact paths using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
- Identify test command from project configuration - Identify test command from project configuration
```bash ```bash

30
.claude/commands/workflow/execute.md
View File

@@ -370,10 +370,10 @@ TodoWrite({
{ {
"task": { /* Complete task JSON with artifacts array */ }, "task": { /* Complete task JSON with artifacts array */ },
"artifacts": { "artifacts": {
"synthesis_specification": { "path": ".workflow/WFS-session/.brainstorming/role analysis documents", "priority": "highest" }, "synthesis_specification": { "path": "{{from context-package.json → brainstorm_artifacts.synthesis_output.path}}", "priority": "highest" },
"topic_framework": { "path": ".workflow/WFS-session/.brainstorming/guidance-specification.md", "priority": "medium" }, "guidance_specification": { "path": "{{from context-package.json → brainstorm_artifacts.guidance_specification.path}}", "priority": "medium" },
"role_analyses": [ /* Individual role analysis files */ ], "role_analyses": [ /* From context-package.json → brainstorm_artifacts.role_analyses[] */ ],
"available_artifacts": [ /* All detected brainstorming artifacts */ ] "conflict_resolution": { "path": "{{from context-package.json → brainstorm_artifacts.conflict_resolution.path}}", "conditional": true }
}, },
"flow_context": { "flow_context": {
"step_outputs": { "step_outputs": {
@@ -385,7 +385,7 @@ TodoWrite({
}, },
"session": { "session": {
"workflow_dir": ".workflow/WFS-session/", "workflow_dir": ".workflow/WFS-session/",
"brainstorming_dir": ".workflow/WFS-session/.brainstorming/", "context_package_path": ".workflow/WFS-session/.process/context-package.json",
"todo_list_path": ".workflow/WFS-session/TODO_LIST.md", "todo_list_path": ".workflow/WFS-session/TODO_LIST.md",
"summaries_dir": ".workflow/WFS-session/.summaries/", "summaries_dir": ".workflow/WFS-session/.summaries/",
"task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json" "task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json"
@@ -397,10 +397,10 @@ TodoWrite({
#### Context Validation Rules #### Context Validation Rules
- **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context - **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
- **Artifacts Available**: Synthesis specifications and brainstorming outputs accessible - **Artifacts Available**: All artifacts loaded from context-package.json
- **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps - **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
- **Dependencies Loaded**: All depends_on summaries available - **Dependencies Loaded**: All depends_on summaries available
- **Session Paths Valid**: All workflow paths exist and accessible, including .brainstorming directory - **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
- **Agent Assignment**: Valid agent type specified in meta.agent - **Agent Assignment**: Valid agent type specified in meta.agent
### 4. Agent Execution Pattern ### 4. Agent Execution Pattern
@@ -477,15 +477,16 @@ Task(subagent_type="{meta.agent}",
"artifacts": [ "artifacts": [
{ {
"type": "synthesis_specification", "type": "synthesis_specification",
"source": "brainstorm_synthesis", "source": "context-package.json → brainstorm_artifacts.synthesis_output",
"path": ".workflow/WFS-[session]/.brainstorming/role analysis documents", "path": "{{loaded dynamically from context-package.json}}",
"priority": "highest", "priority": "highest",
"contains": "complete_integrated_specification" "contains": "complete_integrated_specification"
}, },
{ {
"type": "individual_role_analysis", "type": "individual_role_analysis",
"source": "brainstorm_roles", "source": "context-package.json → brainstorm_artifacts.role_analyses[]",
"path": ".workflow/WFS-[session]/.brainstorming/[role]/analysis.md", "path": "{{loaded dynamically from context-package.json}}",
"note": "Supports analysis*.md pattern (analysis.md, analysis-01.md, analysis-api.md, etc.)",
"priority": "low", "priority": "low",
"contains": "role_specific_analysis_fallback" "contains": "role_specific_analysis_fallback"
} }
@@ -495,10 +496,11 @@ Task(subagent_type="{meta.agent}",
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_synthesis_specification", "step": "load_synthesis_specification",
"action": "Load consolidated role analyses from brainstorming", "action": "Load synthesis specification from context-package.json",
"commands": [ "commands": [
"bash(ls .workflow/WFS-[session]/.brainstorming/role analysis documents 2>/dev/null || echo 'role analyses not found')", "Read(.workflow/WFS-[session]/.process/context-package.json)",
"Read(.workflow/WFS-[session]/.brainstorming/role analysis documents)" "Extract(brainstorm_artifacts.synthesis_output.path)",
"Read(extracted path)"
], ],
"output_to": "synthesis_specification", "output_to": "synthesis_specification",
"on_error": "skip_optional" "on_error": "skip_optional"

1
.claude/commands/workflow/plan.md
View File

@@ -135,7 +135,6 @@ CONTEXT: Existing user database schema, REST API endpoints
**Purpose**: Optional quality gate before task generation - primarily handled by brainstorm synthesis phase **Purpose**: Optional quality gate before task generation - primarily handled by brainstorm synthesis phase
**Note**: Concept enhancement and clarification are now handled in `/workflow:brainstorm:synthesis` Phase 2.5 during brainstorming. This phase is reserved for future validation extensions.
**Current Behavior**: Auto-skip to Phase 4 (Task Generation) **Current Behavior**: Auto-skip to Phase 4 (Task Generation)

6
.claude/commands/workflow/tools/conflict-resolution.md
View File

@@ -90,8 +90,10 @@ Task(
- Analyze current architecture patterns - Analyze current architecture patterns
- Identify current API contracts and interfaces - Identify current API contracts and interfaces
2. **Load Plan Requirements** (from session context) 2. **Load Plan Requirements** (from context-package.json)
- Read .workflow/{session_id}/.brainstorming/*/analysis.md (if exists) - Read .workflow/{session_id}/.process/context-package.json
- Extract role analysis paths from brainstorm_artifacts.role_analyses[]
- Load each role analysis file
- Extract requirements and design decisions - Extract requirements and design decisions
- Identify planned changes - Identify planned changes

30
.claude/commands/workflow/tools/context-gather.md
View File

@@ -155,6 +155,11 @@ Task(
- Identify inter-module dependencies - Identify inter-module dependencies
- Determine core and optional dependencies - Determine core and optional dependencies
#### Step 3.5: Brainstorm Artifacts Discovery
Discover and catalog brainstorming documents (if `.brainstorming/` exists):
- Guidance specification, role analyses (`*/analysis*.md`), synthesis output
- Catalog role analyses by role with file type and timestamp
#### Step 4: Context Packaging #### Step 4: Context Packaging
Generate standardized context-package.json following the format below Generate standardized context-package.json following the format below
@@ -253,6 +258,31 @@ Generate standardized context-package.json following the format below
"config_files": 2, "config_files": 2,
"test_files": 1 "test_files": 1
}, },
"brainstorm_artifacts": {
"guidance_specification": {
"path": ".workflow/WFS-user-auth/.brainstorming/guidance-specification.md",
"exists": true
},
"role_analyses": [
{
"role": "system-architect",
"files": [
{"path": ".workflow/WFS-user-auth/.brainstorming/system-architect/analysis.md", "type": "primary"},
{"path": ".workflow/WFS-user-auth/.brainstorming/system-architect/analysis-api.md", "type": "supplementary"}
]
},
{
"role": "ui-designer",
"files": [
{"path": ".workflow/WFS-user-auth/.brainstorming/ui-designer/analysis.md", "type": "primary"}
]
}
],
"synthesis_output": {
"path": ".workflow/WFS-user-auth/.brainstorming/synthesis-specification.md",
"exists": true
}
},
"conflict_detection": { "conflict_detection": {
"conflict_risk": "medium", "conflict_risk": "medium",
"existing_files": [ "existing_files": [

93
.claude/commands/workflow/tools/task-generate-agent.md
View File

@@ -37,16 +37,17 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
// If in memory: use cached content // If in memory: use cached content
// Else: Load from .workflow/{session-id}/workflow-session.json // Else: Load from .workflow/{session-id}/workflow-session.json
}, },
"analysis_results": { "brainstorm_artifacts": {
// If in memory: use cached content // Loaded from context-package.json → brainstorm_artifacts section
// Else: Load from .workflow/{session-id}/.process/ANALYSIS_RESULTS.md "role_analyses": [
}, {
"artifacts_inventory": { "role": "system-architect",
// If in memory: use cached list "files": [{"path": "...", "type": "primary|supplementary"}]
// Else: Scan .workflow/{session-id}/.brainstorming/ directory }
"synthesis_specification": "path or null", ],
"topic_framework": "path or null", "guidance_specification": {"path": "...", "exists": true},
"role_analyses": ["paths"] "synthesis_output": {"path": "...", "exists": true},
"conflict_resolution": {"path": "...", "exists": true} // if conflict_risk >= medium
}, },
"context_package": { "context_package": {
// If in memory: use cached content // If in memory: use cached content
@@ -68,21 +69,31 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
} }
``` ```
2. **Load Analysis Results** (if not in memory) 2. **Load Context Package** (if not in memory)
```javascript ```javascript
if (!memory.has("ANALYSIS_RESULTS.md")) { if (!memory.has("context-package.json")) {
Read(.workflow/{session-id}/.process/ANALYSIS_RESULTS.md) Read(.workflow/{session-id}/.process/context-package.json)
} }
``` ```
3. **Discover Artifacts** (if not in memory) 3. **Extract & Load Role Analyses** (from context-package.json)
```javascript ```javascript
if (!memory.has("artifacts_inventory")) { // Extract role analysis paths from context package
bash(find .workflow/{session-id}/.brainstorming/ -name "*.md" -type f) const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
.flatMap(role => role.files.map(f => f.path));
// Load each role analysis file
roleAnalysisPaths.forEach(path => Read(path));
```
4. **Load Conflict Resolution** (from context-package.json, if exists)
```javascript
if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
} }
``` ```
4. **MCP Code Analysis** (optional - enhance understanding) 5. **MCP Code Analysis** (optional - enhance understanding)
```javascript ```javascript
// Find relevant files for task context // Find relevant files for task context
mcp__code-index__find_files(pattern="*auth*") mcp__code-index__find_files(pattern="*auth*")
@@ -92,7 +103,7 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
) )
``` ```
5. **MCP External Research** (optional - gather best practices) 6. **MCP External Research** (optional - gather best practices)
```javascript ```javascript
// Get external examples for implementation // Get external examples for implementation
mcp__exa__get_code_context_exa( mcp__exa__get_code_context_exa(
@@ -128,16 +139,22 @@ Task(
### Session Metadata ### Session Metadata
{session_metadata_content} {session_metadata_content}
### Analysis Results ### Role Analyses (Enhanced by Synthesis)
{analysis_results_content} {role_analyses_content}
- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
### Artifacts Inventory ### Artifacts Inventory
- **Synthesis Specification**: {synthesis_spec_path} - **Guidance Specification**: {guidance_spec_path}
- **Topic Framework**: {topic_framework_path}
- **Role Analyses**: {role_analyses_list} - **Role Analyses**: {role_analyses_list}
### Context Package ### Context Package
{context_package_summary} {context_package_summary}
- Includes conflict_risk assessment
### Conflict Resolution (Conditional)
{conflict_resolution_content}
- Exists only if conflict_risk was medium/high
- Contains conflict detection results and resolution strategies
### MCP Analysis Results (Optional) ### MCP Analysis Results (Optional)
**Code Structure**: {mcp_code_index_results} **Code Structure**: {mcp_code_index_results}
@@ -189,8 +206,9 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
- Use the template above for IMPL_PLAN.md generation - Use the template above for IMPL_PLAN.md generation
- Replace all {placeholder} variables with actual session-specific values - Replace all {placeholder} variables with actual session-specific values
- Populate CCW Workflow Context based on actual phase progression - Populate CCW Workflow Context based on actual phase progression
- Extract content from ANALYSIS_RESULTS.md and context-package.json - Extract content from role analyses and context-package.json
- List all detected brainstorming artifacts with correct paths - List all detected brainstorming artifacts with correct paths (role analyses, guidance-specification.md)
- Include conflict resolution status if CONFLICT_RESOLUTION.md exists
#### 3. TODO_LIST.md #### 3. TODO_LIST.md
**Location**: .workflow/{session-id}/TODO_LIST.md **Location**: .workflow/{session-id}/TODO_LIST.md
@@ -222,9 +240,11 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
- This template is already the correct one based on execution mode - This template is already the correct one based on execution mode
**Step 2: Extract and Decompose Tasks** **Step 2: Extract and Decompose Tasks**
- Parse ANALYSIS_RESULTS.md for task recommendations - Parse role analysis.md files for requirements, design specs, and task recommendations
- Review synthesis enhancements and clarifications in role analyses
- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
- Apply task merging rules (merge when possible, decompose only when necessary) - Apply task merging rules (merge when possible, decompose only when necessary)
- Map artifacts to tasks based on domain (UI/Backend/Data) - Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
- Ensure task count ≤10 - Ensure task count ≤10
**Step 3: Generate Task JSON Files** **Step 3: Generate Task JSON Files**
@@ -322,18 +342,23 @@ const agentContext = {
? memory.get("workflow-session.json") ? memory.get("workflow-session.json")
: Read(.workflow/WFS-[id]/workflow-session.json), : Read(.workflow/WFS-[id]/workflow-session.json),
analysis_results: memory.has("ANALYSIS_RESULTS.md")
? memory.get("ANALYSIS_RESULTS.md")
: Read(.workflow/WFS-[id]/.process/ANALYSIS_RESULTS.md),
artifacts_inventory: memory.has("artifacts_inventory")
? memory.get("artifacts_inventory")
: discoverArtifacts(),
context_package: memory.has("context-package.json") context_package: memory.has("context-package.json")
? memory.get("context-package.json") ? memory.get("context-package.json")
: Read(.workflow/WFS-[id]/.process/context-package.json), : Read(.workflow/WFS-[id]/.process/context-package.json),
// Extract brainstorm artifacts from context package
brainstorm_artifacts: extractBrainstormArtifacts(context_package),
// Load role analyses using paths from context package
role_analyses: brainstorm_artifacts.role_analyses
.flatMap(role => role.files)
.map(file => Read(file.path)),
// Load conflict resolution if exists (from context package)
conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
? Read(brainstorm_artifacts.conflict_resolution.path)
: null,
// Optional MCP enhancements // Optional MCP enhancements
mcp_analysis: executeMcpDiscovery() mcp_analysis: executeMcpDiscovery()
} }

169
.claude/commands/workflow/tools/task-generate.md
View File

@@ -10,7 +10,7 @@ examples:
# Task Generation Command # Task Generation Command
## 1. Overview ## 1. Overview
This command generates task JSON files and an `IMPL_PLAN.md` from `ANALYSIS_RESULTS.md`. It automatically detects and integrates brainstorming artifacts, creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate analysis into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront. This command generates task JSON files and an `IMPL_PLAN.md` from brainstorming role analyses. It automatically detects and integrates all brainstorming artifacts (role-specific `analysis.md` files and `guidance-specification.md`), creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate requirements and design specifications from role analyses into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
## 2. Execution Modes ## 2. Execution Modes
@@ -37,8 +37,8 @@ When the `--cli-execute` flag is used, each step in `implementation_approach` **
## 3. Core Principles ## 3. Core Principles
This command is built on a set of core principles to ensure efficient and reliable task generation. 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 - **Role Analysis-Driven**: All generated tasks originate from role-specific `analysis.md` files (enhanced in synthesis phase), ensuring direct link between requirements/design and implementation
- **Artifact-Aware**: Automatically detects and integrates brainstorming outputs (role analyses, guidance-specification.md) to enrich task context - **Artifact-Aware**: Automatically detects and integrates all brainstorming outputs (role analyses, guidance-specification.md, enhancements) to enrich task context
- **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON - **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 - **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 - **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
@@ -52,8 +52,9 @@ The command follows a streamlined, three-step process to convert analysis into e
### Step 1: Input & Discovery ### Step 1: Input & Discovery
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. 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`. 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`. 2. **Context Package Loading** (primary source): Reads `.workflow/{session_id}/.process/context-package.json` for smart context and artifact catalog.
3. **Artifact Discovery**: Scans the `.workflow/{session_id}/.brainstorming/` directory to find `guidance-specification.md` and various role analyses ([role]/analysis*.md). 3. **Brainstorm Artifacts Extraction**: Extracts role analysis paths from `context-package.json` → `brainstorm_artifacts.role_analyses[]` (supports `analysis*.md` automatically).
4. **Document Loading**: Reads role analyses, guidance specification, synthesis output, and conflict resolution (if exists) using paths from context package.
### Step 2: Task Decomposition & Grouping ### 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. Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
@@ -188,19 +189,19 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
"shared_context": {"tech_stack": [], "conventions": []}, "shared_context": {"tech_stack": [], "conventions": []},
"artifacts": [ "artifacts": [
{ {
"path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis*.md", "path": "{{from context-package.json → brainstorm_artifacts.role_analyses[].files[].path}}",
"priority": "highest", "priority": "highest",
"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)" "usage": "Role-specific requirements, design specs, enhanced by synthesis. Paths loaded dynamically from context-package.json (supports multiple files per role: analysis.md, analysis-01.md, analysis-api.md, etc.). Common roles: product-manager, system-architect, ui-designer, data-architect, ux-expert."
},
{
"path": ".workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md",
"priority": "critical",
"usage": "Technical analysis and optimization strategies from planning phase. Use for: risk mitigation, performance optimization, architecture review, implementation patterns"
}, },
{ {
"path": ".workflow/WFS-[session]/.process/context-package.json", "path": ".workflow/WFS-[session]/.process/context-package.json",
"priority": "critical", "priority": "critical",
"usage": "Smart context with focus paths, module structure, dependency graph, existing patterns. Use for: environment setup, dependency resolution, pattern discovery" "usage": "Smart context with focus paths, module structure, dependency graph, existing patterns, tech stack. Use for: environment setup, dependency resolution, pattern discovery, conflict detection results"
},
{
"path": ".workflow/WFS-[session]/.process/CONFLICT_RESOLUTION.md",
"priority": "high",
"usage": "Conflict resolution strategies and selected approaches (conditional, exists only if conflict_risk was medium/high). Use for: understanding code conflicts, applying resolution strategies, migration planning"
}, },
{ {
"path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md", "path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md",
@@ -212,42 +213,39 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
"flow_control": { "flow_control": {
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_role_analyses", "step": "load_context_package",
"action": "Load role analysis documents from brainstorming", "action": "Load context package for artifact paths",
"commands": [ "commands": [
"bash(ls .workflow/WFS-[session]/.brainstorming/*/analysis*.md 2>/dev/null || echo 'not found')", "Read(.workflow/WFS-[session]/.process/context-package.json)"
"Glob(.workflow/WFS-[session]/.brainstorming/*/analysis*.md)",
"Read(each discovered role analysis file)"
], ],
"output_to": "role_analyses", "output_to": "context_package",
"on_error": "skip_optional" "on_error": "fail"
}, },
{ {
"step": "load_role_analysis_artifacts", "step": "load_role_analysis_artifacts",
"action": "Load role-specific analysis documents for technical details (supports multiple files per role)", "action": "Load role analyses from context-package.json (supports multiple files per role)",
"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.", "note": "Paths loaded from context-package.json → brainstorm_artifacts.role_analyses[]. Supports analysis*.md automatically.",
"commands": [ "commands": [
"bash(find .workflow/WFS-[session]/.brainstorming/ -name 'analysis*.md' 2>/dev/null | sort | head -24)", "Read(.workflow/WFS-[session]/.process/context-package.json)",
"Read(.workflow/WFS-[session]/.brainstorming/system-architect/analysis.md)", "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(.workflow/WFS-[session]/.brainstorming/ui-designer/analysis.md)", "Read(each extracted path)"
"Read(.workflow/WFS-[session]/.brainstorming/product-manager/analysis.md)"
], ],
"output_to": "role_analysis_artifacts", "output_to": "role_analysis_artifacts",
"on_error": "skip_optional" "on_error": "skip_optional"
}, },
{ {
"step": "load_planning_context", "step": "load_planning_context",
"action": "Load plan-generated analysis and context intelligence", "action": "Load plan-generated context intelligence and conflict resolution",
"note": "CRITICAL: ANALYSIS_RESULTS.md provides technical guidance (optimization, risk mitigation, architecture review). context-package.json provides smart context (focus paths, dependencies, patterns).", "note": "CRITICAL: context-package.json provides smart context (focus paths, dependencies, patterns). CONFLICT_RESOLUTION.md (if exists) provides conflict resolution strategies.",
"commands": [ "commands": [
"Read(.workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md)", "Read(.workflow/WFS-[session]/.process/context-package.json)",
"Read(.workflow/WFS-[session]/.process/context-package.json)" "bash(test -f .workflow/WFS-[session]/.process/CONFLICT_RESOLUTION.md && cat .workflow/WFS-[session]/.process/CONFLICT_RESOLUTION.md || echo 'No conflicts detected')"
], ],
"output_to": "planning_context", "output_to": "planning_context",
"on_error": "fail", "on_error": "fail",
"usage_guidance": { "usage_guidance": {
"ANALYSIS_RESULTS.md": "Reference for technical decisions, risk mitigation strategies, optimization patterns, architecture review insights from Gemini/Qwen/Codex parallel analysis", "context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding, conflict_risk assessment",
"context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding" "CONFLICT_RESOLUTION.md": "Apply selected conflict resolution strategies, understand migration requirements (conditional, may not exist if no conflicts)"
} }
}, },
{ {
@@ -270,24 +268,25 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
"implementation_approach": [ "implementation_approach": [
{ {
"step": 1, "step": 1,
"title": "Implement task following role analyses and technical guidance", "title": "Implement task following role analyses and context",
"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.", "description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements, design specs, enhancements from synthesis), 2) context-package.json (smart context, focus paths, patterns), 3) CONFLICT_RESOLUTION.md (if exists, conflict resolution strategies). Role analyses are enhanced by synthesis phase with concept improvements and clarifications.",
"modification_points": [ "modification_points": [
"Apply requirements from role analysis documents", "Apply requirements and design specs from role analysis documents",
"Follow technical guidelines from ANALYSIS_RESULTS.md", "Use enhancements and clarifications from synthesis phase",
"Apply conflict resolution strategies (if conflicts were detected)",
"Use context-package.json for focus paths and dependency resolution", "Use context-package.json for focus paths and dependency resolution",
"Consult specific role artifacts for implementation details when needed", "Consult specific role artifacts for implementation details when needed",
"Integrate with existing patterns" "Integrate with existing patterns"
], ],
"logic_flow": [ "logic_flow": [
"Load role analyses (requirements and design decisions from brainstorming)", "Load role analyses (requirements, design, enhancements from synthesis)",
"Load ANALYSIS_RESULTS.md (technical guidance and risk mitigation strategies)", "Load context-package.json (smart context: focus paths, dependencies, patterns, conflict_risk)",
"Load context-package.json (smart context: focus paths, dependencies, existing patterns)", "Load CONFLICT_RESOLUTION.md (if exists, conflict resolution strategies)",
"Extract requirements and design decisions from role documents", "Extract requirements and design decisions from role documents",
"Review technical analysis and optimization strategies from ANALYSIS_RESULTS.md", "Review synthesis enhancements and clarifications",
"Apply conflict resolution strategies (if applicable)",
"Identify modification targets using context package", "Identify modification targets using context package",
"Implement following role requirements and technical guidance", "Implement following role requirements and design specs",
"Apply optimization patterns from ANALYSIS_RESULTS.md",
"Consult role artifacts for detailed specifications when needed", "Consult role artifacts for detailed specifications when needed",
"Validate against acceptance criteria" "Validate against acceptance criteria"
], ],
@@ -307,14 +306,15 @@ This document provides a high-level overview of the entire implementation plan.
--- ---
identifier: WFS-{session-id} identifier: WFS-{session-id}
source: "User requirements" | "File: path" | "Issue: ISS-001" source: "User requirements" | "File: path" | "Issue: ISS-001"
analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md role_analyses: .workflow/{session-id}/.brainstorming/[role]/analysis*.md
artifacts: .workflow/{session-id}/.brainstorming/ artifacts: .workflow/{session-id}/.brainstorming/
context_package: .workflow/{session-id}/.process/context-package.json # CCW smart context context_package: .workflow/{session-id}/.process/context-package.json # CCW smart context
conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md # Conditional, if conflict_risk >= medium
workflow_type: "standard | tdd | design" # Indicates execution model workflow_type: "standard | tdd | design" # Indicates execution model
verification_history: # CCW quality gates verification_history: # CCW quality gates
concept_verify: "passed | skipped | pending" synthesis_clarify: "passed | skipped | pending" # Brainstorm phase clarification
action_plan_verify: "pending" action_plan_verify: "pending"
phase_progression: "brainstorm → context → analysis → concept_verify → planning" # CCW workflow phases phase_progression: "brainstorm → synthesis → context → conflict_resolution → planning" # CCW workflow phases
--- ---
# Implementation Plan: {Project Title} # Implementation Plan: {Project Title}
@@ -333,14 +333,14 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
### CCW Workflow Context ### CCW Workflow Context
**Phase Progression**: **Phase Progression**:
- ✅ Phase 1: Brainstorming (role analyses clarified and refined) - ✅ Phase 1: Brainstorming (role analyses generated by participating roles)
- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed) - ✅ Phase 2: Synthesis (concept enhancement + clarification, {N} questions answered, role analyses refined)
- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights) - ✅ Phase 3: Context Gathering (context-package.json: {N} files, {M} modules analyzed, conflict_risk: {level})
- ✅ Phase 4: Concept Verification (integrated in brainstorming phase | skipped) - ✅ Phase 4: Conflict Resolution ({status}: {conflict_count} conflicts detected and resolved | skipped if no conflicts)
- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md) - ⏳ Phase 5: Task Generation (current phase - generating IMPL_PLAN.md and task JSONs)
**Quality Gates**: **Quality Gates**:
- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending - synthesis-clarify: ✅ Passed ({N} ambiguities resolved, {M} enhancements applied)
- action-plan-verify: ⏳ Pending (recommended before /workflow:execute) - action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
**Context Package Summary**: **Context Package Summary**:
@@ -383,15 +383,15 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
**Context Intelligence (context-package.json)**: **Context Intelligence (context-package.json)**:
- **What**: Smart context gathered by CCW's context-gather phase - **What**: Smart context gathered by CCW's context-gather phase
- **Content**: Focus paths, dependency graph, existing patterns, module structure - **Content**: Focus paths, dependency graph, existing patterns, module structure, tech stack, conflict_risk assessment
- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup - **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup and conflict awareness
- **CCW Value**: Automated intelligent context discovery replacing manual file exploration - **CCW Value**: Automated intelligent context discovery replacing manual file exploration
**Technical Analysis (ANALYSIS_RESULTS.md)**: **Conflict Resolution (CONFLICT_RESOLUTION.md)**:
- **What**: Gemini/Qwen/Codex parallel analysis results - **What**: Conflict analysis and resolution strategies (conditional, exists only if conflict_risk >= medium)
- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns, cross-role synthesis - **Content**: Conflict detection results, resolution options, selected strategies, migration requirements
- **Usage**: Referenced in task planning for technical guidance and risk mitigation - **Usage**: Referenced in task planning for applying conflict resolution strategies and understanding code conflicts
- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence and cross-role integration - **CCW Value**: CLI-powered conflict detection and strategic resolution guidance for complex codebases
### Role Analysis Documents (Highest Priority) ### Role Analysis Documents (Highest Priority)
Role analyses provide specialized perspectives on the implementation: Role analyses provide specialized perspectives on the implementation:
@@ -406,10 +406,10 @@ Role analyses provide specialized perspectives on the implementation:
- **topic-framework.md**: Role-specific discussion points and analysis framework - **topic-framework.md**: Role-specific discussion points and analysis framework
**Artifact Priority in Development**: **Artifact Priority in Development**:
1. Role analysis.md files (primary requirements and design specs from brainstorming) 1. context-package.json (primary source: smart context AND brainstorm artifact catalog in `brainstorm_artifacts`)
2. ANALYSIS_RESULTS.md (technical analysis, optimization strategies, and cross-role synthesis from planning) 2. role/analysis*.md (paths from context-package.json: requirements, design specs, enhanced by synthesis)
3. context-package.json (smart context for execution environment) 3. CONFLICT_RESOLUTION.md (path from context-package.json: conflict strategies, if conflict_risk >= medium)
4. topic-framework.md (discussion framework structure) 4. guidance-specification.md (path from context-package.json: discussion framework)
## 4. Implementation Strategy ## 4. Implementation Strategy
@@ -565,22 +565,22 @@ The command organizes outputs into a standard directory structure.
│ ├── IMPL-1.json # Container task │ ├── IMPL-1.json # Container task
│ ├── IMPL-1.1.json # Leaf task with flow_control │ ├── IMPL-1.1.json # Leaf task with flow_control
│ └── IMPL-1.2.json # Leaf task with flow_control │ └── IMPL-1.2.json # Leaf task with flow_control
├── .braguidance-specification # Input artifacts ├── .brainstorming # Input artifacts from brainstorm + synthesis
│ ├── topic-framework.md │ ├── guidance-specification.md # Discussion framework
│ └── {role}/analysis*.md # Role analyses (may have multiple files per role) │ └── {role}/analysis*.md # Role analyses (enhanced by synthesis, may have multiple files per role)
└── .process/ └── .process/
├── ANALYSIS_RESULTS.md # Input from concept-enhanced ├── context-package.json # Input from context-gather (smart context + conflict_risk)
└── context-package.json # Input from context-gather └── CONFLICT_RESOLUTION.md # Input from conflict-resolution (conditional, if conflict_risk >= medium)
``` ```
## 7. Artifact Integration ## 7. Artifact Integration
The command intelligently detects and integrates artifacts from the `.brainstorming/` directory. The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.
#### Artifact Priority #### Artifact Priority
1. **role/analysis*.md** (highest): Role-specific requirements and design specs from brainstorming (product-manager, system-architect, ui-designer, etc.) 1. **context-package.json** (critical): Primary source - smart context AND all brainstorm artifact paths in `brainstorm_artifacts` section
2. **ANALYSIS_RESULTS.md** (critical): Technical analysis, risk assessment, optimization strategies, and cross-role synthesis from planning phase (generated by concept-enhanced) 2. **role/analysis*.md** (highest): Paths from context-package.json → role-specific requirements, design specs, enhanced by synthesis
3. **guidance-specification.json** (critical): Smart context with focus paths, module structure, and dependency graph from planning phase (generated by context-gather) 3. **CONFLICT_RESOLUTION.md** (high): Path from context-package.json → conflict strategies (conditional, if conflict_risk >= medium)
4. **topic-framework.md** (medium): Discussion framework structure from brainstorming 4. **guidance-specification.md** (medium): Path from context-package.json → discussion framework from brainstorming
#### Artifact-Task Mapping #### Artifact-Task Mapping
Artifacts are mapped to tasks based on their relevance to the task's domain. Artifacts are mapped to tasks based on their relevance to the task's domain.
@@ -598,7 +598,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
**Key Points**: **Key Points**:
- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array - **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 role analysis files from `.brainstorming/*/analysis*.md` - **Context Delivery**: Each codex command receives context via CONTEXT field: `@.workflow/WFS-session/.process/context-package.json` (role analyses loaded dynamically from context package)
- **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity - **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 - **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field
@@ -621,8 +621,12 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_role_analyses", "step": "load_role_analyses",
"action": "Load role analyses for requirements", "action": "Load role analyses from context-package.json",
"commands": ["Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)"], "commands": [
"Read(.workflow/WFS-session/.process/context-package.json)",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analyses", "output_to": "role_analyses",
"on_error": "fail" "on_error": "fail"
}, },
@@ -674,8 +678,12 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_role_analyses", "step": "load_role_analyses",
"action": "Load role analyses", "action": "Load role analyses from context-package.json",
"commands": ["Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)"], "commands": [
"Read(.workflow/WFS-session/.process/context-package.json)",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analyses", "output_to": "role_analyses",
"on_error": "fail" "on_error": "fail"
} }
@@ -685,7 +693,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
"step": 1, "step": 1,
"title": "Implement authentication with Codex", "title": "Implement authentication with Codex",
"description": "Create JWT-based authentication module", "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/*/analysis*.md} EXPECTED: Complete auth module with tests RULES: Follow role analyses\" --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 EXPECTED: Complete auth module with tests RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"], "modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"],
"logic_flow": ["Validate credentials", "Generate JWT", "Return token"], "logic_flow": ["Validate credentials", "Generate JWT", "Return token"],
"depends_on": [], "depends_on": [],
@@ -712,10 +720,11 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
"pre_analysis": [ "pre_analysis": [
{ {
"step": "load_context", "step": "load_context",
"action": "Load context and role analyses", "action": "Load context and role analyses from context-package.json",
"commands": [ "commands": [
"Read(.workflow/WFS-session/.process/context-package.json)", "Read(.workflow/WFS-session/.process/context-package.json)",
"Read(.workflow/WFS-session/.brainstorming/*/analysis*.md)" "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
], ],
"output_to": "full_context", "output_to": "full_context",
"on_error": "fail" "on_error": "fail"
@@ -726,7 +735,7 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
"step": 1, "step": 1,
"title": "Create RBAC models", "title": "Create RBAC models",
"description": "Define role and permission data 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/*/analysis*.md} EXPECTED: Models with migrations RULES: Follow role analyses\" --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 EXPECTED: Models with migrations RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Define role model", "Define permission model", "Create migrations"], "modification_points": ["Define role model", "Define permission model", "Create migrations"],
"logic_flow": ["Design schema", "Implement models", "Generate migrations"], "logic_flow": ["Design schema", "Implement models", "Generate migrations"],
"depends_on": [], "depends_on": [],