# Claude Code Workflow (CCW) - Intelligent Development Workflow System [δΈ­ζ–‡](README_CN.md) | **English** **An innovative AI-powered development workflow orchestration system featuring progressive complexity management, document-state separation architecture, and intelligent multi-agent coordination.** > πŸš€ **Version 2.0+** - Next-generation development automation with advanced architectural patterns and intelligent workflow orchestration. ## πŸ—οΈ System Architecture Claude Code Workflow implements a **4-layer intelligent development architecture**: ### 🧠 Core Innovation: Document-State Separation Pattern - **Markdown Files** β†’ Planning, requirements, task structure, implementation strategy - **JSON Files** β†’ Execution state, progress tracking, session metadata, dynamic changes - **Auto-Sync Engine** β†’ Bidirectional coordination with clear ownership rules ### ⚑ Progressive Complexity Management - **Level 0** (Simple): <5 tasks, minimal structure, direct execution - **Level 1** (Medium): 5-15 tasks, enhanced planning, agent coordination - **Level 2** (Complex): >15 tasks, full orchestration, iterative refinement ### πŸ€– Intelligent Agent Orchestration - **5 Specialized Agents**: Planning β†’ Development β†’ Review β†’ Quality β†’ Memory - **Context Preservation**: Original task context maintained throughout agent chain - **Quality Gates**: Each agent validates input and ensures output standards - **Adaptive Workflows**: Workflow depth matches task complexity requirements ### πŸ”„ Advanced Features - **Session-First Architecture**: All commands auto-discover and inherit active session context - **Embedded Workflow Logic**: Commands contain built-in document generation - **Gemini CLI Integration**: 12+ specialized templates for intelligent context management - **Real-time Synchronization**: Reliable document-state coordination with conflict resolution ## πŸ”₯ Revolutionary Features ### 🎯 Intelligent Workflow Orchestration **Three Execution Patterns**: - **Simple**: `TodoWrite β†’ Context β†’ Implementation β†’ Review` - **Medium**: `TodoWrite β†’ Planning β†’ Implementation β†’ Review` - **Complex**: `TodoWrite β†’ Planning β†’ Implementation β†’ Review β†’ Iteration (max 2 cycles)` ### πŸ—οΈ Advanced Architecture Components #### 1. **5-Agent Specialized System** - **Action Planning Agent** (27KB) - PRD processing & implementation plans - **Code Developer** (13KB) - Test-driven development expert - **Code Review Agent** (12KB) - Quality assurance & security validation - **Conceptual Planning Agent** (9KB) - High-level concept design - **Memory Gemini Bridge** (8KB) - Distributed memory synchronization #### 2. **Dynamic Template Ecosystem** - **10 Role-Based Planning Templates**: Multi-perspective brainstorming - **6 Tech-Stack Templates**: Language-specific development guidelines - **Script-Based Discovery**: YAML frontmatter parsing with semantic loading - **Conditional Content Filtering**: Version-aware template management #### 3. **JSON Document Coordination System** **Hierarchical File Structure**: ``` .workflow/WFS-[topic-slug]/ β”œβ”€β”€ workflow-session.json (master state) β”œβ”€β”€ IMPL_PLAN.md (planning document) β”œβ”€β”€ TODO_LIST.md (progress tracking) └── .task/ β”œβ”€β”€ impl-*.json (main tasks) β”œβ”€β”€ impl-*.*.json (subtasks) └── impl-*.*.*.json (detailed subtasks, max 3 levels) ``` **Data Ownership Rules**: - **Documents Own**: Implementation strategy, requirements, context - **JSON Owns**: Task definitions, status, progress, dependencies - **Shared Responsibility**: Task status, progress calculation, cross-references #### 4. **Real-time Synchronization Engine** ``` File System Monitor β†’ Change Parser β†’ Conflict Detector β†’ Sync Engine β†’ Validator β†’ Audit Log ``` **Conflict Resolution Priority**: Data ownership rules β†’ Recent timestamp β†’ User intent β†’ System consistency ## πŸ“ Project Structure ``` Claude-CCW/ β”œβ”€β”€ .claude/ β”‚ β”œβ”€β”€ agents/ # Specialized development agents β”‚ β”‚ β”œβ”€β”€ conceptual-planning-agent.md β”‚ β”‚ β”œβ”€β”€ action-planning-agent.md β”‚ β”‚ β”œβ”€β”€ code-developer.md β”‚ β”‚ β”œβ”€β”€ code-review-agent.md β”‚ β”‚ └── [4 more agents] β”‚ β”œβ”€β”€ commands/ # Command implementations with file output β”‚ β”‚ β”œβ”€β”€ workflow/ # 8 core workflow commands (all with file generation) β”‚ β”‚ β”œβ”€β”€ task/ # 6 task management commands (JSON + summary files) β”‚ β”‚ β”œβ”€β”€ docs/ # Documentation management commands β”‚ β”‚ └── [utility commands] β”‚ β”œβ”€β”€ planning-templates/ # 10 role-based planning templates β”‚ β”‚ β”œβ”€β”€ system-architect.md β”‚ β”‚ β”œβ”€β”€ ui-designer.md β”‚ β”‚ └── [8 more roles] β”‚ β”œβ”€β”€ tech-stack-templates/ # 6 language-specific guidelines β”‚ β”‚ β”œβ”€β”€ javascript-dev.md β”‚ β”‚ β”œβ”€β”€ python-dev.md β”‚ β”‚ β”œβ”€β”€ react-dev.md β”‚ β”‚ └── [3 more languages] β”‚ β”œβ”€β”€ scripts/ # Dynamic template loaders & executors β”‚ β”‚ β”œβ”€β”€ plan-executor.sh β”‚ β”‚ β”œβ”€β”€ tech-stack-loader.sh β”‚ β”‚ └── gemini-chat-executor.sh β”‚ β”œβ”€β”€ schemas/ # JSON schemas for state management β”‚ β”‚ β”œβ”€β”€ workflow-session.json β”‚ β”‚ β”œβ”€β”€ task.json β”‚ β”‚ └── issue.json β”‚ β”œβ”€β”€ output-styles/ # Document generation templates β”‚ β”‚ └── agent-workflow-coordination.md β”‚ └── workflows/ # Unified workflow system principles β”‚ β”œβ”€β”€ unified-workflow-system-principles.md β”‚ β”œβ”€β”€ session-management-principles.md β”‚ β”œβ”€β”€ file-structure-standards.md β”‚ └── [18+ workflow guidelines] β”œβ”€β”€ .workflow/ # Generated workflow sessions β”‚ β”œβ”€β”€ WFS-[topic-slug]/ # Individual session directories β”‚ β”‚ β”œβ”€β”€ workflow-session.json # Session state β”‚ β”‚ β”œβ”€β”€ IMPL_PLAN.md # Planning document β”‚ β”‚ β”œβ”€β”€ TODO_LIST.md # Task tracking β”‚ β”‚ β”œβ”€β”€ WORKFLOW_ISSUES.md # Issue tracking β”‚ β”‚ β”œβ”€β”€ .task/ # JSON task files β”‚ β”‚ β”œβ”€β”€ .summaries/ # Completion summaries β”‚ β”‚ └── reports/ # Status reports β”‚ └── session_status.jsonl # Multi-session registry β”œβ”€β”€ CLAUDE.md # Project-specific guidelines └── [Project documentation files] ``` ## πŸš€ Core Features ### 1. Unified File Output System **All Workflow Commands Generate Files**: ```bash # Context analysis with exportable reports /workflow:context --export --health-check # β†’ Generates reports/STATUS_REPORT.md and reports/HEALTH_CHECK.md # Implementation with comprehensive logging /workflow:implement --type=medium # β†’ Generates TODO_LIST.md and IMPLEMENTATION_LOG.md # Issue tracking with structured files /workflow:issue create --type=feature "OAuth2 support" # β†’ Generates WORKFLOW_ISSUES.md and issues/ISS-001.json ``` **Dynamic Template System**: ```bash # Discover available planning roles ~/.claude/scripts/plan-executor.sh --list # Load specific role semantically ~/.claude/scripts/plan-executor.sh --load system-architect ``` ### 2. Multi-Agent Workflow Orchestration **Simple Tasks** (Bug fixes, single-file changes): ```bash /workflow:session start simple "Fix login button styling" /workflow:implement --type=simple # Auto-completes with minimal overhead ``` **Medium Tasks** (Multi-component features): ```bash /workflow:session start medium "Add user profile editing" /workflow:plan # Lightweight planning /workflow:implement --type=medium # Multi-agent execution /workflow:review # Quality validation ``` **Complex Tasks** (System-level changes): ```bash /workflow:session start complex "Implement OAuth2 authentication" /workflow:plan # Detailed planning with PRD /workflow:implement --type=complex # Full agent orchestration /task:create "Design OAuth2 architecture" /task:breakdown IMPL-001 /workflow:status # Progress monitoring /workflow:review # Comprehensive review ``` ### 3. Session Management with State Persistence **Complete Session Control**: - **JSON State Management**: All workflow state persisted in `workflow-session.json` - **Task-Level Tracking**: Detailed task management in `tasks.json` - **Pause/Resume**: Safe interruption and recovery - **Progress Monitoring**: Real-time TodoWrite integration **Session Example**: ```json { "session_id": "WFS-2025-001", "type": "complex", "current_phase": "IMPLEMENT", "phases": { "PLAN": {"status": "completed"}, "IMPLEMENT": {"status": "active", "progress": 60}, "REVIEW": {"status": "pending"} } } ``` ### 4. Intelligent Context Analysis **Gemini CLI Integration** with 12+ specialized templates: - **Architecture Analysis**: System structure and component relationships - **Security Review**: Vulnerability assessment and compliance - **Performance Analysis**: Optimization opportunities and bottlenecks - **Pattern Detection**: Code patterns and best practices - **Dependency Analysis**: Module relationships and impacts ### 5. Unified Task Management **Dual-Layer Architecture**: - **Workflow Layer**: Macro-level session and phase management - **Task Layer**: Micro-level task execution and tracking - **Automatic Synchronization**: Bi-directional data consistency - **Unified Status**: Single command for complete project overview ## 🎯 Usage Examples ### Multi-Perspective Feature Planning ```bash # Use conceptual planning agent for brainstorming # System loads multiple planning roles dynamically: # - system-architect (technical feasibility) # - ui-designer (user experience) # - security-expert (security implications) # - data-architect (data requirements) /workflow:session start complex "Real-time chat feature" /workflow:plan # β†’ Generates comprehensive PRD with multi-role analysis # β†’ Creates IMPLEMENTATION_PLAN.md and TASK_DECOMPOSITION.md ``` ### Tech Stack Specific Development ```bash # Code developer agent loads appropriate tech guidelines /workflow:implement --type=medium # β†’ Automatically detects JavaScript/React codebase # β†’ Loads javascript-dev.md and react-dev.md guidelines # β†’ Applies language-specific best practices ``` ### Advanced Session Management ```bash # Complex project with interruption handling /workflow:session start complex "Microservices migration" /workflow:plan # Detailed planning /workflow:implement --type=complex # Begin implementation # Work gets interrupted /workflow:session pause # Safe state preservation # Later resume /workflow:session resume # Continues from exact point /workflow:status # Shows current progress /task:execute IMPL-003.2 # Continue specific task ``` ## πŸ› οΈ Installation & Setup ### Prerequisites - **Claude Code CLI** environment - **Bash/PowerShell** for script execution - **Git** for version control - **Gemini CLI** (optional, for enhanced analysis) ### Installation ```bash # Clone the repository git clone https://github.com/catlog22/Claude-CCW.git cd Claude-CCW # Copy to Claude Code directory cp -r .claude ~/.claude/ cp CLAUDE.md ~/.claude/ # Make scripts executable chmod +x ~/.claude/scripts/*.sh ``` ### Quick Start ```bash # Start with a simple task /workflow:session start simple "Fix responsive layout bug" /workflow:implement --type=simple # Or try a medium complexity task /workflow:session start medium "Add user notification system" /workflow:plan /workflow:implement --type=medium /workflow:review ``` ## πŸ“Š System Capabilities ### Planning & Analysis - **Multi-Role Brainstorming**: 10 specialized planning perspectives - **PRD Generation**: Comprehensive requirement documentation - **Risk Assessment**: Automated risk identification and mitigation - **Dependency Analysis**: Smart module relationship detection ### Development & Implementation - **Tech Stack Awareness**: 6 language-specific development guidelines - **Test-Driven Development**: Automated test generation and execution - **Code Quality Enforcement**: Real-time quality validation - **Pattern Recognition**: Existing codebase pattern analysis ### Project Management - **Session Persistence**: Complete workflow state management - **Progress Tracking**: Real-time TodoWrite integration - **Task Decomposition**: Hierarchical task breakdown - **Status Monitoring**: Unified progress dashboard ### Quality Assurance - **Multi-Phase Review**: Planning β†’ Implementation β†’ Review validation - **Security Analysis**: Automated security assessment - **Performance Monitoring**: Performance impact analysis - **Documentation Updates**: Automatic documentation synchronization ## πŸ”§ Advanced Configuration ### Template Customization Add custom planning roles or tech stack guidelines by: 1. Creating new `.md` files with YAML frontmatter 2. Following the template structure pattern 3. Templates auto-discovered by script loaders ### Session Configuration Modify session behavior in: - `.claude/workflows/session-management-principles.md` - `.claude/schemas/workflow-session.json` ### Agent Coordination Customize agent workflows in: - `.claude/workflows/agent-orchestration-patterns.md` - Individual agent configuration files ## πŸ“ˆ Performance & Scalability - **JSON-Based State**: Efficient session persistence - **Modular Architecture**: Independent component operation - **Dynamic Loading**: On-demand template activation - **Scalable Task Management**: Handles simple to enterprise-level complexity - **Memory Efficient**: Smart context management with Gemini integration ## 🀝 Contributing This is an active development project. Key areas for contribution: - Additional planning role templates - New tech stack development guidelines - Enhanced agent coordination patterns - Performance optimizations - Documentation improvements ## πŸ“„ License [Specify license - typically MIT or Apache 2.0] --- **Claude Code Workflow (CCW)** - Elevating Claude Code development through intelligent workflow orchestration and comprehensive project management.