@zigrivers/scaffold 3.22.0 → 3.24.0

package/skills/mmr/SKILL.md

@@ -14,10 +14,38 @@ Dispatch code reviews to multiple AI model CLIs, poll for results, and collect r
 
 ## Quick Reference
 
+`mmr review` works for any review target — not just PRs. Pick the input mode
+that matches what you want reviewed:
+
 ```bash
-# Dispatch a review for a PR
+# GitHub PR (fetches diff via `gh pr diff`)
 mmr review --pr <number> --focus "description of what to focus on"
 
+# Staged git changes (pre-commit review)
+mmr review --staged --focus "..."
+
+# All tracked uncommitted changes (staged + unstaged) — excludes untracked
+# files; use `scaffold run review-code` for full-worktree coverage
+git diff HEAD | mmr review --diff - --focus "..."
+
+# Branch diff / ref range
+mmr review --base main --head <branch> --focus "..."
+
+# Changes to a specific tracked file since HEAD (pending edits only).
+# If the file has no local changes this pipeline sends an empty diff
+# and MMR will refuse with "no diff content"; use the next form instead
+# to review the file's current contents regardless of git state.
+git diff HEAD -- path/to/file.md | mmr review --diff - --focus "..."
+
+# A file's current contents, regardless of git state (tracked-with-no-
+# changes, untracked, or brand-new). Synthesizes an "all added" diff.
+# `|| true` is required: diff exits 1 whenever files differ, which breaks
+# pipelines under `set -o pipefail`.
+(diff -u /dev/null path/to/file.md || true) | mmr review --diff - --focus "..."
+
+# Existing patch or diff file
+mmr review --diff path/to/changes.patch --focus "..."
+
 # Check progress
 mmr status <job-id>
 
@@ -28,7 +56,20 @@ mmr results <job-id>
 mmr config test
 ```
 
-## After Creating a PR
+All input modes accept `--focus`, `--sync`, `--format`, and `--fix-threshold`
+the same way. The "3-channel review" is not PR-specific — it reviews whatever
+diff you point it at.
+
+**`--diff` contract:** the flag expects diff-format content (a path to a
+`.patch`/`.diff` file, or `-` for stdin). It does not read raw document
+content — wrap the target in a diff first (see the `git diff …` and
+`(diff -u /dev/null … || true)` patterns above). The `|| true` guard is
+required because `diff` exits 1 whenever files differ, which breaks
+pipelines under `set -o pipefail`.
+
+## Common Workflows
+
+**After creating a PR**
 
 1. Run `mmr review --pr <number>`
 2. Note the job ID from the output
@@ -38,6 +79,35 @@ mmr config test
 6. If gate failed: fix findings at or above the threshold severity
 7. If gate passed: proceed to merge
 
+**Reviewing a document or arbitrary file**
+
+Pick the case that matches what the user wants reviewed:
+
+- **Just the pending edits** to a tracked file (what changed since last
+  commit): `git diff HEAD -- path/to/doc.md | mmr review --diff -
+  --focus "..."`. Fails with "no diff content" if the file has no
+  local changes.
+- **The file's current contents**, whether it's tracked-with-no-
+  changes, untracked, or brand-new: wrap as a synthetic "all added"
+  diff first: `(diff -u /dev/null path/to/doc.md || true) |
+  mmr review --diff - --focus "..."`. The `|| true` guard avoids
+  `diff`'s exit-1-on-differences breaking the pipeline under
+  `set -o pipefail`.
+
+Same dispatch / status / results flow as above.
+
+**Reviewing uncommitted work before push**
+
+1. `git add` the files you want reviewed
+2. Run `mmr review --staged`
+3. Fix findings at or above the gate threshold, re-stage, re-run as needed
+
+Prefer the wrapper tools (`scaffold run review-pr`, `scaffold run review-code`)
+when they cover your target — they add auth checks, compensating passes, and
+the agent-review channel on top of `mmr review`. Call `mmr review` directly
+for targets the wrappers don't cover (docs, arbitrary diffs, ref ranges
+outside `main`).
+
 ## Auth Failures
 
 If `mmr review` reports auth failures, follow the recovery instructions in the output:

package/skills/scaffold-runner/SKILL.md

@@ -202,9 +202,9 @@ When the user asks "what tools are available?", "what can I build?", or "show me
 | `scaffold run update` | Update scaffold to the latest version |
 | `scaffold run dashboard` | Open a visual progress dashboard in your browser |
 | `scaffold run prompt-pipeline` | Print the full pipeline reference table |
-| `scaffold run review-code` | Run all 3 code review channels on local code before commit or push |
-| `scaffold run review-pr` | Run all 3 code review channels (Codex CLI, Gemini CLI, Superpowers) on a PR |
-| `scaffold run post-implementation-review` | Full 3-channel codebase review after an AI agent completes all tasks |
+| `scaffold run review-code` | Run all 3 CLI review channels (Codex CLI, Gemini CLI, Claude CLI) on tracked local code (committed branch diff + staged + unstaged — no untracked files) before commit or push, plus Superpowers code-reviewer as a complementary 4th channel |
+| `scaffold run review-pr` | Run all 3 code review channels (Codex CLI, Gemini CLI, Claude CLI) on a PR, plus Superpowers code-reviewer as a complementary 4th channel |
+| `scaffold run post-implementation-review` | Full codebase review (Codex CLI, Gemini CLI, Superpowers code-reviewer) after an AI agent completes all tasks |
 | `scaffold run session-analyzer` | Analyze Claude Code session logs for patterns and insights |
 
 **Display rules:**
@@ -240,7 +240,8 @@ Respond to these natural language requests:
 | "Is X applicable?" / "Do I need X?" | Run `scaffold check <step>` to detect platform and brownfield status |
 | "Set up memory" / "Configure AI memory" / "Add memory" | Run `scaffold run ai-memory-setup` — sets up modular rules, optional MCP memory server, and external context |
 | "Set up testing" / "Add Playwright" / "Add Maestro" | Run `scaffold run add-e2e-testing` — auto-detects web/mobile and configures the right framework(s) |
-| "Run multi-model review" / "Review stories with other models" | Run `scaffold run review-user-stories` at depth 5 (multi-model capabilities are now built into review-user-stories) |
+| "Run multi-model review" / "Review X with all three models" | Route by target — see [Multi-Model Review Routing](#multi-model-review-routing) |
+| "Review stories with other models" | Run `scaffold run review-user-stories` at depth 5 (multi-model capabilities are built into review-user-stories) |
 | "Skip X" | Run `scaffold skip <step> --reason "<user's reason>"` |
 | "Skip X, Y, and Z" | Run `scaffold skip <step1> <step2> <step3> --reason "<reason>"` |
 | "What's left?" / "Show remaining" | Run `scaffold status --compact`, show only pending/in-progress steps |
@@ -338,28 +339,73 @@ scaffold check add-e2e-testing
 
 This is useful when the user asks "Do I need this step?" or when previewing which optional steps apply before running them.
 
+### Multi-Model Review Routing
+
+When the user asks for a "multi-model review", "review this with all three models",
+"run MMR on X", or similar — **do not assume the target is a PR**. Route based on
+what the user is pointing at:
+
+| Target | Command |
+|---|---|
+| GitHub PR (explicit number or current branch's PR) | `scaffold run review-pr [<PR#>]` |
+| Local uncommitted / staged code, before commit or push | `scaffold run review-code` |
+| Pending edits to a tracked file (changes since HEAD) | `git diff HEAD -- <path> \| mmr review --diff - --sync --format json` |
+| Current contents of any file (tracked-with-no-changes, untracked, or brand-new) | `(diff -u /dev/null <path> \|\| true) \| mmr review --diff - --sync --format json` |
+| A branch diff against main (or another ref) | `mmr review --base <ref> --head <ref> --sync --format json` |
+| An existing patch or diff file | `mmr review --diff <path.patch> --sync --format json` |
+| A diff piped from another command | `<cmd> \| mmr review --diff - --sync --format json` (stdin) |
+| A user-story review specifically at depth 5 | `scaffold run review-user-stories` |
+
+If the user's target is ambiguous ("review this with MMR"), ask once which of
+the above applies — don't default to `review-pr` just because it's the most
+common entry point. Doc reviews and uncommitted-work reviews are equally
+first-class.
+
+Pass `--focus "..."` to MMR when the user describes what to evaluate (clarity,
+completeness, security, performance, etc.). See the `mmr` skill for all input
+modes and flags.
+
+**Note on `--diff`:** the flag requires diff-format content (path to a
+`.patch`/`.diff` file, or `-` for stdin). To review a regular document or
+source file, wrap it in a diff first using `git diff HEAD -- <path>`
+(tracked) or `(diff -u /dev/null <path> || true)` (untracked — the
+`|| true` guard is required because `diff` exits 1 whenever files
+differ, which breaks pipelines under `set -o pipefail`) and pipe the
+result into `mmr review --diff -`.
+
 ### Multi-Model Review at Depth 4-5
 
-All review and validation steps now support independent multi-model validation at depth 4-5 using Codex and/or Gemini CLIs. The `multi-model-dispatch` skill documents the correct invocation patterns:
+All review and validation steps support independent multi-model validation at depth 4-5. Two distinct paths exist — **never mix them** — pick based on what step is running:
 
-- **Codex**: `codex exec --skip-git-repo-check -s read-only --ephemeral "prompt" 2>/dev/null` (NOT bare `codex`)
-- **Gemini**: `NO_BROWSER=true gemini -p "prompt" --output-format json --approval-mode yolo 2>/dev/null`
+#### Path A: MMR-backed review (PREFERRED — always use for these steps)
 
-**`NO_BROWSER=true` is required for all Gemini invocations** from Claude Code's Bash tool. Without it, Gemini's child process relaunch shows a consent prompt that hangs in non-TTY shells.
+Applies to: `scaffold run review-pr`, `scaffold run review-code`, and any pipeline review step that invokes `mmr review` directly.
 
-**Auth verification is mandatory before dispatch.** CLI tokens expire mid-session. Before running any review at depth 4-5:
-1. Check Codex auth: `codex login status`
-2. Check Gemini auth: `NO_BROWSER=true gemini -p "respond with ok" -o json` (exit 41 = auth failure)
-3. If auth fails, tell the user to re-authenticate: `! gemini -p "hello"` or `! codex login` (the `!` prefix runs it interactively with TTY access)
-4. **Never silently skip a CLI due to auth failure** — surface it to the user
+- **Channel model:** three CLIs (Codex + Gemini + Claude) dispatched and reconciled by the MMR CLI; scaffold wrappers add the Superpowers code-reviewer agent as a complementary 4th channel reconciled into the same MMR job via `mmr reconcile`.
+- **Note:** `scaffold run post-implementation-review` follows a different channel layout (raw-CLI dispatch of Codex + Gemini + Superpowers, with optional `mmr reconcile` injection if a prior `mmr review` job exists). Treat it as its own path — consult `content/tools/post-implementation-review.md` for specifics.
+- **Invocation:** go through the wrapper (`scaffold run …`) or call `mmr review …` directly. Do NOT shell out to `codex`/`gemini`/`claude` yourself for these steps — MMR handles dispatch, parsing, compensating passes, and verdict.
+- **Auth pre-flight:** run `mmr config test` once per session — it probes all three CLIs and reports status in one call.
+- **If auth fails** for any channel, surface recovery commands to the user: `! codex login`, `! gemini -p "hello"`, or `! claude login`. MMR will emit a compensating pass (via `claude -p`) for each missing external channel, labelled `[compensating: Codex-equivalent]` / `[compensating: Gemini-equivalent]`. Maximum achievable verdict in that case is `degraded-pass`.
+- **Never silently skip a CLI due to auth failure** — surface it to the user.
+
+#### Path B: Legacy / non-MMR direct dispatch
+
+Applies to: some older depth-5 validation steps and any ad-hoc manual dispatch not routed through MMR. The `multi-model-dispatch` skill documents the raw invocation patterns:
+
+- **Codex:** `codex exec --skip-git-repo-check -s read-only --ephemeral "prompt" 2>/dev/null` (NOT bare `codex`)
+- **Gemini:** `NO_BROWSER=true gemini -p "prompt" --output-format json --approval-mode yolo 2>/dev/null`
+- **Claude CLI:** `claude -p "prompt" --output-format json 2>/dev/null`
+
+**`NO_BROWSER=true` is required for all Gemini invocations** from Claude Code's Bash tool. Without it, Gemini's child process relaunch shows a consent prompt that hangs in non-TTY shells.
 
-When running a review step at depth 4-5:
-1. Check CLI availability before dispatching
-2. If both available, run dual-model review for highest quality
-3. If one available, run single-model external review
-4. If neither available, fall back to Claude-only adversarial self-review
+Auth pre-flight for Path B dispatch:
+1. Codex: `codex login status`
+2. Gemini: `NO_BROWSER=true gemini -p "respond with ok" -o json` (exit 41 = auth failure)
+3. Claude CLI: `claude -p "respond with ok"` (typically uses the active Claude Code session)
+4. If any fail: `! codex login`, `! gemini -p "hello"`, or `! claude login` (the `!` prefix runs it interactively with TTY access).
+5. **Never silently skip a CLI due to auth failure** — surface it to the user.
 
-The runner should surface the depth choice as a decision point for review steps, noting that depth 4-5 enables multi-model validation if CLIs are available.
+The runner should surface the depth choice as a decision point for review steps, noting that depth 4-5 enables three-CLI multi-model validation when the CLIs are available.
 
 ## Batch Execution