# πŸš€ Claude Code Workflow (CCW)
[![Version](https://img.shields.io/badge/version-v4.0.1-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: v4.0.1** - UI Design Workflow V2 with Intelligent Page Inference & Agent Mode. See [CHANGELOG.md](CHANGELOG.md) for details. > > **What's New in v4.0.1**: > - 🧠 **Intelligent Page Inference**: Pages auto-extracted from prompt text - no need to specify `--pages` manually > - πŸ€– **Agent Creative Mode**: `--use-agent` enables parallel exploration of diverse design directions > - 🎯 **Unified Variant Control**: Single `--variants` parameter controls both style cards and UI prototypes > - πŸ”€ **Dual Mode Support**: Standalone (quick prototyping) or Integrated (workflow enhancement) > - πŸ’¬ **Dual Input Sources**: Images, text prompts, or hybrid (text guides image analysis) > - ✨ **Extreme Simplification**: All parameters optional with smart defaults > - ⚑ **Parallel Execution**: Agent mode generates variants concurrently for speed --- ## ✨ 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. ### **πŸ“¦ Local Installation (Install-Claude.ps1)** For local installation without network access, use the bundled PowerShell installer: **Installation Modes:** ```powershell # Interactive mode with prompts (recommended) .\Install-Claude.ps1 # Quick install with automatic backup .\Install-Claude.ps1 -Force -BackupAll # Non-interactive install .\Install-Claude.ps1 -NonInteractive -Force ``` **Installation Options:** | Mode | Description | Installs To | |------|-------------|-------------| | **Global** | System-wide installation (default) | `~/.claude/`, `~/.codex/`, `~/.gemini/` | | **Path** | Custom directory + global hybrid | Local: `agents/`, `commands/`
Global: `workflows/`, `scripts/` | **Backup Behavior:** - **Default**: Automatic backup enabled (`-BackupAll`) - **Disable**: Use `-NoBackup` flag (⚠️ overwrites without backup) - **Backup location**: `claude-backup-{timestamp}/` in installation directory **⚠️ Important Warnings:** - `-Force -BackupAll`: Silent file overwrite (with backup) - `-NoBackup -Force`: Permanent file overwrite (no recovery) - Global mode modifies user profile directories ### **βœ… Verify Installation** After installation, run the following command to ensure CCW is working: ```bash /workflow:session:list ``` > **πŸ“ Installation Notes:** > - The installer will automatically install/update `.codex/` and `.gemini/` directories > - **Global mode**: Installs to `~/.codex` and `~/.gemini` > - **Path mode**: Installs to your specified directory (e.g., `project/.codex`, `project/.gemini`) > - **Backup**: Existing files are backed up by default to `claude-backup-{timestamp}/` > - **Safety**: Use interactive mode for first-time installation to review changes --- ## βš™οΈ Configuration ### **Prerequisites: Required Tools** Before using CCW, install the following command-line tools: #### **Core CLI Tools** | Tool | Purpose | Installation | |------|---------|--------------| | **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | | **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | | **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) | #### **System Utilities** | Tool | Purpose | Installation | |------|---------|--------------| | **ripgrep (rg)** | Fast code search | [Download](https://github.com/BurntSushi/ripgrep/releases) or `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) | | **jq** | JSON processing | [Download](https://jqlang.github.io/jq/download/) or `brew install jq` (macOS), `apt install jq` (Ubuntu) | **Quick Install (All Tools):** ```bash # macOS brew install ripgrep jq npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code # Ubuntu/Debian sudo apt install ripgrep jq npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code # Windows (Chocolatey) choco install ripgrep jq npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code ``` ### **Essential: Gemini CLI Setup** Configure Gemini CLI for optimal integration: ```json // ~/.gemini/settings.json { "contextFileName": ["CLAUDE.md", "GEMINI.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 ``` ### **Recommended: MCP Tools** *(Enhanced Analysis)* MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recommended installation** - While CCW has fallback mechanisms, not installing MCP tools may lead to unexpected behavior or degraded performance in some workflows. #### Available MCP Servers | MCP Server | Purpose | Installation Guide | |------------|---------|-------------------| | **Exa MCP** | External API patterns & best practices | [Install Guide](https://smithery.ai/server/exa) | | **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 - ⚑ **Better Reliability**: Primary tools for certain workflows ⚠️ **Note**: Some workflows expect MCP tools to be available. Without them, you may experience: - Slower code analysis and search operations - Reduced context quality in some scenarios - Fallback to less efficient traditional tools - Potential unexpected behavior in advanced workflows --- ## πŸš€ 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: UI Design Refinement** *(Optional for UI-heavy projects)* ```bash # Simplest - pages inferred from prompt (v4.0.2+) /workflow:ui-design:auto --prompt "Modern blog with home, article and author pages, dark theme" # With session integration /workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --variants 3 # Or run individual design phases /workflow:ui-design:extract --images "refs/*.png" --variants 3 /workflow:ui-design:consolidate --variants "variant-1,variant-3" /workflow:ui-design:generate --variants 2 # Preview generated prototypes (NEW!) # Option 1: Open .workflow/WFS-auth/.design/prototypes/index.html in browser # Option 2: Start local server cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080 # Visit http://localhost:8080 for interactive preview with comparison tools /workflow:ui-design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2" ``` **Phase 3: 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 4: Execution** ```bash # Execute tasks with AI agents /workflow:execute # Monitor progress /workflow:status ``` **Phase 5: Testing & Quality Assurance** ```bash # Generate independent test-fix workflow (v3.2.2+) /workflow:test-gen WFS-auth # Creates WFS-test-auth session /workflow:execute # Runs test validation # 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 ``` > **πŸ’‘ When to Use Which Approach?** > > **Use `/workflow:plan` + `/workflow:execute` for:** > - Complex features requiring multiple modules (>3 modules) > - Tasks with multiple subtasks (>5 subtasks) > - Cross-cutting changes affecting architecture > - Features requiring coordination between components > - When you need structured planning and progress tracking > > **Use Claude Code directly for:** > - Simple, focused changes (single file or module) > - Quick bug fixes with clear solutions > - Documentation updates > - Code refactoring within one component > - Straightforward feature additions **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:ui-design:auto` | **v4.0.2** UI design workflow with pure Claude execution. All parameters optional, no external tools. | | `/workflow:ui-design:extract` | **v4.0.2** Extract design from images/text using Claude-native analysis. Single-pass variant generation. | | `/workflow:ui-design:consolidate` | **v4.0.2** Consolidate style variants into validated design tokens using Claude synthesis. | | `/workflow:ui-design:generate` | **v4.0.2** Generate token-driven HTML/CSS prototypes with agent-based execution. | | `/workflow:ui-design:update` | **v4.0.2** Integrate finalized design system into brainstorming artifacts. | | `/workflow:plan` | Create a detailed, executable plan from a description. | | `/workflow:tdd-plan` | Create TDD workflow (6 phases) with test coverage analysis and Red-Green-Refactor cycles. | | `/workflow:execute` | Execute the current workflow plan autonomously. | | `/workflow:status` | Display the current status of the workflow. | | `/workflow:test-gen [--use-codex] ` | Create test generation workflow with auto-diagnosis and fix cycle for completed implementations. | | `/workflow:tdd-verify` | Verify TDD compliance and generate quality report. | | `/workflow:review` | **Optional** manual review (only use when explicitly needed - passing tests = approved code). | | `/workflow:tools:test-context-gather` | Analyze test coverage and identify missing test files. | | `/workflow:tools:test-concept-enhanced` | Generate test strategy and requirements analysis using Gemini. | | `/workflow:tools:test-task-generate` | Generate test task JSON with test-fix-cycle specification. | ### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.0.2)* The design workflow system provides complete UI design refinement with **pure Claude execution**, **intelligent page inference**, and **zero external dependencies**. #### Core Commands **`/workflow:ui-design:auto`** - Complete workflow orchestrator ```bash # Simplest - pages auto-inferred from prompt (v4.0.2) /workflow:ui-design:auto --prompt "Modern blog with home, article and author pages, dark theme" # Multiple style variants /workflow:ui-design:auto --prompt "SaaS dashboard and settings" --variants 3 # Hybrid: images + text prompt /workflow:ui-design:auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" # Integrated with session + creative mode /workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --variants 2 --creative-variants 3 ``` - **πŸ†• Pure Claude**: No external tools (gemini-wrapper, codex) required - **πŸ†• Zero Dependencies**: All analysis and generation done natively - **All Parameters Optional**: Smart defaults and inference for everything - **Page Inference**: Auto-extract pages from `--prompt` text - **Dual Mode**: Standalone (quick prototyping) or Integrated (workflow enhancement) **`/workflow:ui-design:extract`** - Style analysis with dual input sources ```bash # Pure text prompt /workflow:ui-design:extract --prompt "Modern minimalist, dark theme" --variants 3 # Pure images /workflow:ui-design:extract --images "refs/*.png" --variants 3 # Hybrid (text guides image analysis) /workflow:ui-design:extract --images "refs/*.png" --prompt "Linear.app style" --variants 2 ``` - **Claude-Native**: Single-pass analysis, no external tools - **Enhanced Output**: `style-cards.json` with embedded `proposed_tokens` - **Reproducible**: Deterministic structure, version-controlled logic - **Output**: 1 file (vs 4+ in previous versions) **`/workflow:ui-design:consolidate`** - Validate and merge tokens ```bash # Consolidate selected style variants /workflow:ui-design:consolidate --session WFS-auth --variants "variant-1,variant-3" ``` - **Claude Synthesis**: Single-pass generation of all design system files - **Features**: WCAG AA validation, OKLCH colors, W3C token format - **Output**: `design-tokens.json`, `style-guide.md`, `tailwind.config.js`, `validation-report.json` **`/workflow:ui-design:generate`** - Generate HTML/CSS prototypes ```bash # Standard mode (consistent layouts) /workflow:ui-design:generate --pages "dashboard,auth" --variants 2 # Creative mode (diverse layout exploration) /workflow:ui-design:generate --pages "home,product,cart" --creative-variants 3 ``` - **Page Inference**: Auto-detect from session or default to `["home"]` - **Agent-Only**: Task(conceptual-planning-agent) execution - **Creative Mode**: Parallel agents for diverse layout strategies - **Preview Files**: `index.html`, `compare.html`, `PREVIEW.md` **`/workflow:ui-design:update`** - Integrate design system ```bash # Update brainstorming artifacts with design system /workflow:ui-design:update --session WFS-auth --selected-prototypes "login-variant-1" ``` - **Updates**: `synthesis-specification.md`, `ui-designer/style-guide.md` - **Makes design tokens available for task generation** #### Preview System After running `ui-generate`, you get interactive preview tools: **Quick Preview** (Direct Browser): ```bash # Navigate to prototypes directory cd .workflow/WFS-auth/.design/prototypes # Open index.html in browser (double-click or): open index.html # macOS start index.html # Windows xdg-open index.html # Linux ``` **Full Preview** (Local Server - Recommended): ```bash cd .workflow/WFS-auth/.design/prototypes # Choose one: python -m http.server 8080 # Python npx http-server -p 8080 # Node.js php -S localhost:8080 # PHP # Visit: http://localhost:8080 ``` **Preview Features**: - `index.html`: Master navigation with all prototypes - `compare.html`: Side-by-side comparison with viewport controls (Desktop/Tablet/Mobile) - Synchronized scrolling for layout comparison - Dynamic page switching - Real-time responsive testing --- ### **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. | | `/version` | Display version information and check for updates from GitHub. | --- ## 🧩 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.