Release 1.1.0 — one config file, and a process weight you choose

`project.yaml` at the repo root is now the single source of truth for a
project's configuration, replacing `production/stage.txt`,
`production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all
three still read as a fallback; nothing is force-deleted).

**`modes.rigor` — one question instead of six.** `minimal`, `standard` or
`full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`,
`modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to
`minimal`, which is a change from 1.0's behaviour: the heavier tier was
measured costing several times more to reach working code without producing a
better result, and returning nothing when a fresh developer inherited the
project. Pin `modes.rigor: standard` to keep 1.0's process level.

Also in this release:

- `/settings` to view or change any setting, and `project.local.yaml` for
  per-developer preferences that should not be committed.
- `system_overrides` to hold one system to a higher standard than the rest of
  the project, and `testing.strict` to set per test type whether missing
  evidence blocks a story or warns.
- A story that changes anything the player sees is not closed until the game
  has been launched, observed, and a screenshot retained in
  `production/qa/evidence/`. A parse check is not a run. This holds at every
  rigor level, including `minimal`, where automated tests are waived but the
  look is not.
- The code root is engine-specific and enforced as such: Godot `src/`, Unity
  `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a
  project laid out any other way.
- Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh`
  converts a 1.0 layout, non-destructively by default, with a report to review
  before `--finalize` deletes anything.
- Ask-before-write holds regardless of personal automation settings.

Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes:
CHANGELOG.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd

.claude/skills/sprint-plan/SKILL.md

@@ -1,47 +1,110 @@
 ---
 name: sprint-plan
-description: "Generates a new sprint plan or updates an existing one based on the current milestone, completed work, and available capacity. Pulls context from production documents and design backlogs."
+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, Task, AskUserQuestion
+allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion
 model: sonnet
-context: |
-  !ls production/sprints/ 2>/dev/null
+---
+
+!`source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh" 2>/dev/null && 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`.
+
+
+## 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`) and resolve the review mode (once, store for all gate spawns this run):
-1. If `--review [full|lean|solo]` was passed → use that
-2. Else read `production/review-mode.txt` → use that value
-3. Else → default to `lean`
+Extract the mode argument (`new`, `update`, or `status`).
 
-See `.claude/docs/director-gates.md` for the full check pattern.
+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`,
+**6–10** at `balanced` (default), **15–25** at `fine`.
 
 **Review mode check** (before gates run):
-- Read `production/review-mode.txt` if it exists. Use that mode.
-- If the file doesn't exist and this is a `new` sprint: use `AskUserQuestion`:
+- The review mode was already resolved in steps 1–4 above — do not re-resolve it.
+- **Special case:** if steps 1–3 all found nothing configured (no `--review`
+  flag, no `modes.review_mode` in `project.yaml`, no `production/review-mode.txt`)
+  **and** this is a `new` sprint, do not silently take the step-4 `lean` default
+  — instead use `AskUserQuestion`:
   - Prompt: "No review mode is set. Which review depth would you like for this sprint?"
   - Options:
     - `[A] full — spawn all director and lead gates`
     - `[B] lean — skip non-phase-gate director reviews (recommended for most sprints)`
     - `[C] solo — skip all gate spawning`
-  - After selection: write `production/review-mode.txt` with the chosen mode. Say: "Review mode set to [mode] and saved to production/review-mode.txt."
-- If the file doesn't exist and this is NOT a `new` sprint (e.g., updating an existing sprint): default to `lean` silently.
+  - After selection: dual-write the chosen mode — set `modes.review_mode` in `project.yaml` (primary; add the `modes:` block if absent) AND write `production/review-mode.txt` (legacy fallback). Say: "Review mode set to [mode] and saved to project.yaml (and production/review-mode.txt)."
+- In every other case the value resolved in steps 1–4 stands (for a non-`new`
+  sprint with nothing configured, that is the `lean` default).
+
+> **Do not write until Phase 1 confirms the sprint can be planned.** This write
+> lands in Phase 0, before the Phase 1 backlog check that aborts the run —
+> observed live: the run correctly BLOCKED on "No stories found under
+> `production/epics/`" and `project.yaml` had *already* gained
+> `review_mode: lean`. A skill that decides it cannot run must not have edited
+> config on the way to deciding. Hold the selection in memory, complete Phase 1,
+> and write only if planning proceeds.
+> **Confirm the destination before writing.** The question above asks for review
+> depth "for this sprint"; the write is permanent project config on a
+> rigor-fronted knob. Ask explicitly: "Set `modes.review_mode: [mode]` in
+> `project.yaml` (persists beyond this sprint), or use it for this sprint only?"
 
 ---
 
 ## Phase 1: Gather Context
 
-1. **Read the current milestone** from `production/milestones/`.
+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.
 
-3. **Scan design documents** in `design/gdd/` for features tagged as ready
-   for implementation.
+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.
 
-4. **Check the risk register** at `production/risk-register/`.
+   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.
+
+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.
 
 ---
 
@@ -49,7 +112,7 @@ See `.claude/docs/director-gates.md` for the full check pattern.
 
 For `new`:
 
-**Generate a sprint plan** following this format and present it to the user. Do NOT ask to write yet — the producer feasibility gate (Phase 4) runs first and may require revisions before the file is written.
+**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]
@@ -153,7 +216,7 @@ After generating a new sprint plan, also prepare the `production/sprint-status.y
 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) may revise the story list. Both files will be written together after Phase 4 in a single write approval.
+**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:
 
@@ -179,7 +242,7 @@ updated: "[YYYY-MM-DD]"
 stories:
   - id: "[epic-story, e.g. 1-1]"
     name: "[story name]"
-    file: "[production/stories/path.md]"
+    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: ""
@@ -205,7 +268,7 @@ stories that haven't changed, add new stories, remove dropped ones.
 - `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 Task using gate **PR-SPRINT** (`.claude/docs/director-gates.md`).
+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.
 
@@ -273,9 +336,9 @@ After the sprint plan is written and QA plan status is resolved:
 - `/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. The review mode is set in Phase 0 when the file does not exist (for `new` sprints), or can be overridden per-run with `--review full|lean|solo` as an argument. The file `production/review-mode.txt` contains one of:
-- `lean` — skip automated director gates (default if file is absent — fastest for solo dev)
+**Review mode configuration:** All director gates (producer feasibility, QA review, code review) respect the project review mode, resolved by the Phase 0 chain (`--review` flag → `modes.review_mode` in `project.yaml` → `production/review-mode.txt` → the `modes.rigor` expansion, which yields `lean` at standard rigor and `solo` at minimal). For a `new` sprint with nothing configured, Phase 0 prompts for it and dual-writes the choice. The mode is one of:
+- `lean` — skip non-phase-gate director gates (default — fastest for solo dev)
 - `full` — run all director gates as spawned sub-agents
-- `solo` — skip all gates unconditionally (single-developer, no review)
+- `solo` — skip all gate spawning unconditionally (single developer, no review)
 
-This file is read by `/sprint-plan`, `/story-readiness`, `/story-done`, and other skills at startup.
+`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.