# ๐Ÿš€ Claude Code Workflow (CCW)
[![Version](https://img.shields.io/badge/version-v3.0.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]() [![MCP Tools](https://img.shields.io/badge/๐Ÿ”ง_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol) **Languages:** [English](README.md) | [ไธญๆ–‡](README_CN.md)
--- ## โš™๏ธ Installation ### ๐Ÿš€ **Quick One-Line Installation** CCW provides native installation scripts for all platforms - no cross-platform dependencies required! **Windows (PowerShell):** ```powershell Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content ``` **Linux/macOS (Bash/Zsh):** ```bash bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh) ``` ### ๐Ÿ“ฆ **Local Installation from Cloned Repository** If you prefer to review the code before installation: **1. Clone the repository:** ```bash git clone https://github.com/catlog22/Claude-Code-Workflow.git cd Claude-Code-Workflow ``` **2. Run the local installer:** **Windows:** ```powershell .\Install-Claude.ps1 ``` **Linux/macOS:** ```bash chmod +x Install-Claude.sh ./Install-Claude.sh ``` ### โœ… **Verify Installation** After installation, verify CCW is working: ```bash /workflow:session:list ``` ### ๐Ÿ“‹ **Installation Scripts Overview** | Script | Platform | Purpose | |--------|----------|---------| | `install-remote.ps1` | Windows | One-line remote installation via PowerShell | | `install-remote.sh` | Linux/macOS | One-line remote installation via Bash | | `Install-Claude.ps1` | Windows | Local interactive installer with GUI menu | | `Install-Claude.sh` | Linux/macOS | Local interactive installer with colored menu | **All installers support:** - โœ… Interactive mode with arrow-key navigation (Windows) or numbered menu (Linux/macOS) - โœ… Automatic backup of existing files (enabled by default) - โœ… Global installation to `~/.claude/` or custom path - โœ… Non-interactive mode for automation - โœ… Force mode to skip confirmations --- ## ๐Ÿ“‹ 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 v3.0.0**: Major update with **unified CLI command structure**. Consolidates Gemini, Qwen, and Codex commands into a single `/cli:*` command set with `--tool` flag for tool selection. Includes comprehensive workflow guide and command verification. See [CHANGELOG.md](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. ### ๐ŸŒŸ Key Innovations - **๐Ÿ”„ 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 --- ## ๐Ÿ—๏ธ 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 ``` ### ๐Ÿ›๏ธ **Four-Layer Architecture** 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 | --- ## โœจ 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. **โšก Execute Phase** - Autonomous implementation with multi-agent orchestration 4. **๐Ÿงช Test Phase** - Automated test workflow generation with comprehensive coverage 5. **๐Ÿ” Review Phase** - Quality assurance and completion 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 --- ## ๐Ÿ“Š 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"` | | `๐Ÿ“ /update-memory-full` | Complete documentation update | `/update-memory-full` | | `๐Ÿ”„ /update-memory-related` | Smart context-aware updates | `/update-memory-related` | ### ๐Ÿš€ **Unified CLI Commands (v3.0.0+)** | Command | Purpose | Usage | |---|---|---| | `/cli:analyze` | Deep codebase analysis | `/cli:analyze "[target]" [--tool ]` | | `/cli:chat` | Direct interaction with a tool | `/cli:chat "[inquiry]" [--tool ]` | | `/cli:execute` | Intelligent execution with YOLO permissions | `/cli:execute "[description|task-id]" [--tool ]` | | `/cli:cli-init`| Initialize CLI tool configurations | `/cli:cli-init [--tool ]` | | `/cli:mode:bug-index` | Bug analysis and fix suggestions | `/cli:mode:bug-index "[description]" [--tool ]` | | `/cli:mode:code-analysis` | Deep code analysis and debugging | `/cli:mode:code-analysis "[target]" [--tool ]` | | `/cli:mode:plan` | Project planning and architecture | `/cli:mode:plan "[topic]" [--tool ]` | **Supported tools for `--tool` flag:** `gemini` (default), `qwen`, `codex`. --- ### ๐Ÿ“– **Migration Guide: From v2 to v3.0.0** 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 ` 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. --- ### ๐ŸŽฏ **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: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"` | #### ๐ŸŽฏ Workflow Operations | 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` | #### ๐Ÿ”ง Workflow Tools (Internal) | 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"` | #### ๐Ÿท๏ธ 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]` | #### ๐Ÿท๏ธ Issue Management | 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` | #### ๐Ÿง  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 --> EXECUTE["/workflow:execute"] EXECUTE --> TEST["/workflow:test-gen WFS-session-id"] TEST --> REVIEW["/workflow:review"] REVIEW --> DOCS["/workflow:tools: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. 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" ``` #### **โšก Rapid Bug Resolution** ```bash # 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 ``` #### **๐Ÿ“Š Architecture Analysis & Refactoring** ```bash # 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 ``` --- ## ๐Ÿ“– Complete Workflow Guide > **๐Ÿ’ก Community Discussion**: [LINUX DO Forum Thread](https://linux.do/t/topic/995175/24) > **๐Ÿ“ฆ Repository**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow) ### ๐ŸŽฏ Core Workflow Process **Complete Development Flow**: Brainstorm โ†’ User Refinement โ†’ Action Planning โ†’ Execution โ†’ Testing ```mermaid graph LR A[๐Ÿ’ญ Brainstorm] --> B[โœ๏ธ Refinement] B --> C[๐Ÿ“‹ Planning] C --> D[โšก Execution] D --> E[๐Ÿงช Testing] ``` ### ๐Ÿง  Brainstorming Phase #### Available Commands: - `/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) #### Workflow Steps: 1. **Initial Planning**: Execute `/workflow:brainstorm:auto-squeeze [topic]` for automated planning 2. **Refinement**: If unsatisfied with the plan, use individual role commands like `/workflow:brainstorm:ui-designer` to refine 3. **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 ### ๐Ÿ“‹ Action Planning Phase The previous stage is called **Concept Planning**. After completion, enter the **Action Planning** phase: ```bash /workflow:plan "d:\test_project\.workflow\.active-WFS-promptmaster-platform" # Typically pass the session identifier from the previous task, can also add task description ``` #### Plan Command Coordinator Architecture: `/workflow:plan` is designed as a coordinator that automatically orchestrates other slash commands in four phases: 1. **๐Ÿš€ Session Initialization**: `/workflow:session:start` - Start a workflow session 2. **๐Ÿ” 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 3. **๐Ÿงช 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 4. **๐Ÿ“ 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` #### ๐Ÿ—‚๏ธ Context Package Structure Example: ```json { "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"] } } ``` #### ๐Ÿ“‹ Task JSON Structure Example: ```json { "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. ### โšก Execution Phase Enter the execution phase via `/workflow:execute`: #### ๐Ÿค– Automatic Agent Assignment: - **code-developer**: Code development tasks - **code-review-test-agent**: Code review and testing tasks #### ๐Ÿ“š Tech Stack Guidelines Auto-Loading: 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 standards - `python-dev.md` - Python development conventions - `react-dev.md` - React architecture guidelines - `vue-dev.md` - Vue development best practices - `fastapi-dev.md` - FastAPI backend standards > ๐Ÿ’ก **Contributions Welcome**: If you have better tech stack prompts, PRs are welcome! ### ๐Ÿ› Feature Development & Bug Fix Workflow #### Quick Interactive Planning: Use CLI commands for interactive inquiry to form planning documents: ```bash # 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**: Use `/workflow:plan` for structured planning and execution ### ๐Ÿงช Testing Workflow After `/workflow:execute` completion: ```bash # 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** --- ## ๐Ÿ—๏ธ Project Structure ``` ๐Ÿ“ .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 ``` --- ## โšก 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 --- ## โš™๏ธ 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 ``` ### ๐Ÿ”ง **MCP Tools Configuration** *(Optional Enhancement)* [![MCP Tools](https://img.shields.io/badge/๐Ÿ”ง_MCP_Tools-Optional-blue.svg)](https://github.com/modelcontextprotocol) **MCP (Model Context Protocol) tools provide enhanced codebase analysis capabilities. They are completely optional - CCW works perfectly without them.** #### **Quick MCP Setup** 1. **Install MCP Servers** (choose what you need): ```bash # 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 ``` 2. **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 #### **Benefits When Enabled** - ๐Ÿ“Š **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 #### **Configuration Resources** | MCP Server | Installation Guide | Purpose | |------------|-------------------|---------| | ๐ŸŒ **Exa MCP** | [Installation Guide](https://github.com/exa-labs/exa-mcp-server) | External API patterns & best practices | | ๐Ÿ” **Code Index MCP** | [Installation Guide](https://github.com/johnhuang316/code-index-mcp) | Advanced internal codebase search | | ๐Ÿ“– **MCP Protocol** | [Official Documentation](https://github.com/modelcontextprotocol) | Technical specifications | > **๐Ÿ’ก Pro Tip**: Start with basic CCW functionality, then add MCP tools when you want enhanced analysis capabilities. --- ## ๐Ÿค 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.* [![โญ Star on GitHub](https://img.shields.io/badge/โญ-Star%20on%20GitHub-yellow.svg)](https://github.com/catlog22/Claude-Code-Workflow)