--- name: sprint-plan description: "New or updated sprint plan from the current milestone, completed work, and available capacity." argument-hint: "[new|update|status] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/sprint-plan/../../hooks/yaml-helper.sh" resolve_config *) model: sonnet --- !`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=`), or to pinning it on purpose with `/settings --local modes.review_mode=` (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). ```markdown # 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**: ```markdown # 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: ```yaml # 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. --- ## Phase 4: Producer Feasibility Gate **Review mode check** — apply before spawning PR-SPRINT: - `solo` → skip. Note: "PR-SPRINT skipped — Solo mode." Proceed to Phase 5 (QA plan gate). - `lean` → skip (not a PHASE-GATE). Note: "PR-SPRINT skipped — Lean mode." Proceed to Phase 5 (QA plan gate). - `full` → spawn as normal. Before finalising the sprint plan, spawn `producer` via `Agent` using gate **PR-SPRINT** (`.claude/docs/director-gates/pr-sprint.md`). Pass: proposed story list (titles, estimates, dependencies), total team capacity in hours/days, any carryover from the previous sprint, milestone constraints and deadline. Present the producer's assessment. If UNREALISTIC: revise the story selection (defer stories to Should Have or Nice to Have) and re-present the updated plan, then continue to Phase 5. If NOT ASSESSED: name the missing input — it is not REALISTIC. Supply it and re-run PR-SPRINT, or record `NOT ASSESSED — [missing input]` for PR-SPRINT in the plan's header (`.claude/docs/director-gates.md`) and continue to Phase 5, repeating it at the write ask. If CONCERNS, use `AskUserQuestion`: - Prompt: "Producer flagged concerns with this sprint plan. How do you want to proceed?" - Options: - `[A] Proceed as planned — I accept the risk` - `[B] Adjust scope — defer some Should Have stories` - `[C] Extend the sprint timeline` If [A]: continue to Phase 5. If [B]: revise the story list, re-present the updated plan, then continue to Phase 5. If [C]: adjust sprint dates and capacity, re-present the updated plan, then continue to Phase 5. After handling the producer's verdict, continue to Phase 5. The write comes at its end, so the file you approve already holds everything Phase 5 adds. --- ## Phase 5: QA Plan Gate Before closing the sprint plan, check whether a QA plan exists for this sprint. Use `Glob` for `production/qa/qa-plan-*.md` — `/qa-plan` writes `qa-plan-[sprint-slug]-[date].md` — and keep a file whose name or content references this sprint number. **If a QA plan is found**: note it in the sprint plan output — "QA Plan: `[path]`" — and proceed. **If no QA plan exists**: do not silently proceed. Surface this explicitly: > "This sprint has no QA plan. A sprint plan without a QA plan means test requirements are undefined — developers won't know what 'done' looks like from a QA perspective, and the sprint cannot pass the Production → Polish gate without one. > > Run `/qa-plan sprint` now, before starting any implementation. It takes one session and produces the test case requirements each story needs." Use `AskUserQuestion`: - Prompt: "No QA plan found for this sprint. How do you want to proceed?" - Options: - `[A] Run /qa-plan sprint now — I'll do that before starting implementation (Recommended)` - `[B] Skip for now — I understand QA sign-off will be blocked at the Production → Polish gate` Wait for this answer before the write ask below — the two are separate questions. If [A]: note in the plan "QA plan: run `/qa-plan sprint` before implementation begins." If [B]: add a warning block to the sprint plan document: ```markdown > ⚠️ **No QA Plan**: This sprint was started without a QA plan. Run `/qa-plan sprint` > before the last story is implemented. The Production → Polish gate requires a QA > sign-off report, which requires a QA plan. ``` ### Write the plan Ask: "May I write the sprint plan to `production/sprints/sprint-NNN.md` (`[N]` zero-padded to three digits) and `production/sprint-status.yaml`?" If yes, write both files (creating directories as needed). Verdict: **COMPLETE** — sprint plan and status file created. If no: Verdict: **BLOCKED** — user declined write. After writing, add: > **Scope check:** If this sprint includes stories added beyond the original epic scope, run `/scope-check [epic]` to detect scope creep before implementation begins. If the user chose `Run /qa-plan sprint now` in Phase 5, close with "Sprint plan written. Run `/qa-plan sprint` next — then begin implementation." --- ## Phase 6: Next Steps After the sprint plan is written and QA plan status is resolved: - `/qa-plan sprint` — **required before implementation begins** — defines test cases per story so developers implement against QA specs, not a blank slate - `/story-readiness [story-file]` — validate a story is ready before starting it - `/dev-story [story-file]` — begin implementing the first story - `/sprint-status` — check progress mid-sprint - `/scope-check [epic]` — verify no scope creep before implementation begins **Review mode configuration:** All director gates (producer feasibility, QA review, code review) respect the project review mode, resolved in the block at the top of this skill (`--review` flag → `project.local.yaml` → `modes.review_mode` in `project.yaml` → `production/review-mode.txt` → the `modes.rigor` expansion, which yields `lean` at standard rigor and `solo` at minimal). This skill never asks for it or writes it; Phase 0 says where to point a user who wants a different depth. The mode is one of: - `lean` — skip non-phase-gate director gates (the `rigor: standard` value) - `full` — run all director gates as spawned sub-agents - `solo` — skip all gate spawning unconditionally (single developer, no review) `modes.review_mode` in `project.yaml` is the primary source; `production/review-mode.txt` is the legacy fallback. Both are read by `/sprint-plan`, `/story-readiness`, `/story-done`, and other gate-using skills at startup.