| name | sprint-planner |
| version | 1.0.0 |
| description | Converts a backlog into realistic solo-dev sprints accounting for day job + family + surprise maintenance -- with velocity tracking, launch countdown, and honest capacity math. |
sprint-planner
When to use
- Starting the build phase and need to break work into manageable chunks.
- After locking scope (mvp-scope-guardian) to plan the execution order.
- Weekly sprint check-ins to update progress and plan the next sprint.
- Checking if you're on track for a launch date.
When NOT to use
- For generating actual task code (this plans the work, doesn't do it).
- For project-level planning beyond sprints (use mvp-scope-guardian for scope).
- If the project has no defined work items yet.
Prerequisites
- Project must be onboarded in solo-dev-suite.
available_hours_per_week should be set honestly in the profile.- Ideally, scope is locked first so you know what needs building.
Methodology
Honest capacity, not aspirational capacity
The buffer_percent (default 20%) accounts for real life: day job emergencies, family commitments, infra fires, meetings that should have been emails. If you set it to 0%, you're lying to yourself.
Effective hours = hours_per_week x sprint_length_weeks x (1 - buffer_percent/100)
Velocity is earned, not estimated
Until you complete a sprint, you have zero velocity data. The tool tracks actual hours completed per sprint and averages them. Your first sprint estimate will be wrong -- that's the point. By sprint 3, you'll have honest numbers.
Launch countdown: red/yellow/green
If launch_target_date is set in the profile, the tool compares remaining backlog hours against remaining sprint capacity:
- Green: remaining work <= 80% of available capacity (comfortable buffer)
- Yellow: remaining work <= 100% of available capacity (tight but possible)
- Red: remaining work > available capacity (something has to give)
Incomplete items return to backlog
When you complete a sprint, any todo/in-progress items automatically return to the backlog with priority bumped to "high" (you committed to them once -- they matter). Dropped items stay in the sprint record for the retro.
Operations
init
Set up capacity and optional initial backlog.
echo '{"hours_per_week": 10, "sprint_length_weeks": 2, "buffer_percent": 20, "backlog": [{"title": "User auth", "estimate_hours": 12, "priority": "critical", "category": "feature"}, {"title": "API endpoints", "estimate_hours": 8, "priority": "high"}]}' | python scripts/sprint_tool.py init <slug> --from-stdin
hours_per_week defaults to profile's available_hours_per_week if omitted.
add
Add items to the backlog.
echo '{"items": [{"title": "Payment webhook handler", "estimate_hours": 6, "priority": "high", "category": "feature"}]}' | python scripts/sprint_tool.py add <slug> --from-stdin
Single item shorthand (no items wrapper) also works.
plan
Plan the next sprint by pulling items from the backlog.
echo '{"goal": "Core auth + API scaffold", "backlog_ids": ["BL01", "BL02"]}' | python scripts/sprint_tool.py plan <slug> --from-stdin
Warns if planned hours exceed 120% of sprint capacity. Won't plan if there's an active sprint.
start
Activate the next planned sprint.
python scripts/sprint_tool.py start <slug>
update
Update item statuses and actual hours in the active sprint.
echo '{"items": [{"id": "SI01", "status": "done", "actual_hours": 10}, {"id": "SI02", "status": "in-progress"}]}' | python scripts/sprint_tool.py update <slug> --from-stdin
complete
Complete the active sprint. Computes velocity, returns incomplete items to backlog.
python scripts/sprint_tool.py complete <slug> --retro "Auth took longer than expected, need to buffer more for OAuth flows"
show
Display current state: capacity, velocity, launch countdown, active sprint, backlog.
python scripts/sprint_tool.py show <slug>
python scripts/sprint_tool.py show <slug> --json
render
Generate SPRINT_PLAN.md.
python scripts/sprint_tool.py render <slug>
delete
Remove sidecar.
python scripts/sprint_tool.py delete <slug> --yes
Files
| File | Purpose |
|---|
scripts/sprint_tool.py | CLI with all subcommands |
templates/sprint.schema.json | Sidecar JSON Schema |
templates/SPRINT_PLAN.md.tmpl | Rendered doc template |
