create-control-manifest

!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 puts its rule in each one.

Phase 3: Add the global rules

Rules for every layer, each with its source (the project.yaml key, technical-preferences.md, or the engine-reference file), as a layer rule has:

• Naming from naming.*: classes, variables, signals and events, files, constants.
• Performance budgets from performance.*: target frame rate, frame budget, draw calls, memory ceiling.
• Forbidden APIs from deprecated-apis.md, only those that apply to what this project builds. Never copy the table whole: its GodotPhysics3D → Jolt Physics 3D row is 3D-only, and a 2D project does not use that engine. When you cannot tell whether an entry applies (2D or 3D, a module the project may not include), scope the rule ("when using 3D physics: …") or leave it out and list it as unresolved. /create-stories reads this file, and rules that do not apply are rules nobody reads.
• Required patterns from current-best-practices.md, when it exists.
• Forbidden patterns from technical-preferences.md, copied as written.

Phase 4: Show the summary, then the review

## Control Manifest Preview
Engine: [name + version]
ADRs covered: [ADR numbers]
ADRs left out: [ADR-NNNN ([status]), … — every ADR not in A, or "None"]
Rules extracted:
  - Foundation layer: [N] required, [M] forbidden, [P] guardrails
  - Core layer: [N] required, [M] forbidden, [P] guardrails
  - Feature layer: …
  - Presentation layer: …
  - Global: [N] naming conventions, [M] forbidden APIs, [P] approved libraries
Unresolved: [engine entries left out because whether they apply is unclear, or "None"]

Ask: "Does this rule summary look complete?" Options: Yes — review and write it / Add rules — I have more to include / Remove rules — some should be dropped / Stop — I need to review the ADRs first.

The technical review. Read the review_gate line above. skill-gates=skip (solo or lean): no agent; note TD-MANIFEST skipped — [Solo | Lean] mode. skill-gates=run: hand the review to the technical-director agent with gate TD-MANIFEST (.claude/docs/director-gates/td-manifest.md; the agent reads it itself). Brief:

• Objective: check the extracted rules before they are written.
• Give it: the preview above with the full rule list, the ADRs covered, the engine version, and the rules taken from technical preferences or the engine reference.
• Check: every mandatory ADR pattern is captured and stated accurately; the forbidden approaches are complete and correctly attributed; no rule lacks a source ADR or preference document; the guardrails agree with the ADRs' constraints.
• Return: APPROVE, CONCERNS, REJECT, or NOT ASSESSED naming a missing input.
• Boundaries: it writes no file.

Act on the verdict:

• APPROVE: go to Phase 5.
• CONCERNS: ask: "The technical director raised concerns. How do you want to go on?" Options: Revise the flagged rules / Accept and go on / Discuss further.
• REJECT: write nothing; fix the flagged rules and show the summary again.
• NOT ASSESSED: it is not an approval (.claude/docs/director-gates.md). Name what was missing, then supply it and run the review again; or, when the user chooses to go on without it, go to Phase 5 and state TD-MANIFEST: NOT ASSESSED — [input] in the reply and the final verdict line.

Phase 5: Write the control manifest

Ask: "May I write the control manifest to docs/architecture/control-manifest.md?" Options: Yes, write it / Show me the full draft first, then ask again / Not yet — I want more changes. Write only on an explicit yes.

# Control Manifest

> **Engine**: [name + version]
> **Last Updated**: [date]
> **Manifest Version**: [date]
> **ADRs Covered**: [ADR-NNNN, ADR-MMMM, ...]
> **Status**: Active — regenerate with `/create-control-manifest update` when ADRs change

`Manifest Version` is the date this manifest was generated. Stories embed it when
they are written, and `/story-readiness` compares a story's version with this one
to find stories written against old rules. It always equals `Last Updated`: the
same date, for different readers.

This manifest is a programmer's quick reference taken from the Accepted ADRs, the
technical preferences and the engine reference docs. For the reason behind a rule,
read its ADR.

---

## Foundation Layer Rules

*Applies to: scene management, event architecture, save/load, engine start-up*

### Required Patterns
- **[rule]** — source: [ADR-NNNN]

### Forbidden Approaches
- **Never [anti-pattern]** — [brief reason] — source: [ADR-NNNN]

### Performance Guardrails
- **[system]**: max [N]ms/frame — source: [ADR-NNNN]

---

## Core Layer Rules

*Applies to: core gameplay loop, main player systems, physics, collision*

### Required Patterns
...

### Forbidden Approaches
...

### Performance Guardrails
...

---

## Feature Layer Rules

*Applies to: secondary mechanics, AI systems, secondary features*

### Required Patterns
...

### Forbidden Approaches
...

---

## Presentation Layer Rules

*Applies to: rendering, audio, UI, VFX, shaders, animations*

### Required Patterns
...

### Forbidden Approaches
...

---

## Global Rules (All Layers)

### Naming Conventions
| Element | Convention | Example | Source |
|---------|-----------|---------|--------|
| Classes | [convention] | [example] | [`naming.classes` in project.yaml, or technical-preferences.md] |
| Variables | [convention] | [example] | [`naming.variables` in project.yaml, or technical-preferences.md] |
| Signals/Events | [convention] | [example] | [`naming.signals` in project.yaml, or technical-preferences.md] |
| Files | [convention] | [example] | [`naming.files` in project.yaml, or technical-preferences.md] |
| Constants | [convention] | [example] | [`naming.constants` in project.yaml, or technical-preferences.md] |

### Performance Budgets
| Target | Value | Source |
|--------|-------|--------|
| Framerate | [value] | [`performance.target_framerate` in project.yaml, or technical-preferences.md] |
| Frame budget | [value] | [`performance.frame_budget_ms` in project.yaml, or technical-preferences.md] |
| Draw calls | [value] | [`performance.draw_call_limit` in project.yaml, or technical-preferences.md] |
| Memory ceiling | [value] | [`performance.memory_ceiling_mb` in project.yaml, or technical-preferences.md] |

### Approved Libraries / Addons
- [library] — approved for [purpose] — source: technical-preferences.md

### Forbidden APIs ([engine version])
These APIs are deprecated or unverified for [engine + version]:
- `[api name]` — deprecated since [version] / unverified post-cutoff
- Source: `docs/engine-reference/[engine]/deprecated-apis.md`

### Cross-Cutting Constraints
- [constraint that applies in every layer] — source: [ADR-NNNN, preference key or engine-reference file]

Phase 6: Next steps

• No epics yet: "Run /create-epics layer: foundation, then /create-stories [epic-slug]: stories embed this manifest's rules and version."
• A regeneration: "Updated. Tell the team about the changed rules, above all any new Forbidden entries."

Every rule traces to an ADR, a technical preference or an engine reference doc; none is invented, and none is paraphrased in a way that changes its meaning. End with Verdict: COMPLETE — control manifest written after the write, or Verdict: BLOCKED — user declined the write when declined.