Claude-Code-Workflow/README.md

🚀 Claude Code Workflow (CCW)

Languages: English | 中文

---

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 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):

Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content

Linux/macOS (Bash/Zsh):

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:

/workflow:session:list

---

🚀 Getting Started

Complete Development Workflow

Phase 1: Brainstorming & Conceptual Planning

# 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

# 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

# Execute tasks with AI agents
/workflow:execute

# Monitor progress
/workflow:status

Phase 4: Testing & Quality Assurance

# 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:

/workflow:session:start "Add password reset feature"
/workflow:plan "Email-based password reset with token expiry"
/workflow:execute

Bug Fixing:

# Interactive analysis with CLI tools
/cli:mode:bug-index --tool gemini "Login timeout on mobile devices"

# Execute the suggested fix
/workflow:execute

Code Analysis:

# Deep codebase analysis
/cli:mode:code-analysis --tool qwen "Analyze authentication module architecture"

---

🛠️ Command Reference

Unified CLI Commands (`/cli:*)

Use the --tool <gemini|qwen|codex> 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:

// ~/.gemini/settings.json
{
  "contextFileName": "CLAUDE.md"
}

Recommended: .geminiignore

Optimize performance by excluding unnecessary files:

# .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
Code Index MCP	Advanced internal code search	Install Guide

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:

# 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:

{
  "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:

{
  "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:

# 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
• Issues: Report bugs or request features on GitHub Issues.
• Discussions: Join the Community Forum.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.