Creating Sprints
Guide for authoring SPRINT.yaml definitions for autonomous execution.
What is a Sprint?
| Concept | Description |
|---|---|
| Sprint | YAML file defining collections and workflow reference |
| Collection | Named group of items (e.g., step, feature, bug) |
| Item | Individual task with prompt description |
| Workflow | Execution phases applied to collection items |
| PROGRESS.yaml | Compiled sprint with expanded phases |
Sprint Location
.claude/sprints/
├── 2024-01-15_feature-auth/
│ ├── SPRINT.yaml # Sprint definition (you create)
│ └── PROGRESS.yaml # Compiled progress (generated)
└── 2024-01-20_bugfix-login/
├── SPRINT.yaml
└── PROGRESS.yaml
Quick Start
1. Create Sprint Directory
mkdir -p .claude/sprints/$(date +%Y-%m-%d)_my-sprint
2. Create SPRINT.yaml
# .claude/sprints/YYYY-MM-DD_name/SPRINT.yaml
name: My Sprint
workflow: sprint-default
collections:
step:
- prompt: Implement user authentication
- prompt: Add login form validation
- prompt: Create session management
3. Compile and Run
/run-sprint
Sprint Sizing Guidelines
Sprints should have 3-8 steps with a single focused purpose.
| Guideline | Recommendation |
|---|---|
| Step count | 3-8 steps per sprint |
| Focus | Single responsibility or goal |
| Duration | Complete in one session |
| Granularity | Each step = 1 atomic task |
Why 3-8 Steps?
- < 3 steps: Too small, use direct commands instead
- 3-8 steps: Optimal range for autonomous execution
- > 8 steps: Break into multiple sprints or add sub-steps
Single Responsibility
Each sprint should have one focused goal:
| Good | Bad |
|---|---|
| "Implement authentication" | "Implement auth and add logging and fix bugs" |
| "Add API endpoints for users" | "Add API endpoints and refactor database" |
| "Create dashboard UI" | "Create dashboard and optimize backend" |
Step Writing Principles
Good steps are:
- Clear: Unambiguous intent
- Actionable: Concrete deliverable
- Scoped: Bounded in scope
See references/step-writing-guide.md for detailed guidance.
Workflow Selection
| Workflow | Best For | Step Count |
|---|---|---|
sprint-default | Multi-step features | 5-8 |
gherkin-verified-execution | Complex autonomous work | 5-10 |
execute-with-qa | Steps needing verification | 3-6 |
flat-foreach | Simple step iteration | 3-5 |
See references/workflow-selection.md for workflow decision tree.
SPRINT.yaml Fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Human-readable sprint name |
workflow | string | Yes | Workflow reference |
collections | object | Yes | Named collections of items (e.g., step, feature, bug) |
sprint-id | string | No | Unique identifier (auto-generated) |
config | object | No | Sprint configuration |
See references/sprint-schema.md for complete schema.
Item Formats
Items in a collection can be defined as simple prompts or objects with metadata.
Simple Prompt Items
collections:
step:
- prompt: Implement user login endpoint
- prompt: Add JWT token validation
- prompt: Create logout functionality
Items with Metadata
collections:
step:
- prompt: Implement user login endpoint
tags: [auth, api]
- prompt: Add JWT token validation
tags: [auth, security]
- prompt: Create logout functionality
tags: [auth, api]
Example Sprints
Feature Sprint
name: User Authentication Feature
workflow: sprint-default
collections:
step:
- prompt: Create User model with password hashing
- prompt: Implement /auth/register endpoint
- prompt: Implement /auth/login endpoint with JWT
- prompt: Add authentication middleware
- prompt: Create /auth/me endpoint for user profile
Bug Fix Sprint
name: Fix Login Validation
workflow: execute-with-qa
collections:
step:
- prompt: Investigate login validation bug
- prompt: Fix email format validation
- prompt: Add comprehensive test cases
Refactoring Sprint
name: API Response Standardization
workflow: gherkin-verified-execution
collections:
step:
- prompt: Define standard response envelope
- prompt: Refactor user endpoints to use envelope
- prompt: Refactor product endpoints to use envelope
- prompt: Update API documentation
References
references/sprint-schema.md- Complete SPRINT.yaml schemareferences/step-writing-guide.md- Writing effective step promptsreferences/workflow-selection.md- Choosing the right workflow
Assets
assets/sprint-template.yaml- Annotated sprint template
Validation
Before running a sprint:
- Verify YAML syntax is valid
- Ensure workflow reference exists
- Check step count is in 3-8 range
- Confirm each step is actionable
- Verify sprint has single focus
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
| Workflow not found | Invalid workflow reference | Check .claude/workflows/ for available workflows |
| Items not executing | Missing collections | Add collections: with named collection |
| Sprint too long | Too many steps | Break into multiple focused sprints |
| Unclear progress | Steps too vague | Rewrite steps with clear deliverables |
Related
- creating-workflows - Authoring workflow definitions
- orchestrating-sprints - Running and managing sprints
- sprint-creator subagent (
.claude/agents/sprint-creator.md) - Automated sprint creation from plan documents