# ๐ 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 v1.3**: Enhanced task decomposition standards, advanced search strategies with bash command combinations, free exploration phases for agents, and comprehensive workflow system improvements. See [CHANGELOG.md](CHANGELOG.md) for details.
### ๐ Key Innovations
- **๐ง Intelligent Task Decomposition**: New core standards prevent over-fragmentation with functional completeness principles
- **๐ Advanced Search Strategies**: Powerful command combinations using ripgrep, grep, find, awk, sed for comprehensive analysis
- **โก Free Exploration Phase**: Agents can gather supplementary context after structured analysis
- **๐ฏ JSON-First Architecture**: Single source of truth with atomic session management
- **๐ค Dual CLI Integration**: Gemini for analysis, Codex for autonomous development
---
## ๐๏ธ 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 v1.3
### ๐ฏ **Core Task Decomposition Standards**
Revolutionary task decomposition system with four core principles:
1. **๐ฏ Functional Completeness Principle** - Complete, runnable functional units
2. **๐ Minimum Size Threshold** - 3+ files or 200+ lines minimum
3. **๐ Dependency Cohesion Principle** - Tightly coupled components together
4. **๐ Hierarchy Control Rule** - Flat โค5, hierarchical 6-10, re-scope >10
### ๐ **Advanced Search Strategies**
Powerful command combinations for comprehensive codebase analysis:
```bash
# Pattern discovery with context
rg -A 3 -B 3 'authenticate|login|jwt' --type ts --type js | head -50
# Multi-tool analysis pipeline
find . -name '*.ts' | xargs rg -l 'auth' | head -15
# Interface extraction with awk
rg '^\\s*interface\\s+\\w+' --type ts -A 5 | awk '/interface/{p=1} p&&/^}/{p=0;print}'
```
### ๐ **Free Exploration Phase**
Agents can enter supplementary context gathering using bash commands (grep, find, rg, awk, sed) after completing structured pre-analysis steps.
### ๐ง **Intelligent Gemini Wrapper**
Smart automation with token management and approval modes:
- **Analysis Detection**: Keywords trigger `--approval-mode default`
- **Development Detection**: Action words trigger `--approval-mode yolo`
- **Auto Token Management**: Handles `--all-files` based on project size
- **Error Logging**: Comprehensive error tracking and recovery
---
## ๐ 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 | `/gemini:execute task-001` |
| `๐ฏ /gemini:mode:auto` | Auto template selection | `/gemini:mode:auto "analyze security"` |
| `๐ /gemini:mode:bug-index` | Bug analysis workflow | `/gemini:mode:bug-index "payment fails"` |
### ๐ค **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` | Controlled development | `/codex:execute "refactor user service"` |
| `๐ /codex:mode:auto` | **PRIMARY**: Full autonomous | `/codex:mode:auto "build payment system"` |
| `๐ /codex:mode:bug-index` | Autonomous bug fixing | `/codex:mode:bug-index "fix race condition"` |
### ๐ฏ **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-agent planning | `/workflow:brainstorm "microservices architecture"` |
| `๐ /workflow:plan` | Convert to executable plans | `/workflow:plan --from-brainstorming` |
| `๐ /workflow:plan-deep` | Deep architectural planning | `/workflow:plan-deep "API redesign" --complexity=high` |
| `โก /workflow:execute` | Implementation phase | `/workflow:execute --type=complex` |
| `โ
/workflow:review` | Quality assurance | `/workflow:review --auto-fix` |
#### ๐ท๏ธ Task Management
| Command | Function | Usage |
|---------|----------|-------|
| `โ /task:create` | Create implementation task | `/task:create "User Authentication"` |
| `๐ /task:breakdown` | Decompose into subtasks | `/task:breakdown IMPL-1 --depth=2` |
| `โก /task:execute` | Execute specific task | `/task:execute IMPL-1.1 --mode=auto` |
| `๐ /task:replan` | Adapt to changes | `/task:replan IMPL-1 --strategy=adjust` |
---
## ๐ฏ Complete Development Workflows
### ๐ **Complex Feature Development**
```mermaid
graph TD
START[๐ฏ New Feature Request] --> SESSION["/workflow:session:start 'OAuth2 System'"]
SESSION --> BRAINSTORM["/workflow:brainstorm --perspectives=system-architect,security-expert"]
BRAINSTORM --> PLAN["/workflow:plan --from-brainstorming"]
PLAN --> EXECUTE["/workflow:execute --type=complex"]
EXECUTE --> REVIEW["/workflow:review --auto-fix"]
REVIEW --> DOCS["/update-memory-related"]
DOCS --> COMPLETE[โ
Complete]
```
### ๐ฅ **Quick Development Examples**
#### **๐ Full Stack Feature Implementation**
```bash
# 1. Initialize focused session
/workflow:session:start "User Dashboard Feature"
# 2. Multi-perspective analysis
/workflow:brainstorm "dashboard analytics system" \
--perspectives=system-architect,ui-designer,data-architect
# 3. Generate executable plan with task decomposition
/workflow:plan --from-brainstorming
# 4. Autonomous implementation
/codex:mode:auto "Implement user dashboard with analytics, charts, and real-time data"
# 5. Quality assurance and deployment
/workflow:review --auto-fix
/update-memory-related
```
#### **โก 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:auto "Fix race condition in payment validation with proper locking"
/workflow:review --auto-fix
```
#### **๐ Architecture Analysis & Refactoring**
```bash
# Deep architecture work
/workflow:session:start "API Refactoring Initiative"
/gemini:analyze "current API architecture patterns and technical debt"
/workflow:plan-deep "microservices transition" --complexity=high --depth=3
/codex:mode:auto "Refactor monolith to microservices following the analysis"
```
---
## ๐๏ธ 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
โ โโโ ๐ 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
โ โโโ ๐ง 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
```
---
## โก 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 workflows
- **๐ค Codex CLI**: Required for autonomous development
- **๐ Git Repository**: Required for change tracking
- **๐ฏ Claude Code IDE**: Recommended for optimal experience
---
## โ๏ธ 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)