**[English](README.md) | [中文](README_CN.md)**

--- ## ✨ Key Features

### 🎯 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. --- ## 🚀 Quick Start ### Install CCW ```bash npm install -g claude-code-workflow ccw install -m Global ``` ### 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

### Workflow Examples ```bash # Level 1: Instant execution /workflow:lite-lite-lite "Fix typo in README" # Level 2: Lightweight planning /workflow:lite-plan "Add JWT authentication" /workflow:lite-fix "User upload fails with 413 error" # Level 3: Standard planning with session /workflow:plan "Implement payment gateway integration" /workflow:execute # Level 4: Multi-role brainstorming /workflow:brainstorm:auto-parallel "Design real-time collaboration system" --count 5 /workflow:plan --session WFS-xxx /workflow:execute ``` --- ## 🛠️ CLI Tool Installation

CLI	Description	Official Docs
Gemini	Google AI analysis	google-gemini/gemini-cli
Codex	OpenAI autonomous coding	openai/codex
OpenCode	Open-source multi-model	opencode-ai/opencode
Qwen	Alibaba Qwen-Code	QwenLM/Qwen

--- ## 🎭 Semantic CLI Invocation

Users can **semantically specify CLI tools** in prompts - the system automatically invokes the corresponding CLI. ### Basic Invocation

| User Prompt | System Action | |-------------|---------------| | "Use Gemini to analyze the auth module" | Auto-invoke `gemini` CLI for analysis | | "Let Codex review this code" | Auto-invoke `codex` CLI for review | | "Ask Qwen about performance optimization" | Auto-invoke `qwen` CLI for consultation |

### Multi-CLI Orchestration

| Pattern | User Prompt Example | |---------|---------------------| | **Collaborative** | "Use Gemini and Codex to collaboratively analyze security vulnerabilities" | | **Parallel** | "Have Gemini, Codex, and Qwen analyze the architecture in parallel" | | **Iterative** | "Use Gemini to diagnose, then Codex to fix, iterate until resolved" | | **Pipeline** | "Gemini designs the solution, Codex implements, Claude reviews" |

📝 More Examples

```text # Single CLI invocation User: "Use Gemini to analyze the database query performance" → System auto-calls: gemini CLI with analysis task # Collaborative analysis User: "Use Gemini and Codex to collaboratively review the authentication flow" → System auto-calls: gemini + codex CLIs, synthesizes results # Parallel multi-perspective User: "Have all available CLIs analyze this architecture design in parallel" → System auto-calls: gemini, codex, qwen in parallel → merged report # Sequential pipeline User: "Use Gemini to plan the refactoring, then Codex to implement it" → System auto-calls: gemini (plan) → codex (implement) sequentially ```

### Custom CLI Registration Register **any API as a custom CLI** via Dashboard interface: ```bash ccw view # Open Dashboard → Status → API Settings → Add Custom CLI ```

| Field | Example | |-------|---------| | **Name** | `deepseek` | | **Endpoint** | `https://api.deepseek.com/v1/chat` | | **API Key** | `your-api-key` |

> ⚙️ Register once, invoke semantically forever - no code changes needed. --- ## 🔍 ACE Tool Configuration ACE (Augment Context Engine) provides powerful semantic code search.

| Method | Link | |--------|------| | **Official** | [Augment MCP Documentation](https://docs.augmentcode.com/context-services/mcp/overview) | | **Proxy** | [ace-tool (GitHub)](https://github.com/eastxiaodong/ace-tool) |

--- ## 📚 CodexLens Local Search > ⚠️ **In Development**: CodexLens is under iterative optimization. Some features may be unstable.

Search Mode	Description
FTS	Full-text search, based on SQLite FTS5
Semantic	Semantic search, using local embedding models
Hybrid	Hybrid search, combining FTS + Semantic + Reranking

📦 Installation

```bash # Enter codex-lens directory cd codex-lens # Install dependencies pip install -e . # Initialize index codexlens index /path/to/project ``` Open Dashboard via `ccw view`, manage indexes and execute searches in **CodexLens Manager**.

--- ## 💻 CCW CLI Commands ```bash ccw install # Install workflow files ccw view # Open dashboard ccw cli -p "..." # Execute CLI tools (Gemini/Qwen/Codex) ccw upgrade -a # Upgrade all installations ``` ### Dashboard Features

Feature	Description
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

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

--- ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Main Workflow (4 Levels) │ │ ⚡ Level 1: lite-lite-lite (instant, no artifacts) │ │ 📝 Level 2: lite-plan / lite-fix / multi-cli-plan (→ execute) │ │ 📊 Level 3: plan / tdd-plan / test-fix-gen (session persist) │ │ 🧠 Level 4: brainstorm:auto-parallel → plan → execute │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ Issue Workflow (Supplement) │ │ 🔍 discover → 📋 plan → 📦 queue → ▶️ execute (worktree) │ └─────────────────────────────────────────────────────────────────┘ ``` **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 --- ## 🤝 Contributing

--- ## 📄 License

MIT License - see [LICENSE](LICENSE)