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 v3.0.0: Major update with unified CLI command structure. Consolidates Gemini, Qwen, and Codex commands into a single
/cli:*command set with--toolflag for tool selection. Includes comprehensive workflow guide and command verification. See CHANGELOG.md for details.
โ ๏ธ Breaking Changes: Previous tool-specific commands (/gemini:*,/qwen:*,/codex:*) are deprecated. Use new unified/cli:*commands instead. See migration guide below.
- ๐ Enhanced Workflow Lifecycle: Complete development cycle: Brainstorm โ Plan โ Execute โ Test โ Review
- ๐งช Automated Test Generation: Comprehensive test workflow generation (
/workflow:test-gen) with full coverage planning - ๐ฏ JSON-First Architecture: Single source of truth with atomic session management
- ๐ก Brainstorm Artifacts: Multi-perspective planning with synthesis and structured document generation
- ๐ค Intelligent Agent Orchestration: Automated agent assignment and task coordination
- ๐ง MCP Tools Integration (Experimental): Enhanced codebase analysis through Model Context Protocol tools
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
CCW operates through four distinct architectural layers with defined responsibilities and data contracts:
| Layer | Components | Data Flow | Integration Points |
|---|---|---|---|
| ๐ฅ๏ธ Interface Layer | CLI Commands, Gemini/Codex/Qwen Wrappers | User input โ Commands โ Agents | External CLI tools, approval modes |
| ๐ Session Layer | .active-[session] markers, workflow-session.json |
Session state โ Task discovery | Atomic session switching |
| ๐ Task/Data Layer | .task/impl-*.json, hierarchy management |
Task definitions โ Agent execution | JSON-first model, generated views |
| ๐ค Orchestration Layer | Multi-agent coordination, dependency resolution | Agent outputs โ Task updates | Intelligent execution flow |
Complete development lifecycle with quality gates at each phase:
- ๐ก Brainstorm Phase - Multi-perspective conceptual planning with role-based analysis
- ๐ Plan Phase - Structured implementation planning with task decomposition
- โก Execute Phase - Autonomous implementation with multi-agent orchestration
- ๐งช Test Phase - Automated test workflow generation with comprehensive coverage
- ๐ Review Phase - Quality assurance and completion validation
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
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 |
| Command | Function | Example |
|---|---|---|
๐ฏ /enhance-prompt |
Technical context enhancement | /enhance-prompt "add auth system" |
๐ /update-memory-full |
Complete documentation update | /update-memory-full |
๐ /update-memory-related |
Smart context-aware updates | /update-memory-related |
| Command | Purpose | Usage |
|---|---|---|
/cli:analyze |
Deep codebase analysis | /cli:analyze "[target]" [--tool <tool>] |
/cli:chat |
Direct interaction with a tool | /cli:chat "[inquiry]" [--tool <tool>] |
/cli:execute |
Intelligent execution with YOLO permissions | `/cli:execute "[description |
/cli:cli-init |
Initialize CLI tool configurations | /cli:cli-init [--tool <tool>] |
/cli:mode:bug-index |
Bug analysis and fix suggestions | /cli:mode:bug-index "[description]" [--tool <tool>] |
/cli:mode:code-analysis |
Deep code analysis and debugging | /cli:mode:code-analysis "[target]" [--tool <tool>] |
/cli:mode:plan |
Project planning and architecture | /cli:mode:plan "[topic]" [--tool <tool>] |
Supported tools for --tool flag: gemini (default), qwen, codex.
Version 3.0.0 introduces a unified CLI command structure, consolidating the previous tool-specific commands (/gemini:*, /qwen:*, /codex:*) into a single, more powerful /cli:* command set.
Key Change: The specific tool (Gemini, Qwen, Codex) is now selected using the --tool <name> flag. If no tool is specified, it defaults to gemini.
Command Mapping:
| Old Command (v2) | New Command (v3.0.0) | Notes |
|---|---|---|
/gemini:analyze "..." |
/cli:analyze "..." |
Defaults to Gemini. |
/qwen:analyze "..." |
/cli:analyze "..." --tool qwen |
Specify Qwen with --tool. |
/codex:chat "..." |
/cli:chat "..." --tool codex |
Specify Codex with --tool. |
/gemini:execute "..." |
/cli:execute "..." |
Defaults to Gemini. |
/gemini:mode:bug-index "..." |
/cli:mode:bug-index "..." |
Defaults to Gemini. |
/qwen:mode:plan "..." |
/cli:mode:plan "..." --tool qwen |
Specify Qwen with --tool. |
The commands /gemini:mode:auto and /gemini:mode:plan-precise have been removed and their functionality integrated into the enhanced /cli:execute and /cli:mode:plan commands respectively.
| 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:complete |
Complete current session | /workflow:session:complete |
๐ /workflow:session:list |
List all sessions | /workflow:session:list --active |
๐ /workflow:session:switch |
Switch sessions | /workflow:session:switch "Payment Fix" |
| Command | Function | Usage |
|---|---|---|
๐ญ /workflow:brainstorm:* |
Multi-perspective planning with role experts | /workflow:brainstorm:system-architect "microservices" |
๐ /workflow:brainstorm:auto-parallel |
Automated parallel brainstorming | /workflow:brainstorm:auto-parallel "topic" |
๐ /workflow:brainstorm:auto-squeeze |
Automated sequential brainstorming | /workflow:brainstorm:auto-squeeze "topic" |
๐ค /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: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] |
๐งช /workflow:test-gen |
Generate comprehensive test workflows | /workflow:test-gen WFS-session-id |
๐ /workflow:review |
Execute review phase for quality validation | /workflow:review |
| Command | Function | Usage |
|---|---|---|
๐ /workflow:tools:context-gather |
Intelligent context collection | /workflow:tools:context-gather --session WFS-id "task" |
๐งช /workflow:tools:concept-enhanced |
Enhanced concept analysis | /workflow:tools:concept-enhanced --session WFS-id |
๐ /workflow:tools:task-generate |
Manual task generation | /workflow:tools:task-generate --session WFS-id |
๐ค /workflow:tools:task-generate-agent |
Autonomous task generation | /workflow:tools:task-generate-agent --session WFS-id |
๐ /workflow:tools:status |
Advanced status reporting | /workflow:tools:status [task-id] |
๐ /workflow:tools:docs |
Generate hierarchical documentation | /workflow:tools:docs "architecture" | "api" | "all" |
| 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] |
| Command | Function | Usage |
|---|---|---|
โ /workflow:issue:create |
Create new project issue | /workflow:issue:create "API Rate Limiting" --priority=high |
๐ /workflow:issue:list |
List and filter issues | /workflow:issue:list --status=open --assigned=system-architect |
๐ /workflow:issue:update |
Update existing issue | /workflow:issue:update ISS-001 --status=in-progress |
โ
/workflow:issue:close |
Close completed issue | /workflow:issue:close ISS-001 --reason=resolved |
| 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 |
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 --> EXECUTE["/workflow:execute"]
EXECUTE --> TEST["/workflow:test-gen WFS-session-id"]
TEST --> REVIEW["/workflow:review"]
REVIEW --> DOCS["/workflow:tools:docs all"]
DOCS --> COMPLETE[โ
Complete]
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]
# 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. Execute implementation with agent coordination
/workflow:execute
# 6. Generate comprehensive test suite
/workflow:test-gen WFS-user-dashboard-feature
# 7. Quality assurance and review
/workflow:review
# 8. Generate documentation
/workflow:tools:docs "all"# Quick bug fix workflow
/workflow:session:start "Payment Processing Fix"
/cli:mode:bug-index "Payment validation fails on concurrent requests" --tool gemini
/cli:mode:bug-index "Fix race condition in payment validation" --tool codex
/workflow:review# Deep architecture workflow
/workflow:session:start "API Refactoring Initiative"
/cli:analyze "current API architecture patterns and technical debt" --tool gemini
/workflow:plan "microservices transition strategy"
/cli:execute "Refactor monolith to microservices architecture" --tool qwen
/workflow:test-gen WFS-api-refactoring-initiative
/workflow:review๐ก Community Discussion: LINUX DO Forum Thread ๐ฆ Repository: GitHub - Claude-Code-Workflow
Complete Development Flow: Brainstorm โ User Refinement โ Action Planning โ Execution โ Testing
graph LR
A[๐ญ Brainstorm] --> B[โ๏ธ Refinement]
B --> C[๐ Planning]
C --> D[โก Execution]
D --> E[๐งช Testing]
/workflow:brainstorm:auto-parallel- Automated concept planning (parallel execution)/workflow:brainstorm:auto-squeeze- Automated concept planning (sequential execution for testing)- Individual role commands (for replanning)
- Initial Planning: Execute
/workflow:brainstorm:auto-squeeze [topic]for automated planning - Refinement: If unsatisfied with the plan, use individual role commands like
/workflow:brainstorm:ui-designerto refine - Synthesis: Execute
/workflow:brainstorm:synthesisto generate comprehensive planning documentation
Available Role Commands:
๐๏ธ system-architect- System architecture analysis๐จ ui-designer- UI/UX design planning๐๏ธ data-architect- Data architecture design๐ security-expert- Security architecture analysis๐ product-manager- Product requirements analysis๐ฌ innovation-lead- Technical innovation recommendations๐ feature-planner- Feature planning๐ business-analyst- Business process analysis๐ฅ user-researcher- User behavior analysis
The previous stage is called Concept Planning. After completion, enter the Action Planning phase:
/workflow:plan "d:\test_project\.workflow\.active-WFS-promptmaster-platform"
# Typically pass the session identifier from the previous task, can also add task description/workflow:plan is designed as a coordinator that automatically orchestrates other slash commands in four phases:
- ๐ Session Initialization:
/workflow:session:start- Start a workflow session - ๐ Context Gathering:
/workflow:tools:context-gather- Locate relevant code files (for feature updates)
- Use MCP to find example code
- Generate
context-package.jsonfor agent reference
- ๐งช Concept Enhancement:
/workflow:tools:concept-enhanced- Analyze existing plans using CLI tools
- Provide improvement suggestions and key focus areas
- Generate
ANALYSIS_RESULTS.mdfor agent reference
- ๐ Task Generation:
/workflow:tools:task-generateor/workflow:tools:task-generate-agent- Develop detailed plans
- Generate task JSON files,
IMPL_PLAN.md,TODO_LIST.md
{
"metadata": {
"task_description": "Implement PromptMaster platform...",
"phase_type": "brainstorming",
"brainstorming_completed": true,
"session_id": "WFS-promptmaster-platform",
"tech_stack": {
"frontend": ["Vue 3", "TypeScript", "Element Plus"],
"backend": ["Python", "FastAPI", "SQLAlchemy"],
"database": ["PostgreSQL", "Redis"]
}
},
"assets": [
{
"type": "documentation",
"path": ".workflow/WFS-xxx/.brainstorming/synthesis-specification.md",
"priority": "critical"
}
],
"implementation_guidance": {
"start_with": ["Project structure initialization", "Database architecture", "Authentication system"],
"key_deliverables": ["Backend API", "Frontend interface", "Test suite"]
}
}{
"id": "IMPL-1",
"title": "Project Infrastructure & Environment Setup",
"status": "pending",
"meta": {
"type": "feature",
"agent": "@code-developer",
"complexity": "medium",
"priority": "P0"
},
"context": {
"requirements": ["Setup backend project structure", "Configure Docker Compose"],
"focus_paths": ["backend/", "frontend/", "docker-compose.yml"],
"acceptance": ["Backend service running on port 8000", "Frontend running on port 3000"]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_synthesis_specification",
"action": "Load comprehensive specification document",
"commands": ["Read(.workflow/xxx/synthesis-specification.md)"]
}
]
}
}The system automatically generates context and executes the next slash command until the workflow completes.
Enter the execution phase via /workflow:execute:
- code-developer: Code development tasks
- code-review-test-agent: Code review and testing tasks
Agents automatically load corresponding tech stack guidelines based on context (location: ~\.claude\workflows\cli-templates\tech-stacks)
Available Tech Stack Templates:
typescript-dev.md- TypeScript development standardspython-dev.md- Python development conventionsreact-dev.md- React architecture guidelinesvue-dev.md- Vue development best practicesfastapi-dev.md- FastAPI backend standards
๐ก Contributions Welcome: If you have better tech stack prompts, PRs are welcome!
Use CLI commands for interactive inquiry to form planning documents:
# Bug analysis and fixing
/cli:mode:bug-index "Describe bug symptoms" --tool gemini
# Deep code analysis
/cli:mode:code-analysis "Analysis target" --tool codex
# Architecture planning
/cli:mode:plan "Planning topic" --tool qwenExecution Strategy:
- Simple tasks: Let Claude execute directly
- Complex tasks: Use
/workflow:planfor structured planning and execution
After /workflow:execute completion:
# Generate test workflow
/workflow:test-gen WFS-session-id
# Execute test tasks
/workflow:executeTest workflow automatically generates multi-level tests:
- Unit Tests
- Integration Tests
- End-to-End Tests (E2E)
- Performance Tests
- Security Tests
๐ .claude/
โโโ ๐ค agents/ # AI agent definitions
โโโ ๐ฏ commands/ # CLI command implementations
โ โโโ cli/ # NEW: Unified CLI commands
โ โ โโโ mode/
โ โโโ ๐ฏ 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
โ โโโ ๐ง get_modules_by_depth.sh # Project analysis
โ โโโ ๐ read-task-paths.sh # Task path conversion
โโโ ๐ ๏ธ workflows/ # Core workflow documentation
โ โโโ ๐๏ธ workflow-architecture.md # System architecture
โ โโโ ๐ intelligent-tools-strategy.md # Tool selection guide
โ โโโ ๐ง context-search-strategy.md # Search and discovery 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
| 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 |
- ๐ฅ๏ธ 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
- ๐ 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
Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content/workflow:session:list// ~/.gemini/settings.json
{
"contextFileName": "CLAUDE.md"
}# Performance optimization
/dist/
/build/
/node_modules/
/.next/
# Temporary files
*.tmp
*.log
/temp/
# Include important docs
!README.md
!**/CLAUDE.mdMCP (Model Context Protocol) tools provide enhanced codebase analysis capabilities. They are completely optional - CCW works perfectly without them.
-
Install MCP Servers (choose what you need):
# Option 1: Exa MCP Server (External API patterns) # ๐ Installation Guide: https://github.com/exa-labs/exa-mcp-server # Option 2: Code Index MCP (Advanced code search) # ๐ Installation Guide: https://github.com/johnhuang316/code-index-mcp
-
Configure Claude Code IDE:
- Follow the MCP server installation guides above
- Restart Claude Code IDE after MCP server installation
- CCW will automatically detect and use available MCP tools
- ๐ Faster Analysis: Direct codebase indexing vs manual searching
- ๐ External Context: Real-world API patterns and examples
- ๐ Advanced Search: Pattern matching and similarity detection
- โก Automatic Fallback: Uses traditional tools when MCP unavailable
| MCP Server | Installation Guide | Purpose |
|---|---|---|
| ๐ Exa MCP | Installation Guide | External API patterns & best practices |
| ๐ Code Index MCP | Installation Guide | Advanced internal codebase search |
| ๐ MCP Protocol | Official Documentation | Technical specifications |
๐ก Pro Tip: Start with basic CCW functionality, then add MCP tools when you want enhanced analysis capabilities.
- ๐ด Fork the repository
- ๐ฟ Create feature branch:
git checkout -b feature/enhancement-name - ๐ฆ Install dependencies
- โ Test with sample projects
- ๐ค Submit detailed pull request
- โ Follow existing command patterns
- ๐ Maintain backward compatibility
- ๐งช Add tests for new functionality
- ๐ Update documentation
- ๐ท๏ธ Use semantic versioning
| Resource | Link | Description |
|---|---|---|
| ๐ Documentation | Project Wiki | Comprehensive guides |
| ๐ Issues | GitHub Issues | Bug reports & features |
| ๐ฌ Discussions | Community Forum | Community support |
| ๐ Changelog | Release History | Version history |
This project is licensed under the MIT License - see the LICENSE file for details.