🚀 Claude Code Workflow (CCW)

Languages: English | 中文

---

Claude Code Workflow (CCW) is a JSON-driven multi-agent development framework with intelligent CLI orchestration (Gemini/Qwen/Codex), context-first architecture, and automated workflow execution. It transforms AI development from simple prompt chaining into a powerful orchestration system.

🎉 Version 6.1.3: CLI Tool Simplification

Core Improvements:

• 🔧 Simplified edit_file: Parameter-based input only (--path, --old, --new)
• 📝 Updated tool-strategy.md: Added sed as line operation alternative

See CHANGELOG.md for complete details.

📚 New to CCW? Check out the Getting Started Guide for a beginner-friendly 5-minute tutorial!

---

✨ Core Concepts

CCW is built on a set of core principles that distinguish it from traditional AI development approaches:

• Context-First Architecture: Eliminates uncertainty during execution through pre-defined context gathering, ensuring agents have the right information before implementation.
• JSON-First State Management: Task state is fully stored in .task/IMPL-*.json files as the single source of truth, enabling programmatic orchestration without state drift.
• Autonomous Multi-Stage Orchestration: Commands chain-invoke specialized sub-commands and agents to automate complex workflows with zero user intervention.
• Multi-Model Strategy: Leverages the unique strengths of different AI models (e.g., Gemini for analysis, Codex for implementation) for superior results.
• Layered Memory System: A 4-tier documentation system that provides context at the appropriate abstraction level, preventing information overload.
• Specialized Role-Based Agents: A suite of agents (@code-developer, @test-fix-agent, etc.) that emulate a real software team for diverse tasks.

---

⚙️ Installation

📦 npm Install (Recommended)

Install globally via npm:

npm install -g claude-code-workflow

Then install workflow files to your system:

# Interactive installation
ccw install

# Global installation (to ~/.claude)
ccw install -m Global

# Project-specific installation
ccw install -m Path -p /path/to/project

✅ Verify Installation

After installation, open Claude Code and verify that workflow commands are available by running:

/workflow:session:list

If slash commands (e.g., /workflow:*) are recognized, the installation was successful.

---

🖥️ CCW CLI Tool

The ccw command provides a powerful CLI for managing your Claude Code Workflow installation:

Commands

Command	Description
ccw install	Install workflow files to Global (~/.claude) or specific Path
ccw upgrade	Upgrade existing installations to current package version
ccw uninstall	Remove workflow files from an installation
ccw view	Open the workflow dashboard in browser
ccw serve	Start dashboard server without opening browser
ccw list	List all managed installations

Usage Examples

# Install globally
ccw install -m Global

# Install to specific project
ccw install -m Path -p ./my-project

# Open dashboard
ccw view

# Start dashboard server on custom port
ccw serve -p 8080

# Upgrade all installations
ccw upgrade -a

# List installations
ccw list

Dashboard Features

The CCW Dashboard (ccw view) provides:

• 📊 Session Overview: View all workflow sessions with status and progress
• 📋 Task Management: Track task execution and completion
• 🔍 Review Sessions: Manage code review cycles
• ⚙️ MCP Manager: Configure and monitor MCP servers
• 🪝 Hook Manager: Manage Claude Code hooks
• 📁 Project Explorer: Navigate project structure and artifacts

---

🛠️ Command Reference

CCW provides a rich set of commands for managing workflows, tasks, and interactions with AI tools. For a complete list and detailed descriptions of all available commands, please refer to the COMMAND_REFERENCE.md file.

For detailed technical specifications of each command, see COMMAND_SPEC.md.

---

💡 Need Help? Use the Interactive Command Guide

CCW includes a built-in Command Guide Skill to help you discover and use commands effectively:

• CCW-help - Get interactive help and command recommendations
• CCW-issue - Report bugs or request features using guided templates

The Command Guide provides:

• 🔍 Smart Command Search - Find commands by keyword, category, or use case
• 🤖 Next-Step Recommendations - Get suggestions for what to do after any command
• 📖 Detailed Documentation - View arguments, examples, and best practices
• 🎓 Beginner Onboarding - Learn the 14 core commands through guided learning paths
• 📝 Issue Reporting - Generate standardized bug reports and feature requests

Usage Examples:

User: "CCW-help"
→ Interactive menu with command search, recommendations, and documentation

User: "What should I do after /workflow:plan?"
→ Recommends /workflow:execute, /workflow:action-plan-verify with workflow patterns

User: "CCW-issue"
→ Guided template generation for bugs, features, or question inquiries

---

🚀 Quick Start

The best way to get started is by following the 5-minute tutorial in the Getting Started Guide.

Here's a quick example of a common development workflow:

Option 1: Lite-Plan Workflow (⚡ Recommended for Quick Tasks)

Lightweight interactive workflow with in-memory planning and immediate execution:

# Basic usage with auto-detection
/workflow:lite-plan "Add JWT authentication to user login"

# Force code exploration
/workflow:lite-plan -e "Refactor logging module for better performance"

# Basic usage
/workflow:lite-plan "Add unit tests for authentication service"

Interactive Flow:

1. Phase 1: Automatic task analysis and smart code exploration (if needed)
2. Phase 2: Answer clarification questions (if any)
3. Phase 3: Review generated plan and task breakdown
4. Phase 4: Three-dimensional confirmation:
   • ✅ Confirm/Modify/Cancel task
   • 🔧 Choose execution: Agent / Provide Plan Only / CLI (Gemini/Qwen/Codex)
   • 🔍 Optional code review: No / Claude / Gemini / Qwen / Codex
5. Phase 5: Watch live execution and task tracking

Option 2: Lite-Fix Workflow (🐛 Recommended for Bug Fixes)

Intelligent bug diagnosis and fix workflow with adaptive severity assessment:

# Standard bug fix (auto-adapts based on severity)
/workflow:lite-fix "User avatar upload fails with 413 error"

# Production hotfix mode
/workflow:lite-fix --hotfix "Payment gateway 5xx errors"

Workflow Features:

• Phase 1: Intelligent root cause diagnosis with adaptive search
• Phase 2: Automatic impact assessment and risk scoring
• Phase 3: Fix strategy generation based on complexity
• Phase 4: Risk-aware verification planning
• Phase 5: User confirmation with execution selection
• Phase 6: Execution dispatch with complete artifact tracking

Session Artifacts (saved to .workflow/.lite-fix/{bug-slug}-{timestamp}/):

• diagnosis.json - Root cause analysis and reproduction steps
• impact.json - Risk score, severity, and workflow adaptations
• fix-plan.json - Fix strategy and implementation tasks
• task.json - Enhanced Task JSON with complete context
• followup.json - Auto-generated follow-up tasks (hotfix mode only)

Option 3: Full Workflow (📋 Comprehensive Planning)

Traditional multi-stage workflow for complex projects:

1. Create Plan (auto-starts session):

   /workflow:plan "Implement JWT-based user login and registration"
   

2. Execute Plan:

   /workflow:execute
   

3. View Status (optional):

   /workflow:status
   

---

📚 Documentation

CCW provides comprehensive documentation to help you get started quickly and master advanced features:

📖 Getting Started

• Getting Started Guide - 5-minute quick start tutorial
• Installation Guide - Detailed installation instructions (中文)
• Workflow Decision Guide - 🌳 Interactive flowchart to choose the right command
• Examples - Real-world use cases and practical examples
• FAQ - Common questions and troubleshooting

🏗️ Architecture & Design

• Architecture Overview - System design and core components
• Project Introduction - Detailed project overview
• Workflow Diagrams - Visual workflow representations

📋 Command Reference

• Command Reference - Complete list of all commands
• Command Spec - Detailed technical specifications
• Command Flow Standard - Command design patterns

🤝 Contributing

• Contributing Guide - How to contribute to CCW
• Changelog - Version history and release notes

---

🤝 Contributing & Support

• Repository: GitHub - Claude-Code-Workflow
• Issues: Report bugs or request features on GitHub Issues.
• Discussions: Join the Community Forum.
• Contributing: See CONTRIBUTING.md for contribution guidelines.

📄 License

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