mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-26 19:56:37 +08:00
docs: consolidate documentation with 4-level workflow guide
- Add WORKFLOW_GUIDE.md (EN) and WORKFLOW_GUIDE_CN.md (CN) - Simplify README.md to highlight 4-level workflow system - Remove redundant docs: MCP_*.md, WORKFLOW_DECISION_GUIDE*.md, WORKFLOW_DIAGRAMS.md - Move COMMAND_SPEC.md to docs/ - Move codex_mcp.md, CODEX_LENS_AUTO_HYBRID.md to codex-lens/docs/ - Delete temporary debug documents and outdated files Root directory: 28 → 14 MD files
This commit is contained in:
catlog22
351
README.md
351
README.md
@@ -1,312 +1,137 @@
|
||||
# 🚀 Claude Code Workflow (CCW)
|
||||
|
||||
[](https://smithery.ai/skills?ns=catlog22&utm_source=github&utm_medium=badge)
|
||||
|
||||
# Claude Code Workflow (CCW)
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||||
[](https://www.npmjs.com/package/claude-code-workflow)
|
||||
[](LICENSE)
|
||||
[]()
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/actions/workflows/visual-tests.yml)
|
||||
|
||||
**Languages:** [English](README.md) | [中文](README_CN.md)
|
||||
**[English](README.md) | [中文](README_CN.md)**
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
**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.
|
||||
**CCW** is a JSON-driven multi-agent development framework with intelligent CLI orchestration. It provides **4-level workflow system** from rapid execution to full brainstorming, transforming AI development into powerful orchestration.
|
||||
|
||||
> **🎉 Version 6.3.19: Search Enhancement & CLI Tools Upgrade**
|
||||
>
|
||||
> **New Features**:
|
||||
> - 🔍 **Dense + Reranker Search**: Cross-Encoder reranking for improved result relevance
|
||||
> - 💻 **OpenCode AI Support**: New OpenCode CLI tool integration
|
||||
> - 🛠️ **Service Architecture**: Preload service, cache management, UV package manager support
|
||||
> - 📊 **Issue Multi-Queue Execution**: Supports Codex for long-running autonomous work
|
||||
>
|
||||
> **Recommended Workflow**:
|
||||
> - 🚀 **Issue Workflow** (`/issue:plan` → `/issue:queue` → `/issue:execute`): Recommend **Codex** executor for long-running autonomous coding
|
||||
>
|
||||
> See [CHANGELOG.md](CHANGELOG.md) for complete details and migration guide.
|
||||
## Key Features
|
||||
|
||||
> 📚 **New to CCW?** Check out the [**Getting Started Guide**](GETTING_STARTED.md) for a beginner-friendly 5-minute tutorial!
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **4-Level Workflows** | From `lite-lite-lite` (instant) to `brainstorm` (multi-role analysis) |
|
||||
| **Multi-CLI Orchestration** | Gemini, Qwen, Codex, Claude - auto-select or manual |
|
||||
| **Dependency-Aware Parallelism** | Agent parallel execution without worktree complexity |
|
||||
| **Issue Workflow** | Post-development maintenance with optional worktree isolation |
|
||||
| **JSON-First State** | `.task/IMPL-*.json` as single source of truth |
|
||||
| **Dashboard** | Visual session management, CodexLens search, graph explorer |
|
||||
|
||||
> 📖 **New?** See [Workflow Guide](WORKFLOW_GUIDE.md) for the complete 4-level workflow system.
|
||||
|
||||
---
|
||||
|
||||
## ✨ Core Concepts
|
||||
## Quick Start
|
||||
|
||||
CCW is built on a set of core principles that distinguish it from traditional AI development approaches:
|
||||
### Install
|
||||
|
||||
- **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
|
||||
|
||||
### **📋 Requirements**
|
||||
|
||||
| Platform | Node.js | Additional |
|
||||
|----------|---------|------------|
|
||||
| Windows | 20.x or 22.x LTS (recommended) | Node 23+ requires [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) |
|
||||
| macOS | 18.x+ | Xcode Command Line Tools |
|
||||
| Linux | 18.x+ | build-essential |
|
||||
|
||||
> **Note**: The `better-sqlite3` dependency requires native compilation. Using Node.js LTS versions avoids build issues.
|
||||
|
||||
### **📦 npm Install (Recommended)**
|
||||
|
||||
Install globally via npm:
|
||||
```bash
|
||||
npm install -g claude-code-workflow
|
||||
```
|
||||
|
||||
Then install workflow files to your system:
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
/workflow:session:list
|
||||
```
|
||||
If slash commands (e.g., `/workflow:*`) are recognized, the installation was successful.
|
||||
### Choose Your Workflow Level
|
||||
|
||||
---
|
||||
| Level | Command | Use Case |
|
||||
|-------|---------|----------|
|
||||
| **1** | `/workflow:lite-lite-lite` | Quick fixes, config changes |
|
||||
| **2** | `/workflow:lite-plan` | Clear single-module features |
|
||||
| **2** | `/workflow:lite-fix` | Bug diagnosis and fix |
|
||||
| **2** | `/workflow:multi-cli-plan` | Multi-perspective analysis |
|
||||
| **3** | `/workflow:plan` | Multi-module development |
|
||||
| **3** | `/workflow:tdd-plan` | Test-driven development |
|
||||
| **4** | `/workflow:brainstorm:auto-parallel` | New features, architecture design |
|
||||
|
||||
## 🖥️ 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 |
|
||||
| `ccw cli -p "..."` | Execute CLI tools (Gemini/Qwen/Codex) with prompt |
|
||||
| `ccw core-memory` | Manage session clustering and memory |
|
||||
|
||||
### **Usage Examples**
|
||||
### Example Workflows
|
||||
|
||||
```bash
|
||||
# Install globally
|
||||
ccw install -m Global
|
||||
# Level 1: Instant execution
|
||||
/workflow:lite-lite-lite "Fix typo in README"
|
||||
|
||||
# Install to specific project
|
||||
ccw install -m Path -p ./my-project
|
||||
# Level 2: Lightweight planning
|
||||
/workflow:lite-plan "Add JWT authentication"
|
||||
/workflow:lite-fix "User upload fails with 413 error"
|
||||
|
||||
# Open dashboard
|
||||
ccw view
|
||||
# Level 3: Standard planning with session
|
||||
/workflow:plan "Implement payment gateway integration"
|
||||
/workflow:execute
|
||||
|
||||
# Start dashboard server on custom port
|
||||
ccw serve --port 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
|
||||
- 🔍 **CodexLens Manager**: Native code indexing with FTS + Semantic + Hybrid search
|
||||
- 🧠 **Core Memory**: Session clustering visualization with cluster management
|
||||
- 📄 **CLAUDE.md Manager**: File tree viewer for configuration management
|
||||
- 🎯 **Skills Manager**: View and manage Claude Code skills
|
||||
- 🕸️ **Graph Explorer**: Interactive code relationship visualization (Cytoscape.js)
|
||||
- ⚙️ **MCP Manager**: Configure and monitor MCP servers
|
||||
- 🪝 **Hook Manager**: Manage Claude Code hooks
|
||||
- ❓ **Help View**: Internationalized help documentation
|
||||
- 💻 **CLI Manager**: CLI execution history with session resume
|
||||
|
||||
> 📖 See [**Dashboard Guide**](DASHBOARD_GUIDE.md) and [**Dashboard Operations**](DASHBOARD_OPERATIONS_EN.md) for detailed documentation.
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security
|
||||
|
||||
The dashboard server is **localhost-bound by default** and **API endpoints require authentication**. See `ccw/docs/SECURITY.md` for the full security model, token usage, and safe deployment guidance.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 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**](COMMAND_REFERENCE.md) file.
|
||||
|
||||
For detailed technical specifications of each command, see [**COMMAND_SPEC.md**](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
|
||||
# Level 4: Multi-role brainstorming
|
||||
/workflow:brainstorm:auto-parallel "Design real-time collaboration system" --count 5
|
||||
/workflow:plan --session WFS-xxx
|
||||
/workflow:execute
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
The best way to get started is by following the 5-minute tutorial in the [**Getting Started Guide**](GETTING_STARTED.md).
|
||||
|
||||
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:
|
||||
## CLI Tool
|
||||
|
||||
```bash
|
||||
# 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"
|
||||
ccw install # Install workflow files
|
||||
ccw view # Open dashboard
|
||||
ccw cli -p "..." # Execute CLI tools (Gemini/Qwen/Codex)
|
||||
ccw upgrade -a # Upgrade all installations
|
||||
```
|
||||
|
||||
**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
|
||||
### Dashboard Features
|
||||
|
||||
### **Option 2: Lite-Fix Workflow** (🐛 Recommended for Bug Fixes)
|
||||
|
||||
Intelligent bug diagnosis and fix workflow with adaptive severity assessment:
|
||||
|
||||
```bash
|
||||
# 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):
|
||||
```bash
|
||||
/workflow:plan "Implement JWT-based user login and registration"
|
||||
```
|
||||
2. **Execute Plan**:
|
||||
```bash
|
||||
/workflow:execute
|
||||
```
|
||||
3. **View Status** (optional):
|
||||
```bash
|
||||
/workflow:status
|
||||
```
|
||||
- **Session Overview** - Track workflow sessions and progress
|
||||
- **CodexLens** - FTS + Semantic + Hybrid code search
|
||||
- **Graph Explorer** - Interactive code relationship visualization
|
||||
- **CLI Manager** - Execution history with session resume
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
## Documentation
|
||||
|
||||
CCW provides comprehensive documentation to help you get started quickly and master advanced features:
|
||||
|
||||
### 📖 **Getting Started**
|
||||
- [**Getting Started Guide**](GETTING_STARTED.md) - 5-minute quick start tutorial
|
||||
- [**Installation Guide**](INSTALL.md) - Detailed installation instructions ([中文](INSTALL_CN.md))
|
||||
- [**Workflow Decision Guide**](WORKFLOW_DECISION_GUIDE.md) - 🌳 Interactive flowchart to choose the right command
|
||||
- [**Examples**](EXAMPLES.md) - Real-world use cases and practical examples
|
||||
- [**FAQ**](FAQ.md) - Common questions and troubleshooting
|
||||
|
||||
### 🖥️ **Dashboard**
|
||||
- [**Dashboard Guide**](DASHBOARD_GUIDE.md) - Dashboard user guide and interface overview
|
||||
- [**Dashboard Operations**](DASHBOARD_OPERATIONS_EN.md) - Detailed operation instructions
|
||||
|
||||
### 🔄 **Workflow Guides**
|
||||
- [**Issue Loop Workflow**](docs/workflows/ISSUE_LOOP_WORKFLOW.md) - Batch issue processing with two-phase lifecycle (accumulate → resolve)
|
||||
|
||||
### 🏗️ **Architecture & Design**
|
||||
- [**Architecture Overview**](ARCHITECTURE.md) - System design and core components
|
||||
- [**Project Introduction**](PROJECT_INTRODUCTION.md) - Detailed project overview
|
||||
- [**Workflow Diagrams**](WORKFLOW_DIAGRAMS.md) - Visual workflow representations
|
||||
|
||||
### 📋 **Command Reference**
|
||||
- [**Command Reference**](COMMAND_REFERENCE.md) - Complete list of all commands
|
||||
- [**Command Spec**](COMMAND_SPEC.md) - Detailed technical specifications
|
||||
- [**Command Flow Standard**](COMMAND_FLOW_STANDARD.md) - Command design patterns
|
||||
|
||||
### 🤝 **Contributing**
|
||||
- [**Contributing Guide**](CONTRIBUTING.md) - How to contribute to CCW
|
||||
- [**Changelog**](CHANGELOG.md) - Version history and release notes
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [**Workflow Guide**](WORKFLOW_GUIDE.md) | 4-level workflow system (recommended) |
|
||||
| [**Getting Started**](GETTING_STARTED.md) | 5-minute quick start |
|
||||
| [**Dashboard Guide**](DASHBOARD_GUIDE.md) | Dashboard user guide |
|
||||
| [**FAQ**](FAQ.md) | Common questions |
|
||||
| [**Changelog**](CHANGELOG.md) | Version history |
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing & Support
|
||||
## Architecture
|
||||
|
||||
- **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).
|
||||
- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Main Workflow (4 Levels) │
|
||||
│ Level 1: lite-lite-lite (instant, no artifacts) │
|
||||
│ Level 2: lite-plan / lite-fix / multi-cli-plan (→ lite-execute)│
|
||||
│ Level 3: plan / tdd-plan / test-fix-gen (session persistence) │
|
||||
│ Level 4: brainstorm:auto-parallel → plan → execute │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Issue Workflow (Supplement) │
|
||||
│ discover → plan → queue → execute (worktree isolation) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 📄 License
|
||||
**Core Principles:**
|
||||
- **Dependency Analysis** solves parallelism - no worktree needed for main workflow
|
||||
- **Issue Workflow** supplements main workflow for post-development maintenance
|
||||
- Select workflow level based on complexity - avoid over-engineering
|
||||
|
||||
This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
- **Repository**: [GitHub](https://github.com/catlog22/Claude-Code-Workflow)
|
||||
- **Issues**: [Report bugs or request features](https://github.com/catlog22/Claude-Code-Workflow/issues)
|
||||
- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE)
|
||||
|
||||
Reference in New Issue
Block a user