mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 01:37:05 +00:00
Release 1.1.2 — the default path works end to end
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
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
7ed2c3e9c4
commit
b21fa0f7f2
@@ -41,6 +41,11 @@ Users:
|
||||
|
||||
## 🔄 Collaborative Workflow Pattern
|
||||
|
||||
> **At `rigor: minimal` (the default), the design record is the one-page
|
||||
> `design/game-brief.md`, not a set of GDDs.** `/brainstorm` writes it, and the
|
||||
> same question → options → decision → draft → approval protocol applies to it.
|
||||
> The GDD examples below show the `standard` and `full` tiers.
|
||||
|
||||
Every agent interaction should follow this pattern:
|
||||
|
||||
### Pattern: Question → Options → Decision → Draft → Approval
|
||||
@@ -685,4 +690,4 @@ This principle has been fully embedded across the project:
|
||||
- **All skills** — Updated to require approval before writing
|
||||
- **WORKFLOW-GUIDE.md** — Rewritten with collaborative examples
|
||||
- **README.md** — Clarifies collaborative (not autonomous) design
|
||||
- **AskUserQuestion tool** — Integrated into 16 skills for structured option UI
|
||||
- **AskUserQuestion tool** — Used by 68 skills (49 declare it) for structured option UI
|
||||
|
||||
+342
-176
@@ -3,29 +3,33 @@
|
||||
> **How to go from zero to a shipped game using the Agent Architecture.**
|
||||
>
|
||||
> This guide walks you through every phase of game development using the
|
||||
> 49-agent system, 73 slash commands, and 12 automated hooks. It assumes you
|
||||
> 49-agent system, 74 slash commands, and 12 automated hooks. It assumes you
|
||||
> have Claude Code installed and are working from the project root.
|
||||
>
|
||||
> The pipeline has 7 phases. Each phase has a formal gate (`/gate-check`)
|
||||
> that must pass before you advance. The authoritative phase sequence is
|
||||
> defined in `.claude/docs/workflow-catalog.yaml` and read by `/help`.
|
||||
> The pipeline has 7 phases. At `rigor: standard` and `full`, each phase has
|
||||
> a formal gate (`/gate-check`) that must pass before you advance. At
|
||||
> `rigor: minimal` -- the default -- nothing requires a gate; see
|
||||
> [The Default Path](#the-default-path-rigor-minimal). The authoritative
|
||||
> phase sequence is defined in `.claude/docs/workflow-catalog.yaml` and read
|
||||
> by `/help`.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Quick Start](#quick-start)
|
||||
2. [Phase 1: Concept](#phase-1-concept)
|
||||
3. [Phase 2: Systems Design](#phase-2-systems-design)
|
||||
4. [Phase 3: Technical Setup](#phase-3-technical-setup)
|
||||
5. [Phase 4: Pre-Production](#phase-4-pre-production)
|
||||
6. [Phase 5: Production](#phase-5-production)
|
||||
7. [Phase 6: Polish](#phase-6-polish)
|
||||
8. [Phase 7: Release](#phase-7-release)
|
||||
9. [Cross-Cutting Concerns](#cross-cutting-concerns)
|
||||
10. [Appendix A: Agent Quick-Reference](#appendix-a-agent-quick-reference)
|
||||
11. [Appendix B: Slash Command Quick-Reference](#appendix-b-slash-command-quick-reference)
|
||||
12. [Appendix C: Common Workflows](#appendix-c-common-workflows)
|
||||
2. [The Default Path: Rigor Minimal](#the-default-path-rigor-minimal)
|
||||
3. [Phase 1: Concept](#phase-1-concept)
|
||||
4. [Phase 2: Systems Design](#phase-2-systems-design)
|
||||
5. [Phase 3: Technical Setup](#phase-3-technical-setup)
|
||||
6. [Phase 4: Pre-Production](#phase-4-pre-production)
|
||||
7. [Phase 5: Production](#phase-5-production)
|
||||
8. [Phase 6: Polish](#phase-6-polish)
|
||||
9. [Phase 7: Release](#phase-7-release)
|
||||
10. [Cross-Cutting Concerns](#cross-cutting-concerns)
|
||||
11. [Appendix A: Agent Quick-Reference](#appendix-a-agent-quick-reference)
|
||||
12. [Appendix B: Slash Command Quick-Reference](#appendix-b-slash-command-quick-reference)
|
||||
13. [Appendix C: Common Workflows](#appendix-c-common-workflows)
|
||||
|
||||
---
|
||||
|
||||
@@ -38,7 +42,7 @@ Before you start, make sure you have:
|
||||
- **Claude Code** installed and working
|
||||
- **Git** with Git Bash (Windows) or standard terminal (Mac/Linux)
|
||||
- **jq** (optional but recommended -- hooks fall back to `grep` if missing)
|
||||
- **Python 3** (optional -- some hooks use it for JSON validation)
|
||||
- **Python 3** (required -- every skill and hook reads `project.yaml` through it; without it every setting silently falls back to its default)
|
||||
|
||||
### Step 1: Clone and Open
|
||||
|
||||
@@ -59,7 +63,8 @@ This guided onboarding asks where you are and routes you to the right phase:
|
||||
|
||||
- **Path A** -- No idea yet: routes to `/brainstorm`
|
||||
- **Path B** -- Vague idea: routes to `/brainstorm` with seed
|
||||
- **Path C** -- Clear concept: routes to `/setup-engine` and `/map-systems`
|
||||
- **Path C** -- Clear concept: routes to `/brainstorm` to write it down, or
|
||||
straight to `/setup-engine`
|
||||
- **Path D1** -- Existing project, few artifacts: normal flow
|
||||
- **Path D2** -- Existing project, GDDs/ADRs exist: runs `/project-stage-detect`
|
||||
then `/adopt` for brownfield migration
|
||||
@@ -89,7 +94,8 @@ At any point, run:
|
||||
```
|
||||
|
||||
This reads your current phase from `project.stage` in `project.yaml` (falling
|
||||
back to `production/stage.txt`), checks which artifacts exist, and tells you
|
||||
back to `production/stage.txt`) -- at `rigor: minimal`, where the stage never
|
||||
moves, it follows the minimal route instead -- checks which artifacts exist, and tells you
|
||||
exactly what to do next. It distinguishes between REQUIRED next steps and
|
||||
OPTIONAL opportunities.
|
||||
|
||||
@@ -98,7 +104,7 @@ OPTIONAL opportunities.
|
||||
Directories are created as needed. The system expects this layout:
|
||||
|
||||
```
|
||||
src/ # Game source code
|
||||
src/ # Game source code (Godot; Unity: Assets/, Unreal: Source/<Module>/)
|
||||
core/ # Engine/framework code
|
||||
gameplay/ # Gameplay systems
|
||||
ai/ # AI systems
|
||||
@@ -137,7 +143,36 @@ production/ # Sprint plans, milestones, releases
|
||||
> reach the phase that needs them. The important thing is to follow this
|
||||
> structure when you do create them, because the **rules system** enforces
|
||||
> standards based on file paths. Code in `src/gameplay/` gets gameplay rules,
|
||||
> code in `src/ai/` gets AI rules, and so on.
|
||||
> code in `src/ai/` gets AI rules, and so on — and the same for C# and C++ in
|
||||
> Unity and Unreal `Gameplay/` and `AI/` folders.
|
||||
|
||||
---
|
||||
|
||||
## The Default Path: Rigor Minimal
|
||||
|
||||
`modes.rigor` defaults to `minimal` (`/start` asks which tier fits; `/settings`
|
||||
changes it any time). At `minimal` the path to code is four steps:
|
||||
|
||||
1. `/setup-engine` -- configure the engine
|
||||
2. `/brainstorm` -- writes the one-page `design/game-brief.md`, which replaces
|
||||
the full concept doc, the systems decomposition and the per-system GDDs
|
||||
3. `/create-stories` -- turns the brief's MVP list and build order into stories
|
||||
under `production/epics/<slug>/`. No `/create-epics`, no `/sprint-plan`: the
|
||||
brief's build order is the plan
|
||||
4. `/dev-story` then `/story-done`, story by story. `/story-done` names the
|
||||
next story, and `/help` knows this route
|
||||
|
||||
Nothing on this path runs `/gate-check`, so `project.stage` stays at Concept --
|
||||
that is expected. Every skill still runs at any tier; rigor changes what is
|
||||
required, not what is allowed.
|
||||
|
||||
The trade: there are no GDDs to catch design problems before they reach code.
|
||||
Raise rigor with `/settings` when the game outgrows a one-page brief -- several
|
||||
systems that affect each other, a design someone else implements, a team, or a
|
||||
firm release date. Existing files stay where they are, and `/help` shows what
|
||||
the new tier requires next.
|
||||
|
||||
The rest of this guide describes the `standard`/`full` pipeline.
|
||||
|
||||
---
|
||||
|
||||
@@ -262,20 +297,38 @@ This step is **required** before proceeding to Phase 2. Research from 155 game
|
||||
postmortems confirms that skipping systems enumeration costs 5-10x more in
|
||||
production.
|
||||
|
||||
### Step 1.5: Art Bible
|
||||
|
||||
```
|
||||
/art-bible
|
||||
```
|
||||
|
||||
Authors `design/art/art-bible.md`, the visual identity every asset follows.
|
||||
Run it once the concept is approved; `/art-bible` suggests doing it before
|
||||
`/map-systems` (Step 1.4). Sections 1–4 are needed before `/gate-check pre-production`, and all
|
||||
9 before `/gate-check production`. At `standard` it is required only when the
|
||||
game has visual-asset stories; at `minimal` it is optional.
|
||||
|
||||
### Phase 1 Gate
|
||||
|
||||
```
|
||||
/gate-check concept
|
||||
/gate-check systems-design
|
||||
```
|
||||
|
||||
**Requirements to pass:**
|
||||
|
||||
- Engine configured in `project.yaml` (`engine.*`)
|
||||
- `design/gdd/game-concept.md` exists with pillars
|
||||
- `design/gdd/systems-index.md` exists with dependency ordering
|
||||
- `design/gdd/game-concept.md` with content, the game pillars, and a Visual
|
||||
Identity Anchor section (at `minimal`: `design/game-brief.md` with content)
|
||||
- Recommended: a concept prototype whose REPORT.md says PROCEED
|
||||
|
||||
**Verdict:** PASS / CONCERNS / FAIL. CONCERNS is passable with acknowledged
|
||||
risks. FAIL blocks advancement.
|
||||
This is the `full` list. `standard` and `minimal` drop items; the gate's own
|
||||
file, `.claude/skills/gate-check/references/gate-systems-design.md`, has the full
|
||||
checklist and what each tier drops.
|
||||
|
||||
**Verdict:** PASS / CONCERNS / NOT ASSESSED / FAIL. PASS advances the stage.
|
||||
On CONCERNS it advances only if you explicitly accept the risks, which are
|
||||
recorded; a FAIL never advances it. NOT ASSESSED means something required could
|
||||
not be checked.
|
||||
|
||||
---
|
||||
|
||||
@@ -304,7 +357,7 @@ and then all GDDs are cross-checked for consistency.
|
||||
|
|
||||
v
|
||||
Cross-GDD consistency + design theory review
|
||||
PASS / CONCERNS / FAIL
|
||||
PASS / CONCERNS / NOT ASSESSED / FAIL
|
||||
```
|
||||
|
||||
### Step 2.1: Author System GDDs
|
||||
@@ -363,8 +416,8 @@ Checks the sections your `modes.workflow` tier requires (all 8 at `full`, 5 at
|
||||
`standard`) for completeness, formula clarity, edge case resolution,
|
||||
bidirectional dependencies, and testable acceptance criteria.
|
||||
|
||||
**Verdict:** APPROVED / NEEDS REVISION / MAJOR REVISION. Only APPROVED GDDs
|
||||
should proceed.
|
||||
**Verdict:** APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED / NOT ASSESSED.
|
||||
Only APPROVED GDDs should proceed.
|
||||
|
||||
### Step 2.3: Small Changes Without Full GDDs
|
||||
|
||||
@@ -419,15 +472,21 @@ If your game has story, lore, or dialogue, this is when you build it:
|
||||
### Phase 2 Gate
|
||||
|
||||
```
|
||||
/gate-check systems-design
|
||||
/gate-check technical-setup
|
||||
```
|
||||
|
||||
**Requirements to pass:**
|
||||
|
||||
- All MVP systems in `systems-index.md` have `Status: Approved`
|
||||
- Each MVP system has a reviewed GDD
|
||||
- Cross-GDD review report exists (`design/gdd/gdd-cross-review-*.md`)
|
||||
with verdict of PASS or CONCERNS (not FAIL)
|
||||
- `design/gdd/systems-index.md` listing at least the MVP systems, with their
|
||||
dependencies mapped
|
||||
- A GDD for every MVP system, each passing `/design-review` (no MAJOR REVISION
|
||||
NEEDED)
|
||||
- A cross-GDD review report from `/review-all-gdds` whose verdict is not FAIL —
|
||||
and not NOT ASSESSED, which means the GDDs could not be compared
|
||||
|
||||
This is the `full` list. `standard` and `minimal` drop items; the gate's own
|
||||
file, `.claude/skills/gate-check/references/gate-technical-setup.md`, has the full
|
||||
checklist and what each tier drops.
|
||||
|
||||
---
|
||||
|
||||
@@ -459,8 +518,9 @@ gives programmers flat, actionable rules. You also establish UX foundations.
|
||||
Also in this phase:
|
||||
-------------------
|
||||
/ux-design --> /ux-review
|
||||
Accessibility requirements doc
|
||||
Interaction pattern library
|
||||
Accessibility requirements doc (/ux-design accessibility)
|
||||
Interaction pattern library (/ux-design patterns)
|
||||
/test-setup --> test framework + CI workflow
|
||||
```
|
||||
|
||||
### Step 3.1: Master Architecture Document
|
||||
@@ -538,20 +598,42 @@ matrix (visual, motor, cognitive, auditory).
|
||||
|
||||
This document is required in Phase 3 because UX specs (written in Phase 4)
|
||||
reference this tier — it is a design prerequisite, not a UX deliverable.
|
||||
`/ux-design accessibility` authors it; `/ux-design patterns` starts the
|
||||
interaction pattern library (`design/ux/interaction-patterns.md`), which the same
|
||||
gate checks.
|
||||
|
||||
### Step 3.6: Test Framework
|
||||
|
||||
```
|
||||
/test-setup
|
||||
```
|
||||
|
||||
Scaffolds the engine's test root, `.github/workflows/tests.yml` and one example
|
||||
test; the Pre-Production gate checks for them. `/test-helpers` can follow once
|
||||
there are systems to test.
|
||||
|
||||
### Phase 3 Gate
|
||||
|
||||
```
|
||||
/gate-check technical-setup
|
||||
/gate-check pre-production
|
||||
```
|
||||
|
||||
**Requirements to pass:**
|
||||
|
||||
- `docs/architecture/architecture.md` exists
|
||||
- At least 3 ADRs exist and are Accepted
|
||||
- Architecture review report exists
|
||||
- `docs/architecture/control-manifest.md` exists
|
||||
- `design/accessibility-requirements.md` exists
|
||||
- The engine configured, `project.yaml` populated (engine, naming, performance)
|
||||
and the engine reference docs present
|
||||
- Art bible Sections 1–4 (`design/art/art-bible.md`)
|
||||
- `docs/architecture/architecture.md`, at least 3 ADRs covering Foundation-layer
|
||||
systems, an `/architecture-review` report and
|
||||
`docs/architecture/requirements-traceability.md`
|
||||
- The test framework in the engine's test root, `.github/workflows/tests.yml`
|
||||
and one example test (`/test-setup`)
|
||||
- `design/accessibility-requirements.md` and `design/ux/interaction-patterns.md`
|
||||
(`/ux-design accessibility`, `/ux-design patterns`)
|
||||
|
||||
This is the `full` list. `standard` and `minimal` drop items; the gate's own
|
||||
file, `.claude/skills/gate-check/references/gate-pre-production.md`, has the full
|
||||
checklist and what each tier drops.
|
||||
|
||||
---
|
||||
|
||||
@@ -612,12 +694,13 @@ checks — no need to re-specify them per screen.
|
||||
**Interaction Pattern Library:**
|
||||
|
||||
```
|
||||
/ux-design interaction-patterns
|
||||
/ux-design patterns
|
||||
```
|
||||
|
||||
Create `design/ux/interaction-patterns.md` — 16 standard controls plus
|
||||
game-specific patterns (inventory slot, ability icon, HUD bar, dialogue box,
|
||||
etc.) with animation and sound standards.
|
||||
Started in Phase 3 (the Pre-Production gate checks it); extend it here as the
|
||||
key screens add patterns. `design/ux/interaction-patterns.md` holds 16 standard
|
||||
controls plus game-specific patterns (inventory slot, ability icon, HUD bar,
|
||||
dialogue box, etc.) with animation and sound standards.
|
||||
|
||||
**UX Review:**
|
||||
|
||||
@@ -652,7 +735,8 @@ you can build it properly. They answer different questions. If you skipped the
|
||||
concept prototype, now is a reasonable time to run one first before investing
|
||||
in the full slice.
|
||||
|
||||
**Verdict:** The vertical slice produces a PROCEED / PIVOT / KILL verdict.
|
||||
**Verdict:** The vertical slice produces a PROCEED / PIVOT / KILL verdict, or
|
||||
NOT ASSESSED while nobody has played it through.
|
||||
- **PROCEED** → move to Step 4.3 (epics and stories)
|
||||
- **PIVOT** → revise affected GDDs with `/design-system [mechanic]`, then re-run `/vertical-slice`
|
||||
- **KILL** → return to `/brainstorm` with what you learned
|
||||
@@ -685,7 +769,7 @@ automatically to the correct programmer agent.
|
||||
```
|
||||
|
||||
Checks: Design completeness, Architecture coverage, Scope clarity, Definition
|
||||
of Done. Verdict: READY / NEEDS WORK / BLOCKED.
|
||||
of Done. Verdict: READY / NEEDS WORK / BLOCKED / NOT ASSESSED.
|
||||
|
||||
### Step 4.5: Effort Estimation
|
||||
|
||||
@@ -705,35 +789,47 @@ Provides effort estimates with risk assessment.
|
||||
- Asks for sprint goal and available time
|
||||
- Breaks the goal into Must Have / Should Have / Nice to Have tasks
|
||||
- Identifies risks and blockers
|
||||
- Creates `production/sprints/sprint-01.md`
|
||||
- Creates `production/sprints/sprint-001.md`
|
||||
- Populates `production/sprint-status.yaml` (machine-readable story tracking)
|
||||
|
||||
### Step 4.7: Vertical Slice (Hard Gate)
|
||||
### Step 4.7: Vertical Slice (recommended)
|
||||
|
||||
Before advancing to Production, you must build and playtest a Vertical Slice:
|
||||
Before advancing to Production, build and playtest a Vertical Slice:
|
||||
|
||||
- One complete end-to-end core loop, playable from start to finish
|
||||
- Representative quality (not placeholder everything)
|
||||
- Played unguided in at least 3 sessions
|
||||
- Played unguided in at least 1 documented session (3+ recommended)
|
||||
- Playtest report written (`/playtest-report`)
|
||||
|
||||
This is a **hard gate** -- `/gate-check` will auto-FAIL if a human has not
|
||||
played the build unguided.
|
||||
`/gate-check production` treats it as recommended, not blocking: a skipped
|
||||
slice is CONCERNS, a slice nobody has played is NOT ASSESSED, and a built slice
|
||||
that is broken or not fun is a FAIL. At `workflow: minimal` the slice items
|
||||
drop: the gate asks instead whether the current build's core loop is fun and
|
||||
runs end to end.
|
||||
|
||||
### Phase 4 Gate
|
||||
|
||||
```
|
||||
/gate-check pre-production
|
||||
/gate-check production
|
||||
```
|
||||
|
||||
**Requirements to pass:**
|
||||
|
||||
- At least 1 UX spec reviewed in `design/ux/`
|
||||
- UX review completed (APPROVED or NEEDS REVISION with documented risks)
|
||||
- At least 1 prototype with README
|
||||
- Story files exist in `production/epics/[epic-slug]/`
|
||||
- At least 1 sprint plan exists
|
||||
- At least 1 playtest report exists (Vertical Slice played in 3+ sessions)
|
||||
- A first sprint plan in `production/sprints/`, and Foundation and Core epics
|
||||
with their stories under `production/epics/`
|
||||
- The complete art bible (all 9 sections) with its AD-ART-BIBLE sign-off
|
||||
recorded
|
||||
- Every MVP GDD complete, the master architecture document, Foundation and Core
|
||||
ADRs `Accepted`, and the control manifest
|
||||
- UX specs for the key screens (main menu, HUD, pause menu) that passed
|
||||
`/ux-review`
|
||||
- Recommended, not blocking: a Vertical Slice built and played in at least one
|
||||
documented session. Skipped → CONCERNS; built but broken or not fun → FAIL;
|
||||
built but not yet played → NOT ASSESSED
|
||||
|
||||
This is the `full` list. `standard` and `minimal` drop items; the gate's own
|
||||
file, `.claude/skills/gate-check/references/gate-production.md`, has the full
|
||||
checklist and what each tier drops.
|
||||
|
||||
---
|
||||
|
||||
@@ -780,7 +876,7 @@ The production phase centers on the **story lifecycle**:
|
||||
|
||||
This checks design completeness, architecture coverage, ADR status (blocks
|
||||
if ADR is still Proposed), control manifest version (warns if stale), and
|
||||
scope clarity. Verdict: READY / NEEDS WORK / BLOCKED.
|
||||
scope clarity. Verdict: READY / NEEDS WORK / BLOCKED / NOT ASSESSED.
|
||||
|
||||
**2. Implementation:** Work with the appropriate agents:
|
||||
|
||||
@@ -826,7 +922,7 @@ Quick 30-line snapshot reading from `production/sprint-status.yaml`.
|
||||
If scope is growing:
|
||||
|
||||
```
|
||||
/scope-check production/sprints/sprint-03.md
|
||||
/scope-check production/sprints/sprint-003.md
|
||||
```
|
||||
|
||||
This compares current scope against the original plan and flags scope increase,
|
||||
@@ -904,15 +1000,24 @@ recommendation.
|
||||
### Phase 5 Gate
|
||||
|
||||
```
|
||||
/gate-check production
|
||||
/gate-check polish
|
||||
```
|
||||
|
||||
**Requirements to pass:**
|
||||
|
||||
- All MVP stories complete
|
||||
- Playtesting: 3 sessions covering new player, mid-game, and difficulty curve
|
||||
- Fun hypothesis validated
|
||||
- No confusion loops in playtest data
|
||||
- Every core GDD mechanic implemented, and the main gameplay path playable end
|
||||
to end
|
||||
- Tests in the engine's test root covering the Logic and Integration stories,
|
||||
and passing
|
||||
- A smoke-check report in `production/qa/` with PASS or PASS WITH WARNINGS
|
||||
- A `/team-qa` sign-off (APPROVED or APPROVED WITH CONDITIONS)
|
||||
- At least 3 documented playtest sessions (new player, mid-game, difficulty
|
||||
curve) and the fun hypothesis validated or revised
|
||||
- No open S1 Critical bugs, and performance within budget
|
||||
|
||||
This is the `full` list. `standard` and `minimal` drop items; the gate's own
|
||||
file, `.claude/skills/gate-check/references/gate-polish.md`, has the full
|
||||
checklist and what each tier drops.
|
||||
|
||||
---
|
||||
|
||||
@@ -939,6 +1044,10 @@ performance, balance, accessibility, audio, visual polish, and playtesting.
|
||||
Track and Coordinated pass:
|
||||
prioritize performance + art +
|
||||
debt items audio + UX + QA
|
||||
|
||||
/security-audit --> /localize qa --> /release-checklist --> /changelog
|
||||
(per language) + /patch-notes
|
||||
Release readiness: the Polish -> Release gate checks all four.
|
||||
```
|
||||
|
||||
### Step 6.1: Performance Profiling
|
||||
@@ -997,7 +1106,9 @@ missing tests, and outdated dependencies. Each item categorized and prioritized.
|
||||
```
|
||||
|
||||
Coordinates 4 specialists in parallel:
|
||||
1. Performance optimization (performance-analyst)
|
||||
1. Performance optimization (performance-analyst lists the optimisations; a
|
||||
programmer in the active set implements them — at `team.size: individual`,
|
||||
where none is active, the list is handed to `/dev-story`)
|
||||
2. Visual polish (technical-artist)
|
||||
3. Audio polish (sound-designer)
|
||||
4. Feel/juice (gameplay-programmer + technical-artist)
|
||||
@@ -1007,7 +1118,7 @@ You set priorities; the team executes with your approval at each step.
|
||||
### Step 6.7: Localization and Accessibility
|
||||
|
||||
```
|
||||
/localize src/
|
||||
/localize scan
|
||||
```
|
||||
|
||||
Scans for hardcoded strings, concatenation that breaks translation, text that
|
||||
@@ -1016,18 +1127,80 @@ does not account for expansion, and missing locale files.
|
||||
Accessibility is audited against the tier committed in Phase 3's accessibility
|
||||
requirements document.
|
||||
|
||||
### Step 6.8: Security Audit
|
||||
|
||||
```
|
||||
/security-audit
|
||||
```
|
||||
|
||||
Required for the release gate at `standard` and `full`: the newest report must
|
||||
have no open CRITICAL or HIGH finding. A report whose recommendation is NOT
|
||||
ASSESSED leaves the gate's security item NOT ASSESSED.
|
||||
|
||||
### Step 6.9: Localization QA
|
||||
|
||||
```
|
||||
/localize qa
|
||||
```
|
||||
|
||||
Run it for every language you ship. At `full` the release gate needs a PASS (or
|
||||
PASS WITH CONDITIONS) for each; a locale nobody has checked is NOT ASSESSED.
|
||||
|
||||
### Step 6.10: Release Checklist
|
||||
|
||||
```
|
||||
/release-checklist all
|
||||
```
|
||||
|
||||
The argument is the platform scope (`pc`, `console`, `mobile` or `all`), not a
|
||||
version.
|
||||
|
||||
Generates a comprehensive pre-release checklist covering:
|
||||
- Build verification (all platforms compile and run)
|
||||
- Certification requirements (platform-specific)
|
||||
- Store metadata (descriptions, screenshots, trailers)
|
||||
- Legal compliance (EULA, privacy policy, ratings)
|
||||
- Save game compatibility
|
||||
- Analytics verification
|
||||
|
||||
### Step 6.11: Changelog and Patch Notes
|
||||
|
||||
```
|
||||
/patch-notes v1.0.0
|
||||
```
|
||||
|
||||
Generates player-friendly patch notes from git history and sprint data.
|
||||
Translates developer language into player language.
|
||||
|
||||
```
|
||||
/changelog v1.0.0
|
||||
```
|
||||
|
||||
Generates an internal changelog (more technical, for the team).
|
||||
|
||||
The release gate needs the changelog or the patch notes drafted, so write them
|
||||
now; `/team-release` publishes them once the release is a GO.
|
||||
|
||||
### Phase 6 Gate
|
||||
|
||||
```
|
||||
/gate-check polish
|
||||
/gate-check release
|
||||
```
|
||||
|
||||
**Requirements to pass:**
|
||||
|
||||
- At least 3 playtest reports exist
|
||||
- Coordinated polish pass completed (`/team-polish`)
|
||||
- No blocking performance issues
|
||||
- Accessibility tier requirements met
|
||||
- Every milestone feature implemented and the content complete
|
||||
- A QA test plan and a QA sign-off, and every Must Have story's test evidence
|
||||
(UI: retained screenshots; Visual/Feel: screenshots plus lead sign-off)
|
||||
- Smoke check PASS on the release candidate, and the test suite passing
|
||||
- `/balance-check` run, the release checklist completed, and the changelog or
|
||||
patch notes drafted
|
||||
- No open S1–S3 bugs, the newest `/security-audit` with no open CRITICAL or
|
||||
HIGH finding, and a `/localize qa` pass for every locale you ship
|
||||
|
||||
This is the `full` list. `standard` and `minimal` drop items; the gate's own
|
||||
file, `.claude/skills/gate-check/references/gate-release.md`, has the full
|
||||
checklist and what each tier drops.
|
||||
|
||||
---
|
||||
|
||||
@@ -1040,31 +1213,18 @@ Your game is polished, tested, and ready. Now you ship it.
|
||||
### Phase 7 Pipeline
|
||||
|
||||
```
|
||||
/release-checklist --> /launch-checklist --> /team-release
|
||||
| | |
|
||||
v v v
|
||||
Pre-release Full cross-department Coordinate:
|
||||
validation across validation (Go/No-Go build, QA sign-off,
|
||||
code, content, per department) deployment, launch
|
||||
store, legal
|
||||
Also: /changelog, /patch-notes, /hotfix
|
||||
/launch-checklist --> /team-release
|
||||
| |
|
||||
v v
|
||||
Full cross-department Coordinate:
|
||||
validation (Go/No-Go build, QA sign-off,
|
||||
per department) deployment, launch
|
||||
|
||||
The release checklist, security audit and patch notes are done in Polish,
|
||||
before /gate-check release. Also: /hotfix, /day-one-patch
|
||||
```
|
||||
|
||||
### Step 7.1: Release Checklist
|
||||
|
||||
```
|
||||
/release-checklist v1.0.0
|
||||
```
|
||||
|
||||
Generates a comprehensive pre-release checklist covering:
|
||||
- Build verification (all platforms compile and run)
|
||||
- Certification requirements (platform-specific)
|
||||
- Store metadata (descriptions, screenshots, trailers)
|
||||
- Legal compliance (EULA, privacy policy, ratings)
|
||||
- Save game compatibility
|
||||
- Analytics verification
|
||||
|
||||
### Step 7.2: Launch Readiness (Full Validation)
|
||||
### Step 7.1: Launch Readiness (Full Validation)
|
||||
|
||||
```
|
||||
/launch-checklist
|
||||
@@ -1088,24 +1248,13 @@ Complete cross-department validation:
|
||||
| **Infrastructure** | Servers scaled, CDN configured, monitoring active |
|
||||
| **Legal** | EULA finalized, privacy policy, COPPA/GDPR compliance |
|
||||
|
||||
Each item gets a **Go / No-Go** status. All must be Go to ship.
|
||||
What no file can settle — the EULA, pricing, the on-call schedule — is asked
|
||||
once per section: yes, no, not yet or N/A. A "no" or "not yet" is a failed item.
|
||||
The overall status is READY, CONDITIONAL (only items with a workaround or an
|
||||
accepted risk remain), NOT ASSESSED (something is still unconfirmed) or NOT
|
||||
READY (a blocking item failed).
|
||||
|
||||
### Step 7.3: Generate Player-Facing Content
|
||||
|
||||
```
|
||||
/patch-notes v1.0.0
|
||||
```
|
||||
|
||||
Generates player-friendly patch notes from git history and sprint data.
|
||||
Translates developer language into player language.
|
||||
|
||||
```
|
||||
/changelog v1.0.0
|
||||
```
|
||||
|
||||
Generates an internal changelog (more technical, for the team).
|
||||
|
||||
### Step 7.4: Coordinate the Release
|
||||
### Step 7.2: Coordinate the Release
|
||||
|
||||
```
|
||||
/team-release
|
||||
@@ -1118,9 +1267,9 @@ Coordinates release-manager, QA, and DevOps through:
|
||||
4. Deployment preparation
|
||||
5. Go/No-Go decision
|
||||
|
||||
### Step 7.5: Ship
|
||||
### Step 7.3: Ship
|
||||
|
||||
The `validate-push` hook will warn you when pushing to `main` or `develop`.
|
||||
The `validate-push` hook will warn you when pushing to `main` or a `release/*` branch.
|
||||
This is intentional -- release pushes should be deliberate:
|
||||
|
||||
```bash
|
||||
@@ -1128,7 +1277,7 @@ git tag v1.0.0
|
||||
git push origin main --tags
|
||||
```
|
||||
|
||||
### Step 7.6: Post-Launch
|
||||
### Step 7.4: Post-Launch
|
||||
|
||||
**Hotfix workflow** for critical production bugs:
|
||||
|
||||
@@ -1139,7 +1288,7 @@ git push origin main --tags
|
||||
Bypasses normal sprint processes with a full audit trail:
|
||||
1. Creates a hotfix branch
|
||||
2. Implements the fix
|
||||
3. Ensures backport to development branch
|
||||
3. Ensures the fix is backported to `main` (the trunk)
|
||||
4. Documents the incident
|
||||
|
||||
**Post-mortem** after launch stabilizes:
|
||||
@@ -1158,26 +1307,30 @@ These topics apply across all phases.
|
||||
### Director Review Modes
|
||||
|
||||
Director gates are specialist agents that review your work at key workflow steps.
|
||||
By default they run at every checkpoint. You can control how much review you get.
|
||||
**By default none run.** `modes.review_mode` follows `modes.rigor`, and the
|
||||
default rigor, `rigor: minimal`, gives `solo`.
|
||||
|
||||
**Set your review intensity once during `/start`.** Saved to `modes.review_mode`
|
||||
in `project.yaml` (mirrored to `production/review-mode.txt` as a legacy fallback).
|
||||
| Mode | What runs | The default under | Best for |
|
||||
|------|-----------|-------------------|----------|
|
||||
| `full` | All director gates at every step | `rigor: full` | Studio-scale projects, learning the system |
|
||||
| `lean` | Directors only at phase transitions (`/gate-check`) | `rigor: standard` | Experienced devs |
|
||||
| `solo` | No director reviews | `rigor: minimal` | Solo projects, game jams, prototypes |
|
||||
|
||||
| Mode | What runs | Best for |
|
||||
|------|-----------|----------|
|
||||
| `full` | All director gates at every step | New projects, learning the system |
|
||||
| `lean` | Directors only at phase transitions (`/gate-check`) | Experienced devs |
|
||||
| `solo` | No director reviews | Game jams, prototypes, maximum speed |
|
||||
**Change it** with `/settings modes.review_mode=lean` (written to `project.yaml`;
|
||||
an explicit value wins over rigor), or `/settings --local modes.review_mode=full`
|
||||
for your machine only. `/start` does not set it.
|
||||
|
||||
**Override for a single run** without changing your global setting:
|
||||
**Override for a single run** without changing your setting:
|
||||
|
||||
```
|
||||
/brainstorm space horror --review full
|
||||
/architecture-decision --review solo
|
||||
```
|
||||
|
||||
The `--review` flag works on all gate-using skills. Change the global mode at any
|
||||
time by editing `modes.review_mode` in `project.yaml` or re-running `/start`.
|
||||
The `--review` flag works on all gate-using skills. The first of these that is
|
||||
set wins: the flag, `project.local.yaml`, `project.yaml`, a legacy
|
||||
`production/review-mode.txt`, then the rigor default. A `review-mode.txt` left
|
||||
from an older version still overrides rigor — delete it if the mode surprises you.
|
||||
|
||||
Full gate definitions and check pattern: `.claude/docs/director-gates.md`
|
||||
|
||||
@@ -1252,12 +1405,12 @@ The system has 12 hooks that run automatically:
|
||||
|------|---------|-------------|
|
||||
| `session-start.sh` | Session start | Shows branch, recent commits, detects active.md for recovery |
|
||||
| `detect-gaps.sh` | Session start | Detects fresh projects (no engine, no concept) and suggests `/start` |
|
||||
| `pre-compact.sh` | Before compaction | Dumps session state into conversation for auto-recovery |
|
||||
| `post-compact.sh` | After compaction | Reminds Claude to restore session state from `active.md` |
|
||||
| `pre-compact.sh` | Before compaction | Logs the compaction (its output does not reach Claude) |
|
||||
| `post-compact.sh` | After compaction | Debug-log reminder only (its output does not reach Claude) |
|
||||
| `notify.sh` | Notification event | Shows Windows toast notification via PowerShell |
|
||||
| `validate-commit.sh` | Before commit | Checks for design doc references, valid JSON, no hardcoded values |
|
||||
| `validate-push.sh` | Before push | Warns on pushes to main/develop |
|
||||
| `validate-assets.sh` | Before commit | Checks asset naming and size |
|
||||
| `validate-push.sh` | Before push | Warns on pushes to main, master or release/* |
|
||||
| `validate-assets.sh` | After a file write | Checks data-file JSON, and asset naming in Godot's `assets/` |
|
||||
| `validate-skill-change.sh` | Skill file written | Advises running `/skill-test` after `.claude/skills/` changes |
|
||||
| `log-agent.sh` | Agent start | Logs agent invocations for audit trail |
|
||||
| `log-agent-stop.sh` | Agent stop | Completes agent audit trail (start + stop) |
|
||||
@@ -1275,8 +1428,8 @@ survive crashes and context compactions. Previous discussion about written
|
||||
sections can be safely compacted.
|
||||
|
||||
**Automatic recovery:** The `session-start.sh` hook detects and previews
|
||||
`active.md` automatically. The `pre-compact.sh` hook dumps state into the
|
||||
conversation before compaction.
|
||||
`active.md` automatically, and runs again after every compaction, so the
|
||||
checkpoint comes back when the conversation is summarised.
|
||||
|
||||
**Sprint status tracking:** `production/sprint-status.yaml` is the
|
||||
machine-readable story tracker. Written by `/sprint-plan` (init) and
|
||||
@@ -1316,32 +1469,38 @@ These detect which sections are present vs. missing and fill only the gaps.
|
||||
|
||||
### Gate System
|
||||
|
||||
Phase gates are formal checkpoints. Run `/gate-check` with the transition name:
|
||||
Phase gates are formal checkpoints. Run `/gate-check` with the phase you are
|
||||
entering:
|
||||
|
||||
```
|
||||
/gate-check concept # Concept -> Systems Design
|
||||
/gate-check systems-design # Systems Design -> Technical Setup
|
||||
/gate-check technical-setup # Technical Setup -> Pre-Production
|
||||
/gate-check pre-production # Pre-Production -> Production
|
||||
/gate-check production # Production -> Polish
|
||||
/gate-check polish # Polish -> Release
|
||||
/gate-check systems-design # Concept -> Systems Design
|
||||
/gate-check technical-setup # Systems Design -> Technical Setup
|
||||
/gate-check pre-production # Technical Setup -> Pre-Production
|
||||
/gate-check production # Pre-Production -> Production
|
||||
/gate-check polish # Production -> Polish
|
||||
/gate-check release # Polish -> Release
|
||||
```
|
||||
|
||||
**Verdicts:**
|
||||
- **PASS** -- all requirements met, advance to next phase
|
||||
- **CONCERNS** -- requirements met with acknowledged risks, passable
|
||||
- **CONCERNS** -- risks found; the stage advances only if you explicitly accept
|
||||
them, and the accepted risks are recorded
|
||||
- **NOT ASSESSED** -- something required could not be checked; the report names
|
||||
it, so supply it and re-run
|
||||
- **FAIL** -- requirements not met, blocks advancement with specific remediation
|
||||
|
||||
When a gate passes, `project.stage` in `project.yaml` is updated (only then) —
|
||||
mirrored to `production/stage.txt` — which controls the status line and `/help`
|
||||
behavior.
|
||||
When a gate passes — or you accept a CONCERNS verdict's risks — `project.stage`
|
||||
in `project.yaml` is updated (only then; a FAIL never advances it) — mirrored to
|
||||
`production/stage.txt`. At `standard` and `full` the stage drives
|
||||
the status line and `/help`; at `minimal` they follow the brief and stories
|
||||
instead.
|
||||
|
||||
### Reverse Documentation
|
||||
|
||||
For code that exists without design docs (common after brownfield adoption):
|
||||
|
||||
```
|
||||
/reverse-document src/gameplay/combat/
|
||||
/reverse-document design src/gameplay/combat/
|
||||
```
|
||||
|
||||
Reads existing code and generates GDD-format design documentation from it.
|
||||
@@ -1428,9 +1587,9 @@ conflicts go to `producer`.
|
||||
|
||||
## Appendix B: Slash Command Quick-Reference
|
||||
|
||||
### All 73 Commands by Category
|
||||
### All 74 Commands by Category
|
||||
|
||||
#### Onboarding and Navigation (6)
|
||||
#### Onboarding and Navigation (7)
|
||||
|
||||
| Command | Purpose | Phase |
|
||||
|---------|---------|-------|
|
||||
@@ -1439,6 +1598,7 @@ conflicts go to `producer`.
|
||||
| `/project-stage-detect` | Full project audit to determine current phase | Any |
|
||||
| `/setup-engine` | Configure engine, pin version, set preferences | 1 |
|
||||
| `/adopt` | Brownfield audit and migration plan | Any (existing projects) |
|
||||
| `/settings` | View or change project config (rigor, review mode, ...) | Any |
|
||||
| `/skill-improve` | Improve a skill via test-fix-retest loop | Any |
|
||||
|
||||
#### Game Design (6)
|
||||
@@ -1456,7 +1616,7 @@ conflicts go to `producer`.
|
||||
|
||||
| Command | Purpose | Phase |
|
||||
|---------|---------|-------|
|
||||
| `/ux-design` | Author UX specs (screen/flow, HUD, patterns) | 4 |
|
||||
| `/ux-design` | Author UX specs (screen/flow, HUD, patterns) | 3-4 |
|
||||
| `/ux-review` | Validate UX specs for accessibility and GDD alignment | 4 |
|
||||
|
||||
#### Architecture (4)
|
||||
@@ -1495,9 +1655,9 @@ conflicts go to `producer`.
|
||||
| `/scope-check` | Scope creep detection | 5 |
|
||||
| `/perf-profile` | Performance profiling workflow | 6 |
|
||||
| `/tech-debt` | Tech debt scanning and prioritization | 6 |
|
||||
| `/gate-check` | Formal phase gate with PASS/CONCERNS/FAIL | All transitions |
|
||||
| `/gate-check` | Formal phase gate with PASS/CONCERNS/NOT ASSESSED/FAIL | All transitions |
|
||||
| `/reverse-document` | Generate design docs from existing code | Any |
|
||||
| `/security-audit` | Security vulnerability audit (save, network, input) | 6-7 |
|
||||
| `/security-audit` | Security vulnerability audit (save, network, input) | 6 |
|
||||
|
||||
#### QA and Testing (9)
|
||||
|
||||
@@ -1507,8 +1667,8 @@ conflicts go to `producer`.
|
||||
| `/smoke-check` | Critical path smoke test gate before QA hand-off | 5-6 |
|
||||
| `/soak-test` | Soak test protocol for extended play sessions | 6 |
|
||||
| `/regression-suite` | Map test coverage, identify fixed bugs lacking regression tests | 5-6 |
|
||||
| `/test-setup` | Scaffold test framework and CI/CD pipeline | 4 |
|
||||
| `/test-helpers` | Generate engine-specific test helper libraries | 4-5 |
|
||||
| `/test-setup` | Scaffold test framework and CI/CD pipeline | 3 |
|
||||
| `/test-helpers` | Generate engine-specific test helper libraries | 3-5 |
|
||||
| `/test-evidence-review` | Quality review of test files and manual evidence | 5 |
|
||||
| `/test-flakiness` | Detect non-deterministic tests from CI logs | 5-6 |
|
||||
| `/skill-test` | Validate skill files for structural and behavioral correctness | Any |
|
||||
@@ -1528,10 +1688,10 @@ conflicts go to `producer`.
|
||||
|
||||
| Command | Purpose | Phase |
|
||||
|---------|---------|-------|
|
||||
| `/release-checklist` | Pre-release validation | 7 |
|
||||
| `/release-checklist` | Pre-release validation | 6 |
|
||||
| `/launch-checklist` | Full cross-department launch readiness | 7 |
|
||||
| `/changelog` | Auto-generate internal changelog | 7 |
|
||||
| `/patch-notes` | Player-facing patch notes | 7 |
|
||||
| `/changelog` | Auto-generate internal changelog | 6 |
|
||||
| `/patch-notes` | Player-facing patch notes | 6 |
|
||||
| `/hotfix` | Emergency fix workflow | 7+ |
|
||||
| `/day-one-patch` | Scoped patch for issues found after gold master | 7+ |
|
||||
|
||||
@@ -1540,7 +1700,7 @@ conflicts go to `producer`.
|
||||
| Command | Purpose | Phase |
|
||||
|---------|---------|-------|
|
||||
| `/prototype` | Concept prototype — validate core idea before GDDs | 1 |
|
||||
| `/art-bible` | Guided Art Bible authoring — visual identity spec | 1-2 |
|
||||
| `/art-bible` | Guided Art Bible authoring — visual identity spec | 1-4 |
|
||||
| `/vertical-slice` | Production-quality end-to-end build before Production | 4 |
|
||||
| `/localize` | String extraction and validation | 6-7 |
|
||||
|
||||
@@ -1570,7 +1730,7 @@ conflicts go to `producer`.
|
||||
3. /setup-engine (pin engine and version)
|
||||
4. /design-review on concept doc (optional, recommended)
|
||||
5. /map-systems (decompose concept into systems with deps and priorities)
|
||||
6. /gate-check concept (verify you're ready for Systems Design)
|
||||
6. /gate-check systems-design (verify you're ready for Systems Design)
|
||||
7. /design-system per system (guided GDD authoring)
|
||||
```
|
||||
|
||||
@@ -1579,14 +1739,18 @@ conflicts go to `producer`.
|
||||
```
|
||||
1. /design-review on each GDD (make sure they're solid)
|
||||
2. /review-all-gdds (cross-GDD consistency)
|
||||
3. /gate-check systems-design
|
||||
3. /gate-check technical-setup
|
||||
4. /create-architecture + /architecture-decision (per major decision)
|
||||
5. /architecture-review
|
||||
6. /create-control-manifest
|
||||
7. /gate-check technical-setup
|
||||
8. /create-epics layer: foundation + /create-stories [slug] (define epics, break into stories)
|
||||
9. /sprint-plan new
|
||||
10. /story-readiness -> implement -> /story-done (story lifecycle)
|
||||
7. /art-bible (sections 1–4 now) + /test-setup + /ux-design accessibility + /ux-design patterns
|
||||
8. /gate-check pre-production
|
||||
9. /ux-design per key screen + /ux-review
|
||||
10. /vertical-slice (recommended before committing to epics)
|
||||
11. /create-epics layer: foundation + /create-stories [slug] (define epics, break into stories)
|
||||
12. /sprint-plan new
|
||||
13. /gate-check production
|
||||
14. /story-readiness -> implement -> /story-done (story lifecycle)
|
||||
```
|
||||
|
||||
### Workflow 3: "I need to add a complex feature mid-production"
|
||||
@@ -1638,16 +1802,17 @@ conflicts go to `producer`.
|
||||
### Workflow 7: "Shipping the game"
|
||||
|
||||
```
|
||||
1. /gate-check polish (verify Polish phase is complete)
|
||||
2. /tech-debt (decide what's acceptable at launch)
|
||||
3. /localize (final localization pass)
|
||||
4. /release-checklist v1.0.0
|
||||
5. /launch-checklist (full cross-department validation)
|
||||
6. /team-release (coordinate the release)
|
||||
7. /patch-notes and /changelog
|
||||
8. Ship!
|
||||
9. /hotfix if anything breaks post-launch
|
||||
10. Post-mortem after launch stabilizes
|
||||
1. /tech-debt (decide what's acceptable at launch)
|
||||
2. /security-audit (the release gate reads the newest report)
|
||||
3. /localize qa for every language you ship
|
||||
4. /release-checklist all
|
||||
5. /changelog and /patch-notes (drafts; /team-release finalizes them)
|
||||
6. /gate-check release (verify Polish is complete and the game is ready to release)
|
||||
7. /launch-checklist (full cross-department validation)
|
||||
8. /team-release (coordinate the release)
|
||||
9. Ship!
|
||||
10. /hotfix if anything breaks post-launch
|
||||
11. Post-mortem after launch stabilizes
|
||||
```
|
||||
|
||||
### Workflow 8: "I'm lost / don't know what to do next"
|
||||
@@ -1675,7 +1840,8 @@ conflicts go to `producer`.
|
||||
delta time, accessibility, etc.).
|
||||
|
||||
4. **Compact proactively.** At ~65-70% context usage, compact or `/clear`.
|
||||
The pre-compact hook saves your progress. Do not wait until you are at the
|
||||
Your checkpoint in `active.md` survives it, and `session-start.sh` shows it
|
||||
again afterwards. Do not wait until you are at the
|
||||
limit.
|
||||
|
||||
5. **Use the right tier of agent.** Do not ask `creative-director` to write a
|
||||
|
||||
@@ -42,7 +42,7 @@ Engine-specialist agents are instructed to:
|
||||
|
||||
- After upgrading the engine version
|
||||
- When the LLM model is updated (new knowledge cutoff)
|
||||
- After running `/refresh-docs` (if available)
|
||||
- After running `/setup-engine refresh`
|
||||
- When you discover an API the model gets wrong
|
||||
|
||||
### How to Update
|
||||
|
||||
@@ -53,7 +53,7 @@ Changes between Godot versions, focused on post-LLM-cutoff changes (4.4+).
|
||||
| Core | `OS.execute_with_pipe` | Added optional `blocking` parameter |
|
||||
| Core | `RegEx.compile/create_from_string` | Added optional `show_error` parameter |
|
||||
| Rendering | `RenderingDevice.draw_list_begin` | Many parameters removed; `breadcrumb` parameter added |
|
||||
| Rendering | Shader texture types | Parameter/return types changed from `Texture2D` to `Texture` |
|
||||
| Rendering | `Shader.set_default_texture_parameter()` / `get_default_texture_parameter()` | Parameter/return type changed from `Texture2D` to `Texture`; the shading language did not change |
|
||||
| Particles | `.restart()` method | Added optional `keep_seed` parameter (CPU/GPU 2D/3D) |
|
||||
| GUI | `RichTextLabel.push_meta` | Added optional `tooltip` parameter |
|
||||
| GUI | `GraphEdit.connect_node` | Added optional `keep_alive` parameter |
|
||||
|
||||
@@ -7,21 +7,36 @@ This supplements (not replaces) the agent's built-in knowledge.
|
||||
|
||||
## GDScript (4.5+)
|
||||
|
||||
- **Variadic arguments**: Functions can accept arbitrary parameter counts
|
||||
- **Variadic arguments**: Functions can accept arbitrary parameter counts. The
|
||||
rest parameter is written `...name`, comes last, and is typed `Array` or left
|
||||
untyped — `values: Variant...` and `...values: Array[int]` do not parse
|
||||
```gdscript
|
||||
func log_values(prefix: String, values: Variant...) -> void:
|
||||
func log_values(prefix: String, ...values: Array) -> void:
|
||||
for v in values:
|
||||
print(prefix, ": ", v)
|
||||
```
|
||||
|
||||
- **Lambdas capture local variables by value** (every Godot 4 version): a local
|
||||
is captured once, when the lambda is created, and a lambda cannot reassign an
|
||||
outer local — `var hit := false` / `func(): hit = true` leaves the caller's
|
||||
`hit` false. Share state through a reference type (a Dictionary, an Array or
|
||||
an object) and mutate its contents. A rest parameter works in a lambda too, so
|
||||
`func(...args)` connects to a signal with any number of arguments (observed on
|
||||
4.6.1; a one-argument lambda on a zero-argument signal errors "Method expected
|
||||
1 argument(s), but called with 0")
|
||||
```gdscript
|
||||
var state := {"emitted": false}
|
||||
some_signal.connect(func(...args): state.emitted = true)
|
||||
```
|
||||
|
||||
- **Abstract classes and methods**: Use `@abstract` to enforce inheritance
|
||||
```gdscript
|
||||
@abstract
|
||||
class_name BaseEnemy extends CharacterBody3D
|
||||
|
||||
@abstract
|
||||
func get_attack_pattern() -> Array[Attack]:
|
||||
pass # Subclasses MUST override
|
||||
# No body: "a newline or a semicolon is expected after the function header".
|
||||
# Subclasses MUST override it.
|
||||
@abstract func get_attack_pattern() -> Array[Attack]
|
||||
```
|
||||
|
||||
- **Script backtracing**: Detailed call stacks available even in Release builds
|
||||
@@ -99,6 +114,49 @@ This supplements (not replaces) the agent's built-in knowledge.
|
||||
`rg --type gdscript` is a hard error — the search never executes.
|
||||
Always use `rg --glob "*.gd"` (shell) or `glob: "*.gd"` (Grep tool) to filter GDScript files.
|
||||
|
||||
## Command Line — Tests and Parse Check
|
||||
|
||||
Flags, from Godot's command-line tutorial: `--headless` (headless display and a
|
||||
dummy audio driver, "useful for servers and with `--script`"), `--path <dir>`
|
||||
(a directory holding `project.godot`), `-s`/`--script <script>`, `-d`/`--debug`
|
||||
(the local stdout debugger), `--remote-debug <protocol>://<host>[:<port>]`,
|
||||
`--import` (starts the editor, waits for the import, and quits),
|
||||
`--quit-after <n>` (iterations), `--export-debug <preset>` (implies `--import`)
|
||||
and `--check-only` (parse for errors and quit, with `--script`). The editor is
|
||||
not on `PATH` by default: on Windows and Linux run the binary by its relative or
|
||||
absolute path; on macOS run `Godot.app/Contents/MacOS/Godot` inside the bundle.
|
||||
|
||||
gdUnit4's runner is `res://addons/gdUnit4/bin/GdUnitCmdTool.gd`; `-a <dir|suite>`
|
||||
adds suites, reports go to `res://reports/` by default (`-rd` changes it), and
|
||||
the documented exit codes are 0 (all passed), 100 (failures) and 101 (warnings).
|
||||
The command the framework uses:
|
||||
`godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode`.
|
||||
|
||||
Observed on Godot 4.6.1 with gdUnit4 6.1.3 — not in the docs:
|
||||
- 101 is also the exit when every test passed but a test leaked orphan nodes;
|
||||
105 means a test script does not parse; 103 means gdUnit4 refused to run
|
||||
headless (`--ignoreHeadlessMode` missing). 104 is gdUnit4 refusing a Godot
|
||||
older than 4.3 — not reproducible on the pin.
|
||||
- Over zero tests the runner prints `No test cases found` and exits 0.
|
||||
- Without `--remote-debug tcp://127.0.0.1:0`, a script error opens the `-d`
|
||||
debugger and the run waits at a `debug>` prompt; with it, every run prints two
|
||||
`ERROR:` lines about the remote port, which are expected.
|
||||
- A fresh clone has no `.godot/` class cache: run
|
||||
`godot --headless --path . --import` first, or `GdUnitCmdTool.gd` does not
|
||||
load and the run exits 1 having run nothing.
|
||||
- `--check-only` with `-s <file>` exits 1 on valid code that names an autoload
|
||||
(`Identifier not found`), and `--import` / `--quit-after` exit 0 on a parse
|
||||
error — neither is a parse check. The framework's parse check is
|
||||
`godot --headless --path . -s res://.claude/scripts/godot-parse-check.gd -- res://<file>.gd …`
|
||||
(exit 1 when a script does not load).
|
||||
- On Windows, a quoted full path to the editor (`"C:/Program Files/Godot/…exe"`)
|
||||
runs from Git Bash with its stdout and exit code intact.
|
||||
|
||||
Sources:
|
||||
- Command line tutorial: https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html
|
||||
- gdUnit4 command line tool: https://godot-gdunit-labs.github.io/gdUnit4/latest/advanced_testing/cmd/
|
||||
- GDScript reference, lambda functions and rest parameters: https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html
|
||||
|
||||
## Platform (4.5+)
|
||||
|
||||
- **visionOS export**: First new platform since open-sourcing (windowed app mode)
|
||||
|
||||
@@ -38,6 +38,6 @@ with the "Use Instead" column.
|
||||
| String-based `connect()` | Typed signal connections | Type-safe, refactor-friendly |
|
||||
| `$NodePath` in `_process()` | `@onready var` cached reference | Performance: path lookup every frame |
|
||||
| Untyped `Array` / `Dictionary` | `Array[Type]`, typed variables | GDScript compiler optimizations |
|
||||
| `Texture2D` in shader parameters | `Texture` base type | Changed in 4.4 |
|
||||
| `Texture2D` in `Shader.set_default_texture_parameter()` / `get_default_texture_parameter()` | `Texture` base type | Changed in 4.4; the shading language's `sampler2D` / `texture()` did not change |
|
||||
| Manual post-process viewport chains | `Compositor` + `CompositorEffect` | Structured post-processing (4.3+) |
|
||||
| GodotPhysics3D for new projects | Jolt Physics 3D | Default since 4.6; better stability |
|
||||
|
||||
@@ -19,7 +19,9 @@ Last verified: 2026-02-12 | Engine: Godot 4.6
|
||||
|
||||
### 4.4 Changes
|
||||
- **`RenderingDevice.draw_list_begin`**: Many parameters removed; optional `breadcrumb` added
|
||||
- **Shader texture types**: Changed from `Texture2D` to `Texture` base type
|
||||
- **`Shader` default-texture methods**: `set_default_texture_parameter()` takes and
|
||||
`get_default_texture_parameter()` returns `Texture`, not `Texture2D` (the shading
|
||||
language's `sampler2D` / `texture()` did not change)
|
||||
- **Particles `.restart()`**: Added optional `keep_seed` parameter
|
||||
|
||||
### 4.3 Changes (in training data)
|
||||
@@ -55,5 +57,7 @@ Windows default backend: D3D12 (was Vulkan pre-4.6)
|
||||
## Common Mistakes
|
||||
- Assuming Vulkan is the default backend on Windows (D3D12 since 4.6)
|
||||
- Using manual viewport chains instead of Compositor for post-processing
|
||||
- Using `Texture2D` in shader uniform types (use `Texture` since 4.4)
|
||||
- Passing or expecting `Texture2D` in `Shader.set_default_texture_parameter()` /
|
||||
`get_default_texture_parameter()` (the type is `Texture` since 4.4 — the shading
|
||||
language's `sampler2D` / `texture()` did not change)
|
||||
- Not using Shader Baker for projects with many shader variants
|
||||
|
||||
@@ -191,6 +191,13 @@ public override void RecordRenderGraph(RenderGraph renderGraph, ContextContainer
|
||||
|
||||
**Replaces:** Old `CommandBuffer.Execute()` pattern.
|
||||
|
||||
**This is URP's API.** `RecordRenderGraph` overrides URP's `ScriptableRenderPass`.
|
||||
HDRP custom passes are a separate API: a `CustomPass` subclass, run from a Custom
|
||||
Pass Volume, overrides `Setup(ScriptableRenderContext renderContext, CommandBuffer cmd)`,
|
||||
`Execute(CustomPassContext ctx)` and `Cleanup()` (HDRP 17.3, *Create a Custom
|
||||
Pass in a C# script*:
|
||||
https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@17.3/manual/Custom-Pass-Scripting.html).
|
||||
|
||||
---
|
||||
|
||||
## Performance
|
||||
@@ -296,6 +303,40 @@ public IEnumerator Player_TakesDamage_HealthDecreases() {
|
||||
|
||||
---
|
||||
|
||||
## Command Line — Tests
|
||||
|
||||
Documented (Unity Manual, *Run tests from the command line*; Test Framework
|
||||
command-line reference):
|
||||
`<Unity editor> -runTests -batchmode -projectPath <path> -testPlatform <platform> -testResults <file>`.
|
||||
`-batchmode` removes the need for user input. `-testPlatform` takes `EditMode`,
|
||||
`PlayMode` (Play Mode tests in the Editor) or a player platform; with no value,
|
||||
tests run in Edit Mode. `-testResults` defaults to the project root, and the
|
||||
file follows NUnit's XML format: the `<test-run>` element carries
|
||||
`testcasecount`, `result`, `passed` and `failed`, and each `<test-case>` a
|
||||
`fullname` and a `result` of `Passed`, `Failed`, `Inconclusive` or `Skipped`.
|
||||
Unity defines no common exit codes for test runs.
|
||||
|
||||
Observed on Unity 6000.3.23f1 — not in the docs:
|
||||
- `-runTests` exits 0 when every test passes and 2 when one fails; 1 is a
|
||||
compile error (no results file is written), 3 a failed run, 4 an unknown
|
||||
`-testPlatform`. It exits by itself — no `-quit`.
|
||||
- Tests outside `Assets/` are never compiled: the run reports
|
||||
`testcasecount="0"`, `result="Passed"` and exits 0 — a false pass.
|
||||
- Without the `com.unity.test-framework` package, `-runTests` hangs rather
|
||||
than failing.
|
||||
- `Unity` on `PATH` may be Unity's separate CLI, not the editor; it rejects
|
||||
`-batchmode` and `-version` with exit 2. Name the editor executable by its
|
||||
full path.
|
||||
- `-batchmode -quit -projectPath . -logFile -` exits 1 on a compile error and
|
||||
0 when clean.
|
||||
|
||||
Sources:
|
||||
- Run tests from the command line: https://docs.unity3d.com/6000.3/Documentation/Manual/test-framework/run-tests-from-command-line.html
|
||||
- Test Framework command-line arguments: https://docs.unity3d.com/Packages/com.unity.test-framework@1.4/manual/reference-command-line.html
|
||||
- NUnit test result XML format: https://docs.nunit.org/articles/nunit/technical-notes/usage/Test-Result-XML-Format.html
|
||||
|
||||
---
|
||||
|
||||
## Debugging
|
||||
|
||||
### Use Logging Best Practices
|
||||
|
||||
@@ -366,9 +366,11 @@ async void CheckForUpdates() {
|
||||
// ❌ OLD: Resources.Load (synchronous, blocks frame)
|
||||
GameObject prefab = Resources.Load<GameObject>("Enemies/Goblin");
|
||||
|
||||
// ✅ NEW: Addressables (async, non-blocking)
|
||||
var handle = await Addressables.LoadAssetAsync<GameObject>("Enemies/Goblin").Task;
|
||||
GameObject prefab = handle.Result;
|
||||
// ✅ NEW: Addressables (async, non-blocking) — keep the handle so it can be released
|
||||
AsyncOperationHandle<GameObject> handle = Addressables.LoadAssetAsync<GameObject>("Enemies/Goblin");
|
||||
GameObject prefab = await handle.Task;
|
||||
// ... when the asset is no longer needed:
|
||||
Addressables.Release(handle);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -21,6 +21,42 @@ These are production-ready recommendations as of UE 5.7.
|
||||
|
||||
---
|
||||
|
||||
## Command Line — Build and Automation Tests (per platform)
|
||||
|
||||
Build the project's own editor target before running tests (a fresh checkout has
|
||||
no compiled game module), then run the automation tests with the editor. Epic
|
||||
recommends building `<Project>Editor` rather than `UnrealEditor`, so the modules
|
||||
the `.uproject` disables stay disabled. Give the project as an absolute path.
|
||||
|
||||
| Step | Windows | Linux | macOS |
|
||||
|------|---------|-------|-------|
|
||||
| Build the editor target | `Engine/Binaries/DotNET/UnrealBuildTool/UnrealBuildTool.exe <Project>Editor Win64 Development -Project="<abs>/<Project>.uproject"` | `Engine/Build/BatchFiles/Linux/Build.sh <Project>Editor Linux Development -Project="<abs>/<Project>.uproject"` | `Engine/Build/BatchFiles/Mac/Build.sh <Project>Editor Mac Development -Project="<abs>/<Project>.uproject"` |
|
||||
| Editor executable for a command-line run | `Engine/Binaries/Win64/UnrealEditor-Cmd.exe` | `Engine/Binaries/Linux/UnrealEditor` | **NOT SOURCEABLE** — Epic documents only the `Engine/Binaries/Mac/UnrealEditor.app` bundle, not a command-line editor inside it |
|
||||
| Packaged build | `Engine/Binaries/DotNET/AutomationTool/AutomationTool.exe BuildCookRun … -platform=Win64` | `Engine/Build/BatchFiles/RunUAT.sh BuildCookRun … -platform=Linux` | `Engine/Build/BatchFiles/RunUAT.sh BuildCookRun … -platform=Mac` |
|
||||
|
||||
The automation arguments are the same on every platform:
|
||||
`"<abs>/<Project>.uproject" -ExecCmds="Automation RunTests <Project>.; Quit" -unattended -nullrhi -stdout -FullStdOutLogOutput`.
|
||||
`RunTests` is a partial (substring) match. Each test prints
|
||||
`Test Completed. Result={<status>}`, and the run ends with
|
||||
`**** TEST COMPLETE. EXIT CODE: <n> ****` — exit code 0 means no test failed.
|
||||
Only one `Automation` run request is allowed per `-ExecCmds`, and `-testexit=` is
|
||||
legacy.
|
||||
|
||||
The Windows column was run on UE 5.7. The Linux and macOS columns come from
|
||||
Epic's documentation and forum answers by Epic staff (sources below); Epic never
|
||||
prints the full Linux test line, so it is assembled from the executable and the
|
||||
platform-neutral arguments.
|
||||
|
||||
Sources:
|
||||
- Build.sh on Linux and Mac, platform names — *Create an Installed Build*: https://dev.epicgames.com/documentation/en-us/unreal-engine/create-an-installed-build-of-unreal-engine?application_version=5.7
|
||||
- `RunUBT.sh <Target> [Linux|Mac] Development` — *Unreal Insights*: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine?application_version=5.7
|
||||
- `Engine/Binaries/Linux/UnrealEditor`, `Engine/Binaries/Mac/UnrealEditor.app` — *Onboarding Licensees*: https://dev.epicgames.com/documentation/en-us/unreal-engine/onboarding-licensees-in-unreal-engine?application_version=5.7 and *Linux Development Quickstart*: https://dev.epicgames.com/documentation/en-us/unreal-engine/linux-development-quickstart-for-unreal-engine?application_version=5.7
|
||||
- `-nullrhi`, `-unattended`, `-stdout`, `-ExecCmds` — *Command-Line Arguments Reference*: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-command-line-arguments-reference?application_version=5.7
|
||||
- Running tests from the command line — *Run Automation Tests*: https://dev.epicgames.com/documentation/en-us/unreal-engine/run-automation-tests-in-unreal-engine?application_version=5.7 ; result lines and exit code — *Review Test Results*: https://dev.epicgames.com/documentation/en-us/unreal-engine/review-test-results-in-unreal-engine?application_version=5.7
|
||||
- `RunUAT.sh` from `Engine/Build/BatchFiles` on Mac/Linux — *Unreal Automation Tool Overview*: https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-automation-tool-overview-for-unreal-engine?application_version=5.7
|
||||
|
||||
---
|
||||
|
||||
## C++ Coding
|
||||
|
||||
### Use Modern C++ Features (C++20 in UE5.7)
|
||||
|
||||
@@ -107,8 +107,8 @@ void OnRep_Health() {
|
||||
### Server RPC (Client → Server)
|
||||
|
||||
```cpp
|
||||
// Client calls, server executes
|
||||
UFUNCTION(Server, Reliable)
|
||||
// Client calls, server executes. WithValidation declares Server_TakeDamage_Validate.
|
||||
UFUNCTION(Server, Reliable, WithValidation)
|
||||
void Server_TakeDamage(int32 Damage);
|
||||
|
||||
void AMyCharacter::Server_TakeDamage_Implementation(int32 Damage) {
|
||||
|
||||
@@ -176,6 +176,21 @@ void UMyAttributeSet::OnRep_Health(const FGameplayAttributeData& OldHealth) {
|
||||
// Implement other OnRep functions similarly...
|
||||
```
|
||||
|
||||
### Clamping Attributes
|
||||
|
||||
Attribute Sets have no built-in clamping: the Data Table `Min Value` and
|
||||
`Max Value` columns have no effect. Clamp in the Attribute Set:
|
||||
- `PreAttributeChange()` is called just before any modification to an
|
||||
attribute, and is the hook for rules like
|
||||
`Health = Clamp(Health, 0, MaxHealth)` — its `NewValue` is mutable.
|
||||
- `PreAttributeBaseChange()` is called just before a change to an attribute's
|
||||
**base** value when an aggregator exists, and `PostGameplayEffectExecute()`
|
||||
just after a Gameplay Effect is executed to modify the base value — clamp
|
||||
base-value changes from instant effects there.
|
||||
|
||||
Stacking rules govern re-applications of the same Gameplay Effect; they do not
|
||||
bound one attribute pushed by different effects.
|
||||
|
||||
---
|
||||
|
||||
## Gameplay Abilities
|
||||
@@ -391,4 +406,5 @@ void AMyCharacter::OnHealthChanged(const FOnAttributeChangeData& Data) {
|
||||
|
||||
## Sources
|
||||
- https://docs.unrealengine.com/5.7/en-US/gameplay-ability-system-for-unreal-engine/
|
||||
- Clamping: *Gameplay Attributes and Attribute Sets* https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-attributes-and-attribute-sets-for-the-gameplay-ability-system-in-unreal-engine ; `UAttributeSet` API https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UAttributeSet ; `PreAttributeChange` https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UAttributeSet/PreAttributeChange
|
||||
- https://github.com/tranek/GASDocumentation (community guide)
|
||||
|
||||
+59
-23
@@ -5,6 +5,34 @@ These show what runs before and after each skill, and what artifacts flow betwee
|
||||
|
||||
---
|
||||
|
||||
## Default Path: Rigor Minimal (Four Steps to Code)
|
||||
|
||||
`modes.rigor: minimal` is the default. The one-page brief is the design record and
|
||||
its build order is the plan, so there is no epic planning, sprint or phase gate to run.
|
||||
Every skill below still runs at any tier; rigor changes what is required, not what
|
||||
is allowed. `/help` follows this route at `minimal`.
|
||||
|
||||
```
|
||||
MINIMAL PATH (modes.rigor: minimal — the default; no /gate-check, stage stays Concept)
|
||||
/setup-engine ───────────────────────────────────────────────► project.yaml + CLAUDE.md
|
||||
/brainstorm ─────────────────────────────────────────────────► design/game-brief.md (one page)
|
||||
│ (replaces concept doc, systems index, GDDs)
|
||||
▼
|
||||
/create-stories ─────────────────────────────────────────────► production/epics/[slug]/story-*.md
|
||||
│ (brief's build order is the plan —
|
||||
│ no /create-epics, no /sprint-plan)
|
||||
▼ (one story at a time, in build order)
|
||||
/dev-story [story] ──────────────────────────────────────────► routes to correct programmer agent
|
||||
/story-done [story] ─────────────────────────────────────────► story closed + next story named
|
||||
│
|
||||
└── back to /dev-story until every story is Complete, then:
|
||||
play the build · /create-stories for more · /settings to raise rigor
|
||||
```
|
||||
|
||||
The overview below is the `standard`/`full` pipeline.
|
||||
|
||||
---
|
||||
|
||||
## Full Pipeline Overview (Zero to Ship)
|
||||
|
||||
```
|
||||
@@ -16,11 +44,13 @@ PHASE 1: CONCEPT
|
||||
│ PROCEED (validate idea BEFORE writing GDDs)
|
||||
▼
|
||||
/design-review [game-concept.md] ────────────────────────────► concept validated
|
||||
/art-bible ──────────────────────────────────────────────────► design/art/art-bible.md
|
||||
/map-systems ────────────────────────────────────────────────► design/gdd/systems-index.md
|
||||
/gate-check ─────────────────────────────────────────────────► PASS → advance to systems-design
|
||||
│
|
||||
▼
|
||||
PHASE 2: SYSTEMS DESIGN
|
||||
/map-systems ────────────────────────────────────────────────► design/gdd/systems-index.md
|
||||
/map-systems next ───────────────────────────────────────────► picks the next system to design
|
||||
│
|
||||
▼ (for each system, in dependency order)
|
||||
/design-system [name] ──────────────────────────────────────► design/gdd/[system].md
|
||||
@@ -32,30 +62,30 @@ PHASE 2: SYSTEMS DESIGN
|
||||
│
|
||||
▼
|
||||
PHASE 3: TECHNICAL SETUP
|
||||
/create-architecture ────────────────────────────────────────► docs/architecture/master.md
|
||||
/create-architecture ────────────────────────────────────────► docs/architecture/architecture.md
|
||||
/architecture-decision (×N) ─────────────────────────────────► docs/architecture/[adr-nnn].md
|
||||
/architecture-review ────────────────────────────────────────► review report + docs/architecture/tr-registry.yaml
|
||||
/create-control-manifest ────────────────────────────────────► docs/architecture/control-manifest.md
|
||||
/test-setup ─────────────────────────────────────────────────► test framework + CI/CD pipeline
|
||||
/test-helpers ───────────────────────────────────────────────► tests/helpers/ (engine-specific library)
|
||||
/ux-design accessibility ─────────────────────────────────────► design/accessibility-requirements.md
|
||||
/ux-design patterns ──────────────────────────────────────────► design/ux/interaction-patterns.md
|
||||
/gate-check ─────────────────────────────────────────────────► PASS → advance to pre-production
|
||||
│
|
||||
▼
|
||||
PHASE 4: PRE-PRODUCTION
|
||||
[UX — before epics, so specs exist when stories are written]
|
||||
/ux-design [screen/hud/patterns] ────────────────────────────► design/ux/*.md
|
||||
/ux-design [screen/hud] ──────────────────────────────────────► design/ux/*.md
|
||||
/ux-review ──────────────────────────────────────────────────► UX specs approved (HARD gate for /team-ui)
|
||||
|
||||
[Test infrastructure — scaffold before stories reference tests]
|
||||
/test-setup ─────────────────────────────────────────────────► test framework + CI/CD pipeline
|
||||
/test-helpers ───────────────────────────────────────────────► tests/helpers/[engine-specific].gd
|
||||
|
||||
[Vertical slice — before epics, validate full game loop]
|
||||
/vertical-slice ─────────────────────────────────────────────► prototypes/[name]-vertical-slice/REPORT.md
|
||||
/playtest-report ────────────────────────────────────────────► production/playtests/
|
||||
/playtest-report ────────────────────────────────────────────► production/qa/playtests/
|
||||
|
||||
[Stories + sprint plan — only after vertical slice PROCEEDS]
|
||||
/create-epics [layer] ───────────────────────────────────────► production/epics/*/EPIC.md
|
||||
/create-stories [epic-slug] ─────────────────────────────────► production/epics/*/story-*.md
|
||||
/sprint-plan new ────────────────────────────────────────────► production/sprints/sprint-01.md
|
||||
/sprint-plan new ────────────────────────────────────────────► production/sprints/sprint-001.md
|
||||
/gate-check ─────────────────────────────────────────────────► PASS → advance to production
|
||||
│
|
||||
▼
|
||||
@@ -70,14 +100,14 @@ PHASE 5: PRODUCTION (repeating sprint loop)
|
||||
/code-review ────────────────────────────────────────────────► code review report
|
||||
/scope-check ────────────────────────────────────────────────► scope creep detected / clear
|
||||
/content-audit ──────────────────────────────────────────────► GDD content gaps identified
|
||||
/bug-report ─────────────────────────────────────────────────► production/qa/bugs/bug-NNN.md
|
||||
/bug-report ─────────────────────────────────────────────────► production/qa/bugs/BUG-NNNN.md
|
||||
/bug-triage ─────────────────────────────────────────────────► bugs re-prioritized + assigned
|
||||
|
||||
[Team skills for feature areas — spawn when working a full feature]
|
||||
/team-combat / /team-narrative / /team-ui / /team-level / /team-audio
|
||||
|
||||
[QA cycle per sprint]
|
||||
/qa-plan ────────────────────────────────────────────────────► production/qa/qa-plan-sprint-NN.md
|
||||
/qa-plan ────────────────────────────────────────────────────► production/qa/qa-plan-[sprint-slug]-[date].md
|
||||
/smoke-check ────────────────────────────────────────────────► smoke test gate (PASS/FAIL)
|
||||
/regression-suite ───────────────────────────────────────────► coverage gaps + missing regression tests
|
||||
/test-evidence-review ───────────────────────────────────────► evidence quality report
|
||||
@@ -98,17 +128,18 @@ PHASE 6: POLISH
|
||||
/asset-audit ────────────────────────────────────────────────► asset compliance report
|
||||
/tech-debt ──────────────────────────────────────────────────► docs/tech-debt-register.md
|
||||
/soak-test ──────────────────────────────────────────────────► soak test protocol + results
|
||||
/localize ───────────────────────────────────────────────────► localization readiness report
|
||||
/team-polish ────────────────────────────────────────────────► polish sprint orchestrated
|
||||
/team-qa ────────────────────────────────────────────────────► full QA cycle sign-off
|
||||
/security-audit ─────────────────────────────────────────────► production/security/security-audit-[date]-[scope].md
|
||||
/localize qa ────────────────────────────────────────────────► production/localization/loc-qa-[locale]-[date].md
|
||||
/release-checklist ──────────────────────────────────────────► production/releases/release-checklist-[version].md
|
||||
/changelog ──────────────────────────────────────────────────► docs/CHANGELOG.md
|
||||
/patch-notes ────────────────────────────────────────────────► docs/patch-notes/[version].md (draft)
|
||||
/gate-check ─────────────────────────────────────────────────► PASS → advance to release
|
||||
│
|
||||
▼
|
||||
PHASE 7: RELEASE
|
||||
/launch-checklist ───────────────────────────────────────────► launch readiness report
|
||||
/release-checklist ──────────────────────────────────────────► platform-specific checklist
|
||||
/changelog ──────────────────────────────────────────────────► CHANGELOG.md
|
||||
/patch-notes ────────────────────────────────────────────────► player-facing notes
|
||||
/team-release ───────────────────────────────────────────────► release pipeline orchestrated
|
||||
│
|
||||
▼ (post-launch, ongoing)
|
||||
@@ -155,8 +186,11 @@ upstream GDDs (input, if any)
|
||||
|
||||
## Skill Chain: UX / UI Pipeline in Detail
|
||||
|
||||
UX specs are authored in Phase 4 (Pre-Production), before epics are written, so
|
||||
that story acceptance criteria can reference specific UX artifacts.
|
||||
Screen and HUD specs are authored in Phase 4 (Pre-Production), before epics are
|
||||
written, so that story acceptance criteria can reference specific UX artifacts.
|
||||
Accessibility and interaction-pattern specs are authored earlier, in Phase 3
|
||||
(Technical Setup), since at `full` the Technical Setup → Pre-Production gate
|
||||
requires them (at `standard` they are recommended; at `minimal` they drop).
|
||||
|
||||
```
|
||||
design/gdd/*.md (UI/UX requirements extracted)
|
||||
@@ -183,8 +217,10 @@ design/player-journey.md (emotional arc, if authored)
|
||||
├── Phase 4: accessibility audit (accessibility-specialist)
|
||||
└── Phase 5: final review
|
||||
|
||||
Note: /ux-design and /ux-review belong in Phase 4 (Pre-Production).
|
||||
/team-ui belongs in Phase 5 (Production) when a UI feature is being built.
|
||||
Note: /ux-design accessibility and /ux-design patterns belong in Phase 3
|
||||
(Technical Setup); /ux-design screen/hud and /ux-review belong in Phase 4
|
||||
(Pre-Production). /team-ui belongs in Phase 5 (Production) when a UI
|
||||
feature is being built.
|
||||
```
|
||||
|
||||
---
|
||||
@@ -251,9 +287,9 @@ How a story gets from backlog to closed (summary view):
|
||||
## Skill Chain: QA Pipeline in Detail
|
||||
|
||||
```
|
||||
[Phase 4 — one-time infrastructure setup]
|
||||
[Phase 3 — one-time infrastructure setup]
|
||||
/test-setup ────────────────────────────────────────────────────► test framework scaffolded + CI/CD wired
|
||||
/test-helpers ──────────────────────────────────────────────────► tests/helpers/[engine].gd (GDUnit4, NUnit, etc.)
|
||||
/test-helpers ──────────────────────────────────────────────────► tests/helpers/ (GDUnit4, NUnit, etc.)
|
||||
|
||||
[Phase 5 — per-sprint QA cycle]
|
||||
/qa-plan [sprint or feature]
|
||||
@@ -266,7 +302,7 @@ How a story gets from backlog to closed (summary view):
|
||||
│ UI → retained screenshot of each screen (BLOCKING by default)
|
||||
│ Config/Data → smoke check (ADVISORY by default)
|
||||
│ (gate levels are overridable per type via testing.strict in project.yaml)
|
||||
└── Output: production/qa/qa-plan-sprint-NN.md
|
||||
└── Output: production/qa/qa-plan-[sprint-slug]-[date].md
|
||||
│
|
||||
▼
|
||||
/smoke-check
|
||||
@@ -294,7 +330,7 @@ How a story gets from backlog to closed (summary view):
|
||||
/team-qa ───────────────────────────────────────────────────────► full QA cycle sign-off for release gate
|
||||
|
||||
[Ongoing — bug management]
|
||||
/bug-report ────────────────────────────────────────────────────► production/qa/bugs/bug-NNN.md
|
||||
/bug-report ────────────────────────────────────────────────────► production/qa/bugs/BUG-NNNN.md
|
||||
/bug-triage ────────────────────────────────────────────────────► open bugs re-prioritized + assigned
|
||||
|
||||
[Meta — harness validation]
|
||||
|
||||
Reference in New Issue
Block a user