Claude-Code-Workflow/docs/workflows/4-level.md

4-Level Workflow System

The CCW 4-level workflow system provides a structured approach to software development from specification to deployment.

Overview

Level 1: SPECIFICATION → Level 2: PLANNING → Level 3: IMPLEMENTATION → Level 4: VALIDATION

Level 1: Specification

Goal: Define what to build and why.

Activities

Activity	Description	Output
Research	Analyze requirements and context	Discovery context
Product Brief	Define product vision	Product brief
Requirements	Create PRD with acceptance criteria	Requirements document
Architecture	Design system architecture	Architecture document
Epics & Stories	Break down into trackable items	Epics and stories

Agents

• analyst: Conducts research and analysis
• writer: Creates specification documents
• discuss-subagent: Multi-perspective critique

Quality Gate

QUALITY-001 validates:

• All requirements documented
• Architecture approved
• Risks assessed
• Acceptance criteria defined

Example Tasks

RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001

Level 2: Planning

Goal: Define how to build it.

Activities

Activity	Description	Output
Exploration	Multi-angle codebase analysis	Exploration cache
Task Breakdown	Create implementation tasks	Task definitions
Dependency Mapping	Identify task dependencies	Dependency graph
Resource Estimation	Estimate effort and complexity	Plan metadata

Agents

• planner: Creates implementation plan
• architect: Provides technical consultation (on-demand)
• explore-subagent: Codebase exploration

Output

{
  "epic_count": 5,
  "total_tasks": 27,
  "execution_order": [...],
  "tech_stack": {...}
}

Level 3: Implementation

Goal: Build the solution.

Activities

Activity	Description	Output
Code Generation	Write source code	Source files
Unit Testing	Create unit tests	Test files
Documentation	Document code and APIs	Documentation
Self-Validation	Verify implementation quality	Validation report

Agents

• executor: Coordinates implementation
• code-developer: Simple, direct edits
• ccw cli: Complex, multi-file changes

Execution Strategy

Tasks executed in topological order based on dependencies:

TASK-001 (no deps) → TASK-002 (depends on 001) → TASK-003 (depends on 002)

Backends

Backend	Use Case
agent	Simple, direct edits
codex	Complex, architecture
gemini	Analysis-heavy

Level 4: Validation

Goal: Ensure quality.

Activities

Activity	Description	Output
Integration Testing	Verify component integration	Test results
QA Testing	User acceptance testing	QA report
Performance Testing	Measure performance	Performance metrics
Security Review	Security vulnerability scan	Security findings
Code Review	Final quality check	Review feedback

Agents

• tester: Executes test-fix cycles
• reviewer: 4-dimension code review

Review Dimensions

Dimension	Focus
Product	Requirements alignment
Technical	Code quality, patterns
Quality	Testing, edge cases
Coverage	Completeness
Risk	Security, performance

Workflow Orchestration

Beat Model

Event-driven execution with coordinator orchestration:

Event           Coordinator              Workers
────────────────────────────────────────────────
callback/resume → handleCallback ─────────────────┐
                 → mark completed                 │
                 → check pipeline                │
                 → handleSpawnNext ──────────────┼───→ [Worker A]
                 → find ready tasks              │
                 → spawn workers ─────────────────┼───→ [Worker B]
                 → STOP (idle) ──────────────────┘      │
                                                        │
callback <──────────────────────────────────────────────┘

Checkpoints

Spec Checkpoint (after QUALITY-001):

• Pauses for user confirmation
• Validates specification completeness
• Requires manual resume to proceed

Final Gate (after REVIEW-001):

• Final quality validation
• All tests must pass
• Critical issues resolved

Fast-Advance

For simple linear successions, workers can spawn successors directly:

[Worker A] complete
    → Check: 1 ready task? simple successor?
    → YES: Spawn Worker B directly
    → NO: SendMessage to coordinator

Parallel Execution

Some epics can execute in parallel:

EPIC-003: Content Modules ──┐
                           ├──→ EPIC-005: Interaction Features
EPIC-004: Search & Nav ────┘

Error Handling

Scenario	Resolution
Syntax errors	Retry with error context (max 3)
Missing dependencies	Request from coordinator
Backend unavailable	Fallback to alternative
Circular dependencies	Abort, report graph

::: info See Also

• Best Practices - Workflow optimization
• Agents - Agent specialization :::