Claude-Code-Workflow/WORKFLOW_GUIDE.md

CCW Workflow Difficulty Guide

Overview

CCW provides two workflow systems: Main Workflow and Issue Workflow, working together to cover the complete software development lifecycle.

┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│                                   Main Workflow                                              │
│                                                                                              │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐  ┌──────────────┐   │
│  │   Level 1   │ → │   Level 2   │ → │   Level 3   │ → │   Level 4   │→ │   Level 5    │   │
│  │   Rapid     │   │ Lightweight │   │  Standard   │   │ Brainstorm  │  │ Intelligent  │   │
│  │             │   │             │   │             │   │             │  │ Orchestration│   │
│  │ lite-lite-  │   │ lite-plan   │   │    plan     │   │ brainstorm  │  │     ccw-     │   │
│  │    lite     │   │ lite-fix    │   │  tdd-plan   │   │  :auto-     │  │ coordinator  │   │
│  │             │   │ multi-cli-  │   │ test-fix-   │   │  parallel   │  │              │   │
│  │             │   │    plan     │   │    gen      │   │     ↓       │  │  Auto-       │   │
│  │             │   │             │   │             │   │   plan      │  │  analyze &   │   │
│  │             │   │             │   │             │   │             │  │  recommend   │   │
│  └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘  └──────────────┘   │
│                                                                                              │
│  Manual Degree: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶        │
│                 High (manual selection)                                    Low (fully auto) │
│                                                                                              │
│  Complexity: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶         │
│             Low                                                                    High     │
└──────────────────────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ After development
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              Issue Workflow                                 │
│                                                                             │
│     ┌──────────────┐         ┌──────────────┐         ┌──────────────┐     │
│     │  Accumulate  │    →    │    Plan      │    →    │   Execute    │     │
│     │  Discover &  │         │    Batch     │         │   Parallel   │     │
│     │   Collect    │         │   Planning   │         │  Execution   │     │
│     └──────────────┘         └──────────────┘         └──────────────┘     │
│                                                                             │
│     Supplementary role: Maintain main branch stability, worktree isolation  │
└─────────────────────────────────────────────────────────────────────────────┘

---

Main Workflow vs Issue Workflow

Design Philosophy

Aspect	Main Workflow	Issue Workflow
Purpose	Primary development cycle	Post-development maintenance
Timing	Feature development phase	After main workflow completes
Scope	Complete feature implementation	Targeted fixes/enhancements
Parallelism	Dependency analysis → Agent parallel	Worktree isolation (optional)
Branch Model	Work on current branch	Can use isolated worktree

Why Main Workflow Doesn't Use Worktree Automatically?

Dependency analysis already solves parallelism:

1. Planning phase (/workflow:plan) performs dependency analysis
2. Automatically identifies task dependencies and critical paths
3. Partitions into parallel groups (independent tasks) and serial chains (dependent tasks)
4. Agents execute independent tasks in parallel without filesystem isolation

┌─────────────────────────────────────────────────┐
│            Dependency Analysis                  │
│                                                 │
│  Task A ─────┐                                  │
│              ├──→ Parallel Group 1 ──→ Agent 1  │
│  Task B ─────┘                                  │
│                                                 │
│  Task C ────────→ Serial Chain ──────→ Agent 2  │
│       ↓                                         │
│  Task D ────────→                               │
│                                                 │
│  Same worktree, parallelism through scheduling  │
└─────────────────────────────────────────────────┘

Why Issue Workflow Supports Worktree?

Issue Workflow serves as a supplementary mechanism with different scenarios:

1. Main development complete, merged to main
2. Issues discovered requiring fixes
3. Need to fix without affecting current development
4. Worktree isolation keeps main branch stable

Development → Release → Discover Issue → Worktree Fix → Merge back
    ↑                                                      │
    └────────────── Continue new feature ←─────────────────┘

---

Level 1: Rapid Execution (lite-lite-lite)

Simplest - Single CLI analysis to execution, zero artifacts

Characteristics

Property	Value
Complexity	Low
Artifacts	None
State	Stateless
CLI Selection	Auto-analyze task type
Iteration	Via AskUser

Flow

User Input → Clarification → Auto-select CLI → Parallel Analysis → Show Results → Direct Execute
                                  ↓
                            No intermediate files

Command

/workflow:lite-lite-lite
# Or CCW auto-selects for simple tasks

Use Cases

• ✅ Quick fixes
• ✅ Simple feature additions
• ✅ Configuration adjustments
• ✅ Small-scope renaming
• ❌ Multi-module changes
• ❌ Need persistent records

---

Level 2: Lightweight Planning

Lightweight - In-memory planning or single analysis, fast iteration

Included Workflows

Workflow	Purpose	Artifacts	Execution
lite-plan	Clear requirement development	memory://plan	→ lite-execute
lite-fix	Bug diagnosis and fix	.workflow/.lite-fix/	→ lite-execute
multi-cli-plan	Multi-perspective tasks	.workflow/.multi-cli-plan/	→ lite-execute

Common Characteristics

Property	Value
Complexity	Low-Medium
State	Session-scoped / Lightweight persistence
Execution	Unified via lite-execute
Use Case	Relatively clear requirements

---

2.1 lite-plan → lite-execute

In-memory planning + Direct execution

┌─────────────────┐     ┌─────────────────┐
│  lite-plan      │ ──→ │  lite-execute   │
│  In-memory plan │     │  Direct execute │
└─────────────────┘     └─────────────────┘

/workflow:lite-plan    # Planning
/workflow:lite-execute # Execution

Use Case: Clear single-module features

---

2.2 lite-fix

Intelligent diagnosis + Fix (5 phases)

Phase 1: Bug Analysis & Diagnosis
   ├─ Intelligent severity pre-assessment (Low/Medium/High/Critical)
   └─ Parallel cli-explore-agent diagnosis (1-4 angles)

Phase 2: Clarification (optional)
   └─ Aggregate clarification needs, AskUserQuestion

Phase 3: Fix Planning
   ├─ Low/Medium → Claude direct planning
   └─ High/Critical → cli-lite-planning-agent

Phase 4: Confirmation & Selection
   └─ User confirms execution method

Phase 5: Execute
   └─ SlashCommand("/workflow:lite-execute --in-memory --mode bugfix")

/workflow:lite-fix           # Standard fix
/workflow:lite-fix --hotfix  # Emergency hotfix (skip diagnosis)

Artifacts: .workflow/.lite-fix/{bug-slug}-{date}/

• diagnosis-{angle}.json (1-4 diagnosis files)
• diagnoses-manifest.json
• fix-plan.json

Use Case: Bug diagnosis, production emergencies

---

2.3 multi-cli-plan → lite-execute

Multi-CLI collaborative analysis + Consensus convergence (5 phases)

Phase 1: Context Gathering
   └─ ACE semantic search, build context package

Phase 2: Multi-CLI Discussion (iterative)
   ├─ cli-discuss-agent executes Gemini + Codex + Claude
   ├─ Cross-verification, synthesize solutions
   └─ Loop until convergence or max rounds

Phase 3: Present Options
   └─ Display solutions with trade-offs

Phase 4: User Decision
   └─ User selects solution

Phase 5: Plan Generation
   ├─ cli-lite-planning-agent generates plan
   └─ → lite-execute

/workflow:multi-cli-plan "task description"  # Multi-CLI collaborative planning
/workflow:lite-execute                       # Execute selected solution

Artifacts: .workflow/.multi-cli-plan/{MCP-task-slug-date}/

• rounds/*/synthesis.json (per-round analysis)
• context-package.json
• IMPL_PLAN.md + plan.json

vs lite-plan comparison:

Aspect	multi-cli-plan	lite-plan
Context	ACE semantic search	Manual file patterns
Analysis	Multi-CLI cross-verification	Single planning
Iteration	Multiple rounds until convergence	Single round
Confidence	High (consensus-driven)	Medium (single perspective)

Use Case: Multi-perspective analysis, technology selection, solution comparison

---

Level 3: Standard Planning

Standard - Complete planning + Persistent Session + Verification

Included Workflows

Workflow	Purpose	Phases	Artifact Location
plan	Complex feature development	5 phases	.workflow/active/{session}/
tdd-plan	Test-driven development	6 phases	.workflow/active/{session}/
test-fix-gen	Test fix generation	5 phases	.workflow/active/WFS-test-{session}/

Common Characteristics

Property	Value
Complexity	Medium-High
Artifacts	Persistent files (.workflow/active/{session}/)
State	Full session management
Verification	Built-in verification steps
Execution	/workflow:execute
Use Case	Multi-module, traceable tasks

---

3.1 plan → verify → execute

5-phase complete planning workflow

Phase 1: Session Discovery
   └─ /workflow:session:start --auto

Phase 2: Context Gathering
   └─ /workflow:tools:context-gather
      └─ Returns context-package.json + conflict_risk

Phase 3: Conflict Resolution (conditional)
   └─ IF conflict_risk ≥ medium → /workflow:tools:conflict-resolution

Phase 4: Task Generation
   └─ /workflow:tools:task-generate-agent
      └─ Returns IMPL_PLAN.md + IMPL-*.json + TODO_LIST.md

Return: Summary + Next Steps

/workflow:plan "task description"   # Complete planning
/workflow:plan-verify        # Verify plan (recommended)
/workflow:execute                   # Execute
/workflow:review                    # (optional) Review

Artifacts: .workflow/active/{WFS-session}/

• workflow-session.json
• IMPL_PLAN.md
• TODO_LIST.md
• .task/IMPL-*.json
• .process/context-package.json

Use Case: Multi-module changes, refactoring, dependency analysis needed

---

3.2 tdd-plan → execute → tdd-verify

6-phase test-driven development workflow

Phase 1: Session Discovery
   └─ /workflow:session:start --type tdd --auto

Phase 2: Context Gathering
   └─ /workflow:tools:context-gather

Phase 3: Test Coverage Analysis
   └─ /workflow:tools:test-context-gather
      └─ Detect test framework, analyze coverage

Phase 4: Conflict Resolution (conditional)
   └─ IF conflict_risk ≥ medium → /workflow:tools:conflict-resolution

Phase 5: TDD Task Generation
   └─ /workflow:tools:task-generate-tdd
      └─ Generate IMPL tasks with built-in Red-Green-Refactor cycles

Phase 6: TDD Structure Validation
   └─ Verify TDD structure compliance

/workflow:tdd-plan "feature description"  # TDD planning
/workflow:plan-verify              # Verify (recommended)
/workflow:execute                         # Execute (follow Red-Green-Refactor)
/workflow:tdd-verify                      # Verify TDD compliance

TDD Task Structure:

• Each IMPL task contains complete internal Red-Green-Refactor cycle
• meta.tdd_workflow: true
• flow_control.implementation_approach contains 3 steps (red/green/refactor)
• Green phase includes test-fix-cycle configuration

Use Case: Test-driven development, high-quality feature requirements

---

3.3 test-fix-gen → test-cycle-execute

5-phase test fix generation workflow

Phase 1: Create Test Session
   └─ /workflow:session:start --type test --new

Phase 2: Gather Test Context
   ├─ Session Mode: /workflow:tools:test-context-gather
   └─ Prompt Mode: /workflow:tools:context-gather

Phase 3: Test Generation Analysis
   └─ /workflow:tools:test-concept-enhanced
      └─ Multi-layer test requirements (L0: Static, L1: Unit, L2: Integration, L3: E2E)

Phase 4: Generate Test Tasks
   └─ /workflow:tools:test-task-generate
      └─ IMPL-001 (generate) + IMPL-001.5 (quality gate) + IMPL-002 (execute fix)

Phase 5: Return Summary
   └─ → /workflow:test-cycle-execute

Dual-mode support:

Mode	Input Pattern	Context Source
Session Mode	WFS-xxx	Source session summaries
Prompt Mode	Text/file path	Direct codebase analysis

/workflow:test-fix-gen WFS-user-auth-v2        # Session Mode
/workflow:test-fix-gen "Test the auth API"     # Prompt Mode
/workflow:test-cycle-execute                   # Execute test-fix cycle

Artifacts: .workflow/active/WFS-test-{session}/

• .task/IMPL-001.json (test understanding & generation)
• .task/IMPL-001.5-review.json (quality gate)
• .task/IMPL-002.json (test execution & fix cycle)
• .process/TEST_ANALYSIS_RESULTS.md

Use Case: Test failure fixes, coverage improvement

---

Level 4: Brainstorming (brainstorm:auto-parallel)

Most Complex - Multi-role brainstorming + Complete planning + Execution

Characteristics

Property	Value
Complexity	High
Artifacts	Multi-role analysis docs + IMPL_PLAN.md
Role Count	3-9 (default 3)
Execution Mode	Phase 1/3 sequential, Phase 2 parallel

3-Phase Flow

Phase 1: Interactive Framework Generation
   └─ /workflow:brainstorm:artifacts
      ├─ Topic analysis, generate questions
      ├─ Role selection (user confirmation)
      ├─ Role question collection
      ├─ Conflict detection and resolution
      └─ Generate guidance-specification.md

Phase 2: Parallel Role Analysis (parallel)
   └─ N × Task(conceptual-planning-agent)
      ├─ Each role analyzes independently
      └─ Parallel generate {role}/analysis.md

Phase 3: Synthesis Integration
   └─ /workflow:brainstorm:synthesis
      └─ Integrate all role analyses → synthesis-specification.md

Commands

/workflow:brainstorm:auto-parallel "topic" [--count N] [--style-skill package]
/workflow:plan --session {sessionId}     # Plan based on brainstorm results
/workflow:plan-verify             # Verify
/workflow:execute                        # Execute

Available Roles

Role	Description
system-architect	System Architect
ui-designer	UI Designer
ux-expert	UX Expert
product-manager	Product Manager
product-owner	Product Owner
data-architect	Data Architect
scrum-master	Scrum Master
subject-matter-expert	Domain Expert
test-strategist	Test Strategist

Artifact Structure

.workflow/active/WFS-{topic}/
├── workflow-session.json              # Session metadata
└── .brainstorming/
    ├── guidance-specification.md      # Framework (Phase 1)
    ├── {role}/
    │   ├── analysis.md                # Main document
    │   └── analysis-{slug}.md         # Sub-documents (optional, max 5)
    └── synthesis-specification.md     # Integration (Phase 3)

Use Cases

• ✅ New feature design
• ✅ System architecture refactoring
• ✅ Exploratory requirements
• ✅ Uncertain implementation approach
• ✅ Multi-dimensional trade-offs needed
• ❌ Clear requirements
• ❌ Time-sensitive tasks

---

Level 5: Intelligent Orchestration (CCW Coordinator)

Most Intelligent - Automated command chain orchestration + Sequential execution + State persistence

Core Concept: Minimum Execution Units

Definition: A set of commands that must execute together as an atomic group to achieve a meaningful workflow milestone. Splitting these commands breaks the logical flow and creates incomplete states.

Why This Matters:

• Prevents Incomplete States: Avoid stopping after task generation without execution
• User Experience: User gets complete results, not intermediate artifacts requiring manual follow-up
• Workflow Integrity: Maintains logical coherence of multi-step operations

Minimum Execution Units

Planning + Execution Units:

Unit Name	Commands	Purpose	Output
Quick Implementation	lite-plan → lite-execute	Lightweight plan and immediate execution	Working code
Multi-CLI Planning	multi-cli-plan → lite-execute	Multi-perspective analysis and execution	Working code
Bug Fix	lite-fix → lite-execute	Quick bug diagnosis and fix execution	Fixed code
Full Planning + Execution	plan → execute	Detailed planning and execution	Working code
Verified Planning + Execution	plan → plan-verify → execute	Planning with verification and execution	Working code
Replanning + Execution	replan → execute	Update plan and execute changes	Working code
TDD Planning + Execution	tdd-plan → execute	Test-driven development planning and execution	Working code
Test Generation + Execution	test-gen → execute	Generate test suite and execute	Generated tests

Testing Units:

Unit Name	Commands	Purpose	Output
Test Validation	test-fix-gen → test-cycle-execute	Generate test tasks and execute test-fix cycle	Tests passed

Review Units:

Unit Name	Commands	Purpose	Output
Code Review (Session)	review-session-cycle → review-fix	Complete review cycle and apply fixes	Fixed code
Code Review (Module)	review-module-cycle → review-fix	Module review cycle and apply fixes	Fixed code

3-Phase Workflow

Phase 1: Analyze Requirements

Parse task description to extract: goal, scope, constraints, complexity, and task type.

function analyzeRequirements(taskDescription) {
  return {
    goal: extractMainGoal(taskDescription),           // e.g., "Implement user registration"
    scope: extractScope(taskDescription),             // e.g., ["auth", "user_management"]
    constraints: extractConstraints(taskDescription), // e.g., ["no breaking changes"]
    complexity: determineComplexity(taskDescription), // 'simple' | 'medium' | 'complex'
    task_type: detectTaskType(taskDescription)        // See task type patterns below
  };
}

// Task Type Detection Patterns
function detectTaskType(text) {
  // Priority order (first match wins)
  if (/fix|bug|error|crash|fail|debug|diagnose/.test(text)) return 'bugfix';
  if (/tdd|test-driven|test first/.test(text)) return 'tdd';
  if (/test fail|fix test|failing test/.test(text)) return 'test-fix';
  if (/generate test|add test/.test(text)) return 'test-gen';
  if (/review/.test(text)) return 'review';
  if (/explore|brainstorm/.test(text)) return 'brainstorm';
  if (/multi-perspective|comparison/.test(text)) return 'multi-cli';
  return 'feature';  // Default
}

// Complexity Assessment
function determineComplexity(text) {
  let score = 0;
  if (/refactor|migrate|architect|system/.test(text)) score += 2;
  if (/multiple|across|all|entire/.test(text)) score += 2;
  if (/integrate|api|database/.test(text)) score += 1;
  if (/security|performance|scale/.test(text)) score += 1;
  return score >= 4 ? 'complex' : score >= 2 ? 'medium' : 'simple';
}

Phase 2: Discover Commands & Recommend Chain

Dynamic command chain assembly using port-based matching.

Display to user:

Recommended Command Chain:

Pipeline (visual):
Requirement → lite-plan → Plan → lite-execute → Code → test-cycle-execute → Tests Passed

Commands:
1. /workflow:lite-plan
2. /workflow:lite-execute
3. /workflow:test-cycle-execute

Proceed? [Confirm / Show Details / Adjust / Cancel]

User Confirmation:

async function getUserConfirmation(chain) {
  // Present chain with options:
  // - Confirm and execute
  // - Show details
  // - Adjust chain
  // - Cancel
}

Phase 3: Execute Sequential Command Chain

async function executeCommandChain(chain, analysis) {
  const sessionId = `ccw-coord-${Date.now()}`;
  const stateDir = `.workflow/.ccw-coordinator/${sessionId}`;

  // Initialize state
  const state = {
    session_id: sessionId,
    status: 'running',
    created_at: new Date().toISOString(),
    analysis: analysis,
    command_chain: chain.map((cmd, idx) => ({ ...cmd, index: idx, status: 'pending' })),
    execution_results: [],
    prompts_used: []
  };

  // Save initial state
  Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2));

  for (let i = 0; i < chain.length; i++) {
    const cmd = chain[i];

    // Assemble prompt
    let prompt = formatCommand(cmd, state.execution_results, analysis);
    prompt += `\n\nTask: ${analysis.goal}`;
    if (state.execution_results.length > 0) {
      prompt += '\n\nPrevious results:\n';
      state.execution_results.forEach(r => {
        if (r.session_id) {
          prompt += `- ${r.command}: ${r.session_id}\n`;
        }
      });
    }

    // Launch CLI in background
    const taskId = Bash(
      `ccw cli -p "${escapePrompt(prompt)}" --tool claude --mode write`,
      { run_in_background: true }
    ).task_id;

    // Save checkpoint
    state.execution_results.push({
      index: i,
      command: cmd.command,
      status: 'in-progress',
      task_id: taskId,
      session_id: null,
      artifacts: [],
      timestamp: new Date().toISOString()
    });

    // Stop here - wait for hook callback
    Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2));
    break;
  }

  state.status = 'waiting';
  Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2));
  return state;
}

State File Structure

Location: .workflow/.ccw-coordinator/{session_id}/state.json

{
  "session_id": "ccw-coord-20250124-143025",
  "status": "running|waiting|completed|failed",
  "created_at": "2025-01-24T14:30:25Z",
  "updated_at": "2025-01-24T14:35:45Z",
  "analysis": {
    "goal": "Implement user registration",
    "scope": ["authentication", "user_management"],
    "constraints": ["no breaking changes"],
    "complexity": "medium",
    "task_type": "feature"
  },
  "command_chain": [
    {
      "index": 0,
      "command": "/workflow:plan",
      "name": "plan",
      "status": "completed"
    },
    {
      "index": 1,
      "command": "/workflow:execute",
      "name": "execute",
      "status": "running"
    }
  ],
  "execution_results": [
    {
      "index": 0,
      "command": "/workflow:plan",
      "status": "completed",
      "task_id": "task-001",
      "session_id": "WFS-plan-20250124",
      "artifacts": ["IMPL_PLAN.md"],
      "timestamp": "2025-01-24T14:30:25Z",
      "completed_at": "2025-01-24T14:30:45Z"
    }
  ]
}

Complete Lifecycle Decision Flowchart

flowchart TD
    Start([Start New Task]) --> Q0{Is this a bug fix?}

    Q0 -->|Yes| BugFix[🐛 Bug Fix Process]
    Q0 -->|No| Q1{Do you know what to do?}

    BugFix --> BugSeverity{Understand root cause?}
    BugSeverity -->|Clear| LiteFix[/workflow:lite-fix<br>Standard fix /]
    BugSeverity -->|Production incident| HotFix[/workflow:lite-fix --hotfix<br>Emergency hotfix /]
    BugSeverity -->|Unclear| BugDiag[/workflow:lite-fix<br>Auto-diagnose root cause /]

    BugDiag --> LiteFix
    LiteFix --> BugComplete[Bug fixed]
    HotFix --> FollowUp[/Auto-generate follow-up tasks<br>Complete fix + post-mortem /]
    FollowUp --> BugComplete
    BugComplete --> End([Task Complete])

    Q1 -->|No| Ideation[💡 Exploration Phase<br>Clarify requirements]
    Q1 -->|Yes| Q2{Do you know how to do it?}

    Ideation --> BrainIdea[/workflow:brainstorm:auto-parallel<br>Explore product direction /]
    BrainIdea --> Q2

    Q2 -->|No| Design[🏗️ Design Exploration<br>Explore architecture]
    Q2 -->|Yes| Q3{Need planning?}

    Design --> BrainDesign[/workflow:brainstorm:auto-parallel<br>Explore technical solutions /]
    BrainDesign --> Q3

    Q3 -->|Quick and simple| LitePlan[⚡ Lightweight Planning<br>/workflow:lite-plan]
    Q3 -->|Complex and complete| FullPlan[📋 Standard Planning<br>/workflow:plan]

    LitePlan --> Q4{Need code exploration?}
    Q4 -->|Yes| LitePlanE[/workflow:lite-plan -e<br>Task description /]
    Q4 -->|No| LitePlanNormal[/workflow:lite-plan<br>Task description /]

    LitePlanE --> LiteConfirm[Three-dimensional confirmation:<br>1️⃣ Task approval<br>2️⃣ Execution method<br>3️⃣ Code review]
    LitePlanNormal --> LiteConfirm

    LiteConfirm --> Q5{Select execution method}
    Q5 -->|Agent| LiteAgent[/workflow:lite-execute<br>Use @code-developer /]
    Q5 -->|CLI tool| LiteCLI[CLI Execution<br>Gemini/Qwen/Codex]
    Q5 -->|Plan only| UserImpl[User manual implementation]

    FullPlan --> PlanVerify{Verify plan quality?}
    PlanVerify -->|Yes| Verify[/workflow:action-plan-verify /]
    PlanVerify -->|No| Execute
    Verify --> Q6{Verification passed?}
    Q6 -->|No| FixPlan[Fix plan issues]
    Q6 -->|Yes| Execute
    FixPlan --> Execute

    Execute[🚀 Execution Phase<br>/workflow:execute]
    LiteAgent --> TestDecision
    LiteCLI --> TestDecision
    UserImpl --> TestDecision
    Execute --> TestDecision

    TestDecision{Need tests?}
    TestDecision -->|TDD mode| TDD[/workflow:tdd-plan<br>Test-driven development /]
    TestDecision -->|Post-test| TestGen[/workflow:test-gen<br>Generate tests /]
    TestDecision -->|Tests exist| TestCycle[/workflow:test-cycle-execute<br>Test-fix cycle /]
    TestDecision -->|Not needed| Review

    TDD --> TDDExecute[/workflow:execute<br>Red-Green-Refactor /]
    TDDExecute --> TDDVerify[/workflow:tdd-verify<br>Verify TDD compliance /]
    TDDVerify --> Review

    TestGen --> TestExecute[/workflow:execute<br>Execute test tasks /]
    TestExecute --> TestResult{Tests passed?}
    TestResult -->|No| TestCycle
    TestResult -->|Yes| Review

    TestCycle --> TestPass{Pass rate ≥ 95%?}
    TestPass -->|No, continue fixing| TestCycle
    TestPass -->|Yes| Review

    Review[📝 Review Phase]
    Review --> Q7{Need specialized review?}
    Q7 -->|Security| SecurityReview[/workflow:review<br>--type security /]
    Q7 -->|Architecture| ArchReview[/workflow:review<br>--type architecture /]
    Q7 -->|Quality| QualityReview[/workflow:review<br>--type quality /]
    Q7 -->|General| GeneralReview[/workflow:review<br>General review /]
    Q7 -->|Not needed| Complete

    SecurityReview --> Complete
    ArchReview --> Complete
    QualityReview --> Complete
    GeneralReview --> Complete

    Complete[✅ Completion Phase<br>/workflow:session:complete]
    Complete --> End

    style Start fill:#e1f5ff
    style BugFix fill:#ffccbc
    style LiteFix fill:#ffccbc
    style HotFix fill:#ff8a65
    style BugDiag fill:#ffccbc
    style BugComplete fill:#c8e6c9
    style End fill:#c8e6c9
    style BrainIdea fill:#fff9c4
    style BrainDesign fill:#fff9c4
    style LitePlan fill:#b3e5fc
    style FullPlan fill:#b3e5fc
    style Execute fill:#c5e1a5
    style TDD fill:#ffccbc
    style TestGen fill:#ffccbc
    style TestCycle fill:#ffccbc
    style Review fill:#d1c4e9
    style Complete fill:#c8e6c9

Commands

/ccw-coordinator "task description"
# Auto-analyze → recommend command chain → execute sequentially

Use Cases

• ✅ Complex multi-step workflows
• ✅ Uncertain which commands to use
• ✅ Desire end-to-end automation
• ✅ Need full state tracking and resumability
• ✅ Team collaboration with unified execution flow
• ❌ Simple single-command tasks
• ❌ Already know exact commands needed

Relationship with Other Levels

Level	Manual Degree	CCW Coordinator Role
Level 1-4	Manual command selection	Auto-combine these commands
Level 5	Auto command selection	Intelligent orchestrator

CCW Coordinator uses Level 1-4 internally:

• Analyzes task → Auto-selects appropriate Level
• Assembles command chain → Includes Level 1-4 commands
• Executes sequentially → Follows Minimum Execution Units

---

Issue Workflow

Main Workflow Supplement - Post-development continuous maintenance

Two-Phase Lifecycle

┌─────────────────────────────────────────────────────────────────────┐
│                    Phase 1: Accumulation                            │
│                                                                     │
│   Triggers:                                                         │
│   • Post-task review                                                │
│   • Code review findings                                            │
│   • Test failures                                                   │
│                                                                     │
│   ┌────────────┐     ┌────────────┐     ┌────────────┐             │
│   │ discover   │     │ discover-  │     │    new     │             │
│   │ Auto-find  │     │ by-prompt  │     │  Manual    │             │
│   └────────────┘     └────────────┘     └────────────┘             │
│                                                                     │
│   Continuously accumulate issues to pending queue                   │
└─────────────────────────────────────────────────────────────────────┘
                               │
                               │ After sufficient accumulation
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  Phase 2: Batch Resolution                          │
│                                                                     │
│   ┌────────────┐     ┌────────────┐     ┌────────────┐             │
│   │   plan     │ ──→ │   queue    │ ──→ │  execute   │             │
│   │ --all-     │     │ Optimize   │     │  Parallel  │             │
│   │  pending   │     │  order     │     │ execution  │             │
│   └────────────┘     └────────────┘     └────────────┘             │
│                                                                     │
│   Supports worktree isolation, maintains main branch stability      │
└─────────────────────────────────────────────────────────────────────┘

Command List

Accumulation Phase:

/issue:discover            # Multi-perspective auto-discovery
/issue:discover-by-prompt  # Prompt-based discovery
/issue:new                 # Manual creation

Batch Resolution:

/issue:plan --all-pending  # Batch plan all pending
/issue:queue               # Generate optimized execution queue
/issue:execute             # Parallel execution

Collaboration with Main Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                      Development Iteration Loop                     │
│                                                                     │
│   ┌─────────┐                              ┌─────────┐             │
│   │ Feature │ ──→ Main Workflow ──→ Done ──→│ Review  │             │
│   │ Request │     (Level 1-4)              └────┬────┘             │
│   └─────────┘                                   │                  │
│        ▲                                        │ Issues found      │
│        │                                        ▼                  │
│        │                                  ┌─────────┐              │
│        │                                  │  Issue  │              │
│        │                                  │ Workflow│              │
│   Continue│                               └────┬────┘              │
│   new     │                                    │                   │
│   feature │         ┌──────────────────────────┘                   │
│        │         │ Fix complete                                    │
│        │         ▼                                                 │
│   ┌────┴────┐◀──────                                               │
│   │  Main   │    Merge                                             │
│   │ Branch  │    back                                              │
│   └─────────┘                                                      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

---

Workflow Selection Guide

Quick Selection Table

Scenario	Recommended Workflow	Level
Quick fixes, config adjustments	lite-lite-lite	1
Clear single-module features	lite-plan → lite-execute	2
Bug diagnosis and fix	lite-fix	2
Production emergencies	lite-fix --hotfix	2
Technology selection, solution comparison	multi-cli-plan → lite-execute	2
Multi-module changes, refactoring	plan → verify → execute	3
Test-driven development	tdd-plan → execute → tdd-verify	3
Test failure fixes	test-fix-gen → test-cycle-execute	3
New features, architecture design	brainstorm:auto-parallel → plan → execute	4
Complex multi-step workflows, uncertain commands	ccw-coordinator	5
Post-development issue fixes	Issue Workflow	-

Decision Flowchart

Start
  │
  ├─ Is it post-development maintenance?
  │     ├─ Yes → Issue Workflow
  │     └─ No ↓
  │
  ├─ Uncertain which commands to use?
  │     ├─ Yes → Level 5 (ccw-coordinator - auto-analyze & recommend)
  │     └─ No ↓
  │
  ├─ Are requirements clear?
  │     ├─ Uncertain → Level 4 (brainstorm:auto-parallel)
  │     └─ Clear ↓
  │
  ├─ Need persistent Session?
  │     ├─ Yes → Level 3 (plan / tdd-plan / test-fix-gen)
  │     └─ No ↓
  │
  ├─ Need multi-perspective / solution comparison?
  │     ├─ Yes → Level 2 (multi-cli-plan)
  │     └─ No ↓
  │
  ├─ Is it a bug fix?
  │     ├─ Yes → Level 2 (lite-fix)
  │     └─ No ↓
  │
  ├─ Need planning?
  │     ├─ Yes → Level 2 (lite-plan)
  │     └─ No → Level 1 (lite-lite-lite)

Complexity Indicators

System auto-evaluates complexity based on these keywords:

Weight	Keywords
+2	refactor, migrate, architect, system
+2	multiple, across, all, entire
+1	integrate, api, database
+1	security, performance, scale

• High complexity (≥4): Auto-select Level 3-4
• Medium complexity (2-3): Auto-select Level 2
• Low complexity (<2): Auto-select Level 1

---

Semantic CLI Invocation

Users can semantically specify CLI tools in prompts - the system automatically invokes the corresponding CLI.

Basic Invocation

User Prompt	System Action
"Use Gemini to analyze the auth module"	Auto-invoke gemini CLI for analysis
"Let Codex review this code"	Auto-invoke codex CLI for review
"Ask Qwen about performance optimization"	Auto-invoke qwen CLI for consultation

Multi-CLI Orchestration

Pattern	User Prompt Example
Collaborative	"Use Gemini and Codex to collaboratively analyze security vulnerabilities"
Parallel	"Have Gemini, Codex, and Qwen analyze the architecture in parallel"
Iterative	"Use Gemini to diagnose, then Codex to fix, iterate until resolved"
Pipeline	"Gemini designs the solution, Codex implements, Claude reviews"

Custom CLI Registration

Register any API as a custom CLI via Dashboard interface:

ccw view  # Open Dashboard → Status → API Settings → Add Custom CLI

Field	Example
Name	deepseek
Endpoint	https://api.deepseek.com/v1/chat
API Key	your-api-key

Register once, invoke semantically forever - no code changes needed.

---

ACE Tool Configuration

ACE (Augment Context Engine) provides powerful semantic code search. Two configuration methods available:

Method	Link
Official	Augment MCP Documentation
Proxy	ace-tool (GitHub)

Usage Example

mcp__ace-tool__search_context({
  project_root_path: "/path/to/project",
  query: "authentication logic"
})

---

Summary

Level Overview

Level	Name	Included Workflows	Artifacts	Execution
1	Rapid	lite-lite-lite	None	Direct execute
2	Lightweight	lite-plan, lite-fix, multi-cli-plan	Memory/Lightweight files	→ lite-execute
3	Standard	plan, tdd-plan, test-fix-gen	Session persistence	→ execute / test-cycle-execute
4	Brainstorm	brainstorm:auto-parallel → plan	Multi-role analysis + Session	→ execute
5	Intelligent	ccw-coordinator	Full state persistence	Auto-analyze & recommend
-	Issue	discover → plan → queue → execute	Issue records	Worktree isolation (optional)

Core Principles

1. Main Workflow solves parallelism through dependency analysis + Agent parallel execution, no worktree needed
2. Issue Workflow serves as a supplementary mechanism, supporting worktree isolation to maintain main branch stability
3. Select appropriate workflow level based on task complexity, avoid over-engineering
4. Level 1-4 require manual command selection; Level 5 auto-analyzes and recommends optimal command chains
5. Level 2 workflow selection criteria:
   • Clear requirements → lite-plan
   • Bug fix → lite-fix
   • Need multi-perspective → multi-cli-plan
6. Level 3 workflow selection criteria:
   • Standard development → plan
   • Test-driven → tdd-plan
   • Test fix → test-fix-gen
7. Level 5 usage:
   • Uncertain which commands to use → ccw-coordinator
   • Need end-to-end workflow automation → ccw-coordinator
   • Require complete state tracking and resumability → ccw-coordinator