catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-28 09:23:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README and WORKFLOW_GUIDE with simplified content

Browse Source 
- Streamline README documentation
- Update workflow guide with current best practices
This commit is contained in:
catlog22
2026-02-27 22:52:28 +08:00
parent b02c8497c7
commit 690d524aee
4 changed files with 644 additions and 1752 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
README.md
View File

@@ -17,7 +17,7 @@
<br/>
<!-- Typing Animation -->
<a href="https://git.io/typing-svg"><img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=22&pause=1000&color=6366F1&center=true&vCenter=true&random=false&width=600&lines=JSON-Driven+Multi-Agent+Framework;4-Level+Workflow+System;Semantic+CLI+Orchestration;Gemini+%7C+Codex+%7C+OpenCode+%7C+Qwen+%7C+Claude" alt="Typing SVG" /></a>
<a href="https://git.io/typing-svg"><img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=22&pause=1000&color=6366F1&center=true&vCenter=true&random=false&width=600&lines=JSON-Driven+Multi-Agent+Framework;Skill-based+Workflow+System;Semantic+CLI+Orchestration;Gemini+%7C+Codex+%7C+OpenCode+%7C+Qwen+%7C+Claude" alt="Typing SVG" /></a>
</div>
@@ -42,8 +42,8 @@
<tr>
<td width="50%">
### 🎯 4-Level Workflows
From `lite-lite-lite` (instant) to `brainstorm` (multi-role analysis)
### 🎯 Skill-based Workflows
From `lite-plan` (lightweight) to `brainstorm` (multi-role analysis)
### 🔄 Multi-CLI Orchestration
Gemini, Qwen, Codex, Claude - auto-select or manual
@@ -57,8 +57,8 @@ Background queue execution service
</td>
<td width="50%">
### 📦 Workflow Session Commands
start/resume/complete/sync sessions
### 📦 Session Lifecycle
start/resume/complete/sync workflow sessions
### 🖥️ Terminal Dashboard
Multi-terminal grid with execution monitor
@@ -74,7 +74,7 @@ Agent-to-User interactive interface
</table>
</div>
> 📖 **New?** See [Workflow Guide](WORKFLOW_GUIDE.md) for the complete 4-level workflow system.
> 📖 **New?** See [Workflow Guide](WORKFLOW_GUIDE.md) for complete workflow documentation.
---
@@ -87,37 +87,44 @@ npm install -g claude-code-workflow
ccw install -m Global
```
> **Troubleshooting**: If you see `NODE_MODULE_VERSION` mismatch errors for `better-sqlite3`, run `npm rebuild better-sqlite3`. See [FAQ - Troubleshooting](FAQ.md#better-sqlite3-node_module_version-mismatch) for details.
### Workflow Skills vs Commands
### Choose Your Workflow Level
CCW uses two types of invocations:
| Type | Format | Examples |
|------|--------|----------|
| **Skills** | Trigger phrase (no slash) | `workflow:lite-plan`, `brainstorm`, `workflow:plan` |
| **Commands** | Slash command | `/ccw`, `/workflow/session:start`, `/issue/new` |
### Choose Your Workflow Skill
<div align="center">
<table>
<tr><th>Level</th><th>Command</th><th>Use Case</th></tr>
<tr><td><b>2</b></td><td><code>/workflow:lite-plan</code></td><td>Quick fixes, single-module features</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:lite-fix</code></td><td>Bug diagnosis and fix</td></tr>
<tr><td><b>2</b></td><td><code>/workflow:multi-cli-plan</code></td><td>Multi-perspective analysis</td></tr>
<tr><td><b>3</b></td><td><code>/workflow:plan</code></td><td>Multi-module development</td></tr>
<tr><td><b>3</b></td><td><code>/workflow:tdd-plan</code></td><td>Test-driven development</td></tr>
<tr><td><b>4</b></td><td><code>/workflow:brainstorm:auto-parallel</code></td><td>New features, architecture design</td></tr>
<tr><th>Skill Trigger</th><th>Use Case</th></tr>
<tr><td><code>workflow:lite-plan</code></td><td>Lightweight planning, single-module features</td></tr>
<tr><td><code>workflow:multi-cli-plan</code></td><td>Multi-CLI collaborative analysis</td></tr>
<tr><td><code>workflow:plan</code></td><td>Full planning with session persistence</td></tr>
<tr><td><code>workflow:tdd-plan</code></td><td>Test-driven development</td></tr>
<tr><td><code>workflow:test-fix-gen</code></td><td>Test generation and fix cycles</td></tr>
<tr><td><code>brainstorm</code></td><td>Multi-role brainstorming analysis</td></tr>
</table>
</div>
### Workflow Examples
```bash
# Level 2: Lightweight planning (recommended for most tasks)
/workflow:lite-plan "Add JWT authentication"
/workflow:lite-fix "User upload fails with 413 error"
# Skill triggers (no slash - just describe what you want)
workflow:lite-plan "Add JWT authentication"
workflow:plan "Implement payment gateway integration"
workflow:execute
# Level 3: Standard planning with session
/workflow:plan "Implement payment gateway integration"
/workflow:execute
# Brainstorming
brainstorm "Design real-time collaboration system"
# Level 4: Multi-role brainstorming
/workflow:brainstorm:auto-parallel "Design real-time collaboration system" --count 5
/workflow:plan --session WFS-xxx
/workflow:execute
# Slash commands for session management
/workflow/session:start
/workflow/session:resume
/workflow/session:complete
```
---
@@ -172,49 +179,6 @@ Users can **semantically specify CLI tools** in prompts - the system automatical
</div>
<details>
<summary><b>📝 More Examples</b></summary>
```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
```
</details>
### Custom CLI Registration
Register **any API as a custom CLI** via Dashboard interface:
```bash
ccw view # Open Dashboard → Status → API Settings → Add Custom CLI
```
<div align="center">
| Field | Example |
|-------|---------|
| **Name** | `deepseek` |
| **Endpoint** | `https://api.deepseek.com/v1/chat` |
| **API Key** | `your-api-key` |
</div>
> ⚙️ Register once, invoke semantically forever - no code changes needed.
---
## 🔍 ACE Tool Configuration
@@ -245,42 +209,24 @@ ACE (Augment Context Engine) provides powerful semantic code search.
</table>
</div>
<details>
<summary><b>📦 Installation</b></summary>
```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**.
</details>
---
## 💻 CCW CLI Commands
### 🌟 Recommended Commands (Main Features)
### 🌟 Recommended Commands
<div align="center">
<table>
<tr><th>Command</th><th>Description</th><th>When to Use</th></tr>
<tr>
<td><b>/ccw</b></td>
<td>Auto workflow orchestrator - analyzes intent, selects workflow level, executes command chain in main process</td>
<td>✅ General tasks, auto workflow selection, quick development</td>
<td>Auto workflow orchestrator - analyzes intent, selects workflow, executes</td>
<td>✅ General tasks, auto workflow selection</td>
</tr>
<tr>
<td><b>/ccw-coordinator</b></td>
<td>Smart orchestrator - intelligently recommends command chains, allows manual adjustment, executes via external CLI with state persistence</td>
<td>🔧 Complex multi-step workflows, customizable chains, resumable sessions</td>
<td>Smart orchestrator - recommends command chains, allows manual adjustment</td>
<td>🔧 Complex multi-step workflows</td>
</tr>
</table>
</div>
@@ -288,25 +234,33 @@ Open Dashboard via `ccw view`, manage indexes and execute searches in **CodexLen
**Quick Examples**:
```bash
# /ccw - Auto workflow selection (Main Process)
/ccw "Add user authentication" # Auto-selects workflow based on intent
/ccw "Fix memory leak in WebSocket" # Detects bugfix workflow
/ccw "Implement with TDD" # Routes to TDD workflow
# /ccw - Auto workflow selection
/ccw "Add user authentication"
/ccw "Fix memory leak in WebSocket"
/ccw "Implement with TDD"
# /ccw-coordinator - Manual chain orchestration (External CLI)
/ccw-coordinator "Implement OAuth2 system" # Analyzes → Recommends chain → User confirms → Executes
# /ccw-coordinator - Manual chain orchestration
/ccw-coordinator "Implement OAuth2 system"
```
**Key Differences**:
### Session Management Commands
| Aspect | /ccw | /ccw-coordinator |
|--------|------|------------------|
| **Execution** | Main process (SlashCommand) | External CLI (background tasks) |
| **Selection** | Auto intent-based | Smart recommendation + optional adjustment |
| **State** | TodoWrite tracking | Persistent state.json |
| **Use Case** | General tasks, quick dev | Complex chains, resumable |
```bash
/workflow:session:start # Start new workflow session
/workflow:session:resume # Resume paused session
/workflow:session:list # List all sessions
/workflow:session:sync # Sync session work
/workflow:session:complete # Complete session
```
---
### Issue Workflow Commands
```bash
/issue/new # Create new issue
/issue/plan # Plan issue resolution
/issue/queue # Form execution queue
/issue/execute # Execute issue queue
```
### Other CLI Commands
@@ -317,45 +271,17 @@ ccw cli -p "..." # Execute CLI tools (Gemini/Qwen/Codex)
ccw upgrade -a # Upgrade all installations
```
### Dashboard Features
<div align="center">
<table>
<tr><th>Feature</th><th>Description</th></tr>
<tr><td><b>Session Overview</b></td><td>Track workflow sessions and progress</td></tr>
<tr><td><b>CodexLens</b></td><td>FTS + Semantic + Hybrid code search</td></tr>
<tr><td><b>Graph Explorer</b></td><td>Interactive code relationship visualization</td></tr>
<tr><td><b>CLI Manager</b></td><td>Execution history with session resume</td></tr>
</table>
</div>
---
## 📖 Documentation
<div align="center">
| 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 |
</div>
---
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ Main Workflow (4 Levels) │
│ ⚡ Level 1: lite-lite-lite (instant execution) │
│ 📝 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 │
│ Workflow Skills │
│ 📝 workflow:lite-plan / workflow:multi-cli-plan (lightweight) │
│ 📊 workflow:plan / workflow:tdd-plan (session-based) │
│ 🧪 workflow:test-fix-gen / workflow:test-cycle-execute │
│ 🧠 brainstorm (multi-role analysis) │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
@@ -380,13 +306,6 @@ ccw upgrade -a # Upgrade all installations
└─────────────────────────────────────────────────────────────────┘
```
**Core Principles:**
- ⚡ **Dependency Analysis** solves parallelism - no worktree needed for main workflow
- 🤖 **Team Architecture v2** provides unified role-based agent execution with inner loop
- 🔧 **Queue Scheduler** handles background task execution with unified settings
- 🖥️ **Terminal Dashboard** provides real-time monitoring and control
- 🎯 Select workflow level based on complexity - avoid over-engineering
---
## 📦 Project Structure
@@ -396,27 +315,26 @@ Claude-Code-Workflow/
├── .claude/
│ ├── agents/ # 22 specialized agents (team-worker, cli-discuss, etc.)
│ ├── commands/ # Slash commands (5 categories)
│ │ ├── root/ # Root commands (/ccw, /ccw-coordinator)
│ │ ├── ccw.md # Main orchestrator
│ │ ├── ccw-coordinator.md
│ │ ├── cli/ # CLI commands (cli-init, codex-review)
│ │ ├── issue/ # Issue management (plan, execute, queue)
│ │ ├── memory/ # Memory commands (prepare, style-skill-memory)
│ │ └── workflow/ # Workflow commands (brainstorm, plan, session)
│ │ └── workflow/ # Workflow commands (session, ui-design, etc.)
│ └── skills/ # 37 modular skills
│ ├── review-code/ # Code review with rule-based analysis
│ ├── skill-tuning/ # Skill diagnosis and optimization
│ ├── skill-generator/ # Skill scaffolding and generation
│ ├── spec-generator/ # Product specification generation
│ ├── memory-*/ # Memory management skills
│ ├── workflow-*/ # Workflow orchestration skills
│ ├── team-*/ # Team coordination skills
│ ├── workflow-lite-plan/
│ ├── workflow-plan/
│ ├── workflow-tdd/
│ ├── workflow-test-fix/
│ ├── brainstorm/
│ ├── team-*/ # Team coordination skills
│ └── ...
├── ccw/
│ ├── src/ # TypeScript source code
│ │ ├── commands/ # CLI command implementations
│ │ ├── core/ # Core services (a2ui, auth, hooks, routes)
│ │ ├── mcp-server/ # MCP server implementation
│ │ ├── tools/ # Tool implementations
│ │ └── utils/ # Utility functions
│ │ └── tools/ # Tool implementations
│ └── frontend/ # React frontend (Terminal Dashboard, Orchestrator)
├── codex-lens/ # Local semantic code search engine
└── docs/ # Documentation
@@ -445,13 +363,6 @@ Beat Cycle (single beat)
callback <-----------------------------------------+
(next beat) SendMessage + TaskUpdate(completed)
======================================================================
Fast-Advance (skips coordinator for simple linear successors)
======================================================================
[Worker A] Phase 5 complete
+- 1 ready task? simple successor? --> spawn team-worker B directly
+- complex case? --> SendMessage to coordinator
======================================================================
```
**Key Benefits:**
@@ -485,10 +396,6 @@ Visual workflow template editor with drag-drop.
- 🔧 Property panel for node configuration
- ⚡ Slash command integration
### Analysis Viewer
Grid layout for analysis sessions with filtering and fullscreen mode.
---
## 🤝 Contributing
@@ -496,7 +403,6 @@ Grid layout for analysis sessions with filtering and fullscreen mode.
<div align="center">
<a href="https://github.com/catlog22/Claude-Code-Workflow"><img src="https://img.shields.io/badge/GitHub-Repository-181717?style=flat-square" alt="GitHub"/></a>
<a href="https://github.com/catlog22/Claude-Code-Workflow/issues"><img src="https://img.shields.io/badge/Issues-Report_Bug-EF4444?style=flat-square" alt="Issues"/></a>
<a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/Contributing-Guide-10B981?style=flat-square" alt="Contributing"/></a>
</div>
---