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.5.0 - UI Design Workflow with Triple Vision Analysis. See CHANGELOG.md for details.

What's New in v3.5.0:

• 🎨 UI Design Workflow: Complete design refinement workflow from style extraction to prototype generation
• 👁️ Triple Vision Analysis: Combines Claude Code + Gemini + Codex vision capabilities for comprehensive style extraction
• ⏸️ Interactive Checkpoints: User selection points for style variants and prototype confirmation
• 🎯 Zero Agent Overhead: Direct bash execution for CLI tools, removing unnecessary agent wrappers
• 🎨 Style Customization: Runtime override support with --style-overrides parameter
• 📦 Batch Task Generation: Optional automatic task creation for selected prototypes with --batch-plan
• 🔄 Semi-Autonomous Workflow: User-driven continuation at critical design decision points

• 🎯 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.

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)

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.

For local installation without network access, use the bundled PowerShell installer:

Installation Modes:

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

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

After installation, run the following command to ensure CCW is working:

/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

Before using CCW, install the following command-line tools:

Quick Install (All Tools):

# 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

Configure Gemini CLI for optimal integration:

// ~/.gemini/settings.json
{
  "contextFileName": ["CLAUDE.md", "GEMINI.md"]
}

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

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.

• 📊 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

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: UI Design Refinement (Optional for UI-heavy projects)

# Extract design styles from reference images and generate prototypes
/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan

# Or run individual design phases
/workflow:design:style-extract --session WFS-auth --images "refs/*.png"
/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
/workflow:design:ui-generate --session WFS-auth --pages "login,register" --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:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"

Phase 3: 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 4: Execution

# Execute tasks with AI agents
/workflow:execute

# Monitor progress
/workflow:status

Phase 5: Testing & Quality Assurance

# 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

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

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

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

Use the --tool <gemini|qwen|codex> flag to select the desired tool. Defaults to gemini.

The design workflow system provides complete UI design refinement from style extraction to prototype generation with interactive preview tools.

/workflow:design:auto - Complete workflow orchestrator

# Semi-autonomous workflow with user checkpoints
/workflow:design:auto --session WFS-auth --images "refs/*.png" --pages "login,register"
/workflow:design:auto --session WFS-dash --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan

• Checkpoints: User selects style variants (Phase 1) and confirms prototypes (Phase 3)
• Optional: --batch-plan for automatic task generation

/workflow:design:style-extract - Triple vision style analysis

# Extract design from reference images
/workflow:design:style-extract --session WFS-auth --images "design-refs/*.png"

• Vision Sources: Claude Code + Gemini + Codex
• Output: Style variant cards for user selection

/workflow:design:style-consolidate - Validate and merge tokens

# Consolidate selected style variants
/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"

• Features: WCAG AA validation, OKLCH colors, W3C token format
• Output: design-tokens.json, style-guide.md, tailwind.config.js

/workflow:design:ui-generate - Generate HTML/CSS prototypes

# Generate prototypes with preview tools
/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
/workflow:design:ui-generate --session WFS-auth --pages "dashboard" --style-overrides "custom.json"

• 🆕 Preview Files: index.html (navigation), compare.html (side-by-side), PREVIEW.md (instructions)
• Features: Token-driven CSS, semantic HTML5, ARIA attributes, responsive design

/workflow:design:design-update - Integrate design system

# Update brainstorming artifacts with design system
/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"

• Updates: synthesis-specification.md, ui-designer/style-guide.md
• Makes design tokens available for task generation

After running ui-generate, you get interactive preview tools:

Quick Preview (Direct Browser):

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

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

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.

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": [...]
  }
}

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.

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

Each AI model serves its strength:

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

Brainstorm (8 roles) → Synthesis → Plan (4 phases) → Execute → Test → Review

session:start → plan → execute → test-gen → execute

tdd-plan (TEST→IMPL→REFACTOR chains) → execute → tdd-verify

cli:mode:bug-index (analyze) → execute (fix) → test-gen (verify)

• Repository: GitHub - Claude-Code-Workflow
• Issues: Report bugs or request features on GitHub Issues.
• Discussions: Join the Community Forum.

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