Concrete upgrade proposals: a mechanical story-closure gate, evidence receipts, config echo, a domain toolchain, and more

[jiangshoujie]

Hi Donchitos —

I've read through CLAUDE.md, context-management.md, the three largest skills (story-done / dev-story / gate-check), all 12 hooks, and the scripts in .claude/scripts/. Short version: this is the most thoroughly engineered Claude Code template I've come across — the measured minimal default, the two-region active.md schema, the locked verdict vocabulary ("A parse check is not a run"), and the "scripts emit observations, never verdicts" principle (the header comment of project-coherence.sh is a model in itself) are all things I haven't seen elsewhere.

Below are nine concrete improvement proposals from working through the system. Each is self-contained — problem, design (written against the existing directory layout and conventions), acceptance criteria, and rough effort. If any of them appeal to you, I'm happy to send PRs.

---

Proposal 1 — Story closure must be executed by a script (closing the direct-Status-edit bypass)

Problem. All of /story-done's checks are executed by the model itself (grep/glob). The model can skip the checks — or skip /story-done entirely and just edit a story's Status: field to Done. Nothing intercepts that today (story-status.sh is a manual helper, not a guard).

Design.

• New .claude/scripts/close-story.sh <story-path> becomes the only writer of Status: Done. Flow:
  1. yaml-helper.sh resolve_config for the story's system → qa.level / testing.strict
  2. Per story type, verify the existing evidence table (reuse the table already in the skill) against receipts (Proposal 2)
  3. All pass → rewrite the Status line and append a closure receipt; anything missing → exit 1 with an itemized list of reason codes (EVIDENCE_MISSING / RECEIPT_STALE / BUILD_MISMATCH / SIGNOFF_INCOMPLETE). That output doubles as the BLOCKED basis of the completion report.
• New hook .claude/hooks/guard-story-status.sh, wired in settings.json under PreToolUse (Write|Edit): deny when the target matches production/epics/**/*.md, the content contains Status: Done, and the write is not coming from the close-story flow — with a "Run /story-done" hint.

Acceptance. A direct Status edit is blocked by the hook; incomplete evidence makes close-story.sh exit 1 with itemized reason codes.
Effort. S (2–3 days; the path matching can copy validate-assets.sh).

Proposal 2 — Evidence receipts (from "exists" to "provable")

Problem. Today's evidence check globs production/qa/evidence/ for a png + sign-off doc. Reusing another story's screenshot or copying a placeholder image is undetectable. Run result: OBSERVED only requires that the model Read some image — there is no binding of "this screenshot ← this build". Test evidence explicitly reports only "test file present".

Design. Two wrapper scripts; receipts land in the existing evidence directory:

• .claude/scripts/run-tests.sh <test-path>: resolves the engine test command from project.yaml, runs it, writes test-receipt.json:

  { "kind": "test", "story": "TR-combat-013",
    "command": "godot --headless --script tests/unit/combat/test_damage.gd",
    "exit_code": 0, "passed": 12, "failed": 0,
    "timestamp": "…", "build_id": "git:8f3c2e1", "output_sha256": "…" }

• .claude/scripts/run-and-capture.sh: launches the game per engine and captures a screenshot (dev-story already references ScreenshotOnArg.cs — wire that existing convention into the script), writing screenshot-receipt.json with image_sha256 + build_id + story.
• close-story.sh (Proposal 1) reads receipts instead of globbing: image_sha256 must match the file on disk, and build_id must match the current HEAD — otherwise RECEIPT_STALE. Reusing an old screenshot stops working.

Acceptance. Reusing an old screenshot fails closure with RECEIPT_STALE; never-run tests yield no receipt → EVIDENCE_MISSING.
Effort. M (3–5 days; per-OS screenshot capture is the bulk — Godot can start with an autoload-based capture).

Proposal 3 — resolve_config echo + value validation

Problem. Two traps your own comments document: (a) reading project.yaml alone silently ignores project.local.yaml overrides; (b) testing.strict values like yes / 1 / maybe are silently treated as unset. In both cases gates are silently waived while the model and the user believe the config is in effect.

Design.

• yaml-helper.sh resolve_config --explain: prints, per key, "effective value ← source file" alongside the resolution, and the skill preamble injects it. One line of cost to make "which gates are actually in effect" visible to both the model and the human.
• /settings validates on write: a boolean knob receiving anything outside its legal values → refuse the write and list the legal values (moving story-done's "treated as unset" tolerance to a write-time rejection).

Acceptance. /settings testing.strict.logic=1 is refused; the skill preamble shows testing.strict.logic: true ← project.local.yaml.
Effort. S (1–2 days).

Proposal 4 — Independent review receipts

Problem. The Phase 5 Lead Programmer review under review_mode: solo is the same model grading its own work. log-agent.sh records that an agent ran, but not what the review concluded.

Design.

• The reviewer writes a review-receipt on completion (extend the existing review-receipts.sh): {reviewer_agent, model, checklist: [{item, pass, note}], verdict}. Checklist items come from the machine-checkable rules in rules/ (binary verification, not vibes).
• The completion report template (story-done Phase 6) gains a line Reviewed by: <agent>@<model> — receipt: <path>; under solo it explicitly reads Reviewed by: self — no independent review.

Acceptance. Every completion report traces to a reviewer identity and per-item results.
Effort. S–M (2–4 days).

Proposal 5 — Compile the conditional matrices ("run cards")

Problem. dev-story's body is 44KB (~11k tokens) containing a five-layer conditional matrix (rigor × qa.level × story_granularity × testing.strict × system_overrides) expressed entirely in prose and tables. The weaker the model, the more branches get dropped — most visible on non-Claude models. The !yaml-helper resolve_config injection at the top of dev-story is already the right pattern; it just doesn't cover the matrix itself.

Design. Backward-compatible and incremental:

• Each skill gains a machine-readable matrix.yaml (knobs + branches); branch-specific prose moves into .claude/skills/<name>/branches/<knob-value>.md fragments; SKILL.md keeps only the branch-agnostic skeleton.
• yaml-helper.sh compile <skill>: resolves config → assembles the run card for the one effective path (target ≤8KB) → injected via ! in place of the matrix prose. The model only ever sees a single path; it never reads a table again.
• Migration order: dev-story → story-done → gate-check (the three largest, best return).

Acceptance. The three skills' bodies are ≤8KB; running a standard story shows no full-branch STOP text anywhere in the resolved card.
Effort. L (1–2 weeks, incremental per skill).

Proposal 6 — Upgrade /skill-test to behavioral regression (CI for prompts)

Problem. /skill-test today is a static linter + rubric; it cannot verify that gate behavior actually happens. Proposals 1, 2 and 5 each need a regression net.

Design. Seed fixture projects under CCGS Skill Testing Framework/fixtures/, one per behavior:

• stale-screenshot/: complete evidence but an outdated build_id → assert close-story reports RECEIPT_STALE
• direct-status-edit/: simulated bypass → assert the hook denies
• local-override-ignored/: local.yaml override → assert --explain shows the source
  Plus a GitHub Actions workflow (all hooks are bash — they run on CI as-is).

Acceptance. /skill-test behavior runs all fixtures in one command and reports a pass rate.
Effort. M (3–5 days).

Proposal 7 — Model declarations → role mapping (decouple from Anthropic ids)

Problem. Agent frontmatter hardcodes model: opus / sonnet — ids bound to Anthropic product names. Sessions running via Bedrock / Vertex / compatibility gateways with third-party or custom models read meaningless values. And there is no config hook for tiered scheduling ("directors on the flagship, specialists on the workhorse").

Design. project.yaml gains:

models: { director: inherit, lead: inherit, specialist: inherit, reviewer: inherit }

Frontmatter model fields become inherit (= use the session model). The reviewer key doubles as the mount point for Proposal 4's "reviewer on a different model".

Acceptance. Switch model backend or adjust the three-tier mapping without touching any agent file.
Effort. S (1–2 days).

Proposal 8 — Content supply lines (four independently shippable pieces)

• C1 Example project. A companion repo with a 2–3 hour mini-game walkthrough, each skill step showing "what your repo should look like at this point" (keeps the main repo clean, honoring the no-shipped-games principle).
• C2 Asset receipts. Image/audio generation adapters write {source_model, prompt_hash, license, approved_by} receipts into the asset audit — provenance for AI-generated assets is becoming a hard requirement, and it is isomorphic to Proposal 2.
• C3 Engine runtime/CI. Preset Godot headless / Unity batchmode test commands in project.yaml's commands section + a GitHub Actions template (Proposal 6's fixtures reuse it directly).
• C7 Small fixes. notify.sh gains osascript/notify-send branches; UPGRADING gets a migration script (migrate-v1-config.sh is a good start).

Proposal 9 — Domain toolchain: world tech / save systems / dialogue runtime / animation

Problem. After auditing all 74 skills and the relevant agents: the template encodes process knowledge (workflow / review / QA / release) comprehensively, but several technical systems every indie game needs have no domain scaffolding —

• World generation & seamless maps. world-builder owns lore (factions / cultures / history); level-designer owns layout docs (encounter layouts / pacing) — neither touches the technical side. Across all 74 skills there is no procgen coverage (noise terrain / WFC / dungeon generation / tilemap autotiling) and no seamless-streaming coverage (chunk streaming, LOD, UE5 World Partition, Unity Addressables scene grouping, Godot chunking). A user aiming for a seamless world has no domain guidance after /design-system.
• Save systems. No /save-system. Save schema versioning/migration and cloud saves are a classic reputation-damage area for indie games (saves breaking on update). Config/Data stories have a smoke gate, but no skill guides save architecture.
• Dialogue runtime. The writer/narrative line produces text, but there is no skill for dialogue data-format selection (Ink / Yarn / custom), localization key conventions, or the VO pipeline — /localize's technical chain breaks at the source.
• Animation & cinematics. technical-artist exists as an agent with no workflow — no guidance for state machines / blend trees / IK / cutscenes (Timeline).

Why it fits. The team-* / domain-guide pattern is proven (/team-combat etc.); these four are the same pattern extended to the technical-content side. All four are engine-agnostic (per-engine specifics as subsections, matching the existing engine-specialist approach), their outputs flow through the existing GDD → ADR → story pipeline, and they are verified by the existing /story-done gates — no new mechanisms introduced.

Design. Four new skills, written in the style of design-system / create-architecture:

• /world-tech (or split /procgen + /world-streaming): procgen decision tree (deterministic vs runtime, seed management, reproducibility), streaming budget checklist (memory / loading / culling), per-engine subsections
• /save-system: save schema design, version-migration strategy, cloud-save notes; matching ADR template
• /dialogue-system: format comparison, localization key conventions (bridging /localize), VO pipeline
• /animation-pipeline: state machine / blend tree / IK decisions, capture hooks (bridging Proposal 2's screenshot receipts)

Acceptance. Each skill's outputs enter the existing GDD/ADR/story pipeline and are covered by the existing gates (no new mechanisms).
Effort. M each (2–4 days apiece, shippable individually); suggest /world-tech and /save-system first.

---

Priorities (from the maintainer's perspective)

• P0 = Proposals 1+2+3 — closure gate + receipts + config echo. The three interlock into one loop: evidence is produced by scripts, gates are executed by scripts, config is visible to both sides. Shortest path from an honor system to mechanical guarantees, fully within the existing hooks/scripts conventions, backward compatible.
• P1 = Proposals 6+5 — behavioral regression first, then touch the 44KB skills (a refactor with a CI net).
• P2 = Proposals 4+7+8(C1), plus 9 (/world-tech, /save-system first).
• P3 = 8(C2/C3/C7), plus 9 (/dialogue-system, /animation-pipeline).

Closing

One principle across all of this: new capabilities must come with their own receipts and evidence — never add another step that relies on the model's honesty. Happy to send PRs for any of these; Proposals 1+2 would be my starting point.

[Donchitos]

leave it with me mate, some absolute gold here. Will let you know about how we will go about some of these