mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 09:58:36 +00:00
DonchitosandClaude Opus 5.5
b21fa0f7f2
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
80 lines
6.3 KiB
Markdown
80 lines
6.3 KiB
Markdown
# /story-readiness — Handoff Contract
|
|
|
|
## Role in Pipeline
|
|
Validates that a story file contains everything a developer needs to begin
|
|
implementation and produces a READY / NEEDS WORK / BLOCKED / NOT ASSESSED verdict — sits between
|
|
`/create-stories` and `/dev-story`, acting as a blocking gate before any code is written.
|
|
|
|
## Inputs Required
|
|
|
|
### Files That Must Exist
|
|
| File | Required Fields / Sections | Read-Only? |
|
|
|------|---------------------------|-----------|
|
|
| `production/epics/[epic-slug]/story-NNN-[slug].md` | All header fields (`Status:`, `Layer:`, `Type:`, `Manifest Version:`), `## Context` (GDD path, TR-ID, ADR reference, Engine Notes, Control Manifest Rules), `## Acceptance Criteria`, `## Test Evidence`, `## Dependencies`, `## Out of Scope` | Yes |
|
|
| `docs/architecture/control-manifest.md` | `Manifest Version:` date in header, layer rules | Yes (if exists) |
|
|
| `docs/architecture/tr-registry.yaml` | `id`, `status` fields per TR entry | Yes (if exists) |
|
|
| `docs/architecture/adr-NNNN-[slug].md` (all ADRs referenced in stories) | `Status:` field | Yes |
|
|
| `design/gdd/systems-index.md` | Which systems have approved GDDs | Yes |
|
|
|
|
> **Tier.** The manifest, TR registry, ADR and systems-index rows are
|
|
> `standard`/`full` inputs. At `workflow: minimal` the skill is not on the path
|
|
> (`/dev-story` follows `/create-stories` directly); run anyway, it checks
|
|
> acceptance criteria and scope only and treats Architecture Completeness as N/A
|
|
> except the referenced-ADR rule: an ADR the story references that is missing,
|
|
> `Proposed`, `Deprecated` or `Superseded` BLOCKS at every tier (SKILL.md, the tier note above Design
|
|
> Completeness).
|
|
|
|
### Preconditions
|
|
- The story file being validated was produced by `/create-stories` (or follows the same format)
|
|
- For `sprint` scope: a sprint file exists in `production/sprints/` with story path references
|
|
- For `all` scope: `production/epics/` directory exists and contains story files
|
|
|
|
## Outputs Produced
|
|
|
|
### Files Written
|
|
None. This skill is strictly read-only and produces no file modifications under any circumstance.
|
|
|
|
### Output Guarantees
|
|
- A verdict of READY, NEEDS WORK, BLOCKED or NOT ASSESSED is produced for every story file evaluated. `NOT ASSESSED` is not a synonym for `BLOCKED`: BLOCKED names a real, listable obstacle, while NOT ASSESSED means the story could not be evaluated at all. An empty scope yields `NOT ASSESSED — no stories in scope`, never a `Ready: 0 / Needs Work: 0 / Blocked: 0` summary over an empty list
|
|
- Every non-READY verdict includes a specific gap list with fix instructions for each failing checklist item
|
|
- Every BLOCKED verdict names the specific blocker (missing dependency story path, Proposed ADR ID, or unresolved design question marker)
|
|
- For `sprint` scope: a sprint-level escalation warning is prepended if any Must Have story is not READY (NEEDS WORK, BLOCKED or NOT ASSESSED)
|
|
- The skill offers to draft missing sections in conversation but never uses Write or Edit tools
|
|
|
|
## Immutability Rules
|
|
- READS but does NOT modify: story files, `docs/architecture/control-manifest.md`, `docs/architecture/tr-registry.yaml`, all ADR files, `design/gdd/systems-index.md`, sprint files, any referenced asset files (existence-only Glob checks)
|
|
- MODIFIES: nothing
|
|
|
|
## Hard Constraints (Never Violate)
|
|
- Never use Write or Edit tools under any circumstances
|
|
- Never draft corrections directly into files — offer drafts in conversation only
|
|
- Never mark a story READY if its governing ADR has `Status: Proposed`, `Deprecated` or `Superseded`, at any tier
|
|
- Never mark a story READY if a dependency story file is missing or has `Status: Draft`
|
|
- Never re-read the same ADR file multiple times in one run — cache ADR statuses after the first read
|
|
- Never penalize a story for missing `Manifest Version:` if `control-manifest.md` does not exist
|
|
- Never penalize a story for missing TR-ID if `tr-registry.yaml` does not exist
|
|
|
|
## Downstream Skill Expects
|
|
**Next skill:** /dev-story
|
|
|
|
It will rely on this skill's verdict as follows:
|
|
- If verdict is READY: `/dev-story` proceeds with implementation using the story file as its source of truth
|
|
- If verdict is NEEDS WORK, BLOCKED or NOT ASSESSED: `/dev-story` must not be run until the story is corrected (or, for NOT ASSESSED, made readable) and re-validated — a story nobody could evaluate has not been shown ready
|
|
- `/dev-story` reads the same story fields this skill validates — a READY verdict is an implicit guarantee that those fields are present, parseable, and internally consistent:
|
|
- `Type:` field is set to a valid story type
|
|
- `## Acceptance Criteria` contains specific, testable checkbox items
|
|
- `## Test Evidence` specifies a concrete evidence path
|
|
- The governing ADR exists and has `Status: Accepted`
|
|
- `Manifest Version:` matches the current control manifest
|
|
- `TR-ID` in `## Context` is present and resolves in `docs/architecture/tr-registry.yaml` (when the registry exists)
|
|
- `## Dependencies` section is present (may say "None")
|
|
- `## Out of Scope` section is present (checked for existence; `/dev-story` uses it to enforce implementation boundaries)
|
|
|
|
## Known Fragile Points
|
|
- If `control-manifest.md` is regenerated with a new `Manifest Version:` date, every story that embeds the old date will fail the manifest version check — a bulk update of all story `Manifest Version:` fields is required before stories can pass readiness again
|
|
- If an ADR is silently renamed or moved after stories reference it by ID, the ADR file-existence check will BLOCK those stories even though the decision content is unchanged
|
|
- The manifest version comparison is a string date match, not a semantic version comparison — if the date format changes (e.g., from `2026-01-15` to `Jan 15 2026`), all stories will fail the check regardless of actual currency
|
|
- Asset existence checks use Glob — on Windows, path separator mismatches (`\` vs `/`) may cause a Glob miss that incorrectly flags an asset as missing
|
|
- The TR-ID status check auto-passes if the registry does not exist, which means stories written before TR tracking was introduced will always pass this check even if they contain invalid or placeholder IDs like `TR-[system]-???`
|
|
- For `sprint` scope, the skill depends on sprint file formatting to extract story paths — if the sprint file format changes, story paths may not be parsed and the scope silently reduces to zero stories validated
|