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,310 @@
|
||||
# Workflow Modes — Shared Skill Pattern
|
||||
|
||||
This document defines `modes.workflow` and `workflow_overrides` — how much
|
||||
design documentation is REQUIRED before code can begin — for every skill that
|
||||
authors, reviews, gates, or plans against project artifacts. Skills reference
|
||||
this document instead of embedding the tier tables inline.
|
||||
|
||||
**Companion spec**: `.claude/docs/effects-map.md`
|
||||
sections `modes.workflow` and `workflow_overrides` are the source of
|
||||
truth for behavior. This document is the implementation pattern.
|
||||
|
||||
> **Do not read `effects-map.md` during a skill run.** It is ~2,150 lines
|
||||
> (~110 KB) — about five times the size of everything CLAUDE.md loads per
|
||||
> session combined — and it is a reference for *authoring and changing the
|
||||
> spec*, not a runtime input. **This document is self-sufficient** for resolving
|
||||
> the tier and applying it: the resolution chain, the three tiers, the required
|
||||
> sections, and the override rules are all here. If you hit a case this document
|
||||
> genuinely does not cover, read only the one `effects-map.md` section for the
|
||||
> knob in question — never the file.
|
||||
|
||||
**Related shared docs**: `.claude/docs/automation-modes.md` (how skills prompt),
|
||||
`.claude/docs/director-gates.md` (which reviewers spawn). `workflow` is
|
||||
orthogonal to both — it controls *what artifacts must exist*, not *how the
|
||||
skill prompts* or *who reviews*.
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Document
|
||||
|
||||
A skill that authors, reviews, or gates a design artifact resolves the
|
||||
effective workflow tier at startup, then applies the required-section /
|
||||
required-artifact set for that tier.
|
||||
|
||||
**Resolution (per skill):**
|
||||
|
||||
```
|
||||
Resolve the workflow tier (store the result; see scope note below):
|
||||
1. If the resolution is for a named system AND
|
||||
`workflow_overrides.system_overrides.<system>` is set → use that tier
|
||||
2. Else read `modes.workflow` from `project.yaml` → use that value
|
||||
3. Else → use the tier implied by `modes.rigor`
|
||||
(`minimal`→`minimal`, `standard`→`standard`, `full`→`full`;
|
||||
`rigor` itself defaults to `minimal`)
|
||||
```
|
||||
|
||||
`modes.workflow` has **no terminal default** — step 3 is the `rigor` expansion,
|
||||
not a hardcoded `standard`. The resolved value is the same for an unconfigured
|
||||
project, so nothing observable changed; but a skill that hardcodes `standard` as
|
||||
its fallback will ignore `rigor: minimal` and `rigor: full` entirely.
|
||||
|
||||
### What `<system>` is — one derivation, everywhere
|
||||
|
||||
**`<system>` is the GDD filename stem**: `design/gdd/hammer-heat-system.md` →
|
||||
`hammer-heat-system`. That is the key to write under
|
||||
`workflow_overrides.system_overrides`, and every skill must derive it the same
|
||||
way.
|
||||
|
||||
A `TR-[system]-NNN` ID's `[system]` segment is **an alias, not the key**. Accept
|
||||
it as a fallback match when the GDD stem yields nothing, but never derive the key
|
||||
from it in preference to the stem.
|
||||
|
||||
> **Why this is stated here rather than per skill.** Reading *"the `[system]`
|
||||
> segment of its `TR-[system]-NNN` ID (else its `design/gdd/` path)"* — TR-ID
|
||||
> **first** — is the wrong order. A system whose GDD is `hammer-heat-system.md` and
|
||||
> whose requirements are `TR-heat-001` then had **two different override keys
|
||||
> depending on whether a registry entry existed**, and the documented remedy for
|
||||
> a missing GDD section — "set
|
||||
> `workflow_overrides.system_overrides.hammer-heat-system: full`" — was looked up
|
||||
> under `heat`, found nothing, and continued at the project tier **silently**.
|
||||
> The escape hatch existed and could not be reached.
|
||||
|
||||
**A key that matches no system is an error, not a no-op.** If
|
||||
`workflow_overrides.system_overrides` contains a key that resolves to no GDD stem
|
||||
in `design/gdd/`, say so — naming the unmatched key and the stems available.
|
||||
Silently ignoring it is how the above went unnoticed.
|
||||
|
||||
> **Checked where GDDs are expected to already exist — not by the skill that
|
||||
> writes them.** `/gate-check` is the single implementing site (see
|
||||
> `.claude/skills/gate-check/SKILL.md` §"Per-system overrides"), and it runs at a
|
||||
> phase boundary, by which point every in-scope GDD should be on disk. An
|
||||
> unmatched key there is genuinely suspicious.
|
||||
>
|
||||
> `/design-system` **creates** `design/gdd/<system>.md`, so before its first run
|
||||
> the override key matches no stem *by definition* — that is the healthy case,
|
||||
> not an error. It must not report the key as orphaned, and must not refuse to
|
||||
> apply the tier it names. The same holds for any other authoring skill running
|
||||
> before the GDD exists. Applying this rule there would fire on exactly the
|
||||
> configuration it was written to protect.
|
||||
|
||||
---
|
||||
|
||||
Step 1 (the per-system override) applies to skills that act on a named system:
|
||||
- **Single-system, resolve once per run**: `design-system`, `design-review`,
|
||||
`dev-story`, `story-done`, `create-stories` (one story/epic per invocation).
|
||||
- **Multi-system, resolve once per item**: `story-readiness` (per story across
|
||||
`all`/`sprint` scope), `qa-plan` and `regression-suite` audit (per GDD/system).
|
||||
These do NOT freeze a single tier for the run — different systems in one run
|
||||
may resolve to different tiers.
|
||||
|
||||
Skills that operate project-wide (`gate-check`, `create-epics`) use the
|
||||
project-level `workflow` plus consider per-system overrides where the tier table
|
||||
says so.
|
||||
|
||||
> **"Critical ADR" (used in the tier tables):** an ADR governing a
|
||||
> **Foundation-layer** system (scene management, event architecture, save/load,
|
||||
> and the like — the systems whose decisions everything else depends on). At
|
||||
> `standard`, only critical ADRs are required/blocking; non-critical ADRs are
|
||||
> advisory. When in doubt about an ADR's layer, treat it as critical (fail safe
|
||||
> toward requiring it).
|
||||
|
||||
`modes.workflow` reads via **`resolve_config --keys workflow`** (or
|
||||
`resolve_setting modes.workflow`), which applies the whole chain including the
|
||||
`rigor` expansion. Do **not** use `get_effective_yaml_key modes.workflow`: it
|
||||
reads the two YAML files only, so on a project that sets `modes.rigor` and not
|
||||
`modes.workflow` it returns **empty** while the effective tier is whatever rigor
|
||||
implies. (`project.local.yaml` is not allowed to override workflow — it is locked
|
||||
to `project.yaml` per the whitelist — so the only sources are `project.yaml` and
|
||||
the expansion.) Per-system overrides read via
|
||||
`get_yaml_key project.yaml workflow_overrides.system_overrides.<system>`.
|
||||
|
||||
---
|
||||
|
||||
## The Three Tiers
|
||||
|
||||
| Tier | Token/time cost | Required before code | Best for |
|
||||
|------|----------------|---------------------|----------|
|
||||
| `full` | High | All 8 GDD sections per system, full architecture, all ADRs, art bible, UX specs per screen | Teams, commercial titles, learning the full pipeline |
|
||||
| `standard` | Balanced | 5 GDD sections per system, one architecture doc, critical ADRs, game concept, systems index | Projects that outgrew a brief - several interacting systems, or a design someone else implements |
|
||||
| `minimal` | Low | One-page `design/game-brief.md` + engine choice (its build-order field is the plan — no separate sprint plan) | **Default.** Jam projects, small scope, design already in your head |
|
||||
|
||||
**Default**: `minimal` (the rationale block above `_yaml_helper_defaults` in
|
||||
`.claude/hooks/yaml-helper.sh` carries the reasoning and the ordering
|
||||
constraint). **Set by**: `/start`, `/settings`. **Locked to
|
||||
`project.yaml`** (not locally overridable — divergence would change which
|
||||
artifacts must exist on disk).
|
||||
|
||||
> **Permissive, not restrictive.** `workflow` controls what is REQUIRED, not
|
||||
> what is ALLOWED. Any skill can run at any tier. The setting changes what
|
||||
> `gate-check` enforces and what completeness checks validate — never what the
|
||||
> user can invoke.
|
||||
|
||||
> **`minimal` floor.** Even at minimal, engine choice and a filled
|
||||
> **`design/game-brief.md`** are required before code starts — the brief's
|
||||
> build-order field is the plan, so there is no separate `sprint-plan` step.
|
||||
> Everything else can be skipped.
|
||||
|
||||
> **"Game brief" is a real artifact at `minimal`: `design/game-brief.md`.**
|
||||
> `/brainstorm` writes it from the one-page template
|
||||
> (`.claude/docs/templates/game-brief.md`) when the effective tier is `minimal`,
|
||||
> in place of the full-length `design/gdd/game-concept.md` it writes at
|
||||
> `standard`/`full`. The two are distinct files for distinct tiers: any check,
|
||||
> gate, or glob for the `minimal` design artifact must target
|
||||
> **`design/game-brief.md`**; `game-concept.md` remains the `standard`/`full`
|
||||
> concept doc.
|
||||
|
||||
---
|
||||
|
||||
## GDD Required Sections per Tier
|
||||
|
||||
The 8 GDD sections: Overview, Player Fantasy, Detailed Rules, Formulas,
|
||||
Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.
|
||||
|
||||
> **Section-name alias.** "Detailed Rules" is the canonical name in the design
|
||||
> standard, but the GDD template (`.claude/docs/templates/game-design-document.md`)
|
||||
> and `/design-system` author this section under the heading `## Detailed Design`
|
||||
> (with Core Rules / States / Interactions sub-headings). The two names denote the
|
||||
> **same required section** — any skill that detects or validates section presence
|
||||
> (`design-review`, `gate-check`, `adopt`, `project-stage-detect`) must accept
|
||||
> either heading. Do not treat "Detailed Rules" as missing when `## Detailed
|
||||
> Design` is present.
|
||||
|
||||
| Tier | Required GDD sections |
|
||||
|------|----------------------|
|
||||
| `full` | All 8 |
|
||||
| `standard` | **5 required**: Overview, Detailed Rules, Edge Cases, Dependencies, Acceptance Criteria. **Conditional**: Formulas — required when the system **defines numeric rules** (rates, curves, thresholds, costs, damage, drop weights — anything a balance pass would tune); optional only when it defines none. The `Category` column is a hint, not the test. **Skipped**: Player Fantasy, Tuning Knobs. |
|
||||
| `minimal` | None — `design/game-brief.md` replaces GDDs. A GDD may still be authored voluntarily. |
|
||||
|
||||
> **Edge Cases is required at `standard`** (it was promoted from optional —
|
||||
> skipping it produced "what happens if X is null?" debt during implementation).
|
||||
|
||||
> **Art bible is conditional at `standard`** — required only if visual asset
|
||||
> stories exist in the project. Code-focused projects skip it. At `full`, all
|
||||
> 9 art bible sections are required. (`workflow_overrides.art_bible_strict:
|
||||
> true` forces all 9 regardless of tier.)
|
||||
|
||||
---
|
||||
|
||||
## `workflow_overrides`
|
||||
|
||||
This key holds two mechanisms with **different directional rules**. Read the one
|
||||
you are using — conflating them is a known and easy mistake.
|
||||
|
||||
```yaml
|
||||
workflow_overrides:
|
||||
# --- the three boolean FLAGS: additive, stricter-only ---
|
||||
edge_cases: false # force Edge Cases required (no-op at standard/full; relevant at minimal)
|
||||
tuning_knobs: false # force Tuning Knobs required (relevant at standard, no-op at full)
|
||||
art_bible_strict: false # force all 9 art bible sections regardless of asset stories
|
||||
|
||||
# --- system_overrides: replaces a tier, BOTH directions ---
|
||||
system_overrides: {} # per-system tier overrides (see below)
|
||||
```
|
||||
|
||||
**The three boolean flags are additive on top of the chosen `workflow` level —
|
||||
they make requirements STRICTER, never looser.** Each one only ever forces a
|
||||
requirement *on*; setting a flag cannot opt out of a requirement the tier
|
||||
imposes. There is no value of `edge_cases`, `tuning_knobs` or `art_bible_strict`
|
||||
that removes anything.
|
||||
|
||||
**`system_overrides` is not a flag and is not additive.** It *replaces* the
|
||||
effective tier for one named system, in **either** direction — see the next
|
||||
section. A loosening override genuinely loosens: on a `full` project,
|
||||
`system_overrides.inventory: minimal` drops that system's required sections to
|
||||
zero. That is the intended design (it is what makes "one trivial system inside a
|
||||
serious project" expressible), but it means an override is **not** a safe
|
||||
no-op — do not leave one in place assuming the stricter-only rule protects you.
|
||||
|
||||
### Per-system overrides
|
||||
|
||||
```yaml
|
||||
workflow_overrides:
|
||||
system_overrides:
|
||||
combat: full # combat GDD requires all 8 sections regardless of project workflow
|
||||
inventory: minimal # inventory needs no GDD — the game brief covers it (minimal = no required sections)
|
||||
```
|
||||
|
||||
`system_overrides` is a map of `system_name: workflow_level`. The named system
|
||||
uses the override tier; all other systems use the project-level `workflow`.
|
||||
A skill acting on a named system resolves its effective tier via step 1 of the
|
||||
resolution chain above.
|
||||
|
||||
---
|
||||
|
||||
## Effective-Tier Resolution Worked Example
|
||||
|
||||
Project has `modes.workflow: standard`, `workflow_overrides.system_overrides.combat: full`.
|
||||
|
||||
- `/design-system combat` → effective tier **full** → requires all 8 sections
|
||||
- `/design-system inventory` → no override → effective tier **standard** → 5 sections + conditional Formulas
|
||||
- `/gate-check` (Systems Design → Technical Setup) → requires the combat GDD at 8 sections AND every other MVP GDD at 5 sections before passing
|
||||
|
||||
---
|
||||
|
||||
## Per-Skill Behavior (the working summary — sufficient at runtime)
|
||||
|
||||
**Authoring** — branch on the effective tier for required sections (and, for
|
||||
`brainstorm`, for which design artifact is produced — `design/game-brief.md` at
|
||||
`minimal` vs `design/gdd/game-concept.md` at `standard`/`full`):
|
||||
`brainstorm`, `design-system`, `art-bible`, `create-architecture`, `ux-design`,
|
||||
`map-systems`, `architecture-decision`.
|
||||
|
||||
**Review/validation** — validate against the effective tier; missing
|
||||
*required* sections block, missing *optional* sections warn:
|
||||
`design-review`, `review-all-gdds`, `architecture-review`, `consistency-check`,
|
||||
`content-audit`.
|
||||
|
||||
**Gate enforcement** — `gate-check` uses a different artifact checklist per
|
||||
stage per tier (the highest-visibility impact). Each gate's own checklist and
|
||||
tier reductions live in `.claude/skills/gate-check/references/gate-<phase>.md`,
|
||||
and `/gate-check` loads only the one gate it is running — that is the right
|
||||
place to look, not `effects-map.md`.
|
||||
|
||||
**Planning/implementation** — adjust artifact prerequisites:
|
||||
`create-epics`, `create-stories`, `dev-story`, `story-readiness`, `story-done`,
|
||||
`qa-plan`, `regression-suite`.
|
||||
|
||||
**Support** — adjust "what's missing" expectations so optional docs aren't
|
||||
flagged as gaps: `project-stage-detect`, `adopt`, `reverse-document`,
|
||||
`propagate-design-change`, `help`.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Change Mid-Project
|
||||
|
||||
When `workflow` changes via `/settings`, emit an informational note:
|
||||
|
||||
> "Workflow changed from [old] to [new]. Run `/content-audit` to see what's now
|
||||
> required or extra. No automatic migration — existing files stay in place."
|
||||
|
||||
No documents are auto-deleted, auto-generated, or blocked. The setting only
|
||||
affects *new* enforcement going forward.
|
||||
|
||||
---
|
||||
|
||||
## Companion Settings
|
||||
|
||||
These are separate settings that compose with `workflow`. The summaries below
|
||||
are what a skill needs at runtime; `effects-map.md` carries the exhaustive
|
||||
per-skill tables for spec authors, and is not worth loading to apply a knob.
|
||||
|
||||
> **All four below are fronted by `modes.rigor`** (`docs.density`,
|
||||
> `modes.story_granularity`, `qa.level`, `team.size` — along with `workflow` itself,
|
||||
> and `modes.review_mode`, for six fronted knobs total). One question at `/start`
|
||||
> sets all of them; setting any explicitly overrides just that one and leaves its
|
||||
> siblings on the rigor level. `team.size` and `modes.review_mode` are the two that
|
||||
> also stay overridable from `project.local.yaml` (they are personal-experience
|
||||
> knobs, not on-disk artifacts).
|
||||
|
||||
- **`docs.density`** (`terse` | `balanced` | `thorough`) — `workflow` controls
|
||||
*which sections exist*; `density` controls *how deep each section goes*.
|
||||
`rigor` sets the two together; override `docs.density` alone to get
|
||||
`full` + `terse` = "all 8 sections, each compact."
|
||||
- **`modes.story_granularity`** (`coarse` | `balanced` | `fine`) — how big
|
||||
each story is and how many per epic/sprint.
|
||||
- **`qa.level`** (`minimal` | `standard` | `full`) — what test evidence is
|
||||
required to mark stories Done. Composes with `testing.strict`:
|
||||
`qa.level` = is evidence required; `testing.strict` = do failures block.
|
||||
- **`team.size`** (`individual` | `small` | `studio`) — which agents are active by
|
||||
default. Different axis from workflow: workflow controls *what docs are
|
||||
required*, team.size controls *which agents exist to make them*.
|
||||
Reference in New Issue
Block a user