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.1.0-experimental: Introduces experimental MCP (Model Context Protocol) tools integration for enhanced codebase analysis and external context retrieval. Includes Exa MCP Server for external API patterns and Code Index MCP for advanced internal codebase exploration. See CHANGELOG.md for details.
โ ๏ธ Experimental Features: MCP tools are optional and experimental. All existing functionality remains stable.
- ๐ Enhanced Workflow Lifecycle: Complete development cycle: Brainstorm โ Plan โ Verify โ Execute โ Test โ Review
- ๐งช 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
- ๐ง 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
- โ Verify Phase - Pre-execution validation using Gemini (strategic) + Codex (technical)
- โก 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
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
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" |
๐ /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 |
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: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: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" |
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 --> 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]
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. 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"
# 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-deep "microservices transition strategy"
/workflow:plan-verify
/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-designer
to refine - Synthesis: Execute
/workflow:brainstorm:synthesis
to 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.json
for agent reference
- ๐งช Concept Enhancement:
/workflow:tools:concept-enhanced
- Analyze existing plans using CLI tools
- Provide improvement suggestions and key focus areas
- Generate
ANALYSIS_RESULTS.md
for agent reference
- ๐ Task Generation:
/workflow:tools:task-generate
or/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 qwen
Execution Strategy:
- Simple tasks: Let Claude execute directly
- Complex tasks: Follow complete workflow (Brainstorm โ Planning โ Execution)
After /workflow:execute
completion:
# Generate test workflow
/workflow:test-gen WFS-session-id
# Execute test tasks
/workflow:execute
Test 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.md
MCP (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.