Skip to main content

Workflow FAQ

Common questions and answers about CCW workflows.

General Questions​

What is the difference between Main Workflow and Issue Workflow?​

Main Workflow is for primary development (Levels 1-5), while Issue Workflow is for post-development maintenance.

AspectMain WorkflowIssue Workflow
PurposeFeature developmentPost-development fixes
TimingDevelopment phaseAfter main workflow completes
ParallelismDependency analysisWorktree isolation (optional)

How do I choose the right workflow level?​

What are Minimum Execution Units?​

Minimum Execution Units are sets of commands that must execute together as atomic groups. Splitting these commands breaks logical flow and creates incomplete states.

Example: The unit lite-plan -> lite-execute must complete together. Stopping after lite-plan leaves you with a plan but no implementation.

Level 1 Questions​

When should I use Level 1?​

Use Level 1 (lite-lite-lite) when:

  • Quick fixes (typos, minor adjustments)
  • Simple features (single function, small utility)
  • Config changes (environment variables, timeout values)
  • Documentation updates (readme, comments)

Don't use when:

  • Multi-module changes
  • Need persistent records
  • Complex refactoring
  • Test-driven development

Level 2 Questions​

What's the difference between lite-plan, lite-fix, and multi-cli-plan?​

WorkflowPurposeWhen to Use
lite-planClear requirementsSingle-module features
lite-fixBug diagnosisBug fixes, production issues
multi-cli-planMulti-perspective analysisTechnology selection, solution comparison

What is hotfix mode?​

/workflow:lite-fix --hotfix "Production database connection failing"

Hotfix mode:

  • Skips most diagnosis phases
  • Minimal planning (direct execution)
  • Auto-generates follow-up tasks for complete fix + post-mortem
  • Use for production emergencies only

When should I use multi-cli-plan vs lite-plan?​

Use multi-cli-plan when:

  • Need multiple perspectives (Gemini, Codex, Claude)
  • Technology selection decisions
  • Solution comparison
  • Architecture trade-offs

Use lite-plan when:

  • Requirements are clear
  • Single-perspective sufficient
  • Faster iteration needed

Level 3 Questions​

What is the difference between plan, tdd-plan, and test-fix-gen?​

WorkflowPurposeKey Feature
planStandard development5-phase planning with verification
tdd-planTest-driven developmentRed-Green-Refactor cycles
test-fix-genTest fixesProgressive test layers (L0-L3)

What is TDD (Test-Driven Development)?​

TDD follows the Red-Green-Refactor cycle:

  1. Red: Write a failing test
  2. Green: Write minimal code to pass the test
  3. Refactor: Improve code while keeping tests green

The Iron Law:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Why does TDD require tests to be written first?​

AspectTest-FirstTest-After
ProofTests fail before implementationTests pass immediately (proves nothing)
DiscoveryEdge cases found before codingEdge cases found after coding
VerificationVerifies requirementsVerifies implementation

What are the test layers in test-fix-gen?​

LayerTypeDescription
L0StaticType checking, linting
L1UnitFunction-level tests
L2IntegrationComponent interaction
L3E2EFull system tests

Level 4 Questions​

When should I use brainstorm:auto-parallel?​

Use Level 4 (brainstorm:auto-parallel) when:

  • New feature design
  • System architecture refactoring
  • Exploratory requirements
  • Uncertain implementation approach
  • Multi-dimensional trade-offs needed

What roles are available in brainstorm?​

RoleDescription
system-architectSystem design
ui-designerUI design
ux-expertUser experience
product-managerProduct requirements
product-ownerBusiness value
data-architectData structure
scrum-masterProcess and team
subject-matter-expertDomain expertise
test-strategistTesting strategy

What are With-File workflows?​

With-File workflows provide documented exploration with multi-CLI collaboration:

WorkflowPurposeLevel
brainstorm-with-fileMulti-perspective ideation4
debug-with-fileHypothesis-driven debugging3
analyze-with-fileCollaborative analysis3

Level 5 Questions​

When should I use ccw-coordinator?​

Use Level 5 (ccw-coordinator) when:

  • 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

How does ccw-coordinator differ from other levels?​

AspectLevel 1-4Level 5
Command SelectionManualAuto
OrchestrationManualIntelligent
State TrackingVariesFull persistence

Execution Questions​

What is lite-execute?​

lite-execute is the unified execution command for Level 2 workflows:

/workflow:lite-execute --in-memory

Features:

  • Parallel execution for independent tasks
  • Sequential phases for dependent tasks
  • Progress tracking via TodoWrite
  • Optional code review

What is execute?​

execute is the unified execution command for Level 3 workflows:

/workflow:execute --session WFS-{session-id}

Features:

  • Dependency analysis
  • Parallel/sequential task execution
  • Session-based progress tracking
  • Task completion summaries

Session Questions​

How do I resume a paused session?​

/workflow:session:resume  # Resume most recent session
/workflow:session:resume WFS-{session-id}  # Resume specific session

How do I complete a session?​

/workflow:session:complete --session WFS-{session-id}

This archives the session with lessons learned and updates the manifest.

How do I list all sessions?​

/workflow:session:list

Artifact Questions​

Where are workflow artifacts stored?​

LevelArtifact Location
Level 1None (stateless)
Level 2memory://plan or .workflow/.lite-fix/, .workflow/.multi-cli-plan/
Level 3.workflow/active/WFS-{session}/
Level 4.workflow/active/WFS-{session}/.brainstorming/
Level 5.workflow/.ccw-coordinator/{session}/

What files are in a session?​

.workflow/active/WFS-{session}/
├── workflow-session.json          # Session metadata
├── IMPL_PLAN.md                   # Implementation plan
├── TODO_LIST.md                   # Progress tracking
├── .task/
│   ├── IMPL-001.json              # Task definitions
│   ├── IMPL-002.json
│   └── ...
└── .process/
    ├── context-package.json       # Project context
    └── planning-notes.md

Testing Questions​

How do I add tests to existing code?​

# Session Mode (from existing session)
/workflow:test-fix-gen WFS-user-auth-v2

# Prompt Mode (direct description)
/workflow:test-fix-gen "Add unit tests for the auth API"

How do I fix failing tests?​

/workflow:test-fix-gen "Tests failing for user registration"
/workflow:test-cycle-execute

The workflow will:

  1. Analyze test failures
  2. Identify root causes
  3. Fix issues iteratively
  4. Verify >= 95% pass rate

Troubleshooting​

My workflow failed. What should I do?​

  1. Check the error message - Identify the root cause
  2. Review state.json - Check .workflow/.ccw-coordinator/{session}/state.json
  3. Resume the session - Use /workflow:session:resume to continue
  4. Adjust and retry - Modify approach based on error

How do I skip a failing task?​

Edit the task JSON to set status to "completed":

jq '.status = "completed"' .workflow/active/WFS-{session}/.task/IMPL-001.json

How do I clean up old sessions?​

# List sessions
/workflow:session:list

# Remove specific session
rm -rf .workflow/active/WFS-{session-id}

# Clean all completed sessions
/workflow:clean

Best Practices​

What are the workflow best practices?​

  1. Start simple - Use the lowest level that meets your needs
  2. Plan before executing - Use verification steps when available
  3. Test continuously - Integrate testing into your workflow
  4. Review code - Use built-in review workflows
  5. Document decisions - Use brainstorm workflows for complex decisions

When should I use worktree isolation?​

Worktree isolation is primarily for Issue Workflow:

  • After main development is complete
  • Merged to main branch
  • Issues discovered requiring fixes
  • Need to fix without affecting current development

Main Workflow doesn't need worktree because:

  • Dependency analysis solves parallelism
  • Agents execute independent tasks in parallel
  • No filesystem isolation needed