Sprint Orchestration

Manages development sprints through workflow-based compilation with hierarchical phase execution and fresh-context task processing.

Core Concepts

Concept	Definition
Workflow	Reusable phase template in .claude/workflows/
SPRINT.yaml	Sprint input: workflow reference + collections
PROGRESS.yaml	Compiled execution tree (generated)
Execution Loop	Fresh context per task via claude -p

Sprint Structure

.claude/
  workflows/          # Reusable workflow templates
    sprint-default.yaml
    feature-standard.yaml
  sprints/
    YYYY-MM-DD_name/
      SPRINT.yaml     # Input (workflow reference + collections)
      PROGRESS.yaml   # Compiled (generated by compiler)
      context/
      artifacts/

Workflow Architecture

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  SPRINT.yaml    │     │   Compiler   │     │  PROGRESS.yaml  │
│                 │────▶│              │────▶│                 │
│  - workflow-ref │     │  - Resolves  │     │  - Phases       │
│  - collections  │     │    workflow  │     │    └─ Tasks[]   │
│                 │     │  - Expands   │     │  - Status tree  │
│                 │     │    for-each  │     │                 │
└─────────────────┘     └──────────────┘     └─────────────────┘

Commands

Command	Action
init-sprint <name>	Initialize sprint directory
add-step <prompt>	Add step to SPRINT.yaml
import-steps	Bulk import steps
run-sprint	Compile and execute sprint
sprint-status	Show hierarchical progress
pause-sprint	Pause after current phase
resume-sprint	Resume paused sprint
stop-sprint	Force stop
help	Show plugin help

Compilation Process

Compilation occurs automatically on /run-sprint:

1. Read SPRINT.yaml (workflow reference + collections)
2. Resolve workflow template from .claude/workflows/
3. Expand for-each phases into task hierarchy
4. Generate PROGRESS.yaml with full execution tree

# SPRINT.yaml (input)
workflow: sprint-default
collections:
  step:
    - prompt: implement auth module
    - prompt: add unit tests for auth
    - prompt: update API documentation

# PROGRESS.yaml (compiled output)
status: pending
phases:
  - name: prepare
    status: pending
    tasks: [...]
  - name: development
    status: pending
    tasks:
      - id: task-001
        prompt: implement auth module
        status: pending
      - id: task-002
        prompt: add unit tests for auth
        status: pending
  - name: qa
    status: pending
    tasks: [...]

References

• references/workflow-definitions.md - Workflow template syntax and structure
• references/progress-schema.md - PROGRESS.yaml schema specification
• references/compiler-usage.md - Compiler invocation and options
• references/sprint-setup.md - Directory structure and initialization

Assets

• assets/sprint-template.yaml - SPRINT.yaml template
• assets/progress-template.yaml - PROGRESS.yaml template
• assets/workflow-template.yaml - Workflow definition template

Troubleshooting

Issue	Cause	Resolution
Compilation fails	Invalid workflow	Check references/workflow-definitions.md
Workflow not found	Missing .claude/workflows/	Create directory with workflows
Step not expanding	Missing for-each	Verify phase has for-each: step
Loop exits early	PROGRESS.yaml status	Check status field
Sprint paused unexpectedly	Breakpoint reached	Phase has break: true, use /resume-sprint
Sprint blocked	Gate check failed	Max retries exceeded, fix issues manually
Gate keeps failing	Script returns non-zero	Check gate script, review gate-tracking.last-output