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

@@ -1,9 +1,9 @@
 ---
 name: team-ui
-description: "Orchestrate the UI team through the full UX pipeline: from UX spec authoring through visual design, implementation, review, and polish. Integrates with /ux-design, /ux-review, and studio UX templates."
+description: "Orchestrate the UI team through the UX pipeline — authoring, visual design, implementation, review, polish. Uses /ux-design, /ux-review, studio templates."
 argument-hint: "[UI feature description] [--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
 ---
 When this skill is invoked, orchestrate the UI team through a structured pipeline.
@@ -11,20 +11,58 @@ When this skill is invoked, orchestrate the UI team through a structured pipelin
 **Decision Points:** At each phase 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 phase.
+In `collaborative` mode, the user must approve before moving to the next phase.
+In `guided` mode the pipeline advances automatically unless a phase is BLOCKED;
+in `autonomous` mode it runs end to end, recording each phase 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): `ui-programmer` + `ux-designer`. Other agents consulted via these two, not spawned separately.
+- **`small`**: + `accessibility-specialist` + `art-director`.
+- **`studio`**: + engine UI specialist + an adversarial review pass.
+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.**
 
 **Director gate skip rule**: Before spawning creative-director, art-director, or any other Tier 1/2 director for review (outside of PHASE-GATE triggers), apply the resolved mode: skip if solo mode; skip if lean mode and this is not a PHASE-GATE.
 
@@ -32,9 +70,14 @@ Store the resolved mode for use in all subsequent phases.
 - **ux-designer** — User flows, wireframes, accessibility, input handling
 - **ui-programmer** — UI framework, screens, widgets, data binding, implementation
 - **art-director** — Visual style, layout polish, consistency with art bible
-- **engine UI specialist** — Validates UI implementation patterns against engine-specific best practices (read from `.claude/docs/technical-preferences.md` Engine Specialists → UI Specialist)
+- **engine UI specialist** — Validates UI implementation patterns against engine-specific best practices (`specialists.ui` from `project.yaml`; if absent, the UI Specialist line of `## Engine Specialists` in `.claude/docs/technical-preferences.md`)
 - **accessibility-specialist** — Audits accessibility compliance at Phase 4
 
+> **`specialists.ui: null` means UNSET.** Treat it as absent and skip the engine
+> UI specialist; never spawn `null` as an agent name. The v1.0 migration writes
+> the whole `specialists` block whenever any one member is set, so `null` here is
+> ordinary — and the config reader returns it as the non-empty string `"null"`.
+
 **Templates used by this pipeline:**
 - `ux-spec.md` — Standard screen/flow UX specification
 - `hud-design.md` — HUD-specific UX specification
@@ -43,14 +86,20 @@ 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: ux-designer` — User flows, wireframes, accessibility, input handling
 - `subagent_type: ui-programmer` — UI framework, screens, widgets, data binding
 - `subagent_type: art-director` — Visual style, layout polish, art bible consistency
 - `subagent_type: [UI engine specialist]` — Engine-specific UI pattern validation (e.g., unity-ui-specialist, ue-umg-specialist, godot-specialist)
 - `subagent_type: accessibility-specialist` — Accessibility compliance audit
 
-Always provide full context in each agent's prompt (feature requirements, existing UI patterns, platform targets). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 4 review agents can run simultaneously).
+**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.
+
+Launch independent agents in parallel where the pipeline allows it (e.g., Phase 4 review agents can run simultaneously).
 
 ## Pipeline
 
@@ -63,6 +112,30 @@ Before designing anything, read and synthesize:
 - `design/ux/interaction-patterns.md` — existing patterns to reuse (not reinvent)
 - `design/accessibility-requirements.md` — committed accessibility tier (e.g., Basic, Enhanced, Full)
 
+**Report the status of every document above before designing anything.** Phase 1a
+reads five inputs; for a long time only the pattern library was guarded, and the
+other four could be absent without anything noticing. List each as
+present or ABSENT.
+
+**`design/accessibility-requirements.md` is the one that must not pass silently.**
+It carries the committed accessibility tier, which **Phase 3 implements against**
+and **Phase 4 gates on** ("verify compliance against the committed accessibility
+tier … flag any violations as blockers"). If the file is missing there is no tier,
+so that gate has no criterion and would pass while checking nothing — a gate made
+of an absent standard, the same shape as an assertion that can never fail. When it
+is absent:
+- Say so here, and carry it forward: **Phase 4 must report
+  `Accessibility: NOT ASSESSED — no committed tier (design/accessibility-requirements.md absent)`
+  and must NOT report the accessibility gate as passed.**
+- The ux-designer states which tier they designed against as an explicit
+  assumption, so a later reader can see it was assumed rather than committed.
+- Recommend `/ux-design accessibility` to establish the tier.
+
+Absence of `design/gdd/game-concept.md`, `design/player-journey.md` or
+`design/ux/hud.md` is not blocking, but name each missing one in the brief you
+pass to the ux-designer so they design knowing what context they lack, rather
+than inferring it.
+
 **If `design/ux/interaction-patterns.md` does not exist**, surface the gap immediately:
 > "interaction-patterns.md does not exist — no existing patterns to reuse."
 
@@ -104,13 +177,13 @@ Delegate to **art-director**:
 
 ### Phase 3: Implementation
 
-Before implementation begins, spawn the **engine UI specialist** (from `.claude/docs/technical-preferences.md` Engine Specialists → UI Specialist) to review the UX spec and visual design spec for engine-specific implementation guidance:
+Before implementation begins, spawn the **engine UI specialist** (`specialists.ui` from `project.yaml`; if absent, the UI Specialist line of `## Engine Specialists` in `.claude/docs/technical-preferences.md`) to review the UX spec and visual design spec for engine-specific implementation guidance:
 - Which engine UI framework should be used for this screen? (e.g., UI Toolkit vs UGUI in Unity, Control nodes vs CanvasLayer in Godot, UMG vs CommonUI in Unreal)
 - Any engine-specific gotchas for the proposed layout or interaction patterns?
 - Recommended widget/node structure for the engine?
 - Output: engine UI implementation notes to hand off to ui-programmer before they begin
 
-If no engine is configured, skip this step.
+If no engine is configured, skip this step. **Record `Engine validation: NOT ASSESSED — no engine configured (`engine.name` unset in `project.yaml`)` in this run's output.** A skipped check that says nothing is indistinguishable from a check that passed; the reader cannot tell engine guidance was never sought.
 
 Delegate to **ui-programmer**:
 - Implement the UI following the UX spec and visual design spec
@@ -128,7 +201,7 @@ Delegate to **ui-programmer**:
 Delegate in parallel:
 - **ux-designer**: Verify implementation matches wireframes and interaction spec. Test keyboard-only and gamepad-only navigation. Check accessibility features function correctly.
 - **art-director**: Verify visual consistency with art bible. Check at minimum and maximum supported resolutions.
-- **accessibility-specialist**: Verify compliance against the committed accessibility tier documented in `design/accessibility-requirements.md`. Flag any violations as blockers.
+- **accessibility-specialist**: Verify compliance against the committed accessibility tier documented in `design/accessibility-requirements.md`. Flag any violations as blockers. **If that file is absent there is no committed tier, so this gate has no criterion: report `Accessibility: NOT ASSESSED — no committed tier (design/accessibility-requirements.md absent)` and do NOT report the gate as passed**. Carry forward whatever tier Phase 1a recorded as assumed, and say plainly that it was assumed.
 
 All three review streams must report before proceeding to Phase 5.
 
@@ -150,15 +223,17 @@ All three review streams must report before proceeding to Phase 5.
 
 ## 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
@@ -169,8 +244,17 @@ Common blockers:
 ## File Write Protocol
 
 All file writes (UX specs, interaction pattern library updates, implementation files) are
-delegated to sub-agents and sub-skills (`/ux-design`, `ui-programmer`). Each enforces the
-"May I write to [path]?" protocol. This orchestrator does not write files directly.
+delegated to sub-agents and sub-skills. The two follow **different** rules:
+
+- **Sub-agents spawned via `Agent`** (e.g. `ui-programmer`) follow 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.
+- **Sub-skills** (`/ux-design`) are not sub-agents and the exception does not reach
+  them. They follow the normal Collaboration Protocol and ask before writing.
+
+This orchestrator does not write files directly.
 
 ## Output