ksh999000/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios.git synced 2026-10-16 10:17:06 +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/analysis/code-review.md
+161 -82
View File
@@ -2,171 +2,250 @@
## Skill Summary
`/code-review` performs an architectural code review of source files in `src/`,
checking coding standards from `CLAUDE.md` (doc comments on public APIs,
dependency injection over singletons, data-driven values, testability). Findings
are advisory. No director gates are invoked. No code edits are made. Verdicts:
APPROVED, CONCERNS, or NEEDS CHANGES.
`/code-review [file(s)] [story-path]` performs an architectural review of source
files. It reads the target files and the project coding standards (Phase 1),
resolves the engine specialists from `project.yaml` (Phase 2), checks compliance
with any referenced ADR by reading only its `## Decision` and `## Consequences`
sections (Phase 3), then evaluates six standards checks, architecture and SOLID,
and game-specific concerns (Phases 4–6). Applicable engine specialists — and
`qa-tester` for Logic/Integration stories — are spawned in parallel, and every
specialist finding is recorded with file/line, evidence and a VERIFIED /
UNVERIFIED confidence (Phase 7). The report (Phase 8) ends in a verdict, first
match wins: CHANGES REQUIRED, NOT ASSESSED (nothing to review, the engine
specialist review did not run, or a report section — such as ADR Compliance on a
referenced ADR that could not be read — reads NOT ASSESSED), APPROVED WITH
SUGGESTIONS, APPROVED. It grants only `git log` from Bash. Phase 9
offers next steps via `AskUserQuestion`. The skill is read-only and invokes no
director gates.
---
## 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
- [ ] Contains verdict keywords: APPROVED, CONCERNS, NEEDS CHANGES
- [ ] Does NOT require "May I write" language (read-only; findings are advisory output)
- [ ] Contains verdict keywords: APPROVED, APPROVED WITH SUGGESTIONS, CHANGES REQUIRED, NOT ASSESSED
- [ ] Does NOT require "May I write" language (read-only; states that no files are written)
- [ ] Has a next-step handoff (what to do with findings)
---
## Director Gate Checks
None. Code review is a read-only advisory skill; no gates are invoked.
None. Code review invokes no director gates in any review mode. It does spawn
engine specialists and `qa-tester` as reviewers (Phase 7); those are not gates.
---
## Test Cases
### Case 1: Happy Path — Source file follows all coding standards
### Case 1: Happy Path — Standards-compliant file that follows its ADR
**Fixture:**
- `src/gameplay/health_component.gd` exists with:
- All public methods have doc comments (`##` notation)
- No singletons used; dependencies injected via constructor
- No hardcoded values; all constants reference `assets/data/`
- ADR reference in file header: `# ADR: docs/architecture/adr-004-health.md`
- Referenced ADR has `Status: Accepted`
- `project.yaml`: `engine.name: godot`, `specialists.code: godot-gdscript-specialist`, `specialists.shader: null`, `specialists.ui: null`
- `src/gameplay/health_component.gd` meets all six Phase 4 checks:
- Doc comments (`##`) on every public method and the class
- Every method under cyclomatic complexity 10 and under 40 lines
- Dependencies injected; no singletons
- All tuning values loaded from `assets/data/`
- Depends on interfaces, not concrete classes
- Header comment: `# Implements ADR-0004 (docs/architecture/adr-0004-health.md)`
- `docs/architecture/adr-0004-health.md` has `## Decision` and `## Consequences` sections, and the code follows the chosen approach
- The specialist reports no issues; there is nothing to suggest
**Input:** `/code-review src/gameplay/health_component.gd`
**Expected behavior:**
1. Skill reads the source file
2. Skill checks all coding standards: doc comments, DI, data-driven, ADR status
3. All checks pass
4. Skill outputs findings summary with all checks PASS
5. Verdict is APPROVED
1. Skill reads the source file and the coding standards
2. Skill finds the `ADR-0004` reference in the file header
3. Skill greps the ADR's `^## ` headings, then reads only the `## Decision` and `## Consequences` spans
4. `godot-gdscript-specialist` is spawned via `Agent` for the `.gd` file; `shader: null` and `ui: null` are treated as unset and not spawned
5. Report shows ADR Compliance: COMPLIANT, Standards Compliance: 6/6 passing, Engine Specialist Findings: CLEAN, Testability: `N/A — no story path given`, and a Positive Observations section
6. Verdict is APPROVED
7. Phase 9 `AskUserQuestion` offers [A] Run `/story-done` and [B] Stop here
**Assertions:**
- [ ] Each coding standard check is listed in the output
- [ ] All checks show PASS when standards are met
- [ ] Skill reads referenced ADR to confirm its status
- [ ] Verdict is APPROVED
- [ ] No edits are made to any file
- [ ] The ADR is read with a heading map and bounded reads of `## Decision` and `## Consequences`, not an unbounded full read
- [ ] `godot-gdscript-specialist` is spawned for the `.gd` file; no agent named `null` is spawned
- [ ] Standards Compliance reads `6/6 passing` and ADR Compliance reads COMPLIANT
- [ ] Testability reads `N/A — no story path given`; no `qa-tester` is spawned without a story
- [ ] Positive Observations section is present
- [ ] Verdict is APPROVED and Phase 9 offers `/story-done` or stop
- [ ] No file is written or edited
---
### Case 2: Needs Changes — Missing doc comment and singleton usage
### Case 2: Changes Required — Missing doc comments and singleton usage, no ADR
**Fixture:**
- `project.yaml`: `engine.name: godot`, `specialists.code: godot-gdscript-specialist`
- `src/ui/inventory_ui.gd` has:
- 2 public methods without doc comments
- Uses `GameManager.instance` (singleton pattern)
- 2 public methods (`refresh_slots`, `sort_items`) without doc comments
- `GameManager.instance` used at lines 42 and 87
- All other standards met
- No ADR reference in the file header, and no commit touching it names an ADR
- No story path is passed
**Input:** `/code-review src/ui/inventory_ui.gd`
**Expected behavior:**
1. Skill reads the source file
2. Skill detects: 2 missing doc comments on public methods
3. Skill detects: singleton usage at specific lines (e.g., line 42, line 87)
4. Findings list the exact method names and line numbers
5. Verdict is NEEDS CHANGES
1. Skill searches the file header and `git log --oneline -- src/ui/inventory_ui.gd` for `ADR-NNNN` references and finds none
2. Output notes: "No ADR references found — ADR compliance check skipped. For full ADR compliance review, provide the story path: `/code-review [files] [story-path]`."
3. Standards Compliance shows 4/6 passing and lists the failures with line references: the two undocumented methods and the singleton at lines 42 and 87
4. Required Changes lists the missing doc comments and the singleton, with dependency injection as the fix
5. Verdict is CHANGES REQUIRED
6. Phase 9 offers [A] Fix the issues and re-run `/code-review`, [B] Run `/story-done` anyway with noted exceptions, [C] Stop here
**Assertions:**
- [ ] Missing doc comments are listed with method names
- [ ] Singleton usage is flagged with file and line number
- [ ] Verdict is NEEDS CHANGES when BLOCKING-level standard violations exist
- [ ] Skill does not edit the file — findings are for the developer to act on
- [ ] Output suggests replacing singleton with dependency injection
- [ ] The "No ADR references found" note names the story-path form of the command
- [ ] Missing doc comments are listed with method names (`refresh_slots`, `sort_items`), not only line references
- [ ] Singleton usage is flagged with file and line numbers (42, 87)
- [ ] Standards Compliance reads `4/6 passing`
- [ ] Verdict is CHANGES REQUIRED and Phase 9 offers the three CHANGES REQUIRED options
- [ ] Skill does not edit the file
---
### Case 3: Architecture Risk — ADR reference is Proposed, not Accepted
### Case 3: Architectural Violation — Code uses a pattern its ADR rejects
**Fixture:**
- `src/core/save_system.gd` has a header comment: `# ADR: docs/architecture/adr-010-save.md`
- `adr-010-save.md` exists but has `Status: Proposed`
- Code itself follows all other coding standards
- `project.yaml`: `engine.name: godot`, `specialists.code: godot-gdscript-specialist`
- `src/core/save_system.gd` header: `# Implements ADR-0010 (docs/architecture/adr-0010-save-format.md)`
- `adr-0010-save-format.md` `## Decision`: save data goes through `SaveService` as JSON; direct `FileAccess` writes from gameplay code are explicitly rejected
- `save_system.gd` writes save data with `FileAccess.open(..., FileAccess.WRITE)` directly at line 58
- Code otherwise meets all six standards checks
**Input:** `/code-review src/core/save_system.gd`
**Expected behavior:**
1. Skill reads the source file
2. Skill reads referenced ADR — finds `Status: Proposed`
3. Skill flags this as ARCHITECTURE RISK (code is implementing an unaccepted ADR)
4. Other coding standard checks pass
5. Verdict is CONCERNS (risk flag is advisory, not a hard NEEDS CHANGES)
1. Skill reads only the Decision and Consequences sections of ADR-0010
2. The direct `FileAccess` write is classified ARCHITECTURAL VIOLATION (BLOCKING) — a pattern the ADR explicitly rejects
3. ADR Compliance reads VIOLATION, listing ADR-0010, the result and the deviation with its severity
4. The violation appears under Required Changes
5. Verdict is CHANGES REQUIRED
6. Next steps: fix the implementation to comply with `docs/architecture/adr-0010-save-format.md`, or — if the design has legitimately changed — run `/architecture-decision` to revise the existing ADR, not create a competing one
**Assertions:**
- [ ] Skill reads referenced ADR file to check its status
- [ ] ARCHITECTURE RISK is flagged when ADR status is Proposed
- [ ] Verdict is CONCERNS (not NEEDS CHANGES) for ADR risk — advisory severity
- [ ] Output recommends resolving the ADR before the code goes to production
- [ ] The deviation is classified ARCHITECTURAL VIOLATION (BLOCKING), not ADR DRIFT or MINOR DEVIATION
- [ ] ADR Compliance reads VIOLATION and names ADR-0010
- [ ] The violation is listed under Required Changes
- [ ] Verdict is CHANGES REQUIRED
- [ ] Output says to comply with the existing ADR or revise it via `/architecture-decision`, never to write a competing ADR
---
### Case 4: Edge Case — No source files found at specified path
### Case 4: Edge Case — No source files at the specified path
**Fixture:**
- User calls `/code-review src/networking/`
- `src/networking/` directory does not exist
- `project.yaml`: `engine.name: godot`
- `src/networking/` does not exist
**Input:** `/code-review src/networking/`
**Expected behavior:**
1. Skill attempts to read files in `src/networking/`
2. Directory or files not found
3. Skill outputs an error: "No source files found at `src/networking/`"
4. Skill suggests checking `src/` for valid directories
5. No verdict is emitted (nothing was reviewed)
1. Skill records its inputs as FOUND / ABSENT; the target source files are ABSENT
2. Every required input is ABSENT, so the skill stops before producing review sections
3. Output reports `NOT ASSESSED — NO DATA` as the whole verdict, naming `src/networking/` as missing
4. No specialist or `qa-tester` agent is spawned
5. No review section is filled in, and the result is not presented as APPROVED
**Assertions:**
- [ ] Skill does not crash when path does not exist
- [ ] Output names the attempted path in the error message
- [ ] Output suggests checking `src/` for valid file paths
- [ ] No verdict is emitted when there is nothing to review
- [ ] Skill does not crash when the path does not exist
- [ ] Output names the attempted path `src/networking/`
- [ ] Verdict is `NOT ASSESSED — NO DATA`, not APPROVED
- [ ] No specialist agent is spawned when there is nothing to review
---
### Case 5: Gate Compliance — No gate; LP may be consulted separately
### Case 5: No Engine Configured — Skipped specialists announce themselves; no gate
**Fixture:**
- Source file follows most standards but has 1 CONCERNS-level finding (a magic number)
- `review-mode.txt` contains `full`
- `project.yaml` has `modes.review_mode: full` and no `engine.name`; `.claude/docs/technical-preferences.md` reads `[TO BE CONFIGURED]`
- `src/gameplay/loot_system.gd` hardcodes a drop rate `0.05` at line 31; everything else meets the standards
**Input:** `/code-review src/gameplay/loot_system.gd`
**Expected behavior:**
1. Skill reads and reviews the source file
2. No director gate is invoked (code review findings are advisory)
3. Skill presents findings with the CONCERNS verdict
4. Output notes: "Consider requesting a Lead Programmer review for architecture concerns"
5. Skill does not invoke any agent automatically
1. Phase 2 finds no engine configured and skips the engine specialist steps
2. Output records `Engine validation: NOT ASSESSED — no engine configured (engine.name unset in project.yaml)`
3. Engine Specialist Findings reads `N/A — no engine configured`; no engine specialist is spawned
4. Standards Compliance lists the "Configuration values loaded from data files" failure with line 31, and the fix is listed under Required Changes
5. Verdict is CHANGES REQUIRED — the known defect outranks the skipped engine review, which the report still names
6. No director gate is invoked in any review mode
7. No file is edited
**Assertions:**
- [ ] No director gate is invoked in any review mode
- [ ] LP consultation is suggested (not mandated) in the output
- [ ] Output contains the `Engine validation: NOT ASSESSED — no engine configured` line
- [ ] Engine Specialist Findings reads `N/A — no engine configured` and no engine specialist agent is spawned
- [ ] The hardcoded value is reported under Standards Compliance with its line reference
- [ ] Verdict is CHANGES REQUIRED, not NOT ASSESSED and never APPROVED
- [ ] No director gate is invoked, even with review mode `full`
- [ ] No code edits are made
- [ ] Verdict is CONCERNS for advisory-level findings
---
### Case 5b: No Engine Configured, Clean File — NOT ASSESSED, never APPROVED
**Fixture:**
- `project.yaml` has no `engine.name`; `.claude/docs/technical-preferences.md` reads `[TO BE CONFIGURED]`
- `src/gameplay/loot_table.gd` meets all six Phase 4 checks and raises no architecture, SOLID or game-specific concern
**Input:** `/code-review src/gameplay/loot_table.gd`
**Expected behavior:**
1. Phase 2 records `Engine validation: NOT ASSESSED — no engine configured`; no engine specialist is spawned
2. Nothing is listed under Required Changes or Suggestions
3. Verdict is NOT ASSESSED, naming the engine specialist review that did not run
4. Phase 9 offers the NOT ASSESSED options, naming `/setup-engine` as the way to make the review complete
**Assertions:**
- [ ] Verdict is NOT ASSESSED, not APPROVED — a review that skipped the engine check has not approved the code
- [ ] The verdict names the engine specialist review as what did not run
- [ ] Phase 9 does not offer `/story-done`; it names `/setup-engine`
### Case 6: Referenced ADR missing — the section's NOT ASSESSED reaches the verdict
**Fixture:**
- `project.yaml`: `engine.name: godot`, `specialists.code: godot-gdscript-specialist`
- `src/gameplay/stamina.gd` meets all six Phase 4 checks and raises no
architecture, SOLID or game-specific concern; the specialist reports it clean
- Its header reads `# Implements ADR-0008 (docs/architecture/adr-0008-stamina.md)`,
and no such file exists
**Input:** `/code-review src/gameplay/stamina.gd`
**Expected behavior:**
1. Phase 3 finds the `ADR-0008` reference but cannot read the ADR
2. ADR Compliance reads `NOT ASSESSED — ADR-0008 could not be read`
3. Nothing is listed under Required Changes or Suggestions
4. Verdict is NOT ASSESSED, naming the ADR Compliance section and ADR-0008
**Assertions:**
- [ ] ADR Compliance reads NOT ASSESSED and names ADR-0008 — not `NO ADRS FOUND`, not COMPLIANT
- [ ] Verdict is NOT ASSESSED, never APPROVED: a section that could not be assessed reaches the verdict
- [ ] Variant — the file names no ADR at all: ADR Compliance reads `NO ADRS FOUND`, and the verdict is APPROVED (a missing reference is not an unreadable one)
---
## Protocol Compliance
- [ ] Reads source file(s) and coding standards before reviewing
- [ ] Lists each coding standard check in findings output
- [ ] Reads the target file(s) and the coding standards before reviewing (Phase 1)
- [ ] Reads the `specialists` block from `project.yaml`, falling back to `technical-preferences.md`; a `null` specialist is skipped, never spawned
- [ ] Every specialist finding in the report carries file/line, evidence, and VERIFIED or `UNVERIFIED — specialist claim`
- [ ] Does not edit any source files (read-only skill)
- [ ] No director gates are invoked
- [ ] Verdict is one of: APPROVED, CONCERNS, NEEDS CHANGES
- [ ] Verdict, first match: CHANGES REQUIRED, NOT ASSESSED, APPROVED WITH SUGGESTIONS, APPROVED — never an approval when the engine specialist review did not run or any report section reads NOT ASSESSED
- [ ] `allowed-tools` grants `Bash(git log *)` and the scoped `yaml-helper.sh resolve_config` pattern, not bare `Bash` — the skill is read-only: it runs `git log` and the config resolver, nothing else
- [ ] Phase 9's prompt and option branches use the same verdict vocabulary as the Phase 8 report
---
## Coverage Notes
- Batch review of all files in a directory is not explicitly tested; behavior
is assumed to apply the same checks file by file and aggregate the verdict.
- Test coverage checks (verifying corresponding test files exist) are a stretch
goal not tested here; that is primarily the domain of `/test-evidence-review`.
- Batch review of a directory is not tested separately; the same checks apply
file by file.
- The `qa-tester` testability review (Logic and Integration stories, story path
passed as the last argument) is not given its own case.
- Test-file existence checks are the domain of `/test-evidence-review`.