Initial release: Claude Code Workflow (CCW) v2.0

🚀 Revolutionary AI-powered development workflow orchestration system ## 🔥 Core Innovations - **Document-State Separation**: Markdown for planning, JSON for execution state - **Progressive Complexity Management**: Level 0-2 adaptive workflow depth - **5-Agent Orchestration**: Specialized AI agents with context preservation - **Session-First Architecture**: Auto-discovery and state inheritance ## 🏗️ Key Features - Intelligent workflow orchestration (Simple/Medium/Complex patterns) - Real-time document-state synchronization with conflict resolution - Hierarchical task management with 3-level JSON structure - Gemini CLI integration with 12+ specialized templates - Comprehensive file output generation for all workflow commands ## 📦 Installation Remote one-liner installation: ``` iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-CCW/main/install-remote.ps1) ``` ## 🎯 System Architecture 4-layer intelligent development architecture: 1. Command Layer - Smart routing and version management 2. Agent Layer - 5 specialized development agents 3. Workflow Layer - Gemini templates and task orchestration 4. Memory Layer - Distributed documentation and auto-sync 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-11 02:33:51 +08:00 · 2025-09-07 17:39:54 +08:00
commit 445ac823ba
87 changed files with 19076 additions and 0 deletions
--- a/WORKFLOW_DOCUMENT_SYSTEM.md
+++ b/WORKFLOW_DOCUMENT_SYSTEM.md
@@ -0,0 +1,523 @@
+# Workflow Document System - Complete Integration Guide
+
+## 🎯 Overview
+
+This document provides a comprehensive guide to the integrated workflow document system that successfully merges the original design philosophy with the current command architecture. The system follows the core principle: **"Documents store primary plans, JSON manages state"**.
+
+## 📋 Core Design Philosophy
+
+### Document-State Separation
+- **Documents (Markdown)**: Store requirements, task decomposition, implementation strategies, and acceptance criteria
+- **JSON States**: Manage execution status, progress tracking, session coordination, and real-time state changes
+- **Bidirectional Sync**: Automatic coordination between planning documents and state management systems
+
+### Planning-First Approach
+**"Measure twice, cut once"** - Comprehensive planning prevents costly mistakes and ensures quality outcomes.
+
+## 🏗️ Complete Directory Structure
+
+### Unified Workflow Directory
+```
+.workflow/WFS-[topic-slug]/
+├── workflow-session.json          # Session state and document tracking
+├── PLAN.md                         # Basic planning (all complexities)
+├── IMPLEMENTATION_PLAN.md          # Staged execution plan (complex only)
+├── TASK_DECOMPOSITION.md           # Task breakdown (medium+/complex)
+├── TODO_CHECKLIST.md               # Progress tracking (medium+/complex)
+├── .task/                          # Task management system
+│   └── tasks/                      # Individual task JSON files
+│       ├── IMPL-001.json
+│       ├── IMPL-002.json
+│       └── IMPL-003.json
+└── artifacts/                      # Generated files and logs
+    ├── reports/                    # Progress and analysis reports
+    ├── logs/                       # Execution logs and checkpoints
+    └── execution/                  # Task execution artifacts
+        └── IMPL-001/
+            ├── summary.json
+            ├── outputs/
+            └── logs/
+```
+
+## 📄 Document Types and Usage
+
+### 1. PLAN.md - Universal Planning Document
+**Generated for**: All workflow complexities  
+**Purpose**: Basic planning and task identification  
+
+```markdown
+# Implementation Plan - [Project Name]
+
+## Overview
+Brief description of what needs to be implemented
+
+## Requirements
+- [Inherited from workflow session context]
+- [Specific functional requirements]
+
+## Task Breakdown
+- IMPL-001: [Task description]
+- IMPL-002: [Task description]
+- IMPL-003: [Task description]
+
+## Dependencies
+- Task order and relationships
+- External dependencies
+
+## Success Criteria
+- Acceptance criteria for completion
+- Definition of done
+```
+
+### 2. IMPLEMENTATION_PLAN.md - Complex Workflow Strategy
+**Generated for**: Complex workflows only  
+**Purpose**: Detailed staged execution plan with risk assessment
+
+```markdown
+# Implementation Plan - [Project Name]
+
+## Executive Summary
+High-level overview and strategic approach
+
+## Phase Breakdown
+
+### Phase 1: Foundation
+- **Objective**: [Core infrastructure/base components]
+- **Tasks**: IMPL-001, IMPL-002
+- **Duration**: [Estimate]
+- **Success Criteria**: [Measurable outcomes]
+
+### Phase 2: Core Implementation  
+- **Objective**: [Main functionality]
+- **Tasks**: IMPL-003, IMPL-004, IMPL-005
+- **Dependencies**: Phase 1 completion
+
+### Phase 3: Integration & Testing
+- **Objective**: [System integration and validation]
+- **Tasks**: IMPL-006, IMPL-007
+
+## Risk Assessment
+- **High Risk**: [Description] - Mitigation: [Strategy]
+- **Medium Risk**: [Description] - Mitigation: [Strategy]
+
+## Quality Gates
+- Code review requirements
+- Testing coverage targets
+- Performance benchmarks
+
+## Rollback Strategy
+- Rollback triggers and procedures
+- Data preservation approach
+```
+
+### 3. TASK_DECOMPOSITION.md - Hierarchical Task Breakdown
+**Generated for**: Medium+ workflows when triggered, Complex workflows always  
+**Purpose**: Detailed task hierarchy with dependencies and context
+
+```markdown
+# Task Decomposition - [Project Name]
+
+## Task Hierarchy
+
+### IMPL-001: [Parent Task Name]
+**Owner**: [Agent Type]  
+**Effort**: [Estimate]  
+**Status**: [pending|active|completed]
+
+#### Context
+- **Requirements**: [Specific requirements for this task]
+- **Scope**: [Files and components to be modified]
+- **Acceptance Criteria**: [What constitutes completion]
+
+#### Subtasks
+- IMPL-001.1: [Subtask name] - [Agent] - [Status]
+- IMPL-001.2: [Subtask name] - [Agent] - [Status]
+
+#### Dependencies
+- **Upstream**: [Tasks that must complete first]
+- **Downstream**: [Tasks blocked by this task]
+
+## Execution Order
+1. **Parallel Track A**: IMPL-001, IMPL-003
+2. **Sequential**: IMPL-002 (depends on Track A)
+3. **Final**: IMPL-006 (depends on all above)
+
+## Progress Tracking
+- **Total Tasks**: [Count]
+- **Completed**: [Count] ([Percentage]%)
+- **In Progress**: [Count]
+- **Blocked**: [Count]
+```
+
+### 4. TODO_CHECKLIST.md - Progress Tracking
+**Generated for**: Medium+ workflows when triggered, Complex workflows always  
+**Purpose**: Real-time progress tracking with task status
+
+```markdown
+# TODO Checklist - [Project Name]
+
+## Progress Overview
+- **Overall Progress**: [X]% ([completed]/[total] items)
+- **Current Phase**: [Phase name]
+- **Active Tasks**: [Count]
+
+## Phase 1: Foundation
+### IMPL-001: [Task Name]
+- [ ] **IMPL-001.1**: [Subtask] ([Agent])
+  - [ ] Design component interface
+  - [x] Implement basic structure  
+  - [ ] Add unit tests
+- [x] **IMPL-001.2**: [Completed subtask] ([Agent])
+
+**Status**: In Progress (1/2 subtasks complete)
+
+## Blocked Items
+- **IMPL-003**: Waiting for API specification
+  - **Blocker**: External dependency
+  - **Action**: Follow up with API team
+
+## Completed Items ✅
+- **IMPL-000**: [Completed task] - Completed [Date]
+
+## Cross-References
+- Task Details: See TASK_DECOMPOSITION.md
+- Implementation Strategy: See IMPLEMENTATION_PLAN.md
+```
+
+## 🔄 Document Generation Rules
+
+### Complexity-Based Generation
+
+#### Simple Workflows
+**Document Requirements**: Minimal or skip documentation
+- **Generated**: Optional basic PLAN.md
+- **Focus**: Direct implementation over documentation
+- **Use Cases**: Single file changes, bug fixes, small modifications
+
+#### Medium Workflows  
+**Document Requirements**: Structured planning with conditional decomposition
+- **Always Generated**: PLAN.md
+- **Conditionally Generated**: TASK_DECOMPOSITION.md + TODO_CHECKLIST.md
+- **Trigger Conditions**:
+  - Task involves >3 modules/components
+  - >5 distinct subtasks identified
+  - Complex interdependencies detected
+  - Estimated effort >4 hours
+
+#### Complex Workflows
+**Document Requirements**: Complete documentation suite (MANDATORY)
+- **Always Generated**: 
+  - PLAN.md
+  - IMPLEMENTATION_PLAN.md  
+  - TASK_DECOMPOSITION.md
+  - TODO_CHECKLIST.md
+- **Use Cases**: Architecture changes, security implementations, system integrations
+
+### Automatic Generation Triggers
+
+```
+Medium Complexity Triggers:
+IF (modules_affected > 3) OR 
+   (subtasks_count > 5) OR 
+   (estimated_effort > "4h") OR
+   (dependencies_count > 2)
+THEN generate_task_decomposition()
+
+Complex Complexity Triggers:
+IF (architecture_changes = true) OR
+   (security_implementation = true) OR
+   (performance_optimization = true) OR
+   (estimated_effort > "8h") OR
+   (risk_level = "high")
+THEN generate_full_documentation_suite()
+```
+
+## 🔧 Command Integration
+
+### Workflow Commands Integration
+
+#### /workflow:session start
+```bash
+/workflow:session start <complexity> "task description"
+```
+**Document Actions**:
+- Creates session directory structure
+- Initializes document templates based on complexity
+- Prepares JSON state files with document references
+- Sets up document generation capabilities
+
+#### /workflow:plan
+```bash
+/workflow:plan [--force-complex|--force-simple]
+```
+**Document Actions**:
+- Generates PLAN.md for all complexities
+- Generates IMPLEMENTATION_PLAN.md for complex workflows
+- Updates workflow-session.json with document references
+- Creates document directory structure
+
+#### /workflow:implement  
+```bash
+/workflow:implement --type=<simple|medium|complex>
+```
+**Document Actions**:
+- Checks decomposition triggers for medium workflows
+- MANDATORY generates TASK_DECOMPOSITION.md + TODO_CHECKLIST.md for complex
+- Creates individual task JSON files linked to documents
+- Synchronizes task creation between documents and JSON states
+
+### Task Commands Integration
+
+#### /task:create
+```bash
+/task:create "task title" [--from-decomposition]
+```
+**Document Actions**:
+- Updates TASK_DECOMPOSITION.md and TODO_CHECKLIST.md if they exist
+- Can import from existing TASK_DECOMPOSITION.md structure
+- Maintains cross-references between documents and JSON
+- Triggers document generation if conditions are met
+
+#### /task:status
+```bash
+/task:status [--format=tree|list|json] [--detailed]
+```
+**Document Actions**:
+- Displays progress from TODO_CHECKLIST.md
+- Shows document-based task hierarchy
+- Indicates document sync status
+- Provides document-aware progress reporting
+
+#### /task:breakdown
+```bash
+/task:breakdown <task-id> [--strategy=auto|interactive]
+```
+**Document Actions**:
+- Generates/updates TASK_DECOMPOSITION.md
+- Creates corresponding TODO_CHECKLIST.md entries
+- Maintains parent-child relationships in documents
+- Updates document cross-references
+
+#### /task:execute
+```bash
+/task:execute <task-id> [--mode=auto|guided|review]
+```
+**Document Actions**:
+- Uses context from TASK_DECOMPOSITION.md if available
+- Updates TODO_CHECKLIST.md progress during execution
+- Stores execution artifacts in structured directory
+- Maintains document-JSON synchronization
+
+## 🔄 Document-JSON Coordination
+
+### Data Ownership Rules
+
+#### Documents Own (Source of Truth)
+- Requirements and scope definition
+- Task breakdown and structure
+- Implementation strategies and approaches
+- Acceptance criteria and quality standards
+- Risk assessments and mitigation plans
+
+#### JSON States Own (Source of Truth)
+- Current execution status (pending/active/completed/blocked)
+- Progress percentages and timing
+- Agent assignments and execution results
+- Session metadata and timestamps
+- Dynamic state changes
+
+#### Shared Responsibility (Synchronized)
+- Task hierarchies (structure in docs, status in JSON)
+- Dependencies (defined in docs, status tracked in JSON)
+- Progress tracking (structure in docs, current state in JSON)
+
+### Synchronization Mechanisms
+
+#### Document → JSON Updates
+```
+Event: Task decomposition document created
+Action: 
+  - Create corresponding task entries in JSON
+  - Import task hierarchy and dependencies
+  - Initialize status as "pending"
+  - Link JSON tasks to document sections
+```
+
+#### JSON → Document Updates  
+```
+Event: Task status changed in JSON
+Action:
+  - Update TODO_CHECKLIST.md with new status
+  - Update progress percentages
+  - Mark completion timestamps
+  - Update dependency blocking status
+```
+
+### Session State with Document Tracking
+
+```json
+{
+  "session_id": "WFS-[topic-slug]", 
+  "project": "OAuth2 authentication system",
+  "type": "complex",
+  "status": "active",
+  "current_phase": "IMPLEMENT",
+  "directory": ".workflow/WFS-[topic-slug]",
+  "documents": {
+    "planning": {
+      "PLAN.md": {
+        "status": "generated", 
+        "path": ".workflow/WFS-[topic-slug]/PLAN.md"
+      },
+      "IMPLEMENTATION_PLAN.md": {
+        "status": "generated",
+        "path": ".workflow/WFS-[topic-slug]/IMPLEMENTATION_PLAN.md"
+      }
+    },
+    "implementation": {
+      "TASK_DECOMPOSITION.md": {
+        "status": "generated",
+        "path": ".workflow/WFS-[topic-slug]/TASK_DECOMPOSITION.md"
+      },
+      "TODO_CHECKLIST.md": {
+        "status": "generated", 
+        "path": ".workflow/WFS-[topic-slug]/TODO_CHECKLIST.md"
+      }
+    }
+  },
+  "task_system": {
+    "enabled": true,
+    "directory": ".workflow/WFS-[topic-slug]/.task",
+    "next_task_id": 4
+  }
+}
+```
+
+### Individual Task JSON Structure
+
+```json
+{
+  "id": "IMPL-001",
+  "title": "Build authentication module",
+  "status": "pending",
+  "type": "feature",
+  "agent": "code-developer",
+  "effort": "4h",
+  "context": {
+    "inherited_from": "WFS-[topic-slug]",
+    "requirements": ["JWT authentication", "OAuth2 support"],
+    "scope": ["src/auth/*", "tests/auth/*"],
+    "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"]
+  },
+  "dependencies": {
+    "upstream": [],
+    "downstream": ["IMPL-002"]
+  },
+  "subtasks": [],
+  "execution": {
+    "attempts": 0,
+    "current_attempt": null,
+    "history": []
+  },
+  "metadata": {
+    "created_at": "2025-09-05T10:30:00Z",
+    "last_updated": "2025-09-05T10:30:00Z",
+    "last_sync": "2025-09-05T10:30:00Z",
+    "version": "1.0"
+  }
+}
+```
+
+## 🚀 Usage Examples
+
+### Example 1: Simple Bug Fix
+```bash
+# Start simple workflow - minimal documentation
+/workflow:session start simple "fix login timeout issue"
+/workflow:implement --type=simple
+# Documents: Optional PLAN.md or skip documentation
+# Focus: Direct implementation
+```
+
+### Example 2: Medium Feature Implementation
+```bash
+# Start medium workflow - structured planning
+/workflow:session start medium "add user profile editing"
+/workflow:plan  # Generates PLAN.md
+/workflow:implement --type=medium
+# If >3 modules detected: Auto-generates TASK_DECOMPOSITION.md + TODO_CHECKLIST.md
+```
+
+### Example 3: Complex System Integration
+```bash
+# Start complex workflow - full documentation suite
+/workflow:session start complex "implement OAuth2 authentication"
+/workflow:plan  # Generates PLAN.md + IMPLEMENTATION_PLAN.md
+/workflow:implement --type=complex
+# MANDATORY: Generates TASK_DECOMPOSITION.md + TODO_CHECKLIST.md
+```
+
+### Example 4: Task Management with Documents
+```bash
+# Create tasks from decomposition document
+/task:create --from-decomposition
+# Monitor progress with document integration
+/task:status --format=tree  # Shows document-based hierarchy
+# Execute with document context
+/task:execute IMPL-001  # Uses TASK_DECOMPOSITION.md context
+```
+
+## 🎯 Key Benefits
+
+### 1. **Unified Planning System**
+- Consistent document formats across all workflow types
+- Clear complexity-based requirements
+- Automatic generation based on triggers
+
+### 2. **Seamless Integration** 
+- Documents and JSON work together automatically
+- No manual synchronization required
+- Real-time coordination between planning and execution
+
+### 3. **Scalable Complexity Management**
+- Simple tasks: minimal overhead
+- Medium tasks: structured when needed
+- Complex tasks: comprehensive documentation
+
+### 4. **Comprehensive Tracking**
+- Progress visible in both documents and JSON
+- Cross-references maintained automatically
+- Full audit trail of decisions and changes
+
+### 5. **Original Design Preserved**
+- **Documents**: Store primary plans and strategies
+- **JSON**: Manage execution state and progress
+- **Coordination**: Automatic bidirectional sync
+
+## 📚 Technical Documentation References
+
+**Core System Architecture**:
+- `@~/.claude/workflows/unified-workflow-system-principles.md` - **Master reference for all core principles**
+
+**Implementation Details**:
+- `@~/.claude/workflows/workflow-document-management-principles.md` - Document generation templates and rules
+- `@~/.claude/workflows/hierarchical-document-splitting-system.md` - **Hierarchical document splitting with 3-level structure**
+- `@~/.claude/workflows/session-management-principles.md` - Session state management implementation
+- `@~/.claude/workflows/task-management-principles.md` - Task JSON schemas and validation
+- `@~/.claude/workflows/file-structure-establishment-process.md` - Directory structure creation process
+- `@~/.claude/workflows/json-document-coordination-system.md` - Technical synchronization details
+
+## 🎉 Success Metrics
+
+### Implementation Success
+✅ **Complete Document System**: All 4 document types implemented and integrated  
+✅ **Hierarchical Structure**: 3-level progressive document splitting (Level 0/1/2)
+✅ **Unified Directory Structure**: Consistent `.workflow/WFS-[topic-slug]/` format across all commands  
+✅ **Smart Document Management**: Automatic splitting/merging based on project scale
+✅ **Automatic Generation**: Smart triggers based on complexity and conditions  
+✅ **Bidirectional Sync**: Documents and JSON states coordinate seamlessly  
+✅ **Command Integration**: All workflow and task commands support hierarchical document system  
+✅ **Scalable Architecture**: Handles projects from simple fixes to complex systems (>100 tasks)
+✅ **Original Design Fusion**: Successfully merged original workflow.md vision with current architecture
+
+The workflow document system now fully realizes the vision of **"Documents for primary plans, JSON for state management"** while providing a scalable, integrated, and user-friendly development workflow experience.