# ๐ Claude Code Workflow (CCW)
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
[](LICENSE)
[]()
**Languages:** [English](README.md) | [ไธญๆ](README_CN.md)
---
## ๐ Overview
**Claude Code Workflow (CCW)** is a next-generation multi-agent automation framework for software development that orchestrates complex development tasks through intelligent workflow management and autonomous execution.
> **๐ฏ Latest Release v2.0**: Major architectural evolution with enhanced workflow lifecycle, Python-powered backend (`pycli`), comprehensive test workflow generation, plan verification system, and brainstorm artifacts integration. See [CHANGELOG.md](CHANGELOG.md) for details.
### ๐ Key Innovations
- **๐ Enhanced Workflow Lifecycle**: Complete development cycle: Brainstorm โ Plan โ Verify โ Execute โ Test โ Review
- **๐ Python-Powered Backend**: Advanced `pycli` integration with hierarchical vector database support for semantic context discovery
- **๐งช Automated Test Generation**: Comprehensive test workflow generation (`/workflow:test-gen`) with full coverage planning
- **โ
Plan Verification System**: Pre-execution validation using dual Gemini/Codex analysis (`/workflow:plan-verify`)
- **๐ฏ JSON-First Architecture**: Single source of truth with atomic session management
- **๐ก Brainstorm Artifacts**: Multi-perspective planning with synthesis and structured document generation
---
## ๐๏ธ System Architecture
### **๐ง Core Architectural Principles**
```mermaid
graph TB
subgraph "๐ฅ๏ธ CLI Interface Layer"
CLI[CLI Commands]
GEM[Gemini CLI]
COD[Codex CLI]
WRAPPER[Intelligent Gemini Wrapper]
end
subgraph "๐ Session Management"
MARKER[".active-session markers"]
SESSION["workflow-session.json"]
WDIR[".workflow/ directories"]
end
subgraph "๐ JSON-First Task System"
TASK_JSON[".task/impl-*.json"]
HIERARCHY["Task Hierarchy (max 2 levels)"]
STATUS["Task Status Management"]
DECOMP["Task Decomposition Engine"]
end
subgraph "๐ค Multi-Agent Orchestration"
PLAN_AGENT[Conceptual Planning Agent]
ACTION_AGENT[Action Planning Agent]
CODE_AGENT[Code Developer Agent]
REVIEW_AGENT[Code Review Agent]
MEMORY_AGENT[Memory Gemini Bridge]
end
CLI --> WRAPPER
WRAPPER --> GEM
CLI --> COD
GEM --> PLAN_AGENT
COD --> CODE_AGENT
PLAN_AGENT --> TASK_JSON
ACTION_AGENT --> TASK_JSON
CODE_AGENT --> TASK_JSON
TASK_JSON --> DECOMP
DECOMP --> HIERARCHY
HIERARCHY --> STATUS
SESSION --> MARKER
MARKER --> WDIR
```
### ๐๏ธ **Three-Pillar Foundation**
| ๐๏ธ **JSON-First Data Model** | โก **Atomic Session Management** | ๐งฉ **Adaptive Complexity** |
|---|---|---|
| Single source of truth | Marker-based session state | Auto-adjusts to project size |
| Sub-millisecond queries | Zero-overhead switching | Simple โ Medium โ Complex |
| Generated Markdown views | Conflict-free concurrency | Task limit enforcement |
| Data consistency guaranteed | Instant context switching | Intelligent decomposition |
---
## โจ Major Enhancements v2.0
### ๐ **Enhanced Workflow Lifecycle**
Complete development lifecycle with quality gates at each phase:
1. **๐ก Brainstorm Phase** - Multi-perspective conceptual planning with role-based analysis
2. **๐ Plan Phase** - Structured implementation planning with task decomposition
3. **โ
Verify Phase** - Pre-execution validation using Gemini (strategic) + Codex (technical)
4. **โก Execute Phase** - Autonomous implementation with multi-agent orchestration
5. **๐งช Test Phase** - Automated test workflow generation with comprehensive coverage
6. **๐ Review Phase** - Quality assurance and completion validation
### ๐ **Python-Powered Backend (`pycli`)**
Advanced semantic context discovery system:
```bash
# Hierarchical vector database support
pycli --semantic-search "authentication patterns"
# Auto-detects parent directory vector DB
pycli --context-discovery --inherit-parent
# Intelligent file relevance scoring
pycli --analyze-relevance "jwt token validation"
```
### ๐งช **Automated Test Generation**
Comprehensive test workflow creation:
- **Implementation Analysis**: Scans completed IMPL-* tasks for test requirements
- **Multi-layered Testing**: Unit, Integration, E2E, Performance, Security tests
- **Agent Assignment**: Specialized test agents for different test types
- **Dependency Mapping**: Test execution follows implementation dependency chains
### โ
**Plan Verification System**
Dual-engine validation before execution:
- **Gemini Strategic Analysis**: High-level feasibility and architectural soundness
- **Codex Technical Analysis**: Implementation details and technical feasibility
- **Cross-Validation**: Identifies conflicts between strategic vision and technical constraints
- **Improvement Suggestions**: Actionable recommendations before implementation begins
---
## ๐ Complexity Management System
CCW automatically adapts workflow structure based on project complexity:
| **Complexity** | **Task Count** | **Structure** | **Features** |
|---|---|---|---|
| ๐ข **Simple** | <5 tasks | Single-level | Minimal overhead, direct execution |
| ๐ก **Medium** | 5-10 tasks | Two-level hierarchy | Progress tracking, automated docs |
| ๐ด **Complex** | >10 tasks | Force re-scoping | Multi-iteration planning required |
---
## ๐ ๏ธ Complete Command Reference
### ๐ฎ **Core System Commands**
| Command | Function | Example |
|---------|----------|---------|
| `๐ฏ /enhance-prompt` | Technical context enhancement | `/enhance-prompt "add auth system"` |
| `๐ /context` | Unified context management | `/context --analyze --format=tree` |
| `๐ /update-memory-full` | Complete documentation update | `/update-memory-full` |
| `๐ /update-memory-related` | Smart context-aware updates | `/update-memory-related` |
### ๐ **Gemini CLI Commands** (Analysis & Investigation)
| Command | Purpose | Usage |
|---------|---------|-------|
| `๐ /gemini:analyze` | Deep codebase analysis | `/gemini:analyze "authentication patterns"` |
| `๐ฌ /gemini:chat` | Direct Gemini interaction | `/gemini:chat "explain this architecture"` |
| `โก /gemini:execute` | Intelligent execution with YOLO permissions | `/gemini:execute "implement task-001"` |
| `๐ฏ /gemini:mode:auto` | Auto template selection | `/gemini:mode:auto "analyze security vulnerabilities"` |
| `๐ /gemini:mode:bug-index` | Bug analysis and fix suggestions | `/gemini:mode:bug-index "payment processing fails"` |
| `๐ /gemini:mode:plan` | Project planning and architecture | `/gemini:mode:plan "microservices architecture"` |
| `๐ฏ /gemini:mode:plan-precise` | Precise path planning analysis | `/gemini:mode:plan-precise "complex refactoring"` |
### ๐ฎ **Qwen CLI Commands** (Architecture & Code Generation)
| Command | Purpose | Usage |
|---------|---------|-------|
| `๐ /qwen:analyze` | Architecture analysis and code quality | `/qwen:analyze "system architecture patterns"` |
| `๐ฌ /qwen:chat` | Direct Qwen interaction | `/qwen:chat "design authentication system"` |
| `โก /qwen:execute` | Intelligent implementation with YOLO permissions | `/qwen:execute "implement user authentication"` |
| `๐ /qwen:mode:auto` | Auto template selection and execution | `/qwen:mode:auto "build microservices API"` |
| `๐ /qwen:mode:bug-index` | Bug analysis and fix suggestions | `/qwen:mode:bug-index "memory leak in service"` |
| `๐ /qwen:mode:plan` | Architecture planning and analysis | `/qwen:mode:plan "design scalable database"` |
| `๐ฏ /qwen:mode:plan-precise` | Precise architectural planning | `/qwen:mode:plan-precise "complex system migration"` |
### ๐ค **Codex CLI Commands** (Development & Implementation)
| Command | Purpose | Usage |
|---------|---------|-------|
| `๐ /codex:analyze` | Development analysis | `/codex:analyze "optimization opportunities"` |
| `๐ฌ /codex:chat` | Direct Codex interaction | `/codex:chat "implement JWT auth"` |
| `โก /codex:execute` | Autonomous implementation with YOLO permissions | `/codex:execute "refactor user service"` |
| `๐ /codex:mode:auto` | **PRIMARY**: Full autonomous development | `/codex:mode:auto "build payment system"` |
| `๐ /codex:mode:bug-index` | Autonomous bug fixing and implementation | `/codex:mode:bug-index "fix race condition"` |
| `๐ /codex:mode:plan` | Development planning and implementation | `/codex:mode:plan "implement API endpoints"` |
### ๐ฏ **Workflow Management**
#### ๐ Session Management
| Command | Function | Usage |
|---------|----------|-------|
| `๐ /workflow:session:start` | Create new session | `/workflow:session:start "OAuth2 System"` |
| `โธ๏ธ /workflow:session:pause` | Pause current session | `/workflow:session:pause` |
| `โถ๏ธ /workflow:session:resume` | Resume session | `/workflow:session:resume "OAuth2 System"` |
| `๐ /workflow:session:list` | List all sessions | `/workflow:session:list --active` |
| `๐ /workflow:session:switch` | Switch sessions | `/workflow:session:switch "Payment Fix"` |
#### ๐ฏ Workflow Operations
| Command | Function | Usage |
|---------|----------|-------|
| `๐ญ /workflow:brainstorm:*` | Multi-perspective planning with role experts | `/workflow:brainstorm:system-architect "microservices"` |
| `๐ค /workflow:brainstorm:synthesis` | Synthesize all brainstorming perspectives | `/workflow:brainstorm:synthesis` |
| `๐จ /workflow:brainstorm:artifacts` | Generate structured planning documents | `/workflow:brainstorm:artifacts "topic description"` |
| `๐ /workflow:plan` | Convert to executable implementation plans | `/workflow:plan "description" \| file.md \| ISS-001` |
| `๐ /workflow:plan-deep` | Deep technical planning with Gemini analysis | `/workflow:plan-deep "requirements description"` |
| `โ
/workflow:plan-verify` | Pre-execution validation using dual analysis | `/workflow:plan-verify` |
| `โก /workflow:execute` | Coordinate agents for implementation | `/workflow:execute` |
| `๐ /workflow:resume` | Intelligent workflow resumption | `/workflow:resume [--from TASK-ID] [--retry]` |
| `๐ /workflow:status` | Generate on-demand views from task data | `/workflow:status [task-id] [format] [validation]` |
| `๐งช /workflow:test-gen` | Generate comprehensive test workflows | `/workflow:test-gen WFS-session-id` |
| `๐ /workflow:review` | Execute review phase for quality validation | `/workflow:review` |
| `๐ /workflow:docs` | Generate hierarchical documentation | `/workflow:docs "architecture" \| "api" \| "all"` |
#### ๐ท๏ธ Task Management
| Command | Function | Usage |
|---------|----------|-------|
| `โ /task:create` | Create implementation task with context | `/task:create "User Authentication System"` |
| `๐ /task:breakdown` | Intelligent task decomposition | `/task:breakdown task-id` |
| `โก /task:execute` | Execute tasks with appropriate agents | `/task:execute task-id` |
| `๐ /task:replan` | Replan tasks with detailed input | `/task:replan task-id ["text" \| file.md \| ISS-001]` |
#### ๐ง Brainstorming Role Commands
| Role | Command | Purpose |
|------|---------|---------|
| ๐๏ธ **System Architect** | `/workflow:brainstorm:system-architect` | Technical architecture analysis |
| ๐ **Security Expert** | `/workflow:brainstorm:security-expert` | Security and threat analysis |
| ๐ **Product Manager** | `/workflow:brainstorm:product-manager` | User needs and business value |
| ๐จ **UI Designer** | `/workflow:brainstorm:ui-designer` | User experience and interface |
| ๐ **Business Analyst** | `/workflow:brainstorm:business-analyst` | Process optimization analysis |
| ๐ฌ **Innovation Lead** | `/workflow:brainstorm:innovation-lead` | Emerging technology opportunities |
| ๐ **Feature Planner** | `/workflow:brainstorm:feature-planner` | Feature development planning |
| ๐๏ธ **Data Architect** | `/workflow:brainstorm:data-architect` | Data modeling and analytics |
| ๐ฅ **User Researcher** | `/workflow:brainstorm:user-researcher` | User behavior analysis |
| ๐ **Auto Selection** | `/workflow:brainstorm:auto` | Dynamic role selection |
---
## ๐ฏ Complete Development Workflows
### ๐ **Enhanced Workflow Lifecycle**
```mermaid
graph TD
START[๐ฏ New Feature Request] --> SESSION["/workflow:session:start 'OAuth2 System'"]
SESSION --> BRAINSTORM["/workflow:brainstorm:system-architect topic"]
BRAINSTORM --> SYNTHESIS["/workflow:brainstorm:synthesis"]
SYNTHESIS --> PLAN["/workflow:plan description"]
PLAN --> VERIFY["/workflow:plan-verify"]
VERIFY --> EXECUTE["/workflow:execute"]
EXECUTE --> TEST["/workflow:test-gen WFS-session-id"]
TEST --> REVIEW["/workflow:review"]
REVIEW --> DOCS["/workflow:docs all"]
DOCS --> COMPLETE[โ
Complete]
```
### โก **Workflow Session Management**
```mermaid
graph LR
START[๐ Session Start] --> MARKER[๐ท๏ธ .active-session marker]
MARKER --> JSON[๐ workflow-session.json]
JSON --> TASKS[๐ฏ .task/IMPL-*.json]
TASKS --> PAUSE[โธ๏ธ Pause: Remove marker]
PAUSE --> RESUME[โถ๏ธ Resume: Restore marker]
RESUME --> SWITCH[๐ Switch: Change active session]
```
### ๐ฅ **Quick Development Examples**
#### **๐ Complete Feature Development Workflow**
```bash
# 1. Initialize focused session
/workflow:session:start "User Dashboard Feature"
# 2. Multi-perspective brainstorming
/workflow:brainstorm:system-architect "dashboard analytics system"
/workflow:brainstorm:ui-designer "dashboard user experience"
/workflow:brainstorm:data-architect "analytics data flow"
# 3. Synthesize all perspectives
/workflow:brainstorm:synthesis
# 4. Create executable implementation plan
/workflow:plan "user dashboard with analytics and real-time data"
# 5. Verify plan before execution
/workflow:plan-verify
# 6. Execute implementation with agent coordination
/workflow:execute
# 7. Generate comprehensive test suite
/workflow:test-gen WFS-user-dashboard-feature
# 8. Quality assurance and review
/workflow:review
# 9. Generate documentation
/workflow:docs "all"
```
#### **โก Rapid Bug Resolution**
```bash
# Quick bug fix workflow
/workflow:session:start "Payment Processing Fix"
/gemini:mode:bug-index "Payment validation fails on concurrent requests"
/codex:mode:bug-index "Fix race condition in payment validation"
/workflow:review
```
#### **๐ Architecture Analysis & Refactoring**
```bash
# Deep architecture workflow
/workflow:session:start "API Refactoring Initiative"
/gemini:analyze "current API architecture patterns and technical debt"
/workflow:plan-deep "microservices transition strategy"
/workflow:plan-verify
/qwen:mode:auto "Refactor monolith to microservices architecture"
/workflow:test-gen WFS-api-refactoring-initiative
/workflow:review
```
---
## ๐๏ธ Project Structure
```
๐ .claude/
โโโ ๐ค agents/ # AI agent definitions
โโโ ๐ฏ commands/ # CLI command implementations
โ โโโ ๐ gemini/ # Gemini CLI commands
โ โโโ ๐ค codex/ # Codex CLI commands
โ โโโ ๐ฏ workflow/ # Workflow management
โโโ ๐จ output-styles/ # Output formatting templates
โโโ ๐ญ planning-templates/ # Role-specific planning
โโโ ๐ฌ prompt-templates/ # AI interaction templates
โโโ ๐ง scripts/ # Automation utilities
โ โโโ ๐ gemini-wrapper # Intelligent Gemini wrapper
โ โโโ ๐ pycli # NEW: Python CLI backend
โ โโโ ๐ ๏ธ install_pycli.sh # NEW: Python tools installer
โ โโโ ๐ read-task-paths.sh # Task path conversion
โ โโโ ๐๏ธ get_modules_by_depth.sh # Project analysis
โโโ ๐ ๏ธ workflows/ # Core workflow documentation
โ โโโ ๐๏ธ workflow-architecture.md # System architecture
โ โโโ ๐ intelligent-tools-strategy.md # Tool selection guide
โ โโโ ๐ python-tools-strategy.md # NEW: Python backend strategy
โ โโโ ๐ง tools-implementation-guide.md # Implementation details
โโโ โ๏ธ settings.local.json # Local configuration
๐ .workflow/ # Session workspace (auto-generated)
โโโ ๐ท๏ธ .active-[session] # Active session markers
โโโ ๐ WFS-[topic-slug]/ # Individual sessions
โโโ โ๏ธ workflow-session.json # Session metadata
โโโ ๐ .task/impl-*.json # Task definitions
โโโ ๐ IMPL_PLAN.md # Planning documents
โโโ โ
TODO_LIST.md # Progress tracking
โโโ ๐ .summaries/ # Completion summaries
โโโ ๐ง .process/ # NEW: Planning artifacts
โ โโโ ๐ ANALYSIS_RESULTS.md # Analysis results
โโโ ๐งช WFS-test-[session]/ # NEW: Generated test workflows
```
---
## โก Performance & Technical Specs
### ๐ **Performance Metrics**
| Metric | Performance | Details |
|--------|-------------|---------|
| ๐ **Session Switching** | <10ms | Atomic marker file operations |
| ๐ **JSON Queries** | <1ms | Direct JSON access, no parsing overhead |
| ๐ **Doc Updates** | <30s | Medium projects, intelligent targeting |
| ๐ **Context Loading** | <5s | Complex codebases with caching |
| โก **Task Execution** | 10min timeout | Complex operations with error handling |
### ๐ ๏ธ **System Requirements**
- **๐ฅ๏ธ OS**: Windows 10+, Ubuntu 18.04+, macOS 10.15+
- **๐ฆ Dependencies**: Git, Node.js (Gemini), Python 3.8+ (Codex)
- **๐พ Storage**: ~50MB core + variable project data
- **๐ง Memory**: 512MB minimum, 2GB recommended
### ๐ **Integration Requirements**
- **๐ Gemini CLI**: Required for analysis and strategic planning workflows
- **๐ค Codex CLI**: Required for autonomous development and bug fixing
- **๐ฎ Qwen CLI**: Required for architecture analysis and code generation
- **๐ Git Repository**: Required for change tracking and version control
- **๐ฏ Claude Code IDE**: Recommended for optimal experience
- **๐ Python 3.8+**: Required for advanced pycli backend features
---
## โ๏ธ Installation & Configuration
### ๐ **Quick Installation**
```powershell
Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
```
### โ
**Verify Installation**
```bash
/workflow:session list
```
### โ๏ธ **Essential Configuration**
#### **Gemini CLI Setup**
```json
// ~/.gemini/settings.json
{
"contextFileName": "CLAUDE.md"
}
```
#### **Optimized .geminiignore**
```bash
# Performance optimization
/dist/
/build/
/node_modules/
/.next/
# Temporary files
*.tmp
*.log
/temp/
# Include important docs
!README.md
!**/CLAUDE.md
```
---
## ๐ค Contributing
### ๐ ๏ธ **Development Setup**
1. ๐ด Fork the repository
2. ๐ฟ Create feature branch: `git checkout -b feature/enhancement-name`
3. ๐ฆ Install dependencies
4. โ
Test with sample projects
5. ๐ค Submit detailed pull request
### ๐ **Code Standards**
- โ
Follow existing command patterns
- ๐ Maintain backward compatibility
- ๐งช Add tests for new functionality
- ๐ Update documentation
- ๐ท๏ธ Use semantic versioning
---
## ๐ Support & Resources
| Resource | Link | Description |
|----------|------|-------------|
| ๐ **Documentation** | [Project Wiki](https://github.com/catlog22/Claude-Code-Workflow/wiki) | Comprehensive guides |
| ๐ **Issues** | [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues) | Bug reports & features |
| ๐ฌ **Discussions** | [Community Forum](https://github.com/catlog22/Claude-Code-Workflow/discussions) | Community support |
| ๐ **Changelog** | [Release History](CHANGELOG.md) | Version history |
---
## ๐ License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
---
**๐ Claude Code Workflow (CCW)**
*Professional software development workflow automation through intelligent multi-agent coordination and autonomous execution capabilities.*
[](https://github.com/catlog22/Claude-Code-Workflow)