mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 01:37:05 +00:00
Release 1.1.0 — one config file, and a process weight you choose
`project.yaml` at the repo root is now the single source of truth for a project's configuration, replacing `production/stage.txt`, `production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all three still read as a fallback; nothing is force-deleted). **`modes.rigor` — one question instead of six.** `minimal`, `standard` or `full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to `minimal`, which is a change from 1.0's behaviour: the heavier tier was measured costing several times more to reach working code without producing a better result, and returning nothing when a fresh developer inherited the project. Pin `modes.rigor: standard` to keep 1.0's process level. Also in this release: - `/settings` to view or change any setting, and `project.local.yaml` for per-developer preferences that should not be committed. - `system_overrides` to hold one system to a higher standard than the rest of the project, and `testing.strict` to set per test type whether missing evidence blocks a story or warns. - A story that changes anything the player sees is not closed until the game has been launched, observed, and a screenshot retained in `production/qa/evidence/`. A parse check is not a run. This holds at every rigor level, including `minimal`, where automated tests are waived but the look is not. - The code root is engine-specific and enforced as such: Godot `src/`, Unity `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a project laid out any other way. - Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh` converts a 1.0 layout, non-destructively by default, with a report to review before `--finalize` deletes anything. - Ask-before-write holds regardless of personal automation settings. Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes: CHANGELOG.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5
Claude Opus 5
parent
984023ddac
commit
d05699707f
@@ -0,0 +1,76 @@
|
||||
# /create-epics — Handoff Contract
|
||||
|
||||
## Role in Pipeline
|
||||
Translates approved GDDs and architecture documents into one EPIC.md file per
|
||||
architectural module, defining scope, ADR governance, engine risk, and requirement
|
||||
traceability — sits between architecture review and story decomposition.
|
||||
|
||||
## Inputs Required
|
||||
|
||||
### Files That Must Exist
|
||||
| File | Required Fields / Sections | Read-Only? |
|
||||
|------|---------------------------|-----------|
|
||||
| `design/gdd/systems-index.md` | System list, layer assignments, priority order | Yes |
|
||||
| `design/gdd/[system].md` | `## Summary`, `## Acceptance Criteria`, `## Overview` (all 8 required sections) | Yes |
|
||||
| `docs/architecture/architecture.md` | Module ownership, API boundaries | Yes |
|
||||
| `docs/architecture/adr-NNNN-[slug].md` (all governing ADRs) | `Status:`, `GDD Requirements Addressed`, `Decision`, `Engine Compatibility` | Yes |
|
||||
| `docs/architecture/control-manifest.md` | `Manifest Version:` date in header | Yes |
|
||||
| `docs/architecture/tr-registry.yaml` | TR-IDs with `id`, `system`, requirement text | Yes |
|
||||
| `docs/engine-reference/[engine]/VERSION.md` | Engine name, version, risk levels | Yes |
|
||||
|
||||
### Preconditions
|
||||
- `/create-control-manifest` has been run and `docs/architecture/control-manifest.md` exists
|
||||
- `/architecture-review` has passed (at minimum Foundation and Core ADRs are Accepted)
|
||||
- All in-scope GDDs have status `Approved` or `Designed` in `systems-index.md`
|
||||
- The target layer's GDDs are stable — do not run for Feature layer until Core is nearly complete
|
||||
|
||||
## Outputs Produced
|
||||
|
||||
### Files Written
|
||||
| File | Guaranteed Fields / Sections | Notes |
|
||||
|------|------------------------------|-------|
|
||||
| `production/epics/[epic-slug]/EPIC.md` | `Layer`, `GDD` path, `Architecture Module`, `Status: Ready`, `## Governing ADRs` table, `## GDD Requirements` table with TR-IDs and ADR coverage, `## Definition of Done`, `## Overview` | Created per approved epic |
|
||||
| `production/epics/index.md` | `Epic`, `Layer`, `System`, `GDD`, `Stories`, `Status` columns | Created or appended |
|
||||
|
||||
### Output Guarantees
|
||||
- Every EPIC.md contains a `## Governing ADRs` table with at least one row (or a documented note if none apply)
|
||||
- Every EPIC.md contains a `## GDD Requirements` table where each row has a `TR-ID` and an `ADR Coverage` cell (either `ADR-NNNN ✅` or `❌ No ADR`)
|
||||
- The `GDD:` field in the EPIC.md header is a valid relative path to the source GDD
|
||||
- The `Layer:` field is one of: Foundation, Core, Feature, Presentation
|
||||
- The `Status:` field is set to `Ready`
|
||||
- The `Stories:` field reads `Not yet created — run /create-stories [epic-slug]`
|
||||
- Untraced requirements (TR-IDs with no ADR) are flagged in the GDD Requirements table with `❌ No ADR`
|
||||
- `production/epics/index.md` has an entry for every epic written in this run
|
||||
|
||||
## Immutability Rules
|
||||
- READS but does NOT modify: `design/gdd/systems-index.md`, all GDD files, `docs/architecture/architecture.md`, all ADR files in `docs/architecture/adr-NNNN-[slug].md` pattern, `docs/architecture/control-manifest.md`, `docs/architecture/tr-registry.yaml`, `docs/engine-reference/[engine]/VERSION.md`
|
||||
- MODIFIES: `production/epics/[epic-slug]/EPIC.md` (creates), `production/epics/index.md` (creates or updates)
|
||||
|
||||
## Hard Constraints (Never Violate)
|
||||
- Never create story files — this skill stops at the epic level
|
||||
- Never invent content not sourced from GDDs, ADRs, or architecture docs
|
||||
- Never skip the per-epic approval prompt before writing
|
||||
- Never write an EPIC.md without first presenting the epic definition to the user
|
||||
- Never mark a TR-ID as covered by an ADR unless that ADR's `Status:` is `Accepted`
|
||||
- Never create epics for a layer whose dependency layer is not yet substantially complete
|
||||
|
||||
## Downstream Skill Expects
|
||||
**Next skill:** /create-stories
|
||||
|
||||
It will read:
|
||||
- `production/epics/[epic-slug]/EPIC.md` — specifically: `Layer:`, `GDD:` path, `Architecture Module:`, the full `## Governing ADRs` table (ADR IDs and summaries), and the full `## GDD Requirements` table (TR-IDs and ADR coverage status)
|
||||
- `production/epics/index.md` — to enumerate available epics when no argument is given
|
||||
|
||||
It assumes:
|
||||
- The `GDD:` path in EPIC.md resolves to a readable file
|
||||
- Every ADR listed in `## Governing ADRs` exists as a file and has an `Accepted` status
|
||||
- TR-IDs in `## GDD Requirements` match entries in `docs/architecture/tr-registry.yaml`
|
||||
- The epic slug used in the directory name matches the slug referenced in `index.md`
|
||||
- `Status: Ready` means stories have NOT yet been created (it will replace this line)
|
||||
|
||||
## Known Fragile Points
|
||||
- If the EPIC.md template structure changes (section names, header field names, table column order), `/create-stories` will silently fail to parse governance data and may produce incomplete or incorrect stories
|
||||
- If `tr-registry.yaml` is regenerated with renumbered IDs after EPIC.md files are written, the TR-IDs in existing EPIC.md files become stale and mislead `/create-stories`
|
||||
- If an ADR is retroactively changed from `Accepted` to `Proposed` after the epic is written, the EPIC.md will still show it as governing — `/create-stories` will embed it without a BLOCKED flag
|
||||
- If `systems-index.md` layer assignments change after epics are created, the `Layer:` field in existing EPIC.md files will be incorrect and `/create-stories` will use the wrong layer context
|
||||
- `production/epics/index.md` is append-updated — if an epic is regenerated, a duplicate row may appear
|
||||
@@ -1,13 +1,18 @@
|
||||
---
|
||||
name: create-epics
|
||||
description: "Translate approved GDDs + architecture into epics — one epic per architectural module. Defines scope, governing ADRs, engine risk, and untraced requirements. Does NOT break into stories — run /create-stories [epic-slug] after each epic is created."
|
||||
description: "Turn GDDs plus architecture into epics — one per architectural module, with untraced requirements. Then /create-stories [epic-slug]."
|
||||
argument-hint: "[system-name | layer: foundation|core|feature|presentation | all] [--review full|lean|solo]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion
|
||||
allowed-tools: Read, Glob, Grep, Write, Agent, AskUserQuestion
|
||||
model: sonnet
|
||||
agent: technical-director
|
||||
---
|
||||
|
||||
!`source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh" 2>/dev/null && resolve_config --keys review_mode,automation,workflow,docs.density,story_granularity,system_overrides`
|
||||
|
||||
Resolved above — use as-is; `--review` overrides `review_mode`. No block →
|
||||
defaults in `.claude/docs/config-resolution.md`.
|
||||
|
||||
|
||||
# Create Epics
|
||||
|
||||
An epic is a named, bounded body of work that maps to one architectural module.
|
||||
@@ -22,18 +27,52 @@ will have changed.
|
||||
|
||||
**Next step after each epic:** `/create-stories [epic-slug]`
|
||||
|
||||
**When to run:** After `/create-control-manifest` and `/architecture-review` pass.
|
||||
**When to run:** After `/create-control-manifest` and `/architecture-review` pass
|
||||
(at `full`). At `standard`, critical ADRs + a control manifest suffice. At
|
||||
`minimal`, this skill is **optional and not part of the path** — `/create-stories`
|
||||
synthesizes the epic from `design/game-brief.md` itself (Option A). If run anyway,
|
||||
it decomposes directly from the brief with no GDD/ADR/manifest prerequisite.
|
||||
|
||||
> **At `minimal`, this skill is optional — `/create-stories` synthesizes the epic**
|
||||
> (Option A). At that tier `/create-stories` reads `design/game-brief.md`
|
||||
> directly, writes a lightweight implicit `production/epics/<slug>/EPIC.md`, and
|
||||
> generates stories from the MVP list — so the path is `/brainstorm` →
|
||||
> `/create-stories` → `/dev-story`, with no separate `/create-epics` or
|
||||
> `/sprint-plan` step. **At `standard`/`full` an epic IS required**:
|
||||
> `/create-stories` reads `production/epics/[slug]/EPIC.md`, and skipping this
|
||||
> skill there leaves `/dev-story` with no story to implement — a dead end, not a
|
||||
> shortcut.
|
||||
|
||||
---
|
||||
|
||||
## 1. Parse Arguments
|
||||
|
||||
Resolve the review mode (once, store for all gate spawns this run):
|
||||
1. If `--review [full|lean|solo]` was passed → use that
|
||||
2. Else read `production/review-mode.txt` → use that value
|
||||
3. Else → default to `lean`
|
||||
|
||||
See `.claude/docs/director-gates.md` for the full check pattern.
|
||||
See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.
|
||||
|
||||
|
||||
Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
|
||||
(collaborative asks always · guided major-only · autonomous logs and proceeds;
|
||||
`automation_always_ask` categories always prompt).
|
||||
|
||||
**`workflow`** (per `.claude/docs/workflow-modes.md`):
|
||||
|
||||
create-epics runs project-wide: it uses the project-level tier for its
|
||||
prerequisite expectations and consults
|
||||
`workflow_overrides.system_overrides.<system>` per-system when reading each
|
||||
in-scope GDD. See "Workflow tier adjustment" in Step 2.
|
||||
|
||||
**`story_granularity`** — it sizes the
|
||||
epic's story breakdown: expect **3–5** child stories per epic at `coarse`, **5–10**
|
||||
at `balanced` (default), **10–20** at `fine`.
|
||||
|
||||
**`docs.density`** — it controls the *depth* of each epic's written scope and
|
||||
rationale, not the story count (that is `story_granularity`). `modes.rigor` sets
|
||||
it alongside `workflow`; set `docs.density` explicitly to vary epic prose alone:
|
||||
`terse` = scope as bullets, one-line rationale; `balanced` = a scope paragraph
|
||||
with light rationale (default); `thorough` = full scope prose with governing-ADR
|
||||
rationale and risk discussion. The EPIC.md tables (GDD requirements, governing
|
||||
ADRs) are structural and stay whole at every density.
|
||||
|
||||
**Modes:**
|
||||
- `/create-epics all` — process all systems in layer order
|
||||
@@ -48,16 +87,34 @@ See `.claude/docs/director-gates.md` for the full check pattern.
|
||||
|
||||
## 2. Load Inputs
|
||||
|
||||
### Step 2a — Summary scan (fast)
|
||||
### Step 2a — Summary scan (fast, fail-open)
|
||||
|
||||
Grep all GDDs for their `## Summary` sections before reading anything fully:
|
||||
**Establish the denominator first.** Glob `design/gdd/*.md`, excluding the
|
||||
non-system docs (`game-concept.md`, `systems-index.md`, `game-pillars.md`,
|
||||
`gameplay-tags.md`, `entity-registry.md`, `fixture-swap-ledger.md`, and any
|
||||
`gdd-cross-review-*.md` — the same set `gdd-structure-check.sh` skips). Call the
|
||||
count **N**. If N is 0, there are no system GDDs — report "No system GDDs found
|
||||
in `design/gdd/` — run `/design-system` first" and stop.
|
||||
|
||||
Scan for Summary sections:
|
||||
|
||||
```
|
||||
Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
|
||||
Grep pattern="^## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
|
||||
```
|
||||
|
||||
For `layer:` or `[system-name]` modes: filter to only in-scope GDDs based on
|
||||
the Summary quick-reference. Skip full-reading anything out of scope.
|
||||
Interpret the **M** matches against N. These are three different outcomes, and
|
||||
a zero-match scan is **never** the same as "nothing in scope":
|
||||
|
||||
| Result | Meaning | Action |
|
||||
|---|---|---|
|
||||
| **M = N** | Every GDD has a Summary. | For `layer:`/`[system-name]` modes, use the Summary Quick-reference (Layer/Priority) to pick the in-scope set; skip full-reading the rest. |
|
||||
| **0 < M < N** | Partial adoption — older GDDs predate `## Summary`. | Scope the M by their Summaries; determine the scope of the **N − M** unmatched from `systems-index.md` (layer/priority) and full-read those. |
|
||||
| **0 matches, N > 0** | Expected for GDDs authored before `/design-system` emitted `## Summary`. | Determine scope for **all N** from `systems-index.md` and full-read the in-scope set. This is the pre-optimization behaviour — correct, only more expensive. Note once: "No `## Summary` sections found across [N] GDDs — scoping from `systems-index.md` instead of Summary." |
|
||||
|
||||
**Never treat an absent `## Summary` as an absent system.** The scan narrows the
|
||||
*read* set when it succeeds; it never shrinks the *in-scope* set. In `all` mode
|
||||
every system is in scope regardless of Summary, so the scan is a convenience
|
||||
only — never a filter.
|
||||
|
||||
### Step 2b — Full document load (in-scope systems only)
|
||||
|
||||
@@ -68,13 +125,38 @@ Read for in-scope systems:
|
||||
- `design/gdd/systems-index.md` — authoritative system list, layers, priority
|
||||
- In-scope GDDs only (Approved or Designed status, filtered by Step 2a results)
|
||||
- `docs/architecture/architecture.md` — module ownership and API boundaries
|
||||
- Accepted ADRs **whose domains cover in-scope systems only** — read the "GDD Requirements Addressed", "Decision", and "Engine Compatibility" sections; skip ADRs for unrelated domains
|
||||
- Accepted ADRs **whose domains cover in-scope systems only** — skip ADRs for
|
||||
unrelated domains entirely. For each in-scope ADR, load only the "GDD
|
||||
Requirements Addressed", "Decision", and "Engine Compatibility" sections —
|
||||
never an unbounded full read:
|
||||
```
|
||||
Grep pattern="^## (GDD Requirements Addressed|Decision|Engine Compatibility)" path="docs/architecture/[adr-file].md" output_mode="content" -n
|
||||
```
|
||||
then `Read(offset, limit)` bounded to each match through the next `## `
|
||||
heading (or to end of file for the last match). This matters most on a
|
||||
large ADR — measured at 47k tokens this way vs. 103k for an unbounded
|
||||
read of the same size file.
|
||||
- `docs/architecture/control-manifest.md` — manifest version date from header
|
||||
- `docs/architecture/tr-registry.yaml` — for tracing requirements to ADR coverage
|
||||
- `docs/engine-reference/[engine]/VERSION.md` — engine name, version, risk levels
|
||||
|
||||
Report: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."
|
||||
|
||||
> **Workflow tier adjustment** (resolved in Step 1; per-system via
|
||||
> `system_overrides`). The inputs above are the `full` baseline:
|
||||
> - **`full`** — every in-scope GDD must be Approved with all 8 sections; TR
|
||||
> registry + control manifest are required inputs; untraced requirements
|
||||
> (Step 4) are flagged before proceeding.
|
||||
> - **`standard`** — GDDs need the 5 required sections (+ conditional Formulas)
|
||||
> approved; only **critical (Foundation-layer) ADRs** are expected; the control
|
||||
> manifest is read if present, not required. A system pinned higher via
|
||||
> `system_overrides` must still meet its higher bar.
|
||||
> - **`minimal`** — decompose against `design/game-brief.md` +
|
||||
> acceptance criteria. Do not require GDDs, ADRs, the TR registry, or the
|
||||
> manifest; skip the untraced-requirement gate. If run, the epic is still
|
||||
> produced — but note `/create-stories` also synthesizes one from the brief when
|
||||
> this skill is skipped (the default `minimal` path).
|
||||
|
||||
---
|
||||
|
||||
## 3. Processing Order
|
||||
@@ -87,15 +169,27 @@ Process in dependency-safe layer order:
|
||||
|
||||
Within each layer, use the order from `systems-index.md`.
|
||||
|
||||
> **At `minimal` there is no `systems-index.md`** — `/map-systems` is not required
|
||||
> at that tier, so nothing has produced one. Derive the layer split and ordering
|
||||
> from `design/game-brief.md` instead: its **Build order** field names what must
|
||||
> exist first. Do not stop, and do not send the user to `/map-systems` to satisfy
|
||||
> an ordering hint — the tier deliberately skips it.
|
||||
|
||||
---
|
||||
|
||||
## 4. Define Each Epic
|
||||
|
||||
For each system, map it to an architectural module from `architecture.md`.
|
||||
|
||||
Check ADR coverage against the TR registry:
|
||||
Check ADR coverage against the TR registry **per the resolved tier** (Step 1):
|
||||
- **`full`** — trace every TR-ID; warn on each untraced requirement (below).
|
||||
- **`standard`** — only **critical (Foundation-layer) ADRs** are expected; trace
|
||||
those. Treat untraced non-critical requirements as informational (list them, do
|
||||
not block or emit the Blocked-story warning).
|
||||
- **`minimal`** — skip this check entirely (no TR registry / ADR expected).
|
||||
|
||||
- **Traced requirements**: TR-IDs that have an Accepted ADR covering them
|
||||
- **Untraced requirements**: TR-IDs with no ADR — warn before proceeding
|
||||
- **Untraced requirements**: TR-IDs with no ADR — warn before proceeding (full only)
|
||||
|
||||
Present to user before writing anything:
|
||||
|
||||
@@ -132,7 +226,7 @@ Use `AskUserQuestion`:
|
||||
- `lean` → skip (not a PHASE-GATE). Note: "PR-EPIC skipped — Lean mode." Proceed to Step 5 (write epic files).
|
||||
- `full` → spawn as normal.
|
||||
|
||||
After all epics for the current layer are defined (Step 4 completed for all in-scope systems), and before writing any files, spawn `producer` via Task using gate **PR-EPIC** (`.claude/docs/director-gates.md`).
|
||||
After all epics for the current layer are defined (Step 4 completed for all in-scope systems), and before writing any files, spawn `producer` via `Agent` using gate **PR-EPIC** (`.claude/docs/director-gates/pr-epic.md`).
|
||||
|
||||
Pass: the full epic structure summary (all epics, their scope summaries, governing ADR counts), the layer being processed, milestone timeline and team capacity.
|
||||
|
||||
@@ -233,6 +327,10 @@ After writing all epics for the requested scope:
|
||||
|
||||
## Collaborative Protocol
|
||||
|
||||
**Applies in `collaborative` mode (the default).** For `guided` and
|
||||
`autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below
|
||||
describe what collaborative mode requires, not universal behavior.
|
||||
|
||||
1. **One epic at a time** — present each epic definition before asking to create it
|
||||
2. **Warn on gaps** — flag untraced requirements before proceeding
|
||||
3. **Ask before writing** — per-epic approval before writing any file
|
||||
|
||||
Reference in New Issue
Block a user