Claude-Code-Workflow/docs/guide/workflows.md

CCW Workflows

Understanding and using CCW's workflow system for efficient development.

What are Workflows?

CCW workflows are orchestrated sequences of tasks that guide a project from initial concept to completed implementation. They ensure consistency, quality, and proper documentation throughout the development lifecycle.

Workflow Levels

CCW uses a 4-level workflow system:

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

Using Workflows

Starting a Workflow

Begin a new workflow with the team-lifecycle-v4 skill:

Skill(skill="team-lifecycle-v4", args="Build user authentication system")

This creates a complete workflow:

1. Specification phase (RESEARCH-001 through QUALITY-001)
2. Planning phase (PLAN-001)
3. Implementation phase (IMPL-001)
4. Validation phase (TEST-001 and REVIEW-001)

Workflow Execution

The workflow executes automatically:

1. Specification: Analyst and writer agents research and document requirements
2. Checkpoint: User reviews and approves specification
3. Planning: Planner creates implementation plan with task breakdown
4. Implementation: Executor writes code
5. Validation: Tester and reviewer validate quality

Resume Workflow

After a checkpoint, resume the workflow:

ccw workflow resume

Workflow Tasks

Specification Tasks

Task	Agent	Output
RESEARCH-001	analyst	Discovery context
DRAFT-001	writer	Product brief
DRAFT-002	writer	Requirements (PRD)
DRAFT-003	writer	Architecture design
DRAFT-004	writer	Epics & stories
QUALITY-001	reviewer	Readiness report

Implementation Tasks

Task	Agent	Output
PLAN-001	planner	Implementation plan
IMPL-001	executor	Source code
TEST-001	tester	Test results
REVIEW-001	reviewer	Code review

Custom Workflows

Create custom workflows for your team:

# .ccw/workflows/feature-development.yaml
name: Feature Development
description: Standard workflow for new features

levels:
  - name: specification
    tasks:
      - type: research
        agent: analyst
      - type: document
        agent: writer
        documents: [prd, architecture]

  - name: planning
    tasks:
      - type: plan
        agent: planner

  - name: implementation
    tasks:
      - type: implement
        agent: executor
      - type: test
        agent: tester

  - name: validation
    tasks:
      - type: review
        agent: reviewer

checkpoints:
  - after: specification
    action: await_user_approval
  - after: validation
    action: verify_quality_gates

Workflow Configuration

Configure workflow behavior in ~/.claude/workflows/config.json:

{
  "defaults": {
    "autoAdvance": true,
    "checkpoints": ["specification", "implementation"],
    "parallel": true
  },
  "agents": {
    "analyst": {
      "timeout": 300000,
      "retries": 3
    }
  }
}

Best Practices

1. Clear Requirements

Start with clear, specific requirements:

// Good: Specific
Skill(skill="team-lifecycle-v4", args="Build JWT authentication with refresh tokens")

// Bad: Vague
Skill(skill="team-lifecycle-v4", args="Add auth")

2. Checkpoint Reviews

Always review checkpoints:

• Specification checkpoint: Validate requirements
• Implementation checkpoint: Verify progress

3. Feedback Loops

Provide feedback during workflow:

# Add feedback during review
ccw workflow feedback --task REVIEW-001 --message "Tests need more edge cases"

4. Monitor Progress

Track workflow status:

# Check workflow status
ccw workflow status

# View task details
ccw workflow task IMPL-001

Troubleshooting

Stalled Workflow

If a workflow stalls:

# Check for blocked tasks
ccw workflow status --blocked

# Reset stuck tasks
ccw workflow reset --task IMPL-001

Failed Tasks

Retry failed tasks:

# Retry with new prompt
ccw workflow retry --task IMPL-001 --prompt "Fix the TypeScript errors"

::: info See Also

• 4-Level System - Detailed workflow explanation
• Best Practices - Workflow optimization :::