Sprint Plan Builder

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,story_granularity,workflow

Resolved above — use as-is; --review overrides review_mode. No block → defaults in .claude/docs/config-resolution.md.

Sprint Plan

Existing Sprints

!ls production/sprints/ 2>/dev/null || echo "(no production/sprints/ directory yet)"

Resolved before this skill runs — use it to identify the previous sprint in Phase 1 rather than re-globbing.

Phase 0: Parse Arguments

Extract the mode argument (new, update, or status).

See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automation_always_ask categories always prompt).

story_granularity — it sets how many stories to allocate per sprint, scaled by velocity: 2–4 at coarse (the default, via rigor: minimal), 6–10 at balanced (rigor: standard), 15–25 at fine. A Ready backlog smaller than the range is planned whole — never padded with invented stories.

Review mode check (before gates run):

• Use the review mode from the resolved block above (--review overrides it for this run) — do not re-resolve it, and do not ask for it. With nothing configured it follows modes.rigor: solo at minimal, lean at standard.
• Never write a review mode — not to project.yaml, not to production/review-mode.txt. modes.review_mode is one of the knobs modes.rigor fronts: pinning it in project.yaml shadows the rigor expansion, and the legacy file sits above that expansion, so either write would freeze director-review depth for good. --review covers a one-off. If the user wants a different depth to persist, point them to changing modes.rigor (/settings modes.rigor=<minimal|standard|full>), or to pinning it on purpose with /settings --local modes.review_mode=<full|lean|solo> (a personal override in project.local.yaml).

Phase 1: Gather Context

1. Read the current milestone from production/milestones/ if it exists. No skill writes this directory — it is authored by hand from .claude/docs/templates/milestone-definition.md. On the majority of projects it is absent, which is the normal state, not a gap: note "no milestone defined — planning against the story backlog alone" and continue. Never block sprint planning on it, and never infer a milestone from the sprint files.

2. Read the previous sprint (if any) from production/sprints/ to understand velocity and carryover. In new mode:

   • The new sprint's number [N] is the highest sprint-NNN.md in the Existing Sprints listing plus one (001 when there is none). It is the [N] in the plan's title, its QA plan path and the write ask.
   • Every story of the previous sprint that is not Complete — by its status in production/sprint-status.yaml, else its story file's Status line — goes in the Carryover table with a Reason and a New Estimate. It appears only there, never again as new Must Have / Should Have / Nice to Have work.

3. Find the stories to plan — this is the actual backlog, and it is the one input this phase cannot do without:

   Glob production/epics/**/story-*.md
   Grep pattern="^> \*\*Status\*\*" glob="production/epics/**/story-*.md" output_mode="content"

   Stories live at production/epics/[epic-slug]/story-NNN-[slug].md — that is where /create-stories writes them and where /dev-story looks for them. Plan from the ones marked Ready. Use the grep rather than reading each story: at this stage you need status and title, not the body.

   If the glob returns nothing: "No stories found under production/epics/. Run /create-stories first (at standard/full, /create-epics before it)." Do not proceed to invent work items — a sprint plan that references stories which do not exist cannot be implemented. Verdict: BLOCKED — no stories to plan.

4. Scan design documents in design/gdd/ for additional context on the features those stories implement. At workflow: minimal there are no per-system GDDs — use design/game-brief.md instead, and do not treat the absent GDDs as missing work. (Note: /sprint-plan is optional at minimal — the brief's Build order already is the plan.)

5. Check the risk register at production/risk-register/ if it exists. Like the milestone above, no skill writes it — entries are authored by hand from .claude/docs/templates/risk-register-entry.md. If the directory is absent, say so once ("no risk register — risks assessed from the sprint contents only") rather than skipping risk assessment silently.

Phase 2: Generate Output

For new:

Generate a sprint plan following this format and present it to the user. Do NOT ask to write yet — the gate phases run first and may require revisions before the file is written: the producer feasibility gate (Phase 4, spawned only in full review mode — skipped in lean/solo) and the QA plan check (Phase 5, all modes).

# Sprint [N] — [Start Date] to [End Date]

## Sprint Goal
[One sentence describing what this sprint achieves toward the milestone]

## Capacity
- Total days: [X]
- Buffer (20%): [Y days reserved for unplanned work]
- Available: [Z days]

## Tasks

### Must Have (Critical Path)
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
|----|------|-------------|-----------|-------------|-------------------|

### Should Have
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
|----|------|-------------|-----------|-------------|-------------------|

### Nice to Have
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria |
|----|------|-------------|-----------|-------------|-------------------|

## Carryover from Previous Sprint
| Task | Reason | New Estimate |
|------|--------|-------------|

## Risks
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|

## Dependencies on External Factors
- [List any external dependencies]

## Definition of Done for this Sprint
- [ ] All Must Have tasks completed
- [ ] All tasks pass acceptance criteria
- [ ] QA plan exists (`production/qa/qa-plan-[sprint-slug]-[date].md`, from `/qa-plan sprint`)
- [ ] All Logic/Integration stories have passing unit/integration tests
- [ ] Smoke check passed (`/smoke-check sprint`)
- [ ] QA sign-off report: APPROVED or APPROVED WITH CONDITIONS (`/team-qa sprint`)
- [ ] No S1 or S2 bugs in delivered features
- [ ] Design documents updated for any deviations
- [ ] Code reviewed and merged

For update:

Update an existing sprint plan:

1. Read the most recent sprint plan from production/sprints/.
2. Present the current story list with their current statuses from production/sprint-status.yaml.
3. Ask the user what to change: stories to add, remove, reprioritize, or re-estimate. Use AskUserQuestion to gather changes.
4. Apply the changes and re-present the full revised plan for review.
5. Re-run the producer feasibility gate (Phase 4) on the revised plan.
6. Write the updated markdown plan and yaml together (same approval as new mode).

Note: update mode does not reset story statuses. Stories already marked in-progress or done keep their status. Only backlog and ready-for-dev stories can be removed or reprioritized freely.

For status:

Generate a status report:

# Sprint [N] Status -- [Date]

## Progress: [X/Y tasks complete] ([Z%])

### Completed
| Task | Completed By | Notes |
|------|-------------|-------|

### In Progress
| Task | Owner | % Done | Blockers |
|------|-------|--------|----------|

### Not Started
| Task | Owner | At Risk? | Notes |
|------|-------|----------|-------|

### Blocked
| Task | Blocker | Owner of Blocker | ETA |
|------|---------|-----------------|-----|

## Burndown Assessment
[On track / Behind / Ahead]
[If behind: What is being cut or deferred]

## Emerging Risks
- [Any new risks identified this sprint]

Phase 3: Prepare Sprint Status File

After generating a new sprint plan, also prepare the production/sprint-status.yaml content. This is the machine-readable source of truth for story status — read by /sprint-status, /story-done, and /help without markdown parsing.

Do not write the yaml yet — hold it in context. The producer feasibility gate (Phase 4, full review mode only) may revise the story list; the QA plan check (Phase 5) runs in every mode. Both files are written together after Phase 5 in a single write approval.

Format:

# Auto-generated by /sprint-plan. Updated by /story-done and /dev-story.
# DO NOT edit manually — use /story-done to update story status.
#
# Status value mapping (yaml ↔ story file Status field):
#   backlog        ↔  Not Started
#   ready-for-dev  ↔  Ready
#   in-progress    ↔  In Progress
#   review         ↔  In Review
#   done           ↔  Complete
#   blocked        ↔  Blocked

sprint: [N]
goal: "[sprint goal]"
start: "[YYYY-MM-DD]"
end: "[YYYY-MM-DD]"
generated: "[YYYY-MM-DD]"
updated: "[YYYY-MM-DD]"

stories:
  - id: "[epic-story, e.g. 1-1]"
    name: "[story name]"
    file: "[production/epics/[epic-slug]/story-NNN-[slug].md]"   # the real path, verbatim from the Glob above
    priority: must-have        # must-have | should-have | nice-to-have
    status: ready-for-dev      # backlog | ready-for-dev | in-progress | review | done | blocked
    owner: ""
    estimate_days: 0
    blocker: ""
    completed: ""

Initialize each story from the sprint plan's task tables:

• Must Have tasks → priority: must-have, status: ready-for-dev
• Should Have tasks → priority: should-have, status: backlog
• Nice to Have tasks → priority: nice-to-have, status: backlog
• Carryover rows → the story's previous priority, and the status it has now

For update: read the existing sprint-status.yaml, carry over statuses for stories that haven't changed, add new stories, remove dropped ones.