ksh999000/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios.git synced 2026-10-17 10:47:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Release 1.1.2 — the default path works end to end

Browse Source 
Fix release for 1.1.1: the minimal path end to end, engine commands that
run on Godot, Unity and Unreal, hook warnings you can see, and verdicts
that say when they could not check. Details in CHANGELOG.md; upgrade
steps in UPGRADING.md (v1.1.1 → v1.1.2).

Fixes #67
Fixes #131

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
This commit is contained in:
Donchitos
2026-09-29 21:32:19 +10:00
co-authored by Claude Opus 5.5
parent 7ed2c3e9c4
commit b21fa0f7f2
383 changed files with 22888 additions and 10618 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CCGS Skill Testing Framework/skills/readiness/story-readiness.md
+178 -100
View File
@@ -3,22 +3,34 @@
## Skill Summary
`/story-readiness` validates that a story file is ready for a developer to
pick up and implement. It checks four dimensions: Design (embedded GDD
requirements), Architecture (ADR references and status), Scope (clear
boundaries and DoD), and Definition of Done (testable criteria). It produces
a READY / NEEDS WORK / BLOCKED verdict. It is a read-only skill and runs
before any developer picks up a story.
pick up and implement. It loads its reference context once (systems index,
the control manifest's `Manifest Version:` header, the TR registry, and every
ADR's status via a single Grep), then evaluates each story against six
checklist groups: Design Completeness, Architecture Completeness, Scope
Clarity, Open Questions, Asset References, and Definition of Done. The workflow
tier resolved for the story's system decides which groups block (`full`: all;
`standard`: architecture items advisory except a critical ADR; `minimal`:
architecture N/A) — except one rule at every tier: an ADR the story references that
is missing, `Proposed`, `Deprecated` or `Superseded` BLOCKS, because `/dev-story`
stops on it. At `minimal`, `design/game-brief.md` stands in for the GDD. It produces a READY / NEEDS WORK / BLOCKED / NOT ASSESSED
verdict. It is read-only — it never writes or edits a file. In `full` review
mode it then runs the QL-STORY-READY gate (`qa-lead`).
A fixture that sets neither `qa.level` nor `modes.rigor` resolves `qa.level:
minimal` (the `rigor: minimal` default). There the evidence item auto-passes for
Logic, Integration and Config/Data stories — never for UI or Visual/Feel, whose
retained screenshot is required at every `qa.level` (Case 6).
---
## Static Assertions (Structural)
Verified automatically by `/skill-test static` — no fixture needed.
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 or numbered check sections
- [ ] Contains verdict keywords: READY, NEEDS WORK, BLOCKED
- [ ] Does NOT require "May I write" language (read-only skill)
- [ ] Contains verdict keywords: READY, NEEDS WORK, BLOCKED, NOT ASSESSED
- [ ] Does NOT require "May I write" language — `allowed-tools` has no Write or Edit
- [ ] Has a next-step handoff (what to do after verdict)
---
@@ -28,168 +40,234 @@ Verified automatically by `/skill-test static` — no fixture needed.
### Case 1: Happy Path — Fully ready story
**Fixture:**
- Story file exists at `production/epics/core/story-light-pickup.md`
- Story contains:
- `TR-ID: TR-light-001` (GDD requirement reference)
- `ADR: docs/architecture/adr-003-inventory.md`
- Referenced ADR exists and has status `Accepted`
- Referenced TR-ID exists in `docs/architecture/tr-registry.yaml`
- Story has `## Acceptance Criteria` with ≥3 testable items
- Story has `## Definition of Done` section
- Story has `Status: Ready for Dev`
- Manifest version in story header matches current `docs/architecture/control-manifest.md`
- `project.yaml` sets `modes.workflow: full` and `modes.review_mode: solo`
- Story file exists at `production/epics/core/story-light-pickup.md` containing:
- A `GDD: design/gdd/light-system.md` reference quoting the specific requirement
- `TR-light-001`, present with `status: active` in `docs/architecture/tr-registry.yaml`
- `ADR: ADR-0003`; `docs/architecture/adr-0003-inventory.md` has `## Status` Accepted
- `Type: Logic`, an `## Acceptance Criteria` section with 3 testable items, and a `## Test Evidence` section naming the test path
- An estimate, an Out of Scope statement, and `Dependencies: None`
- Engine notes (or "N/A — no engine API involved"), the relevant manifest rules, and a performance note
- A `Manifest Version:` equal to the one in `docs/architecture/control-manifest.md`
- No TBD / UNRESOLVED markers and no asset paths
- A sprint plan in `production/sprints/` lists other stories
**Input:** `/story-readiness production/epics/core/story-light-pickup.md`
**Expected behavior:**
1. Skill reads the story file
2. Skill reads the referenced ADR — verifies status is `Accepted`
3. Skill reads `docs/architecture/tr-registry.yaml` — verifies TR-ID exists
4. Skill reads `docs/architecture/control-manifest.md` — verifies manifest version matches
5. Skill evaluates all 4 dimensions (Design, Architecture, Scope, DoD)
6. Skill outputs READY verdict with all checks passing
1. Skill reports "Validating 1 story files."
2. Skill loads context once: greps `Manifest Version` from the control manifest,
indexes `tr-registry.yaml`, and resolves every ADR status with one
`Grep pattern="^## Status" glob="docs/architecture/adr-*.md"` scan
3. Skill evaluates all six checklist groups
4. Skill outputs READY with all checks passing
5. Phase 8 notes "QL-STORY-READY skipped — Solo mode."
6. Section 7 surfaces other ready stories from the sprint
**Assertions:**
- [ ] Skill reads the referenced ADR file (not just the story)
- [ ] Skill verifies ADR status is `Accepted` (not `Proposed`)
- [ ] Skill reads `tr-registry.yaml` to verify TR-ID exists
- [ ] Output includes check results for all 4 dimensions
- [ ] ADR status is resolved from the one-scan `^## Status` Grep over `docs/architecture/adr-*.md`, not by reading each ADR in full, and ADR-0003 is found Accepted
- [ ] Skill looks up `TR-light-001` in `tr-registry.yaml` and finds it active
- [ ] The current manifest version is taken from a Grep of the manifest header, not a full read
- [ ] The "Passing Checks (N/[total])" section names all six groups — Design Completeness, Architecture Completeness, Scope Clarity, Open Questions, Asset References ("no asset references"), Definition of Done — with the passing items under each
- [ ] Verdict is READY when all checks pass
- [ ] Skill does not write any files
- [ ] Section 7 lists up to 3 other ready sprint stories — or states "Next ready stories: no sprint file found" / "none ready in [sprint]" rather than omitting the section
---
### Case 2: Blocked Path — Referenced ADR is Proposed (not Accepted)
**Fixture:**
- Story file exists with `ADR: docs/architecture/adr-005-light-system.md`
- `adr-005-light-system.md` exists but has `Status: Proposed`
- All other story content is otherwise complete
- `project.yaml` sets `modes.workflow: full`
- Story `production/epics/core/story-light-system.md` references `ADR-0005`
- `docs/architecture/adr-0005-light-system.md` exists with `## Status` Proposed
- All other story content is complete
**Input:** `/story-readiness production/epics/core/story-light-system.md`
**Expected behavior:**
1. Skill reads the story
2. Skill reads `adr-005-light-system.md` — finds `Status: Proposed`
3. Skill flags this as a BLOCKING issue (cannot implement against unaccepted ADR)
4. Skill outputs BLOCKED verdict
5. Skill recommends: accept or reject the ADR before picking up the story
1. The status scan finds ADR-0005 `Proposed`
2. Skill flags it BLOCKED with the fix text "BLOCKED: ADR-0005 is Proposed — wait for acceptance before implementing."
3. Skill outputs BLOCKED, listing the ADR under Blockers
**Assertions:**
- [ ] Verdict is BLOCKED (not NEEDS WORK or READY) when ADR is Proposed
- [ ] Output explicitly names the Proposed ADR as the blocker
- [ ] Output recommends resolving ADR status before proceeding
- [ ] Verdict is BLOCKED (not NEEDS WORK or READY) when the ADR is Proposed at `full`
- [ ] Output explicitly names ADR-0005 as the blocker
- [ ] Output says to wait for the ADR's acceptance before implementing
- [ ] Skill does not output READY regardless of other checks passing
- [ ] Variant — same story at `modes.workflow: standard`, with `| **Layer** | Feature |` in ADR-0005's `## Engine Compatibility` table (non-critical): the story references the Proposed ADR, so the verdict is still BLOCKED — a referenced Proposed ADR blocks at every tier, because `/dev-story` stops on it
- [ ] Variant — the same non-critical ADR at `standard`, now `Accepted`, with the story's `Manifest Version:` older than the control manifest's: the stale version is listed under Gaps as advisory, with its `Fix:` line, and the verdict is READY — an advisory gap does not downgrade it
---
### Case 3: Needs Work — Missing Acceptance Criteria
### Case 3: Needs Work — Missing Acceptance Criteria (checked at every tier)
**Fixture:**
- Story file exists but has no `## Acceptance Criteria` section
- ADR reference exists and is `Accepted`
- TR-ID exists in registry
- Manifest version matches
- `project.yaml` sets `modes.workflow: minimal`
- Story `production/epics/core/story-oxygen-drain.md` has `Type: Logic` but no `## Acceptance Criteria` section
- The story references no ADR, no TR-ID and no manifest version
**Input:** `/story-readiness production/epics/core/story-oxygen-drain.md`
**Expected behavior:**
1. Skill reads the story
2. Skill finds no Acceptance Criteria section
3. Skill flags this as a NEEDS WORK issue (story is incomplete, not blocked)
4. Skill outputs NEEDS WORK verdict
5. Skill names the missing section and suggests adding measurable criteria
1. At `minimal`, skill evaluates Design Completeness and Scope Clarity and treats Architecture Completeness as N/A
2. Skill finds no acceptance criteria
3. Skill outputs NEEDS WORK, naming the gap with a `Fix:` line suggesting specific, observable criteria
**Assertions:**
- [ ] Verdict is NEEDS WORK (not BLOCKED or READY) when Acceptance Criteria section is absent
- [ ] Output identifies the missing Acceptance Criteria section specifically
- [ ] Output suggests adding testable/measurable criteria
- [ ] Skill distinguishes NEEDS WORK (fixable without external dependencies) from BLOCKED (requires outside action)
- [ ] Verdict is NEEDS WORK (not BLOCKED or READY) when the Acceptance Criteria section is absent
- [ ] Output identifies the missing Acceptance Criteria specifically, with a `Fix:` line proposing measurable criteria
- [ ] No ADR, TR-ID or manifest gap is flagged — Architecture Completeness is N/A at `minimal`
- [ ] The story is not BLOCKED: nothing requires outside action (no missing/DRAFT dependency, no unowned UNRESOLVED question)
- [ ] Variant — the same `minimal` story with acceptance criteria traced to `design/game-brief.md`'s MVP feature (no `design/gdd/` path): "GDD requirement referenced" passes — the brief stands in for the GDD at `minimal`
- [ ] Variant — the story also names `ADR-0005`, whose `## Status` is `Proposed`: the verdict is BLOCKED at `minimal` too — the referenced-ADR rule is the one Architecture Completeness item that is not N/A
---
### Case 4: Edge Case — Stale manifest version
**Fixture:**
- Story file has `Manifest Version: 2026-01-15` in its header
- `project.yaml` sets `modes.workflow: full`
- Story has `Manifest Version: 2026-01-15` in its header
- `docs/architecture/control-manifest.md` has `Manifest Version: 2026-03-10`
- Versions do not match (story was created before manifest was updated)
- Everything else in the story passes
**Input:** `/story-readiness production/epics/core/story-mirror-rotation.md`
**Expected behavior:**
1. Skill reads the story and extracts manifest version `2026-01-15`
2. Skill reads control manifest header and extracts current version `2026-03-10`
3. Skill detects version mismatch
4. Skill flags this as an ADVISORY issue (not blocking, but worth noting)
5. Verdict is NEEDS WORK with manifest staleness noted
1. Skill extracts `2026-01-15` from the story
2. Skill greps the manifest header and extracts `2026-03-10`
3. The story's version is older → the "Manifest version is current" item fails
4. Verdict is NEEDS WORK, with the fix to review the changed rules and update the story's `Manifest Version:`
**Assertions:**
- [ ] Skill reads `docs/architecture/control-manifest.md` to get current version
- [ ] Skill compares story's embedded manifest version against current manifest version
- [ ] Stale manifest version results in NEEDS WORK (not BLOCKED, not READY)
- [ ] Output explains that the story's embedded guidance may be outdated
---
- [ ] Skill gets the current version by grepping `Manifest Version` in `docs/architecture/control-manifest.md`
- [ ] Skill compares the story's embedded version against the current one
- [ ] At `full`, a stale manifest version results in NEEDS WORK (not BLOCKED, not READY)
- [ ] Output explains that new manifest rules may apply, and the `Fix:` says to review the changed rules, update the story if needed, then set its `Manifest Version:` to current
---
### Case 5: Director Gate — QL-STORY-READY behavior across review modes
**Fixture:**
- Story file exists and is READY (all 4 dimensions pass, ADR Accepted, criteria present)
- `production/session-state/review-mode.txt` exists
- `project.yaml` sets `modes.workflow: full`
- Story file exists and passes every checklist item
- Review mode comes from `modes.review_mode` (legacy mirror `production/review-mode.txt`) or `--review`
**Case 5a — full mode:**
- `review-mode.txt` contains `full`
**Input:** `/story-readiness production/epics/core/story-light-pickup.md` (full mode)
**Case 5a — full mode:** `/story-readiness production/epics/core/story-light-pickup.md --review full`
**Expected behavior:**
1. Skill reads review mode — determines `full`
2. After completing its own 4-dimension check, skill invokes QL-STORY-READY gate
3. QA lead reviews the story for readiness
4. If QA lead verdict is INADEQUATE → story verdict is BLOCKED regardless of 4-dimension result
5. If QA lead verdict is ADEQUATE → verdict proceeds normally
1. Skill completes its own checklist and verdict first
2. Skill spawns `qa-lead` via `Agent` with gate QL-STORY-READY, passing the story
file path, story type, acceptance criteria (verbatim), the GDD requirement
(TR-ID and text), dependency status and the Phase 4 verdict
3. ADEQUATE → story cleared
4. GAPS → `AskUserQuestion`: `Update story with suggested gaps` / `Accept and proceed anyway` / `Discuss further`
5. INADEQUATE → the gate says the story must be revised before sprint inclusion:
the checklist's READY is demoted to NEEDS WORK and the final verdict line is
restated with the gaps; the user is asked whether to update the story or
proceed anyway, and proceeding is recorded as an override, not as READY
6. NOT ASSESSED (a gate input was missing) → the missing input is named and never
read as ADEQUATE: it is supplied and the gate re-run, or READY becomes NOT ASSESSED
**Assertions (5a):**
- [ ] Skill reads review mode before deciding whether to invoke QL-STORY-READY
- [ ] QL-STORY-READY gate is invoked in full mode after the 4-dimension check completes
- [ ] A QA lead INADEQUATE verdict overrides a READY 4-dimension result → final verdict BLOCKED
- [ ] Gate invocation is noted in output: "Gate: QL-STORY-READY — [result]"
- [ ] Skill uses the resolved review mode before deciding whether to spawn QL-STORY-READY
- [ ] QL-STORY-READY is spawned only after the checklist verdict exists
- [ ] A GAPS result produces the three-option `AskUserQuestion`
- [ ] An INADEQUATE result overrides the checklist's READY: the final verdict is NEEDS WORK, restated with the gate's specific gaps
- [ ] If the user proceeds anyway, the verdict stays NEEDS WORK and the output states the override ("proceeding despite QL-STORY-READY: INADEQUATE (user override)") — never a silent READY
- [ ] A NOT ASSESSED answer from the gate names the missing input and never leaves READY standing: unless the input is supplied and the gate re-run, the verdict is NOT ASSESSED
**Case 5b — lean or solo mode:**
- `review-mode.txt` contains `lean` or `solo`
**Case 5b — lean or solo mode:** `--review lean` or `--review solo`
**Expected behavior:**
1. Skill reads review mode — determines `lean` or `solo`
2. QL-STORY-READY gate is SKIPPED
3. Output notes the skip: "[QL-STORY-READY] skipped — Lean/Solo mode"
4. Verdict is based on 4-dimension check only
1. QL-STORY-READY is skipped
2. Output notes "QL-STORY-READY skipped — Lean mode." or "QL-STORY-READY skipped — Solo mode."
3. Verdict is based on the checklist only
**Assertions (5b):**
- [ ] QL-STORY-READY gate does NOT spawn in lean or solo mode
- [ ] Skip is explicitly noted in output
- [ ] Verdict is based on 4-dimension check alone
- [ ] QL-STORY-READY does NOT spawn in lean or solo mode
- [ ] The skip is noted in the output with the mode named
- [ ] Verdict is based on the checklist alone
---
### Case 6: UI story at `qa.level: minimal` — the screenshot plan is never waived
**Fixture:**
- `project.yaml` sets `modes.workflow: standard` and `qa.level: minimal` (set on
its own, so only the test-evidence axis is at `minimal` and every checklist
group is evaluated)
- No `docs/architecture/control-manifest.md` and no `tr-registry.yaml` yet
- Story `production/epics/ui/story-003-shop-panel.md` has `Type: UI`, a
`GDD: design/gdd/shop.md` reference quoting the requirement it implements, two
testable acceptance criteria naming what the shop panel shows, "No ADR applies —
pure layout", engine notes, an estimate, an Out of Scope statement,
`Dependencies: None` and a performance note — and no `## Test Evidence` section,
nor any other mention of where a screenshot will go
- No TBD / UNRESOLVED markers and no asset paths
**Input:** `/story-readiness production/epics/ui/story-003-shop-panel.md`
**Expected behavior:**
1. The architecture items pass or auto-pass (explicit "No ADR applies"; no
TR-ID, manifest version or manifest to check)
2. The "Test evidence requirement is clear" item still applies — UI is the
exception to the `qa.level: minimal` auto-pass
3. `testing.strict.ui` is unset, so the item is strict by default: the missing
section makes the story NEEDS WORK
4. The `Fix:` asks for a `## Test Evidence` section naming where the retained
screenshot of each screen touched will go under `production/qa/evidence/`
**Assertions:**
- [ ] Verdict is NEEDS WORK, not READY — the evidence item does not auto-pass for a UI story at `qa.level: minimal`
- [ ] The gap names the missing screenshot plan, and its `Fix:` points at `production/qa/evidence/`
- [ ] The missing screenshot plan is the only gap — no ADR, TR-ID or manifest gap is flagged
- [ ] Variant — a `Type: Logic` story with three testable criteria and no `## Test Evidence` section, same config: the evidence item auto-passes at `qa.level: minimal`, so the missing section alone does not make it NEEDS WORK
---
### Case 7: NOT ASSESSED — nothing to evaluate, or an ADR nobody can read
**Case 7a — zero stories in scope:**
- `production/epics/` holds only `EPIC.md` index files, no story files
- **Input:** `/story-readiness all`
**Assertions (7a):**
- [ ] Output is `NOT ASSESSED — no stories in scope`, naming `production/epics/**/*.md` as the path searched
- [ ] It routes to `/create-epics [layer]` then `/create-stories [epic-slug]`
- [ ] No `Ready: 0 / Needs Work: 0 / Blocked: 0` summary is printed over an empty list
**Case 7b — a referenced ADR with no readable status:**
- `project.yaml` sets `modes.workflow: full`
- Story `production/epics/core/story-save-slots.md` passes every other item and
references `ADR-0007`; `docs/architecture/adr-0007-save-format.md` exists but has
no `## Status` section
- **Input:** `/story-readiness production/epics/core/story-save-slots.md`
**Assertions (7b):**
- [ ] The ADR check is NOT ASSESSED — the status is unknown, not failed — and the verdict is NOT ASSESSED: not BLOCKED, not READY
- [ ] Output names `docs/architecture/adr-0007-save-format.md` and routes to `/architecture-decision retrofit docs/architecture/adr-0007-save-format.md`
- [ ] Variant — the story names `ADR-0007` but no such file exists: that is a finding about the story, so the verdict is BLOCKED ("referenced ADR is missing"), not NOT ASSESSED
---
## Protocol Compliance
- [ ] Does NOT use Write or Edit tools (read-only skill)
- [ ] Presents complete check results before verdict
- [ ] Does not ask for approval (no file writes)
- [ ] Ends with recommended next step (fix issues or proceed to implementation)
- [ ] Distinguishes three verdict levels clearly (READY vs NEEDS WORK vs BLOCKED)
- [ ] Does NOT use Write or Edit tools; any help filling gaps is drafted in conversation only
- [ ] Single-story output follows the Section 5 template: Verdict line, "Passing Checks (N/[total])", Gaps each with a `Fix:` line, and Blockers when BLOCKED
- [ ] Does not ask for write approval (no file writes)
- [ ] Ends with a recommended next step (fix the gaps, or `/dev-story [story-path]` once READY)
- [ ] Keeps the verdict levels distinct — NOT ASSESSED (could not evaluate) is never reported as BLOCKED
---
## Coverage Notes
- Case where TR-ID is missing from the registry entirely is not explicitly
tested here; it follows the same NEEDS WORK pattern as Case 3.
- The "no argument" path (skill auto-detecting the current story) is not
tested because it depends on `production/session-state/active.md` content,
which is hard to fixture reliably.
- A TR-ID missing from the registry follows the same NEEDS WORK pattern as Case 4.
- The zero-story scope is Case 7a; the `sprint` / `all` aggregate output over real
stories and the Must Have sprint escalation warning are not tested here.
- The no-argument path (scope chosen via `AskUserQuestion`) is not tested.
- Stories with multiple ADR references are not tested; behavior is assumed to
be additive (all ADRs must be Accepted for READY verdict).