Story ReadinessSAFE

Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: story-readiness
description: "Is a story implementation-ready? Checks clear acceptance criteria, open questions, ADR refs. READY/NEEDS WORK/BLOCKED/NOT ASSESSED."
argument-hint: "[story-file-path or 'all' or 'sprint'] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, AskUserQuestion, Agent, Bash(bash "*/.claude/skills/story-readiness/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,qa.level,testing.strict,system_overrides`

Resolved above — use as-is; `--review` overrides `review_mode`. No block →
defaults in `.claude/docs/config-resolution.md`.


# Story Readiness

This skill validates that a story file contains everything a developer needs
to begin implementation — no mid-sprint design interruptions, no guessing,
no ambiguous acceptance criteria. Run it before assigning a story.

**This skill is read-only.** It never edits story files. It reports findings
and asks whether the user wants help filling gaps.

**Output:** Verdict per story (READY / NEEDS WORK / BLOCKED / NOT ASSESSED) with a specific

> **`NOT ASSESSED` is not a synonym for `BLOCKED`.** `BLOCKED` is a
> finding about the story — a Proposed ADR, an ADR file it names that does not
> exist, an unresolved dependency — and it tells the reader exactly what to clear.
> Use `NOT ASSESSED` when the story could not be evaluated at all: the file is
> unreadable or unparseable, a referenced ADR exists but has no readable
> `## Status` (malformed), or a referenced design document cannot be located, so
> the checks below cannot run. Collapsing that into `BLOCKED` reports a blocker
> that does not exist and hides the one that does — the reader chases a phantom
> blocker instead of the unreadable file.
> `READY` must never be reachable for a story that was not actually evaluated.
>
> **Precedence — first matching rule wins**, in this order: **BLOCKED**, then
> **NEEDS WORK**, then **NOT ASSESSED**, then **READY**. `NOT ASSESSED` outranks
> `READY` (a story that could not be evaluated has not been shown ready) and
> ranks **below** both failure verdicts (a known blocker is more actionable than
> an unknown, and demoting it behind an access problem buries it). A story with
> both a real blocker and an unevaluable check is `BLOCKED` — the blocker is the
> actionable finding. This half of the rank has to be stated: the rule above
> establishes only that `READY` is unreachable, which would leave the ordering
> against `BLOCKED` to inference.
gap list for each non-ready story.

---

## Phase 0: Resolve Review Mode


See `.claude/docs/director-gates.md` for the full check pattern and mode definitions. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.


Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
(collaborative asks always · guided major-only · autonomous logs and proceeds;
`automation_always_ask` categories always prompt).

**Resolve the workflow tier per story** (per `.claude/docs/workflow-modes.md`):
for the system a story belongs to (**the GDD filename stem** of its `GDD:` path;
the `[system]` segment of a `TR-[system]-NNN` ID is a fallback alias only), use the
`system_overrides` row for that system if the block lists one, else the
project value. When validating multiple stories (`all` / `sprint` scope),
resolve **per story** — different systems may sit at different tiers. The tier
sets which checklist sections block — see the note in Section 3.

**`qa.level`**: controls whether a test requirement is
validated. At `minimal`, the "Test evidence requirement is clear" item
auto-passes (no requirement validated); at `standard`, validate the per-type test
requirement (strictness from `testing.strict`); at `full`, also validate a
coverage target. Distinct axis from `workflow`. **UI and Visual/Feel stories are
the exception at `minimal`:** their retained screenshot is required at every
`qa.level`, so for them the item is still validated — the tests are waived, the
look is not.

---

## 1. Parse Arguments

**Scope:** `$ARGUMENTS` with any `--review <mode>` pair removed (blank = ask user via AskUserQuestion). What remains is one value — a path may contain spaces.

- **Specific path** (e.g., `/story-readiness production/epics/combat/story-001-basic-attack.md`):
  validate that single story file.
- **`sprint`**: read the current sprint plan from `production/sprints/` (most
  recent file), extract every story path it references, validate each one.
- **`all`**: glob `production/epics/**/*.md`, exclude `EPIC.md` index files,
  validate every story file found.
- **No argument**: ask the user which scope to validate.

If no argument is given, use `AskUserQuestion`:
- "What would you like to validate?"
  - Options: "A specific story file", "All stories in the current sprint",
    "All stories in production/epics/", "Stories for a specific epic"

Report the scope before proceeding: "Validating [N] story files."

> **If the scope resolves to ZERO story files, stop and report
> `NOT ASSESSED — no stories in scope`.** Name which scope was searched and
> which path was empty (`production/epics/**/*.md`, the sprint file's story
> list, or the specific path given), and route: `/create-epics [layer]` then
> `/create-stories [epic-slug]`.
>
> **The zero-scope path is mandatory.** Without it an empty glob falls through
> to the Section 5 aggregate template and renders `Ready: 0 /
> Needs Work: 0 / Blocked: 0` above an empty list — **indistinguishable from
> "I checked every story and none needed work"**. It is the core failure of this
> framework exactly: a scan that finds nothing because there was nothing to
> scan, reported the same way as a clean result. Three zeros read as a healthy
> sprint.
>
> Note what made this survive: `NOT ASSESSED` was already in this skil

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.