/create-control-manifest

name: create-control-manifest
description: "Builds a short list of must-do and never-do coding rules per system from accepted ADRs. Use when the user wants programmer rules or a cheat sheet from the ADRs, or needs it regenerated after ADR changes."
argument-hint: "[update — regenerate from current ADRs] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/create-control-manifest/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/adr-status.sh*), Bash(bash .claude/scripts/md-section.sh *)
model: sonnet

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

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

Ask with the question tool. Without one, list the options numbered and end your turn to wait. A skipped or dismissed question is not an answer: ask again in plain text.

Create Control Manifest

The control manifest is a flat rules sheet for programmers: what to do and what never to do, by architectural layer, taken from the Accepted ADRs, the project's technical preferences and the engine reference docs. The ADRs say *why*; the manifest says *what*.

**Writes:** `docs/architecture/control-manifest.md`, after the user's yes. **When:** after `/architecture-review` passes and the ADRs are Accepted. Run it again whenever an ADR is accepted or revised.

Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided asks on major choices, autonomous logs and goes on; `automation_always_ask` categories always ask).

Phase 1: Load the inputs

ADRs

`bash .claude/scripts/adr-status.sh` reads every `docs/architecture/adr-*.md` in one pass: the counts first (`adrs`, then `accepted`, `proposed`, `deprecated`, `superseded`, `unfilled`, `other`, `no_status`), then one row per ADR with its status and layer. Establish the denominator first: decide from the counts, before reading any ADR:

| Counts | Meaning | Action | |---|---|---| | `adrs 0` | No ADRs. | "No ADRs found — run `/architecture-decision` before building a control manifest." Stop. | | `accepted` ≥ 1 | Normal. | The Accepted rows are the set **A**. Name every other ADR, with its status, in the Phase 4 preview: the user approves a manifest knowing what it leaves out. | | `accepted 0`, some with a status | No Accepted ADRs. | "[N] ADRs found, none Accepted. A manifest built from Proposed ADRs would encode decisions that may still change." Ask whether to go on with the Proposed ones or stop. **Never write an empty manifest silently.** | | every ADR `no_status` | **Malformed ADRs, not an empty Accepted set.** | "[N] ADRs found, none has a `## Status` section, so acceptance cannot be told. Run `/architecture-decision retrofit [file]` on each." Stop. Never treat them as Accepted. |

Each stop above ends with `Verdict: BLOCKED — [the reason]`. Note the number and title of every ADR a rule comes from.

Project config

• `naming.*` and `performance.*` from `project.yaml`; for any key absent or empty,

`.claude/docs/technical-preferences.md`.

• Approved libraries and forbidden patterns from

`.claude/docs/technical-preferences.md` (not migrated to `project.yaml`).

Engine reference

• `docs/engine-reference/[engine]/VERSION.md` for the engine and version.
• `docs/engine-reference/[engine]/deprecated-apis.md`: these become forbidden APIs.
• `docs/engine-reference/[engine]/current-best-practices.md`, when it exists.

What exists already

`docs/architecture/control-manifest.md` present: this run regenerates it; read it before the Phase 5 write, which replaces it. `production/epics/*/EPIC.md` present: epics exist. Phase 6 picks its next step from both.

Report: "Loaded [A] Accepted ADRs of [N], engine: [name + version]."

Phase 2: Extract the rules from each ADR

For each ADR in **A**, read only four sections, never the whole file:

bash .claude/scripts/md-section.sh extract docs/architecture/[adr-file].md "Decision"

and the same for `Alternatives Considered`, `Performance Implications` and `Engine Compatibility`. Context, Consequences, Migration Plan and Validation Criteria say why a decision was made; the manifest records what to do. A section an ADR lacks: note it for that ADR and go on. A section missing from **every** ADR in A: report "No Accepted ADR has a `[section]` section — the manifest's [category] rules will be empty. Verify this is intended." Read beyond the four only when a section points outside itself ("subject to the constraints in Context"), and then that one section.

From each ADR:

• **Required patterns** (Decision): every "must", "should", "required to",

"always", and every pattern or approach it mandates, including any `### Implementation Guidelines` inside it. Never look for that sub-heading alone: many ADRs state their mandates directly under Decision, and a scan for the sub-heading alone yields an empty section.

• **Forbidden approaches** (Alternatives Considered): every rejected alternative,

with why it was rejected as the rule ("never use X because Y"), and any named anti-pattern.

• **Performance guardrails** (Performance Implications): budgets ("max N ms per

frame for this system") and memory limits.

• **Engine API constraints** (Engine Compatibility): post-cutoff APIs that need

verifying, behaviour that differs from what a model would assume, fields or methods that changed in the pinned version.

**Layer.** Each rule goes under the layer of the system it governs, the ADR's `layer` column where it has one:

• **Foundation:** scene management, event architecture, save/load, engine start-up
• **Core:** core gameplay loop, main player systems, physics and collision
• **Feature:** secondary systems and mechanics, AI
• **Presentation:** rendering, audio, UI, VFX, shaders

An ADR that spans layers put