# πŸš€ Claude Code Workflow (CCW)
[![Version](https://img.shields.io/badge/version-v3.2.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]() [![MCP Tools](https://img.shields.io/badge/πŸ”§_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol) **Languages:** [English](README.md) | [δΈ­ζ–‡](README_CN.md)
--- **Claude Code Workflow (CCW)** is a next-generation multi-agent automation framework that orchestrates complex software development tasks through intelligent workflow management and autonomous execution. > **πŸŽ‰ Latest: v3.2.0** - Simplified agent architecture with "Tests Are the Review" philosophy. See [CHANGELOG.md](CHANGELOG.md) for details. > > **What's New in v3.2.0**: > - πŸ”„ Simplified from 3 agents to 2 core agents (`@code-developer`, `@test-fix-agent`) > - βœ… "Tests Are the Review" - Passing tests = approved code > - πŸ§ͺ Enhanced test-fix workflow with automatic execution and fixing > - πŸ“¦ Interactive installation with version selection menu --- ## ✨ Key Features - **🎯 Context-First Architecture**: Pre-defined context gathering eliminates execution uncertainty and error accumulation. - **πŸ€– Multi-Agent System**: Specialized agents (`@code-developer`, `@test-fix-agent`) with tech-stack awareness and automated test validation. - **πŸ”„ End-to-End Workflow Automation**: From brainstorming to deployment with multi-phase orchestration. - **πŸ“‹ JSON-First Task Model**: Structured task definitions with `pre_analysis` steps for deterministic execution. - **πŸ§ͺ TDD Workflow Support**: Complete Test-Driven Development with Red-Green-Refactor cycle enforcement. - **🧠 Multi-Model Orchestration**: Leverages Gemini (analysis), Qwen (architecture), and Codex (implementation) strengths. - **βœ… Pre-execution Verification**: Validates plans with both strategic (Gemini) and technical (Codex) analysis. - **πŸ”§ Unified CLI**: A single, powerful `/cli:*` command set for interacting with various AI tools. - **πŸ“¦ Smart Context Package**: `context-package.json` links tasks to relevant codebase files and external examples. --- ## βš™οΈ Installation ### **πŸš€ Quick One-Line Installation** **Windows (PowerShell):** ```powershell Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content ``` **Linux/macOS (Bash/Zsh):** ```bash bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh) ``` ### **πŸ“‹ Interactive Version Selection** After running the installation command, you'll see an interactive menu with real-time version information: ``` Detecting latest release and commits... Latest stable: v3.2.0 (2025-10-02 04:27 UTC) Latest commit: cdea58f (2025-10-02 08:15 UTC) ==================================================== Version Selection Menu ==================================================== 1) Latest Stable Release (Recommended) |-- Version: v3.2.0 |-- Released: 2025-10-02 04:27 UTC \-- Production-ready 2) Latest Development Version |-- Branch: main |-- Commit: cdea58f |-- Updated: 2025-10-02 08:15 UTC |-- Cutting-edge features \-- May contain experimental changes 3) Specific Release Version |-- Install a specific tagged release \-- Recent: v3.2.0, v3.1.0, v3.0.1 ==================================================== Select version to install (1-3, default: 1): ``` **Version Options:** - **Option 1 (Recommended)**: Latest stable release with verified production quality - **Option 2**: Latest development version from main branch with newest features - **Option 3**: Specific version tag for controlled deployments > πŸ’‘ **Pro Tip**: The installer automatically detects and displays the latest version numbers and release dates from GitHub. Just press Enter to select the recommended stable release. ### **βœ… Verify Installation** After installation, run the following command to ensure CCW is working: ```bash /workflow:session:list ``` --- ## πŸš€ Getting Started ### Complete Development Workflow **Phase 1: Brainstorming & Conceptual Planning** ```bash # Multi-perspective brainstorming with role-based agents /workflow:brainstorm:auto-parallel "Build a user authentication system" # Review and refine specific aspects (optional) /workflow:brainstorm:ui-designer "authentication flows" /workflow:brainstorm:synthesis # Generate consolidated specification ``` **Phase 2: Action Planning** ```bash # Create executable implementation plan /workflow:plan "Implement JWT-based authentication system" # OR for TDD approach /workflow:tdd-plan "Implement authentication with test-first development" ``` **Phase 3: Execution** ```bash # Execute tasks with AI agents /workflow:execute # Monitor progress /workflow:status ``` **Phase 4: Testing & Quality Assurance** ```bash # Generate comprehensive test suite (standard workflow) /workflow:test-gen /workflow:execute # OR verify TDD compliance (TDD workflow) /workflow:tdd-verify ``` ### Quick Start for Simple Tasks **Feature Development:** ```bash /workflow:session:start "Add password reset feature" /workflow:plan "Email-based password reset with token expiry" /workflow:execute ``` **Bug Fixing:** ```bash # Interactive analysis with CLI tools /cli:mode:bug-index --tool gemini "Login timeout on mobile devices" # Execute the suggested fix /workflow:execute ``` **Code Analysis:** ```bash # Deep codebase analysis /cli:mode:code-analysis --tool qwen "Analyze authentication module architecture" ``` --- ## πŸ› οΈ Command Reference ### **Unified CLI Commands (`/cli:*)** *Use the `--tool ` flag to select the desired tool. Defaults to `gemini`.* | Command | Description | |---|---| | `/cli:analyze` | Deep codebase analysis. | | `/cli:chat` | Direct, interactive chat with a tool. | | `/cli:execute` | Execute a task with full permissions. | | `/cli:cli-init`| Initialize CLI tool configurations for the workspace. | | `/cli:mode:bug-index` | Analyze bugs and suggest fixes. | | `/cli:mode:code-analysis` | Perform deep code analysis and debugging. | | `/cli:mode:plan` | Project planning and architecture analysis. | ### **Workflow Commands (`/workflow:*)** | Command | Description | |---|---| | `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). | | `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. | | `/workflow:plan` | Create a detailed, executable plan from a description. | | `/workflow:tdd-plan` | Create a Test-Driven Development workflow with Red-Green-Refactor cycles. | | `/workflow:execute` | Execute the current workflow plan autonomously. | | `/workflow:status` | Display the current status of the workflow. | | `/workflow:test-gen` | Automatically generate a test plan from the implementation. | | `/workflow:tdd-verify` | Verify TDD compliance and generate quality report. | | `/workflow:review` | **Optional** manual review (only use when explicitly needed - passing tests = approved code). | ### **Task & Memory Commands** | Command | Description | |---|---| | `/task:*` | Manage individual tasks (`create`, `breakdown`, `execute`, `replan`). | | `/update-memory-full` | Re-index the entire project documentation. | | `/update-memory-related` | Update documentation related to recent changes. | --- ## βš™οΈ Configuration ### **Essential: Gemini CLI Setup** Configure Gemini CLI for optimal integration: ```json // ~/.gemini/settings.json { "contextFileName": "CLAUDE.md" } ``` ### **Recommended: .geminiignore** Optimize performance by excluding unnecessary files: ```bash # .geminiignore (in project root) /dist/ /build/ /node_modules/ /.next/ *.tmp *.log /temp/ # Include important docs !README.md !**/CLAUDE.md ``` ### **Optional: MCP Tools** *(Enhanced Analysis)* MCP (Model Context Protocol) tools provide advanced codebase analysis. **Completely optional** - CCW works perfectly without them. #### Available MCP Servers | MCP Server | Purpose | Installation Guide | |------------|---------|-------------------| | **Exa MCP** | External API patterns & best practices | [Install Guide](https://github.com/exa-labs/exa-mcp-server) | | **Code Index MCP** | Advanced internal code search | [Install Guide](https://github.com/johnhuang316/code-index-mcp) | #### Benefits When Enabled - πŸ“Š **Faster Analysis**: Direct codebase indexing vs manual searching - 🌐 **External Context**: Real-world API patterns and examples - πŸ” **Advanced Search**: Pattern matching and similarity detection - ⚑ **Automatic Fallback**: Uses traditional tools when MCP unavailable --- ## 🧩 How It Works: Design Philosophy ### The Core Problem Traditional AI coding workflows face a fundamental challenge: **execution uncertainty leads to error accumulation**. **Example:** ```bash # Prompt 1: "Develop XX feature" # Prompt 2: "Review XX architecture in file Y, then develop XX feature" ``` While Prompt 1 might succeed for simple tasks, in complex workflows: - The AI may examine different files each time - Small deviations compound across multiple steps - Final output drifts from the intended goal > **CCW's Mission**: Solve the "1-to-N" problem β€” building upon existing codebases with precision, not just "0-to-1" greenfield development. --- ### The CCW Solution: Context-First Architecture #### 1. **Pre-defined Context Gathering** Instead of letting agents randomly explore, CCW uses structured context packages: **`context-package.json`** created during planning: ```json { "metadata": { "task_description": "...", "tech_stack": {"frontend": [...], "backend": [...]}, "complexity": "high" }, "assets": [ { "path": "synthesis-specification.md", "priority": "critical", "sections": ["Backend Module Structure"] } ], "implementation_guidance": { "start_with": ["Step 1", "Step 2"], "critical_security_items": [...] } } ``` #### 2. **JSON-First Task Model** Each task includes a `flow_control.pre_analysis` section: ```json { "id": "IMPL-1", "flow_control": { "pre_analysis": [ { "step": "load_architecture", "commands": ["Read(architecture.md)", "grep 'auth' src/"], "output_to": "arch_context", "on_error": "fail" } ], "implementation_approach": { "modification_points": ["..."], "logic_flow": ["..."] }, "target_files": ["src/auth/index.ts"] } } ``` **Key Innovation**: The `pre_analysis` steps are **executed before implementation**, ensuring agents always have the correct context. #### 3. **Multi-Phase Orchestration** CCW workflows are orchestrators that coordinate slash commands: **Planning Phase** (`/workflow:plan`): ``` Phase 1: session:start β†’ Create session Phase 2: context-gather β†’ Build context-package.json Phase 3: concept-enhanced β†’ CLI analysis (Gemini/Qwen) Phase 4: task-generate β†’ Generate task JSONs with pre_analysis ``` **Execution Phase** (`/workflow:execute`): ``` For each task: 1. Execute pre_analysis steps β†’ Load context 2. Apply implementation_approach β†’ Make changes 3. Validate acceptance criteria β†’ Verify success 4. Generate summary β†’ Track progress ``` #### 4. **Multi-Model Orchestration** Each AI model serves its strength: | Model | Role | Use Cases | |-------|------|-----------| | **Gemini** | Analysis & Understanding | Long-context analysis, architecture review, bug investigation | | **Qwen** | Architecture & Design | System design, code generation, architectural planning | | **Codex** | Implementation | Feature development, testing, autonomous execution | **Example:** ```bash # Gemini analyzes the problem space /cli:mode:code-analysis --tool gemini "Analyze auth module" # Qwen designs the solution /cli:analyze --tool qwen "Design scalable auth architecture" # Codex implements the code /workflow:execute # Uses @code-developer with Codex ``` --- ### From 0-to-1 vs 1-to-N Development | Scenario | Traditional Workflow | CCW Approach | |----------|---------------------|--------------| | **Greenfield (0β†’1)** | βœ… Works well | βœ… Adds structured planning | | **Feature Addition (1β†’2)** | ⚠️ Context uncertainty | βœ… Context-package links to existing code | | **Bug Fixing (Nβ†’N+1)** | ⚠️ May miss related code | βœ… Pre-analysis finds dependencies | | **Refactoring** | ⚠️ Unpredictable scope | βœ… CLI analysis + structured tasks | --- ### Key Workflows #### **Complete Development (Brainstorm β†’ Deploy)** ``` Brainstorm (8 roles) β†’ Synthesis β†’ Plan (4 phases) β†’ Execute β†’ Test β†’ Review ``` #### **Quick Feature Development** ``` session:start β†’ plan β†’ execute β†’ test-gen β†’ execute ``` #### **TDD Workflow** ``` tdd-plan (TESTβ†’IMPLβ†’REFACTOR chains) β†’ execute β†’ tdd-verify ``` #### **Bug Fixing** ``` cli:mode:bug-index (analyze) β†’ execute (fix) β†’ test-gen (verify) ``` --- ## 🀝 Contributing & Support - **Repository**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow) - **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues). - **Discussions**: Join the [Community Forum](https://github.com/catlog22/Claude-Code-Workflow/discussions). ## πŸ“„ License This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.