From 8ba9e736a52a042b0dec1c95da2587611edf2d5e Mon Sep 17 00:00:00 2001 From: Donchitos <150119193+Donchitos@users.noreply.github.com> Date: Sun, 29 Mar 2026 19:38:20 +1100 Subject: [PATCH] Add gate intensity modes: full, lean, and solo review control Adds a --review flag to all 13 gate-using skills and a global production/review-mode.txt config (set during /start). Full runs all director gates, lean skips per-skill gates but keeps phase gates, solo skips all directors. Documents modes in director-gates.md, WORKFLOW-GUIDE.md, and README.md. Co-Authored-By: Claude Sonnet 4.6 --- .claude/docs/director-gates.md | 41 +++++++++++++++++++ .claude/skills/architecture-decision/SKILL.md | 5 ++- .claude/skills/brainstorm/SKILL.md | 5 ++- .claude/skills/create-architecture/SKILL.md | 5 ++- .claude/skills/create-epics/SKILL.md | 5 ++- .claude/skills/create-stories/SKILL.md | 5 ++- .claude/skills/design-system/SKILL.md | 5 ++- .claude/skills/gate-check/SKILL.md | 7 +++- .claude/skills/map-systems/SKILL.md | 5 ++- .claude/skills/milestone-review/SKILL.md | 9 +++- .claude/skills/playtest-report/SKILL.md | 5 ++- .claude/skills/prototype/SKILL.md | 5 ++- .claude/skills/quick-design/SKILL.md | 2 + .claude/skills/sprint-plan/SKILL.md | 9 +++- .claude/skills/start/SKILL.md | 31 ++++++++++++-- .claude/skills/story-done/SKILL.md | 5 ++- README.md | 1 + docs/WORKFLOW-GUIDE.md | 27 ++++++++++++ 18 files changed, 160 insertions(+), 17 deletions(-) diff --git a/.claude/docs/director-gates.md b/.claude/docs/director-gates.md index d42058a..48347fb 100644 --- a/.claude/docs/director-gates.md +++ b/.claude/docs/director-gates.md @@ -23,6 +23,47 @@ the verdict using the **Verdict handling** rules below. --- +## Review Modes + +Review intensity controls whether director gates run. It can be set globally +(persists across sessions) or overridden per skill run. + +**Global config**: `production/review-mode.txt` — one word: `full`, `lean`, or `solo`. +Set once during `/start`. Edit the file directly to change it at any time. + +**Per-run override**: any gate-using skill accepts `--review [full|lean|solo]` as an +argument. This overrides the global config for that run only. + +Examples: +``` +/brainstorm space horror → uses global mode +/brainstorm space horror --review full → forces full mode this run +/architecture-decision --review solo → skips all gates this run +``` + +| Mode | What runs | Best for | +|------|-----------|----------| +| `full` | All gates active — current behaviour | New projects, teams, learning the workflow | +| `lean` | PHASE-GATEs only (`/gate-check`) — all per-skill gates skipped | Experienced devs who trust their own design work | +| `solo` | No director gates anywhere | Game jams, prototypes, seasoned solo devs at speed | + +**Check pattern — apply before every gate spawn:** + +``` +Before spawning gate [GATE-ID]: +1. If skill was called with --review [mode], use that +2. Else read production/review-mode.txt +3. Else default to full + +Apply the resolved mode: +- solo → skip all gates. Note: "[GATE-ID] skipped — Solo mode" +- lean → skip unless this is a PHASE-GATE (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE) + Note: "[GATE-ID] skipped — Lean mode" +- full → spawn as normal +``` + +--- + ## Invocation Pattern (copy into any skill) ``` diff --git a/.claude/skills/architecture-decision/SKILL.md b/.claude/skills/architecture-decision/SKILL.md index 43a85d8..adb37fe 100644 --- a/.claude/skills/architecture-decision/SKILL.md +++ b/.claude/skills/architecture-decision/SKILL.md @@ -1,7 +1,7 @@ --- name: architecture-decision description: "Creates an Architecture Decision Record (ADR) documenting a significant technical decision, its context, alternatives considered, and consequences. Every major technical choice should have an ADR." -argument-hint: "[title]" +argument-hint: "[title] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Task --- @@ -10,6 +10,9 @@ When this skill is invoked: ## 0. Parse Arguments — Detect Retrofit Mode +Extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + **If the argument starts with `retrofit` followed by a file path** (e.g., `/architecture-decision retrofit docs/architecture/adr-0001-event-system.md`): diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md index 209c6ed..fdae11f 100644 --- a/.claude/skills/brainstorm/SKILL.md +++ b/.claude/skills/brainstorm/SKILL.md @@ -1,7 +1,7 @@ --- name: brainstorm description: "Guided game concept ideation — from zero idea to a structured game concept document. Uses professional studio ideation techniques, player psychology frameworks, and structured creative exploration." -argument-hint: "[genre or theme hint, or 'open' for fully open brainstorm]" +argument-hint: "[genre or theme hint, or 'open'] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, WebSearch, AskUserQuestion --- @@ -10,7 +10,8 @@ When this skill is invoked: 1. **Parse the argument** for an optional genre/theme hint (e.g., `roguelike`, `space survival`, `cozy farming`). If `open` or no argument, start from - scratch. + scratch. Also extract `--review [full|lean|solo]` if present and store as + the review mode override for this run (see `.claude/docs/director-gates.md`). 2. **Check for existing concept work**: - Read `design/gdd/game-concept.md` if it exists (resume, don't restart) diff --git a/.claude/skills/create-architecture/SKILL.md b/.claude/skills/create-architecture/SKILL.md index 70c743a..85840bc 100644 --- a/.claude/skills/create-architecture/SKILL.md +++ b/.claude/skills/create-architecture/SKILL.md @@ -1,7 +1,7 @@ --- name: create-architecture description: "Guided, section-by-section authoring of the master architecture document for the game. Reads all GDDs, the systems index, existing ADRs, and the engine reference library to produce a complete architecture blueprint before any code is written. Engine-version-aware: flags knowledge gaps and validates decisions against the pinned engine version." -argument-hint: "[focus-area: full | layers | data-flow | api-boundaries | adr-audit]" +argument-hint: "[focus-area: full | layers | data-flow | api-boundaries | adr-audit] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Bash context: fork @@ -17,6 +17,9 @@ It sits between design and implementation, and must exist before sprint planning **Distinct from `/architecture-decision`**: ADRs record individual point decisions. This skill creates the whole-system blueprint that gives ADRs their context. +Extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + **Argument modes:** - **No argument / `full`**: Full guided walkthrough — all sections, start to finish - **`layers`**: Focus on the system layer diagram only diff --git a/.claude/skills/create-epics/SKILL.md b/.claude/skills/create-epics/SKILL.md index 4954d82..e9becf5 100644 --- a/.claude/skills/create-epics/SKILL.md +++ b/.claude/skills/create-epics/SKILL.md @@ -1,7 +1,7 @@ --- 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." -argument-hint: "[system-name | layer: foundation|core|feature|presentation | all]" +argument-hint: "[system-name | layer: foundation|core|feature|presentation | all] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write context: fork @@ -28,6 +28,9 @@ will have changed. ## 1. Parse Arguments +Extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + **Modes:** - `/create-epics all` — process all systems in layer order - `/create-epics layer: foundation` — Foundation layer only diff --git a/.claude/skills/create-stories/SKILL.md b/.claude/skills/create-stories/SKILL.md index a5cfd7a..e45875c 100644 --- a/.claude/skills/create-stories/SKILL.md +++ b/.claude/skills/create-stories/SKILL.md @@ -1,7 +1,7 @@ --- name: create-stories description: "Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic." -argument-hint: "[epic-slug | epic-path]" +argument-hint: "[epic-slug | epic-path] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write context: fork @@ -27,6 +27,9 @@ then Core, and so on — matching the dependency order. ## 1. Parse Argument +Extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + - `/create-stories [epic-slug]` — e.g. `/create-stories combat` - `/create-stories production/epics/combat/EPIC.md` — full path also accepted - No argument — ask: "Which epic would you like to break into stories?" diff --git a/.claude/skills/design-system/SKILL.md b/.claude/skills/design-system/SKILL.md index 83bb915..e823633 100644 --- a/.claude/skills/design-system/SKILL.md +++ b/.claude/skills/design-system/SKILL.md @@ -1,7 +1,7 @@ --- name: design-system description: "Guided, section-by-section GDD authoring for a single game system. Gathers context from existing docs, walks through each required section collaboratively, cross-references dependencies, and writes incrementally to file." -argument-hint: " (e.g., 'movement', 'progression', 'dialogue')" +argument-hint: " [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite --- @@ -10,6 +10,9 @@ When this skill is invoked: ## 1. Parse Arguments & Validate +Extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + A system name or retrofit path is **required**. If missing, fail with: > "Usage: `/design-system ` — e.g., `/design-system movement` > Or to fill gaps in an existing GDD: `/design-system retrofit design/gdd/[system-name].md` diff --git a/.claude/skills/gate-check/SKILL.md b/.claude/skills/gate-check/SKILL.md index 27bc776..767bc3b 100644 --- a/.claude/skills/gate-check/SKILL.md +++ b/.claude/skills/gate-check/SKILL.md @@ -1,7 +1,7 @@ --- name: gate-check description: "Validate readiness to advance between development phases. Produces a PASS/CONCERNS/FAIL verdict with specific blockers and required artifacts. Use when user says 'are we ready to move to X', 'can we advance to production', 'check if we can start the next phase', 'pass the gate'." -argument-hint: "[target-phase: systems-design | technical-setup | pre-production | production | polish | release]" +argument-hint: "[target-phase: systems-design | technical-setup | pre-production | production | polish | release] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Write context: fork @@ -37,6 +37,11 @@ The project progresses through these stages: **Target phase:** `$ARGUMENTS[0]` (blank = auto-detect current stage, then validate next transition) +Also extract `--review [full|lean|solo]` if present. Note: in `solo` mode, +director spawns (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE) are skipped — +gate-check becomes artifact-existence checks only. In `lean` mode, all three +directors still run (phase gates are the purpose of lean mode). + - **With argument**: `/gate-check production` — validate readiness for that specific phase - **No argument**: Auto-detect current stage using the same heuristics as `/project-stage-detect`, then validate the NEXT phase transition diff --git a/.claude/skills/map-systems/SKILL.md b/.claude/skills/map-systems/SKILL.md index dd92da6..05c20a3 100644 --- a/.claude/skills/map-systems/SKILL.md +++ b/.claude/skills/map-systems/SKILL.md @@ -1,7 +1,7 @@ --- name: map-systems description: "Decompose a game concept into individual systems, map dependencies, prioritize design order, and create the systems index." -argument-hint: "[optional: 'next' to pick highest-priority undesigned system, or a system name to hand off to /design-system]" +argument-hint: "[next | system-name] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, TodoWrite --- @@ -17,6 +17,9 @@ Two modes: - **`next`**: `/map-systems next` — Pick the highest-priority undesigned system from the index and hand off to `/design-system` (Phase 6). +Also extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + --- ## 2. Phase 1: Read Concept (Required Context) diff --git a/.claude/skills/milestone-review/SKILL.md b/.claude/skills/milestone-review/SKILL.md index f67cec9..2e6a052 100644 --- a/.claude/skills/milestone-review/SKILL.md +++ b/.claude/skills/milestone-review/SKILL.md @@ -1,11 +1,18 @@ --- name: milestone-review description: "Generates a comprehensive milestone progress review including feature completeness, quality metrics, risk assessment, and go/no-go recommendation. Use at milestone checkpoints or when evaluating readiness for a milestone deadline." -argument-hint: "[milestone-name|current]" +argument-hint: "[milestone-name|current] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write --- +## Phase 0: Parse Arguments + +Extract the milestone name (`current` or a specific name) and any `--review [full|lean|solo]` +flag. Store the review mode as the override for this run (see `.claude/docs/director-gates.md`). + +--- + ## Phase 1: Load Milestone Data Read the milestone definition from `production/milestones/`. If the argument is `current`, use the most recently modified milestone file. diff --git a/.claude/skills/playtest-report/SKILL.md b/.claude/skills/playtest-report/SKILL.md index ff403c9..a216a58 100644 --- a/.claude/skills/playtest-report/SKILL.md +++ b/.claude/skills/playtest-report/SKILL.md @@ -1,13 +1,16 @@ --- name: playtest-report description: "Generates a structured playtest report template or analyzes existing playtest notes into a structured format. Use this to standardize playtest feedback collection and analysis." -argument-hint: "[new|analyze path-to-notes]" +argument-hint: "[new|analyze path-to-notes] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write --- ## Phase 1: Parse Arguments +Extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + Determine the mode: - `new` → generate a blank playtest report template diff --git a/.claude/skills/prototype/SKILL.md b/.claude/skills/prototype/SKILL.md index cad1fe3..c739b5c 100644 --- a/.claude/skills/prototype/SKILL.md +++ b/.claude/skills/prototype/SKILL.md @@ -1,7 +1,7 @@ --- name: prototype description: "Rapid prototyping workflow. Skips normal standards to quickly validate a game concept or mechanic. Produces throwaway code and a structured prototype report." -argument-hint: "[concept-description]" +argument-hint: "[concept-description] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task context: fork @@ -11,6 +11,9 @@ isolation: worktree ## Phase 1: Define the Question +Extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + Read the concept description from the argument. Identify the core question this prototype must answer. If the concept is vague, state the question explicitly before proceeding — a prototype without a clear question wastes time. --- diff --git a/.claude/skills/quick-design/SKILL.md b/.claude/skills/quick-design/SKILL.md index 874cfcd..4bd9ab5 100644 --- a/.claude/skills/quick-design/SKILL.md +++ b/.claude/skills/quick-design/SKILL.md @@ -247,6 +247,8 @@ implementation. Reference this spec in the story's GDD Reference field. ### Pipeline Notes +Verdict: **COMPLETE** — quick design spec written and ready for implementation. + Quick Design Specs **bypass** `/design-review` and `/review-all-gdds` by design. They are for small, low-risk, well-scoped changes where the cost of the full review pipeline exceeds the risk of the change itself. diff --git a/.claude/skills/sprint-plan/SKILL.md b/.claude/skills/sprint-plan/SKILL.md index e32e2a1..60b62ab 100644 --- a/.claude/skills/sprint-plan/SKILL.md +++ b/.claude/skills/sprint-plan/SKILL.md @@ -1,13 +1,20 @@ --- name: sprint-plan description: "Generates a new sprint plan or updates an existing one based on the current milestone, completed work, and available capacity. Pulls context from production documents and design backlogs." -argument-hint: "[new|update|status]" +argument-hint: "[new|update|status] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Write, Edit context: | !ls production/sprints/ 2>/dev/null --- +## Phase 0: Parse Arguments + +Extract the mode argument (`new`, `update`, or `status`) and any `--review [full|lean|solo]` +flag. Store the review mode as the override for this run (see `.claude/docs/director-gates.md`). + +--- + ## Phase 1: Gather Context 1. **Read the current milestone** from `production/milestones/`. diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md index d2f4459..e079c02 100644 --- a/.claude/skills/start/SKILL.md +++ b/.claude/skills/start/SKILL.md @@ -3,12 +3,12 @@ name: start description: "First-time onboarding — asks where you are, then guides you to the right workflow. No assumptions." argument-hint: "[no arguments]" user-invocable: true -allowed-tools: Read, Glob, Grep, AskUserQuestion +allowed-tools: Read, Glob, Grep, Write, AskUserQuestion --- # Guided Onboarding -This skill is read-only — it reports findings but writes no files. +This skill writes one file: `production/review-mode.txt` (review mode config set in Phase 3b). This skill is the entry point for new users. It does NOT assume you have a game idea, an engine preference, or any prior experience. It asks first, then routes you to the right workflow. @@ -145,6 +145,31 @@ The user needs creative exploration before anything else. --- +## Phase 3b: Set Review Mode + +Check if `production/review-mode.txt` already exists. + +**If it exists**: Read it and show the current mode — "Review mode is set to `[current]`." — then proceed to Phase 4. Do not ask again. + +**If it does not exist**: Use `AskUserQuestion`: + +- **Prompt**: "One setup choice: how much design review would you want as you work through the workflow?" +- **Options**: + - `Full (recommended)` — Director specialists review at each key workflow step. Best for new projects or when you want structured feedback on your decisions. + - `Lean` — Directors only at phase gate transitions (/gate-check). Skips per-skill reviews. For experienced users who trust their own design work. + - `Solo` — No director reviews at all. Maximum speed. Best for game jams, prototypes, or if the reviews feel like overhead. + +Write the choice to `production/review-mode.txt` immediately after the user +selects — no separate "May I write?" needed, as the write is a direct +consequence of the selection: +- `Full (recommended)` → write `full` +- `Lean` → write `lean` +- `Solo` → write `solo` + +Create the `production/` directory if it does not exist. + +--- + ## Phase 4: Confirm Before Proceeding After presenting the recommended path, use `AskUserQuestion` to ask the user which step they'd like to take first. Never auto-run the next skill. @@ -168,7 +193,7 @@ Verdict: **COMPLETE** — user oriented and handed off to next step. - **User picks D but project is empty**: Gently redirect — "It looks like the project is a fresh template with no artifacts yet. Would Path A or B be a better fit?" - **User picks A but project has code**: Mention what you found — "I noticed there's already code in `src/`. Did you mean to pick D (existing work)?" -- **User is returning (engine configured, concept exists)**: Skip onboarding entirely — "It looks like you're already set up! Your engine is [X] and you have a game concept at `design/gdd/game-concept.md`. Want to pick up where you left off? Try `/sprint-plan` or just tell me what you'd like to work on." +- **User is returning (engine configured, concept exists)**: Skip onboarding entirely — "It looks like you're already set up! Your engine is [X] and you have a game concept at `design/gdd/game-concept.md`. Review mode: `[read from production/review-mode.txt, or 'full (default)' if missing]`. Want to pick up where you left off? Try `/sprint-plan` or just tell me what you'd like to work on." - **User doesn't fit any option**: Let them describe their situation in their own words and adapt. --- diff --git a/.claude/skills/story-done/SKILL.md b/.claude/skills/story-done/SKILL.md index 6c2fc1e..227e464 100644 --- a/.claude/skills/story-done/SKILL.md +++ b/.claude/skills/story-done/SKILL.md @@ -1,7 +1,7 @@ --- name: story-done description: "End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint." -argument-hint: "[story-file-path]" +argument-hint: "[story-file-path] [--review full|lean|solo]" user-invocable: true allowed-tools: Read, Glob, Grep, Bash, Edit --- @@ -20,6 +20,9 @@ forgotten, and the story file reflects actual completion status. ## Phase 1: Find the Story +Extract `--review [full|lean|solo]` if present and store as the review mode +override for this run (see `.claude/docs/director-gates.md`). + **If a file path is provided** (e.g., `/story-done production/epics/core/story-damage-calculator.md`): read that file directly. diff --git a/README.md b/README.md index b6fcd5f..1bee058 100644 --- a/README.md +++ b/README.md @@ -267,6 +267,7 @@ This is a **template**, not a locked framework. Everything is meant to be custom - **Add rules** — create new path-scoped rules for your project's directory structure - **Tune hooks** — adjust validation strictness, add new checks - **Pick your engine** — use the Godot, Unity, or Unreal agent set (or none) +- **Set review intensity** — `full` (all director gates), `lean` (phase gates only), or `solo` (none). Set during `/start` or edit `production/review-mode.txt`. Override per-run with `--review solo` on any skill. ## Platform Support diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index 7bd0c74..bc2f629 100644 --- a/docs/WORKFLOW-GUIDE.md +++ b/docs/WORKFLOW-GUIDE.md @@ -1142,6 +1142,33 @@ Ask Claude to create a post-mortem using the template at 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. + +**Set your review intensity once during `/start`.** Saved to `production/review-mode.txt`. + +| 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 | + +**Override for a single run** without changing your global 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 `production/review-mode.txt` directly or re-running `/start`. + +Full gate definitions and check pattern: `.claude/docs/director-gates.md` + +--- + ### The Collaboration Protocol This system is **user-driven collaborative**, not autonomous.