@zigrivers/scaffold 3.4.0 → 3.5.0

package/README.md

@@ -76,6 +76,13 @@ Independent review from Google's model. Can run alongside or instead of Codex.
 - Requires: Google account (free tier available)
 - Verify: `gemini --version`
 
+**mmr** (multi-model review CLI)
+Automates dispatching, monitoring, and reconciling code reviews across multiple AI model CLIs. Works standalone or with Scaffold.
+- Install: `npm install -g @zigrivers/mmr`
+- Verify: `mmr --help`
+- Setup: `mmr config init` (auto-detects installed CLIs)
+- See: [mmr — Multi-Model Review CLI](#mmr--multi-model-review-cli)
+
 **Playwright MCP** (web apps only)
 Lets Claude control a real browser for visual testing and screenshots.
 - Install: `claude mcp add playwright npx @playwright/mcp@latest`
@@ -151,6 +158,12 @@ npm update -g @zigrivers/scaffold
 brew upgrade scaffold
 ```
 
+### mmr
+
+```bash
+npm update -g @zigrivers/mmr
+```
+
 ### Plugin
 
 ```
@@ -343,6 +356,97 @@ scaffold dashboard           # open a visual progress dashboard in your browser
 - **The pipeline is a guide, not a cage.** Skip steps that don't apply (`scaffold skip <step> --reason "..."`). Run them out of order if you know what you're doing. Scaffold tracks dependencies so it'll tell you if you're missing a prerequisite.
 - **Depth controls thoroughness.** Each step runs at a depth from 1 (focused, fast) to 5 (exhaustive). The mvp preset defaults to depth 1; deep defaults to 5. You can override per step or per session: `"Use depth 3 for everything"`.
 
+### Game Development
+
+Scaffold fully supports game development projects. When you select `game` as your project type, a **project-type overlay** activates 24 game-specific pipeline steps and injects game domain expertise into existing steps — all while keeping the standard pipeline workflow (status, next, rework, multi-model review) fully functional.
+
+#### Getting Started
+
+```bash
+# Interactive — the wizard asks about your engine, multiplayer, platforms, etc.
+scaffold init
+
+# Non-interactive with defaults (engine: custom, single-player, PC)
+scaffold init --project-type game --auto
+
+# Non-interactive with specific methodology
+scaffold init --project-type game --methodology deep --auto
+
+# Adopt an existing game project (auto-detects Unity/Unreal/Godot)
+scaffold adopt
+```
+
+#### How It Works
+
+Game support uses a **project-type overlay** architecture. You choose your methodology normally (`mvp`, `deep`, or `custom`), then `projectType: game` layers on top:
+
+- **Enables 24 game steps** — GDD, performance budgets, art bible, audio design, etc.
+- **Disables 3 web-centric steps** — `design-system`, `ux-spec`, `review-ux` (replaced by `game-ui-spec`)
+- **Injects 29 game knowledge entries** into existing steps (e.g., game engine evaluation into `tech-stack`, game testing patterns into `tdd`)
+- **Remaps artifact references** so downstream steps read game-specific docs instead of web ones
+
+A game jam project uses `mvp` + game overlay (fewer steps, lower depth). An AAA project uses `deep` + game overlay (all steps, max depth).
+
+#### Game Configuration
+
+During `scaffold init`, the wizard asks game-specific questions with progressive disclosure:
+
+| Category | Questions |
+|----------|-----------|
+| **Core** (always asked) | Game engine (Unity/Unreal/Godot/custom), multiplayer mode (none/local/online/hybrid), target platforms (PC/console/mobile/VR/AR) |
+| **Conditional** | Online services (if multiplayer), content structure (levels/open-world/procedural/endless), economy type (none/progression/monetized) |
+| **Advanced** (opt-in) | Narrative depth, supported locales, NPC AI complexity, mod support, persistence model |
+
+These answers control which conditional steps activate. A single-player puzzle game gets a different pipeline than a multiplayer live-service RPG.
+
+#### Game Pipeline Steps
+
+**Always enabled** (12 steps):
+
+| Step | Phase | What It Produces |
+|------|-------|-----------------|
+| `game-design-document` | Pre | Game pillars, core loop, mechanics catalog, progression systems |
+| `review-gdd` | Pre | Multi-pass review of GDD for pillar coherence, scope feasibility |
+| `performance-budgets` | Foundation | Frame budgets, memory budgets, GPU limits, loading targets per platform |
+| `game-accessibility` | Specification | XAG-aligned accessibility plan (visual, motor, cognitive, auditory) |
+| `input-controls-spec` | Specification | Input bindings, rebinding, haptics, dead zones, cross-play fairness |
+| `game-ui-spec` | Specification | HUD, menus, controller navigation, settings, FTUE/tutorial, UI states |
+| `review-game-ui` | Specification | Multi-pass review of game UI for completeness and accessibility |
+| `content-structure-design` | Specification | Level layouts, world regions, procedural rulesets, or mission templates |
+| `art-bible` | Specification | Art style, asset specs, naming conventions, DCC pipeline, LOD strategy |
+| `audio-design` | Specification | Audio direction, adaptive music, spatial audio, middleware config, VO |
+| `playtest-plan` | Quality | Playtest types, schedule, feedback templates, balance testing |
+| `analytics-telemetry` | Quality | Event taxonomy, crash telemetry, data pipeline, privacy compliance |
+
+**Conditional** (12 steps — activated by your game configuration):
+
+| Step | Activates When | What It Produces |
+|------|---------------|-----------------|
+| `narrative-bible` | Narrative is light/heavy | World lore, characters, dialogue systems, branching narrative |
+| `netcode-spec` | Multiplayer is online/hybrid | Network topology, tick rate, prediction, lag compensation, anti-cheat |
+| `review-netcode` | Netcode spec enabled | Latency tolerance, bandwidth, cheat resistance review |
+| `ai-behavior-design` | NPC AI is simple/complex | Behavior trees, pathfinding, perception, difficulty scaling |
+| `economy-design` | Economy is not none | Currencies, loot tables, monetization, legal compliance |
+| `review-economy` | Economy design enabled | Inflation analysis, exploit detection, ethical monetization review |
+| `online-services-spec` | Online services selected | Identity, leaderboards, matchmaking, moderation, cloud save |
+| `modding-ugc-spec` | Mod support enabled | Mod API, sandboxing, distribution, content moderation |
+| `save-system-spec` | Persistence is not none | Save format, cloud sync, corruption recovery, migration |
+| `localization-plan` | Multiple locales | String management, fonts (CJK/RTL), VO localization, LQA |
+| `live-ops-plan` | Live-ops selected | Content cadence, events, hotfix deployment, maintenance |
+| `platform-cert-prep` | Console/mobile/VR targets | Sony TRC, Xbox XR, Nintendo Lotcheck, store compliance checklists |
+
+#### Engine Detection
+
+`scaffold adopt` automatically detects game engines in existing projects:
+
+| Engine | Detection Signal |
+|--------|-----------------|
+| Unity | `Assets/*.meta` files |
+| Unreal | `*.uproject` file |
+| Godot | `project.godot` file |
+
+When detected, `scaffold adopt` sets `projectType: game` and `gameConfig.engine` in your config, enabling the full game overlay.
+
 ## The Pipeline
 
 ### Phase 0 — Product Vision (vision)
@@ -546,16 +650,291 @@ You don't need both — Scaffold works with whichever CLIs are available. Having
 
 ### mmr — Multi-Model Review CLI
 
-Scaffold includes `mmr`, a standalone CLI that automates multi-model code review dispatch, monitoring, and reconciliation. Instead of manually running each review channel, `mmr` handles it all:
+`mmr` is a standalone CLI that automates multi-model code review. It solves the problems teams hit when manually orchestrating reviews across Claude, Codex, and Gemini: timeouts, auth failures, inconsistent prompts, fragile output parsing, and manual reconciliation.
+
+**The core problem it solves:** Without `mmr`, an AI agent dispatching multi-model reviews has to manually construct CLI commands for each model, handle per-tool auth quirks, improvise timeout handling, parse different output formats, and reconcile findings across channels. In practice, this takes 4-6+ minutes per review and frequently fails. `mmr` reduces this to three commands.
 
+#### How mmr Works
+
+```
+mmr review --pr 47           ──→  Dispatches to all channels in background
+                                   Returns job ID immediately
+                                   Agent continues working
+
+mmr status mmr-a1b2c3        ──→  Poll progress (which channels done?)
+                                   Exit code: 0=done, 1=running, 2=failed
+
+mmr results mmr-a1b2c3       ──→  Reconcile findings across channels
+                                   Apply severity gate
+                                   Output unified findings
+                                   Exit code: 0=passed, 1=gate failed
+```
+
+**Key features:**
+
+- **Async job model** — reviews run in background processes. The agent fires `mmr review` and continues working. No blocking for 4-6 minutes.
+- **Per-channel auth verification** — checks authentication before every dispatch. Auth failures are never silent — `mmr` tells you exactly what expired and the command to fix it.
+- **Immutable core prompt** — every channel gets the same severity definitions (P0-P3), output format spec (JSON), and review criteria. No prompt drift between channels.
+- **Automated reconciliation** — when two channels flag the same location, that's consensus (high confidence). When only one channel flags something, it's unique (medium confidence). P0 from any single source is always high confidence.
+- **Configurable severity gate** — project default in `.mmr.yaml`, override per-review with `--fix-threshold`. Default: P2 (fix P0/P1/P2, skip P3).
+- **Multiple output formats** — JSON (default, for machines), text (terminals), markdown (PR comments).
+
+#### Installing mmr
+
+**npm** (available now):
+```bash
+npm install -g @zigrivers/mmr
+```
+
+**Homebrew** (available after next scaffold release):
 ```bash
-mmr review --pr 47 --focus "auth flow"   # Dispatch to all channels (async)
-mmr status mmr-a1b2c3                     # Poll progress
-mmr results mmr-a1b2c3                    # Reconciled findings + gate
-mmr config test                           # Pre-flight auth check
+brew tap zigrivers/scaffold
+brew install mmr
 ```
 
-`mmr` is installed alongside Scaffold, or independently via `npm install -g @zigrivers/mmr`. Run `mmr config init` to auto-detect installed CLIs and generate a `.mmr.yaml` config. See the [mmr design spec](docs/superpowers/specs/2026-04-05-mmr-multi-model-review-design.md) for full details.
+Verify: `mmr --help`
+
+#### Enabling mmr in an Existing Project
+
+**Step 1: Install the model CLIs you want to use**
+
+You need at least one. More models = more diverse review perspectives.
+
+```bash
+# Claude Code (you probably already have this)
+npm install -g @anthropic-ai/claude-code
+
+# Codex CLI (requires ChatGPT Plus/Pro/Team subscription)
+npm install -g @openai/codex
+
+# Gemini CLI (free tier available with Google account)
+npm install -g @google/gemini-cli
+```
+
+**Step 2: Authenticate each CLI**
+
+Each CLI needs a one-time interactive authentication:
+
+```bash
+# Claude — if not already logged in
+claude login
+
+# Codex — opens browser for OAuth
+codex login
+
+# Gemini — opens browser for OAuth
+gemini -p "hello"
+```
+
+**Step 3: Initialize mmr in your project**
+
+```bash
+cd your-project
+mmr config init
+```
+
+This auto-detects which CLIs are installed and generates `.mmr.yaml` in your project root:
+
+```
+Detected CLIs:
+  ✓ claude (claude -p)
+  ✓ gemini (gemini -p)
+  ✗ codex (not found)
+
+Generated .mmr.yaml with 2 enabled channels.
+Run `mmr config test` to verify authentication.
+```
+
+**Step 4: Verify authentication**
+
+```bash
+mmr config test
+```
+
+```
+  claude    ✓ installed    ✓ authenticated
+  gemini    ✓ installed    ✓ authenticated
+  codex     ✗ not installed (skipped)
+
+  2/3 channels ready.
+```
+
+If any channel shows an auth failure, `mmr` tells you the exact command to fix it.
+
+**Step 5: Commit the config**
+
+```bash
+git add .mmr.yaml
+git commit -m "chore: add mmr multi-model review config"
+```
+
+This ensures your team shares the same channel configuration.
+
+**Step 6 (optional): Customize review criteria**
+
+Edit `.mmr.yaml` to add project-specific review criteria that get injected into every review prompt:
+
+```yaml
+review_criteria:
+  - "Verify all database queries use parameterized statements"
+  - "Check that error messages do not leak internal state"
+  - "Ensure all API endpoints validate authentication"
+```
+
+You can also adjust per-channel timeouts, the default severity threshold, and named review templates for different review types (PR reviews, implementation plan reviews, etc.).
+
+#### Using mmr Day-to-Day
+
+**After creating a PR:**
+
+```bash
+mmr review --pr 47 --focus "auth flow, session handling"
+# → Job mmr-a1b2c3 started. 2/2 channels dispatched.
+```
+
+**Continue working, then check back:**
+
+```bash
+mmr status mmr-a1b2c3
+# → claude: completed (47s) | gemini: running (2m12s)
+
+# Later:
+mmr status mmr-a1b2c3
+# → All channels complete.
+```
+
+**Collect reconciled results:**
+
+```bash
+mmr results mmr-a1b2c3
+# → JSON output with gate_passed, reconciled_findings, per_channel details
+
+mmr results mmr-a1b2c3 --format text
+# → Human-readable terminal output
+
+mmr results mmr-a1b2c3 --format markdown
+# → Markdown table for PR comments
+```
+
+**Review staged changes before committing:**
+
+```bash
+mmr review --staged --focus "regression risk"
+```
+
+**Review a diff between branches:**
+
+```bash
+mmr review --base main --head feature/auth
+```
+
+**Override severity gate for a critical path:**
+
+```bash
+mmr review --pr 47 --fix-threshold P1    # Only fix P0 and P1
+mmr review --pr 47 --fix-threshold P0    # Only fix critical/security issues
+```
+
+#### mmr Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `mmr review` | Dispatch a review job to all configured channels |
+| `mmr status <job-id>` | Check progress of a running job |
+| `mmr results <job-id>` | Collect, reconcile, and output findings |
+| `mmr config init` | Auto-detect CLIs and generate `.mmr.yaml` |
+| `mmr config test` | Verify all channels (installation + auth) |
+| `mmr config channels` | List configured channels |
+| `mmr jobs list` | Show recent review jobs |
+| `mmr jobs prune` | Remove old jobs (default: older than 7 days) |
+
+#### mmr Configuration (.mmr.yaml)
+
+The config file controls channel definitions, defaults, and project-specific review criteria:
+
+```yaml
+version: 1
+
+defaults:
+  fix_threshold: P2        # P0/P1/P2 block the gate, P3 is informational
+  timeout: 300             # Per-channel timeout in seconds
+  format: json             # Default output format
+  job_retention_days: 7    # Auto-prune old jobs
+
+# Project-specific criteria appended to every review prompt
+review_criteria:
+  - "Check for SQL injection in all query builders"
+  - "Verify RBAC rules match API contract"
+
+# Channel definitions (auto-generated by mmr config init)
+channels:
+  claude:
+    enabled: true
+    command: claude -p
+    auth:
+      check: "claude -p 'respond with ok' 2>/dev/null"
+      timeout: 5
+      failure_exit_codes: [1]
+      recovery: "Run: claude login"
+
+  gemini:
+    enabled: true
+    command: gemini -p
+    flags:
+      - "--approval-mode yolo"
+      - "--output-format json"
+    env:
+      NO_BROWSER: "true"
+    auth:
+      check: "NO_BROWSER=true gemini -p 'respond with ok' -o json 2>&1"
+      timeout: 5
+      failure_exit_codes: [41]
+      recovery: "Run: gemini -p 'hello' (interactive, opens browser)"
+    timeout: 360     # Gemini tends to be slower
+
+  codex:
+    enabled: true
+    command: codex exec
+    flags:
+      - "--skip-git-repo-check"
+      - "-s read-only"
+      - "--ephemeral"
+    auth:
+      check: "codex login status 2>/dev/null"
+      timeout: 5
+      failure_exit_codes: [1]
+      recovery: "Run: codex login"
+```
+
+**User-level defaults** can be set in `~/.mmr/config.yaml` for settings that apply across all projects (e.g., which channels are installed on your machine). Project config overrides user config. CLI flags override everything.
+
+**Adding a new model CLI** requires only a YAML config change — no code modifications to `mmr`. When a new model CLI ships, add its channel definition to `.mmr.yaml` and you're ready.
+
+#### Severity Levels
+
+mmr uses a standardized P0-P3 severity classification across all channels:
+
+| Level | Name | Definition | Gate Default |
+|-------|------|------------|-------------|
+| **P0** | Critical | Will cause failure, data loss, security vulnerability, or fundamental architectural flaw | Blocks |
+| **P1** | High | Will cause bugs in normal usage, inconsistency, or blocks downstream work | Blocks |
+| **P2** | Medium | Improvement opportunity — style, naming, documentation, minor optimization | Blocks |
+| **P3** | Trivial | Personal preference, trivial nits | Informational |
+
+With the default `fix_threshold: P2`, any P0, P1, or P2 finding fails the gate. Only P3-only reviews pass.
+
+#### Reconciliation Rules
+
+When multiple channels return findings, mmr applies consensus rules:
+
+| Scenario | Confidence | Action |
+|----------|-----------|--------|
+| 2+ channels flag same location, same severity | **High** | Report at agreed severity |
+| 2+ channels flag same location, different severity | **Medium** | Report at higher severity |
+| All channels approve (no findings) | **High** | Gate passed |
+| One channel flags P0, others approve | **High** | Report P0 (critical from any source) |
+| One channel flags P1/P2, others approve | **Medium** | Report with attribution |
+| Channels contradict each other | **Low** | Present both for user adjudication |
 
 ### How It Works
 
@@ -771,6 +1150,7 @@ Options: `--dry-run` to preview, `minor`/`major`/`patch` to specify the bump, `c
 | **Knowledge base** | 60 domain expertise entries that get injected into prompts. Can be extended with project-local overrides. |
 | **MCP** | Model Context Protocol. A way for Claude to use external tools like a headless browser. |
 | **Meta-prompt** | A short intent declaration in `content/pipeline/` that gets assembled into a full prompt at runtime. |
+| **mmr** | Multi-Model Review CLI (`@zigrivers/mmr`). Standalone tool for async multi-model code review dispatch, reconciliation, and severity gating. |
 | **Methodology** | A preset (deep, mvp, custom) controlling which steps run and at what depth. |
 | **Multi-model review** | Independent validation from Codex/Gemini CLIs at depth 4-5, catching blind spots a single model misses. |
 | **PRD** | Product Requirements Document. The foundation for everything Scaffold builds. |
@@ -826,6 +1206,15 @@ NO_BROWSER=true gemini -p "Review this artifact..." --output-format json --appro
 ```
 These are documented in detail in the `multi-model-dispatch` skill.
 
+**mmr review dispatches but no channels return results**
+Check auth: `mmr config test`. If channels show auth failures, re-authenticate with the recovery command shown. If channels are installed but the review hangs, check the per-channel timeout in `.mmr.yaml` — some models take 3-5 minutes for large diffs. Increase `timeout` to 360-600 seconds for large PRs.
+
+**mmr results says "gate failed" but I disagree with the findings**
+Use `mmr results <job-id> --format text` to see the full reconciled findings with source attribution and confidence scores. Single-source findings with "unique" agreement are less certain than "consensus" findings. Override the threshold for a specific review: `mmr review --pr 47 --fix-threshold P1` (only gate on P0 and P1).
+
+**How do I add a new AI model CLI to mmr?**
+Add a channel definition to `.mmr.yaml` with the command, auth check, and output parser. No code changes needed. See the [mmr Configuration](#mmr-configuration-mmryaml) section for the full schema.
+
 **I upgraded and my pipeline shows old step names**
 Run `scaffold status` — the state manager automatically migrates old step names (e.g., `add-playwright` → `add-e2e-testing`, `multi-model-review` → `automated-pr-review`) and removes retired steps.
 
@@ -873,7 +1262,22 @@ content/
 ├── tools/            # 10 tool meta-prompts (stateless, category: tool)
 ├── knowledge/        # 61 domain expertise entries (core, product, review, validation, finalization, execution, tools)
 ├── methodology/      # 3 YAML presets (deep, mvp, custom)
-└── skills/           # 3 skill templates with {{markers}} for multi-platform resolution
+└── skills/           # Skill templates with {{markers}} for multi-platform resolution (includes mmr)
+```
+
+### mmr package layout
+
+`@zigrivers/mmr` lives in `packages/mmr/` as an independent workspace package:
+
+```
+packages/mmr/
+├── src/
+│   ├── commands/     # review, status, results, config, jobs (yargs)
+│   ├── config/       # Zod schema, 4-layer config loader, builtin channel presets
+│   ├── core/         # job-store, auth, prompt assembly, parser, reconciler, dispatcher
+│   └── formatters/   # json, text, markdown output formatters
+├── templates/        # Immutable core review prompt (severity defs, output format)
+└── tests/            # 60 tests across 11 files
 ```
 
 Generated output (gitignored):