Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/pipeline/create-control-manifest.md

Skill Test Spec: /create-control-manifest

Skill Summary

/create-control-manifest reads the Accepted ADRs in docs/architecture/ and generates a control manifest — a flat, actionable rules sheet that captures the required patterns, forbidden approaches, performance guardrails and engine API constraints for each architectural layer (Foundation, Core, Feature, Presentation), plus global rules from project config and engine reference docs. Story authors use it so stories inherit the correct architectural rules without reading every ADR.

The skill counts ADRs first, resolves each ADR's ## Status with a Grep before reading any ADR body, and builds the manifest from the Accepted set only. It previews rule counts per layer, runs the TD-MANIFEST director gate when the review mode is full (skipped with a note in solo and lean), then asks "May I write the Control Manifest?" before writing docs/architecture/control-manifest.md. Verdicts: COMPLETE on write, BLOCKED when the user declines the write.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keywords: COMPLETE, BLOCKED
• Contains "May I write" collaborative protocol language (for the control manifest)
• Has a next-step handoff at the end (/create-epics then /create-stories)
• Documents that only Accepted ADRs are included (not Proposed)
• Names gate TD-MANIFEST and its solo/lean skip notes

---

Director Gate Checks

One gate: TD-MANIFEST (technical-director, .claude/docs/director-gates/td-manifest.md), spawned after the user accepts the Phase 4 rule summary and before the Phase 5 write ask.

• full → spawned; receives the Control Manifest Preview, the ADRs covered, the engine version and any rules sourced from preferences or engine reference docs
• lean → skipped; output notes "TD-MANIFEST skipped — Lean mode."
• solo → skipped; output notes "TD-MANIFEST skipped — Solo mode."

Verdict handling: APPROVE → proceed to the write ask; CONCERNS → AskUserQuestion with Revise flagged rules / Accept and proceed / Discuss further; REJECT → the manifest is not written, flagged rules are fixed and the summary re-presented; NOT ASSESSED [missing input] → never read as APPROVE: the missing input is named, then supplied and the gate re-run, or the run goes on with TD-MANIFEST: NOT ASSESSED — [input] stated in the output and the Verdict line.

---

Test Cases

Case 1: Happy Path — 4 Accepted ADRs create a correct manifest

Fixture:

• docs/architecture/ contains adr-0001-*.md … adr-0004-*.md, each with a ## Status section reading Accepted
• Each ADR has ## Decision (with "must"/"always" statements) and ## Alternatives Considered (with rejected alternatives)
• No existing docs/architecture/control-manifest.md
• Review mode resolves to solo

Input: /create-control-manifest

Expected behavior:

1. Globs docs/architecture/adr-*.md (N = 4), then Greps ^## Status to resolve the Accepted set before reading any ADR body
2. Greps only the Decision / Alternatives Considered / Performance Implications / Engine Compatibility sections of the Accepted ADRs
3. Reports "Loaded 4 Accepted ADRs, engine: [name + version]."
4. Shows the Control Manifest Preview (rule counts per layer, ADRs covered) and asks "Does this rule summary look complete?"
5. Notes "TD-MANIFEST skipped — Solo mode."
6. Asks "May I write the Control Manifest?" with option [A] Yes — write to docs/architecture/control-manifest.md
7. Writes the manifest after approval; Verdict: COMPLETE

Assertions:

• All 4 Accepted ADRs are listed under ADRs Covered in the manifest header
• Each layer section has ### Required Patterns and ### Forbidden Approaches
• Every rule carries its source — — source: [ADR-NNNN] for a layer rule; a global rule names its project.yaml / technical-preferences.md key or engine-reference file (e.g. deprecated-apis.md)
• Preview is shown and "Does this rule summary look complete?" is asked before any write ask
• "TD-MANIFEST skipped — Solo mode." appears; no technical-director is spawned
• Skill does NOT write before the "May I write the Control Manifest?" approval
• Verdict is COMPLETE after writing

---

Case 2: Failure Path — No ADRs found

Fixture:

• docs/architecture/ directory exists but contains no adr-*.md files

Input: /create-control-manifest

Expected behavior:

1. Glob returns N = 0
2. Skill outputs: "No ADRs found — run /architecture-decision before building a control manifest."
3. Skill stops — no Status Grep, no preview, no write ask, no file written

Assertions:

• The "No ADRs found" message is printed
• Skill recommends /architecture-decision as the next action
• No control manifest file is written and no "May I write" ask is shown
• Verdict COMPLETE is NOT emitted (the skill stops at Phase 1)

---

Case 3: Mixed ADR Statuses — Only Accepted ADRs included

Fixture:

• docs/architecture/ contains 5 ADRs: 3 with ## Status Accepted, 2 with ## Status Proposed (ADR-0004, ADR-0005)

Input: /create-control-manifest

Expected behavior:

1. N = 5; the ^## Status Grep returns 5 matches, 3 reading Accepted — the "some Accepted" row applies and the Accepted set A = the 3 ADRs
2. Section extraction is filtered to set A
3. Preview reports "Loaded 3 Accepted ADRs", ADRs covered lists only the 3, and ADRs excluded names ADR-0004 (Proposed) and ADR-0005 (Proposed)
4. Proceeds without asking about Proposed ADRs (that ask is reserved for the none-Accepted case)

Assertions:

• Status is resolved with the ^## Status Grep before any ADR section is read
• The preview's ADRs covered and the manifest's ADRs Covered list exactly the 3 Accepted ADRs
• Both excluded ADRs are named, with their status, in the preview the user sees before approving — the skill does not silently omit them
• No rule in the manifest is sourced from either Proposed ADR
• The "none Accepted — proceed with Proposed or stop?" ask is NOT shown for this fixture

---

Case 4: Edge Case — Regenerating an existing manifest

Fixture:

• docs/architecture/control-manifest.md already exists with Manifest Version and Last Updated both dated last week
• docs/architecture/ contains Accepted ADRs, one of them accepted since then
• production/epics/ already holds epics with stories, so the first-run /create-epics next step does not apply

Input: /create-control-manifest update

Expected behavior:

1. Skill rebuilds the manifest from the current Accepted ADRs (same Phases 1–4)
2. Asks "May I write the Control Manifest?" before overwriting
3. The new manifest's Manifest Version and Last Updated are both today's date
4. After writing, prints "Updated. Recommend notifying the team of changed rules — especially any new Forbidden entries."

Assertions:

• The existing file is not overwritten before "May I write the Control Manifest?" is approved
• The newly accepted ADR appears in ADRs Covered
• Manifest Version equals Last Updated and is the generation date (not a v1→v2 counter)
• The regeneration next-step ("Updated. Recommend notifying the team…") is shown instead of the first-run /create-epics handoff

---

Case 5: Director Gate — TD-MANIFEST in full review mode returns REJECT

Fixture:

• 4 Accepted ADRs exist
• Review mode resolves to full
• TD-MANIFEST returns REJECT, naming one rule that has no source ADR

Input: /create-control-manifest

Expected behavior:

1. Skill shows the Phase 4 preview; user picks [A] Yes — looks good, run the director review and write the manifest
2. Spawns technical-director via Agent with gate TD-MANIFEST, passing the preview (full rule list), ADRs covered and engine version
3. On REJECT: does not write the manifest; fixes the flagged rule and re-presents the summary
4. "May I write the Control Manifest?" is not asked while the REJECT stands

Assertions:

• TD-MANIFEST is spawned only after the Phase 4 summary is accepted
• The gate receives the rule list, ADRs covered and engine version
• On REJECT no manifest file is written
• The flagged rule is revised and the summary re-presented before any write ask
• No "TD-MANIFEST skipped" note appears in full mode

---

Case 6: Edge Case — No Accepted ADR, and ADRs with no ## Status

Fixture (none Accepted):

• docs/architecture/ contains 3 ADRs, each with ## Status Proposed

Fixture (malformed):

• docs/architecture/ contains 3 ADRs, none with a ## Status section

Input (both fixtures): /create-control-manifest

Expected behavior (none Accepted):

1. N = 3; the ^## Status Grep matches 3, none reading Accepted
2. Reports "3 ADRs found, none Accepted. A manifest built from Proposed ADRs would encode decisions that may still change." and asks whether to proceed with the Proposed ADRs or stop

Expected behavior (malformed):

1. N = 3; the ^## Status Grep matches nothing
2. Reports "3 ADRs found, none has a ## Status section — acceptance cannot be determined. Run /architecture-decision retrofit [file] on each." and stops

Assertions:

• None Accepted: the ask is shown and no empty manifest is written
• Malformed: the run stops — the ADRs are not treated as Accepted and no manifest is written
• Malformed: the retrofit command reads /architecture-decision retrofit [file] — the form that skill parses
• In neither fixture is a rule summary previewed or a "May I write" ask shown before the user proceeds

---

Protocol Compliance

• Counts ADRs and resolves ## Status before reading ADR sections
• Only Accepted ADRs included, and every excluded ADR is named with its status in the preview; the none-Accepted and no-## Status cases stop or ask instead of emitting an empty manifest
• Rule summary shown to user before the gate and before "May I write"
• "May I write the Control Manifest?" asked before writing docs/architecture/control-manifest.md
• TD-MANIFEST runs in full, is skipped with a named note in lean/solo
• Ends with next-step handoff: /create-epics layer: foundation then /create-stories [epic-slug]

---

Coverage Notes

• The exact section structure of the generated manifest (constraint tables, pattern lists) is defined by the skill body and not re-enumerated in test assertions.
• What happens after the user proceeds with Proposed ADRs (Case 6) is not fixture-tested.
• TD-MANIFEST APPROVE, CONCERNS and NOT ASSESSED paths, and the lean skip note, are not separately fixture-tested.
• Relevance filtering of deprecated-apis.md entries (2D vs 3D scoping) is not covered.