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
text
.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
text
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐ │ 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:
- •Read SPRINT.yaml (workflow reference + collections)
- •Resolve workflow template from
.claude/workflows/ - •Expand for-each phases into task hierarchy
- •Generate PROGRESS.yaml with full execution tree
yaml
# 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 |