# 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.` 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 `` is — one derivation, everywhere **`` 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/.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.`. --- ## 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-.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*.