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/team-level/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: team-level
-description: "Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation."
+description: "Orchestrate the level team — level-designer, narrative-director, world-builder, art-director, systems-designer, qa-tester — for complete area creation."
 argument-hint: "[level name or area to design] [--review full|lean|solo]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion, TaskCreate, TaskGet, TaskList, TaskUpdate
 model: sonnet
 ---
 
@@ -12,20 +12,58 @@ When this skill is invoked:
 **Decision Points:** At each step transition, use `AskUserQuestion` to present
 the user with the subagent's proposals as selectable options. Write the agent's
 full analysis in conversation, then capture the decision with concise labels.
-The user must approve before moving to the next step.
+In `collaborative` mode, the user must approve before moving to the next step.
+In `guided` mode the pipeline advances automatically unless a step is BLOCKED;
+in `autonomous` mode it runs end to end, recording each step outcome via
+`log_decision`. Decisions in `automation_always_ask` categories
+(`is_always_ask_category` helper) always prompt regardless of mode. See
+`.claude/docs/automation-modes.md`.
 
-## Phase 0: Resolve Review Mode
+## Phase 0: Resolve Config
 
-1. If `--review [mode]` was passed as an argument, use that mode.
-2. Else read `production/review-mode.txt` — use whatever is written there.
-3. Else default to `lean`.
+!`source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh" 2>/dev/null && resolve_config --keys review_mode,automation,team.size`
 
-Modes:
+Resolved above — use as-is; `--review` overrides `review_mode`. No block →
+defaults in `.claude/docs/config-resolution.md`.
+
+`review_mode` sets gate depth:
 - `full` — spawn all director and lead gates as described
 - `lean` — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE)
 - `solo` — skip all director gate spawning entirely; run the skill without any agent gates
 
-Store the resolved mode for use in all subsequent phases.
+`automation` drives the Decision Points note above. See the Decision Points note above and
+`.claude/docs/automation-modes.md` for how each mode changes pipeline behavior.
+
+**`team.size`**: which agents are active (orthogonal to review_mode gate-depth and workflow docs).
+- **`individual`** (default): `level-designer` + `gameplay-programmer`. Other agents consulted via these two, not spawned separately.
+- **`small`**: + `systems-designer` + `art-director`.
+- **`studio`**: + `narrative-director` + `world-builder` + `accessibility-specialist`.
+Directors (CD/TD/PR) still spawn at phase gates regardless of size; a non-core agent needed at `individual` routes through the nearest active core agent with an informational note. **"Phase gate" means any phase that ends in an `AskUserQuestion` decision point before the pipeline advances** — not every phase. Apply the test literally: if the phase below has no decision point, it is not a gate, and an agent restricted to "phase gates only" is not spawned for it. This active-set scoping applies throughout the pipeline below: any phase that names an agent outside the active set routes through the nearest core agent rather than spawning it.
+
+**Announce the active set before Step 1 — never let the collapse be silent.**
+Before spawning anything, state in one line which agents this run will actually
+spawn, and which the pipeline below names but will **not** spawn at the resolved
+`team.size`. For example:
+
+> `Active set (team.size: <resolved>): <the agents listed for that size above>.`
+> `Not spawned this run: <every other agent this pipeline names> — consulted`
+> `through <nearest active core agent>. Raise team.size (or modes.rigor) to widen.`
+
+Fill it from the `team.size` list directly above and the agents this file's own
+pipeline names — not from an example. Both sets differ per orchestrator.
+
+The pipeline below reads as a multi-agent fan-out and at the shipped default it
+is one or two agents — `team-release` names eight and runs one, `team-narrative`
+names six across five phases and runs `writer` alone. **The collapse is correct**:
+`team.size` is rigor-fronted and the narrow default is the token lever, measured
+at roughly 10x. What was wrong is that nothing said so, so a reader could not
+distinguish a correctly-collapsed run from a broken pipeline, and the per-agent
+"routes through the nearest core agent with an informational note" rule above
+fires at routing time and never states the shape of the run as a whole.
+
+This is the same rule as the skipped-check reporting elsewhere in this file: **a constraint that is enforced but never surfaced is
+indistinguishable, to the person reading the output, from one that was never
+enforced.**
 
 1. **Read the argument** for the target level or area (e.g., `tutorial`,
    `forest dungeon`, `hub town`, `final boss arena`).
@@ -39,7 +77,7 @@ Store the resolved mode for use in all subsequent phases.
 
 ## How to Delegate
 
-Use the Task tool to spawn each team member as a subagent:
+Use the `Agent` tool to spawn each team member as a subagent:
 - `subagent_type: narrative-director` — Narrative purpose, characters, emotional arc
 - `subagent_type: world-builder` — Lore context, environmental storytelling, world rules
 - `subagent_type: level-designer` — Spatial layout, pacing, encounters, navigation
@@ -48,13 +86,17 @@ Use the Task tool to spawn each team member as a subagent:
 - `subagent_type: accessibility-specialist` — Navigation clarity, colorblind safety, cognitive load
 - `subagent_type: qa-tester` — Test cases, boundary testing, playtest checklist
 
-Always provide full context in each agent's prompt (game concept, pillars, existing level docs, narrative docs).
+**Brief each agent — do not dump context.** Read the shared inputs **once** and pass a distilled brief inline: the lines each agent actually needs, never a file path for a document you have already read (an agent handed a path re-reads the whole file). Pass a path only for a document you have not read and only that agent needs.
+
+**End every agent prompt with a return contract:** "Write your full output to `[path]` — that named path is your write authorisation under the bounded exception below, so write it without a separate approval prompt. Return **only** (1) the path written, (2) a ≤5-bullet summary of decisions, (3) any BLOCKED/CONCERNS items, one line each. Do not restate the documents you read." Without it, an agent returns everything it read back into this session.
+
+> **Why this does not violate the Collaboration Protocol.** `CLAUDE.md` requires an agent to ask "May I write this to [filepath]?" before Write/Edit. A subagent spawned here writes **without** asking, and that is a deliberate, bounded exception rather than an oversight — the same call already made for `consistency-check` appending to `active.md`. The exception holds only when all three are true: (1) the path is one **you** named in the prompt, so the user approved the destination when they approved the phase; (2) it is a new artifact under `production/`, `docs/` or `tests/`, never an edit to existing source or config; (3) the phase that produced it is itself gated by an `AskUserQuestion` before the pipeline advances. Outside those three, the agent must ask. **Do not "fix" this by asking per subagent** — a prompt per agent per phase makes an orchestrator unusable, which is why the exception exists.
 
 3. **Orchestrate the level design team** in sequence:
 
 ### Step 1: Narrative + Visual Direction (narrative-director + world-builder + art-director, parallel)
 
-Spawn all three agents simultaneously — issue all three Task calls before waiting for any result.
+Spawn all three agents simultaneously — issue all three `Agent` calls before waiting for any result.
 
 Spawn the `narrative-director` agent to:
 - Define the narrative purpose of this area (what story beats happen here?)
@@ -148,12 +190,15 @@ Spawn the `qa-tester` agent to:
 4. **Compile the level design document** combining all team outputs into the
    level design template format.
 
-After all subagent outputs are collected, spawn `level-designer` via Task to compile and write the final document:
-- Pass: all subagent outputs (verbatim), the level brief, game pillars, relevant GDD sections
-- Ask level-designer to: compile into the level design document format, then request user approval before writing ("May I write the compiled level design to design/levels/[level-name].md?")
-- The orchestrator does NOT call Write directly for the final document.
+The orchestrator already holds every sub-agent's output — **compile the document
+itself; do not re-spawn `level-designer` and re-send all outputs verbatim.** That
+second spawn pays a fresh agent's overhead plus a full re-transmission of context
+the orchestrator already has, to move text it is already holding. After compiling
+into the level-design template format, ask the user directly via
+`AskUserQuestion`: "May I write the compiled level design to
+`design/levels/[level-name].md`?" On approval, write it.
 
-5. **Save to** `design/levels/[level-name].md` (handled by the level-designer subagent after user approval — see above).
+5. **Save to** `design/levels/[level-name].md` after that approval.
 
 6. **Output a summary** with: area overview, encounter count, estimated asset
    list, narrative beats, any cross-team dependencies or open questions, open
@@ -162,9 +207,16 @@ After all subagent outputs are collected, spawn `level-designer` via Task to com
 
 ## File Write Protocol
 
-All file writes (level design docs, narrative docs, test checklists) are delegated
-to sub-agents spawned via Task. Each sub-agent enforces the "May I write to [path]?"
-protocol. This orchestrator does not write files directly.
+Per-agent artifacts (narrative docs, test checklists) are written by the
+sub-agent that produced them, under the **bounded exception** documented above
+under "Why this does not violate the Collaboration Protocol" — the path is one
+you named, the artifact is new under `production/`, `docs/` or `tests/`, and the
+phase is gated by an `AskUserQuestion`. A sub-agent does **not** prompt per write
+inside those bounds; outside them it must ask. The **one exception is the final
+compiled level-design document**: the
+orchestrator already holds every input, so it compiles and writes that file
+itself after its own "May I write …?" prompt (Step 4) — re-spawning an agent
+just to write text the orchestrator is already holding is pure overhead.
 
 Verdict: **COMPLETE** — level design document produced and all team outputs compiled.
 Verdict: **BLOCKED** — one or more agents blocked; partial report produced with unresolved items listed.
@@ -177,15 +229,17 @@ Verdict: **BLOCKED** — one or more agents blocked; partial report produced wit
 
 ## Error Recovery Protocol
 
-If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:
+**First, verify the artifact.** If the return contract named a path, check the
+path exists before treating the phase as done — **a named artifact that is not
+on disk is a failed phase, however fluent the response reads.** An agent can
+burn a full phase and return a plausible preamble having written nothing, which
+is neither BLOCKED nor an error nor "cannot complete", so the trigger below
+never fires. Resume it naming the unmet contract; the context is
+usually still there.
 
-1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
-2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
-3. **Offer options** via AskUserQuestion with choices:
-   - Skip this agent and note the gap in the final report
-   - Retry with narrower scope
-   - Stop here and resolve the blocker first
-4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.
+If any spawned agent returns BLOCKED, errors, or cannot complete: **surface it
+immediately, don't proceed past a dependency it blocks, and always produce a
+partial report.** Full procedure: `.claude/docs/error-recovery-protocol.md`.
 
 Common blockers:
 - Input file missing (story not found, GDD absent) → redirect to the skill that creates it