mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 09:58:36 +00:00
Release 1.1.0 — one config file, and a process weight you choose
`project.yaml` at the repo root is now the single source of truth for a project's configuration, replacing `production/stage.txt`, `production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all three still read as a fallback; nothing is force-deleted). **`modes.rigor` — one question instead of six.** `minimal`, `standard` or `full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to `minimal`, which is a change from 1.0's behaviour: the heavier tier was measured costing several times more to reach working code without producing a better result, and returning nothing when a fresh developer inherited the project. Pin `modes.rigor: standard` to keep 1.0's process level. Also in this release: - `/settings` to view or change any setting, and `project.local.yaml` for per-developer preferences that should not be committed. - `system_overrides` to hold one system to a higher standard than the rest of the project, and `testing.strict` to set per test type whether missing evidence blocks a story or warns. - A story that changes anything the player sees is not closed until the game has been launched, observed, and a screenshot retained in `production/qa/evidence/`. A parse check is not a run. This holds at every rigor level, including `minimal`, where automated tests are waived but the look is not. - The code root is engine-specific and enforced as such: Godot `src/`, Unity `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a project laid out any other way. - Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh` converts a 1.0 layout, non-destructively by default, with a report to review before `--finalize` deletes anything. - Ask-before-write holds regardless of personal automation settings. Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes: CHANGELOG.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5
Claude Opus 5
parent
984023ddac
commit
d05699707f
@@ -1,17 +1,40 @@
|
||||
---
|
||||
name: design-review
|
||||
description: "Reviews a game design document for completeness, internal consistency, implementability, and adherence to project design standards. Run this before handing a design document to programmers."
|
||||
argument-hint: "[path-to-design-doc] [--depth full|lean|solo]"
|
||||
description: "Reviews one design document for completeness, internal consistency, implementability, and design standards. Before handing to programmers."
|
||||
argument-hint: "[path-to-design-doc] [--review full|lean|solo]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion
|
||||
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
!`source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh" 2>/dev/null && resolve_config --keys review_mode,automation,workflow,system_overrides`
|
||||
|
||||
Resolved above — use as-is; `--review` overrides `review_mode`. No block →
|
||||
defaults in `.claude/docs/config-resolution.md`.
|
||||
|
||||
|
||||
## Phase 0: Parse Arguments
|
||||
|
||||
Extract `--depth [full|lean|solo]` if present. Default is `full` when no flag is given.
|
||||
|
||||
**Note**: `--depth` controls the *analysis depth* of this skill (how many specialist agents are spawned). It is independent of the global review mode in `production/review-mode.txt`, which controls director gate spawning. These are two different concepts — `--depth` is about how thoroughly *this* skill analyses the document.
|
||||
See `.claude/docs/director-gates.md` for the full check pattern. 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).
|
||||
|
||||
**`workflow`** for the GDD under review — use the `system_overrides` row for `<system>` if the block lists one, else the project value. Validation scope follows the tier:
|
||||
- `full` — all 8 sections validated; any missing section blocks approval.
|
||||
- `standard` — the 5 required sections (Overview, Detailed Rules, Edge Cases,
|
||||
Dependencies, Acceptance Criteria) block if missing; Formulas blocks only when
|
||||
the system defines numeric rules (rates, curves, thresholds, costs — the
|
||||
category is a hint, not the test); Player Fantasy and
|
||||
Tuning Knobs are advisory (warn, never block) unless `workflow_overrides`
|
||||
require them.
|
||||
- `minimal` — no GDD is expected; if one exists, validate the 5 standard
|
||||
sections advisorily.
|
||||
|
||||
Resolved mode controls how thorough this review is:
|
||||
|
||||
- **`full`**: Complete review — all phases + specialist agent delegation (Phase 3b)
|
||||
- **`lean`**: All phases, no specialist agents — faster, single-session analysis
|
||||
@@ -21,7 +44,68 @@ Extract `--depth [full|lean|solo]` if present. Default is `full` when no flag is
|
||||
|
||||
## Phase 1: Load Documents
|
||||
|
||||
Read the target design document in full. Read CLAUDE.md to understand project context and standards. Read related design documents referenced or implied by the target doc (check `design/gdd/` for related systems).
|
||||
**Freshness check first — a re-review of an unchanged document costs full
|
||||
price (~46k tokens, measured) and reproduces the same verdict.** Run:
|
||||
|
||||
```
|
||||
Bash: bash .claude/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml"
|
||||
```
|
||||
|
||||
The registry is in the check because this review consults it for
|
||||
cross-document facts — an unchanged GDD reviewed against a *changed*
|
||||
registry can reach different conclusions, so the skip is only safe when
|
||||
**every** listed line reads `UNCHANGED` (an absent registry simply doesn't
|
||||
appear in the output and doesn't block the skip).
|
||||
|
||||
- **All `UNCHANGED`** and the log's latest entry carries a verdict — surface it:
|
||||
*"This document is byte-identical to its last review on [date] (verdict:
|
||||
[verdict])."* If that verdict was APPROVED, offer via `AskUserQuestion`:
|
||||
`[A] Use the prior verdict (Recommended)` / `[B] Re-review anyway` —
|
||||
`guided` proceeds with [A] and notes it; `autonomous` logs via
|
||||
`log_decision` and uses the prior verdict. If it was NEEDS REVISION or
|
||||
MAJOR REVISION NEEDED, say so plainly: the document has not changed since
|
||||
it failed review — the prior findings stand; revising the document is the
|
||||
next step, not re-reviewing it. Offer to display the prior findings from
|
||||
the log.
|
||||
- **Only the registry line reads `CHANGED`** (doc `UNCHANGED`) — the prior
|
||||
verdict stands except for cross-document facts: re-verify the doc's
|
||||
registry-sourced values against the new registry and re-issue the verdict;
|
||||
escalate to a full re-review only if a conflict appears.
|
||||
- **Target doc `CHANGED` or `NEW`, or `RECEIPT: NONE`** — proceed with the
|
||||
full review below. **Do not offer a partial/delta re-review that skips
|
||||
reading or re-analyzing unchanged sections.** Measured against a full review:
|
||||
three independent designs (a straightforward section-scoped pass, one with
|
||||
an explicit forced whole-document scan step, and one gated on a
|
||||
genuinely thorough two-round prior review) each caught only 2 of 6 real
|
||||
defects a full review found on the same document, and the most
|
||||
careful version cost *more* tokens than the full review while catching
|
||||
the same reduced fraction. "Unchanged since last review" only means
|
||||
byte-identical to what was reviewed then — it says nothing about whether
|
||||
that prior pass was itself complete, and no amount of "scan everything
|
||||
anyway" instruction reliably overcame a model's attention naturally
|
||||
narrowing to the flagged change.
|
||||
|
||||
Read the target design document in full. Read CLAUDE.md to understand project context and standards.
|
||||
|
||||
**For cross-document facts, prefer the registry over sibling GDDs.** If
|
||||
`design/registry/entities.yaml` exists **and lists entries for this system**,
|
||||
grep it — these are the established facts this GDD must not contradict, and they
|
||||
replace reading sibling GDDs to rediscover them:
|
||||
```
|
||||
Grep pattern="source: design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -A 6
|
||||
Grep pattern="design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -B 8
|
||||
```
|
||||
The first finds entries this system **owns** — the `-A 6` context includes their
|
||||
`referenced_by:` block. The second finds entries that **reference** this system —
|
||||
`referenced_by:` is a block sequence (the key and its paths are on separate
|
||||
lines), so match the path with `-B 8` context to see the owning entry, not a
|
||||
`referenced_by.*name` one-liner (which never matches the block form).
|
||||
|
||||
**If `design/registry/entities.yaml` does not exist, or lists no entry for this
|
||||
system** — the file ships as an empty stub, so this is the default until
|
||||
`/design-system` has populated it — fall back to reading the related GDDs the
|
||||
target doc names in its Dependencies section. Bound the read to those, not to
|
||||
everything "implied". Do not glob-read all of `design/gdd/`.
|
||||
|
||||
**Dependency graph validation:** For every system listed in the Dependencies section, use Glob to check whether its GDD file exists in `design/gdd/`. Flag any that don't exist yet — these are broken references that downstream authors will hit.
|
||||
|
||||
@@ -33,16 +117,34 @@ Read the target design document in full. Read CLAUDE.md to understand project co
|
||||
|
||||
## Phase 2: Completeness Check
|
||||
|
||||
Evaluate against the Design Document Standard checklist:
|
||||
**Step 2a — gather section presence deterministically (no document read):**
|
||||
|
||||
- [ ] Has Overview section (one-paragraph summary)
|
||||
- [ ] Has Player Fantasy section (intended feeling)
|
||||
- [ ] Has Detailed Rules section (unambiguous mechanics)
|
||||
- [ ] Has Formulas section (all math defined with variables)
|
||||
- [ ] Has Edge Cases section (unusual situations handled)
|
||||
- [ ] Has Dependencies section (other systems listed)
|
||||
- [ ] Has Tuning Knobs section (configurable values identified)
|
||||
- [ ] Has Acceptance Criteria section (testable success conditions)
|
||||
```
|
||||
Bash: bash .claude/scripts/gdd-structure-check.sh [target-doc-path]
|
||||
```
|
||||
|
||||
It prints a `PRESENT:` list and, when applicable, an `ABSENT:` list. It reports
|
||||
**presence only** and makes no REQUIRED/ADVISORY judgment — that is Step 2b's
|
||||
job. It already accepts `## Detailed Design` as satisfying the `Detailed Rules`
|
||||
requirement, so do not flag that as missing.
|
||||
|
||||
**Step 2b — apply the tier.** Using the Step 2a lists, evaluate against the
|
||||
Design Document Standard checklist below. **Mark each section REQUIRED or
|
||||
ADVISORY per the resolved workflow tier (Phase 0).** A missing REQUIRED section
|
||||
blocks approval; a missing ADVISORY section is surfaced as a recommendation but
|
||||
does not block.
|
||||
|
||||
A section reported PRESENT can still fail review if it is an empty heading —
|
||||
spot-read any section the verdict actually turns on.
|
||||
|
||||
- [ ] Has Overview section (one-paragraph summary) — REQUIRED at all tiers
|
||||
- [ ] Has Player Fantasy section (intended feeling) — REQUIRED at `full`; ADVISORY at `standard`
|
||||
- [ ] Has Detailed Rules section (unambiguous mechanics) — REQUIRED at `full`/`standard`. The GDD template titles this section `## Detailed Design` (it carries Core Rules / States / Interactions sub-headings); accept **either** heading as satisfying this requirement — do not flag "Detailed Rules" as missing when a `## Detailed Design` section is present.
|
||||
- [ ] Has Formulas section (all math defined with variables) — REQUIRED at `full`; at `standard` REQUIRED whenever the system defines numeric rules (rates, curves, thresholds, costs, damage, drop weights), else ADVISORY. The system's `Category` is a hint, not the test — do not clear this on a category token alone
|
||||
- [ ] Has Edge Cases section (unusual situations handled) — REQUIRED at `full`/`standard`
|
||||
- [ ] Has Dependencies section (other systems listed) — REQUIRED at `full`/`standard`
|
||||
- [ ] Has Tuning Knobs section (configurable values identified) — REQUIRED at `full`; ADVISORY at `standard` unless `workflow_overrides.tuning_knobs`
|
||||
- [ ] Has Acceptance Criteria section (testable success conditions) — REQUIRED at `full`/`standard`
|
||||
|
||||
---
|
||||
|
||||
@@ -76,7 +178,7 @@ Evaluate against the Design Document Standard checklist:
|
||||
|
||||
### Step 1 — Identify all domains the GDD touches
|
||||
|
||||
Read the GDD and identify every domain present. A GDD can touch multiple domains simultaneously — be thorough. Common signals:
|
||||
Using the GDD **already loaded in Phase 1** — do not re-read it — identify every domain present. A GDD can touch multiple domains simultaneously — be thorough. Common signals:
|
||||
|
||||
| If the GDD contains... | Spawn these agents |
|
||||
|------------------------|-------------------|
|
||||
@@ -91,7 +193,7 @@ Read the GDD and identify every domain present. A GDD can touch multiple domains
|
||||
| Multiplayer, sync, replication | `network-programmer` |
|
||||
| Audio cues, music triggers | `audio-director` |
|
||||
| Performance, draw calls, memory | `performance-analyst` |
|
||||
| Engine-specific patterns or APIs | Primary engine specialist (from `.claude/docs/technical-preferences.md`) |
|
||||
| Engine-specific patterns or APIs | Primary engine specialist (`<engine>-specialist` from `engine.name` — Godot→`godot-specialist`, Unity→`unity-specialist`, Unreal→`unreal-specialist`; fall back to the Primary line of `## Engine Specialists` in `technical-preferences.md`) |
|
||||
| Acceptance criteria, test coverage | `qa-lead` |
|
||||
| Data schema, resource structure | `systems-designer` |
|
||||
| Any gameplay system | `game-designer` (always) |
|
||||
@@ -102,12 +204,12 @@ These are the most common baselines — but not required for pure UI specs, audi
|
||||
|
||||
### Step 2 — Spawn all relevant specialists in parallel
|
||||
|
||||
**CRITICAL: Task in this skill spawns a SUBAGENT — a separate independent Claude session
|
||||
**CRITICAL: `Agent` in this skill spawns a SUBAGENT — a separate independent Claude session
|
||||
with its own context window. It is NOT task tracking. Do NOT simulate specialist
|
||||
perspectives internally. Do NOT reason through domain views yourself. You MUST issue
|
||||
actual Task calls. A simulated review is not a specialist review.**
|
||||
actual `Agent` calls. A simulated review is not a specialist review.**
|
||||
|
||||
Issue all Task calls simultaneously. Do NOT spawn one at a time.
|
||||
Issue all `Agent` calls simultaneously. Do NOT spawn one at a time.
|
||||
|
||||
**Prompt each specialist adversarially:**
|
||||
> "Here is the GDD for [system] and the main review's structural findings so far.
|
||||
@@ -146,8 +248,18 @@ Mark every finding with its source: `[game-designer]`, `[economy-designer]`, `[c
|
||||
Specialists consulted: [list agents spawned]
|
||||
Re-review: [Yes — prior verdict was X on YYYY-MM-DD / No — first review]
|
||||
|
||||
### Completeness: [X/8 sections present]
|
||||
[List missing sections]
|
||||
### Completeness: [X/N sections present, where N is the count REQUIRED at this project's `modes.workflow`]
|
||||
[List only sections missing that are REQUIRED at this tier. Mark ADVISORY gaps
|
||||
separately as "advisory at `standard`" — do not list them as missing.]
|
||||
|
||||
> **N is not 8 unless `workflow: full`.** The tier table earlier in this skill is
|
||||
> authoritative: 8 required at `full`, 5 at `standard` (+ Formulas when the system
|
||||
> defines numeric rules), 0 at `minimal`. Hardcoding `/8` here
|
||||
> reintroduces the tier confusion in the presentation layer after the logic
|
||||
> layer already handles it — reporting a `standard` project as "5/8 missing Player
|
||||
> Fantasy, Formulas, Tuning Knobs" warns about three sections that project's own
|
||||
> configuration says it does not need, which trains the reader to ignore the
|
||||
> review.
|
||||
|
||||
### Dependency Graph
|
||||
[List each declared dependency and whether its GDD file exists on disk]
|
||||
@@ -179,7 +291,20 @@ systems touched, and whether new ADRs are required.
|
||||
- **XL** — cross-cutting concern, 5+ dependencies, multiple new ADRs likely
|
||||
Label clearly: "Rough scope signal: M (producer should verify before sprint planning)"
|
||||
|
||||
### Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]
|
||||
### Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED / NOT ASSESSED]
|
||||
|
||||
> **`NOT ASSESSED` when the review could not actually be performed.**
|
||||
> The other three verdicts are all claims about the design's quality, so each one
|
||||
> asserts that the document was read and judged. Use `NOT ASSESSED` instead when
|
||||
> the target document is absent, unreadable, or empty of the sections being
|
||||
> reviewed, or when a document it depends on is missing so the criteria cannot be
|
||||
> applied. **Name what was unavailable and which skill produces it.**
|
||||
>
|
||||
> `APPROVED` is the dangerous default here: a review that could not find its
|
||||
> input has not approved anything, and this verdict is consumed downstream as a
|
||||
> sign-off. `NOT ASSESSED` outranks `APPROVED` in any aggregate — it does not
|
||||
> outrank the two revision verdicts, because a known problem is more actionable
|
||||
> than an unknown one.
|
||||
```
|
||||
|
||||
This skill is read-only — no files are written during Phase 4.
|
||||
@@ -213,7 +338,9 @@ After all revisions are complete, show a summary table (blocker → fix applied)
|
||||
- `[C] Move to next system — /design-system [next-system] (#N in design order)`
|
||||
- `[D] Stop here`
|
||||
|
||||
Never end the revision flow with plain text. Always close with this widget.
|
||||
In collaborative and guided modes, never end the revision flow with plain text —
|
||||
always close with this widget. In autonomous mode, summarize the outcome and
|
||||
record via `log_decision`.
|
||||
|
||||
**Second widget — tracking records (combined, for APPROVED path):**
|
||||
|
||||
@@ -243,8 +370,26 @@ Specialists: [list]
|
||||
Blocking items: [count] | Recommended: [count]
|
||||
Summary: [2-3 sentence summary of key findings from creative-director verdict]
|
||||
Prior verdict resolved: [Yes / No / First review]
|
||||
Findings:
|
||||
- [BLOCKING] [section]: [one-line finding]
|
||||
- [RECOMMENDED] [section]: [one-line finding]
|
||||
[output of: Bash: bash .claude/scripts/review-receipts.sh hash "[target-doc-path]" — plus "design/registry/entities.yaml" if the registry file exists]
|
||||
```
|
||||
|
||||
Findings rules: one line per finding, named by the section it lives in;
|
||||
write `- none` when the verdict carried no findings. This is documentation
|
||||
for a human reader of the revision history, not a mechanism the skill reads
|
||||
back — a delta re-review that skipped re-analyzing unchanged sections was
|
||||
tried and reverted (see Phase 1) after measuring it against a full review.
|
||||
|
||||
The hash line is the receipt Phase 1 reads on the next run to detect a
|
||||
byte-identical re-review — the one form of skip that's actually safe,
|
||||
because the input is provably the same, not merely believed to be adequately
|
||||
covered by a prior pass. Always include it, whatever the verdict — an
|
||||
unchanged document that previously FAILED review is exactly the case where
|
||||
skipping a redundant re-review saves the most (the prior findings stand
|
||||
verbatim).
|
||||
|
||||
---
|
||||
|
||||
**Final closing widget — always show after all file writes complete:**
|
||||
@@ -265,4 +410,6 @@ Build the option list dynamically — only include options that are genuinely ne
|
||||
|
||||
Assign letters A, B, C… only to included options. Mark the most pipeline-advancing option as `(recommended)`.
|
||||
|
||||
Never end the skill with plain text after file writes. Always close with this widget.
|
||||
In collaborative and guided modes, never end the skill with plain text after
|
||||
file writes — always close with this widget. In autonomous mode, print the next
|
||||
step and record via `log_decision`.
|
||||
|
||||
Reference in New Issue
Block a user