---

name: creating-sprints description: Guide for creating sprint definitions in SPRINT.yaml. This skill should be used when users want to create sprint, new sprint planning, sprint definition best practices, or define steps for autonomous execution. Triggers on "create sprint", "new sprint", "sprint definition", "define steps".

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 schema
• references/step-writing-guide.md - Writing effective step prompts
• references/workflow-selection.md - Choosing the right workflow

Assets

• assets/sprint-template.yaml - Annotated sprint template

Validation

Before running a sprint:

1. Verify YAML syntax is valid
2. Ensure workflow reference exists
3. Check step count is in 3-8 range
4. Confirm each step is actionable
5. 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