@zigrivers/scaffold 2.1.2 → 2.38.0

package/pipeline/vision/innovate-vision.md

@@ -0,0 +1,157 @@
+---
+name: innovate-vision
+description: Discover strategic innovation opportunities in the product vision
+summary: "Explores untapped opportunities — adjacent markets, AI-native capabilities, ecosystem partnerships, and contrarian positioning — and proposes innovations for your approval."
+phase: "vision"
+order: 030
+dependencies: [review-vision]
+outputs: [docs/vision.md]
+conditional: "if-needed"
+knowledge-base: [vision-craft]
+---
+
+## Purpose
+Discover strategic innovation opportunities within the product vision. This
+covers market positioning, competitive strategy, ecosystem thinking, and
+contrarian bets. It operates at the strategic level — should the product be
+positioned differently? Are there market opportunities being missed? What
+would an AI-native rethinking look like?
+
+This is distinct from PRD innovation (innovate-prd), which covers feature-level
+gaps. If an idea is about a specific feature, it belongs in PRD innovation,
+not here.
+
+## Inputs
+- docs/vision.md (required) — Vision document to analyze
+- docs/reviews/vision-review-vision.md (optional) — review findings for context
+
+## Expected Outputs
+- docs/vision.md — updated with approved strategic innovations
+
+## Quality Criteria
+- Innovations are strategic-level, not feature-level
+- (mvp) Each innovation categorized: market opportunity, positioning, AI-native, ecosystem, or contrarian
+- (mvp) Each innovation includes: what to change, why, impact (high/medium/low), cost estimate
+- (mvp) Each suggestion has an implementation cost estimate (trivial/moderate/significant)
+- (mvp) Recommended disposition stated for each: must-have, backlog, or reject with rationale
+- (deep) Impact assessments compared to existing document content
+- (deep) Each approved innovation is integrated with the same subsection headings and detail level as existing vision sections
+- Vision scope is respected — no uncontrolled strategic drift
+- User approval is obtained before modifying the vision document
+
+## Methodology Scaling
+- **deep**: Full innovation pass across all 5 dimensions. Competitive research
+  via web search. Detailed integration of approved innovations into vision.
+- **mvp**: Not applicable — this step is conditional and skipped in MVP.
+- **custom:depth(1-5)**: Depth 1-2: Quick scan only — identify 1-2 high-impact
+  strategic angles with brief rationale. Depth 3: quick scan for positioning
+  gaps and obvious market opportunities. Depth 4-5: full innovation pass
+  across all 5 dimensions.
+
+## Conditional Evaluation
+Enable when: project has competitive landscape content in vision.md, user
+explicitly requests a strategic innovation pass, or the vision review
+(review-vision) identifies strategic gaps or weak positioning. Skip when:
+vision is minimal/exploratory, depth < 3, or user explicitly declines innovation.
+
+## Mode Detection
+If this step has been run before (tracking comment
+`<!-- scaffold:innovate-vision -->` exists in docs/vision.md), this is a
+re-innovation pass. Focus on new opportunities from vision changes since last run.
+
+## Update Mode Specifics
+- **Detect prior artifact**: `<!-- scaffold:innovate-vision -->` tracking
+  comment in docs/vision.md
+- **Preserve**: Previously accepted strategic decisions, positioning choices
+  approved by user
+- **Triggers for update**: Vision strategy changed, new market data available,
+  user requests re-evaluation
+- **Conflict resolution**: if a previously rejected strategic angle is now
+  relevant due to vision changes, re-propose with updated rationale
+
+## Instructions
+
+Deeply research docs/vision.md and identify strategic innovation opportunities
+across 5 dimensions. This is the last chance to strengthen the vision before
+it drives the PRD and everything downstream.
+
+### Dimension 1: Market Opportunity Expansion
+
+Research adjacent opportunities:
+- Adjacent markets or segments not currently addressed
+- Underserved niches within the target audience
+- Timing advantages (regulatory changes, technology shifts, cultural moments)
+- Platform or ecosystem opportunities that could amplify reach
+- Geographic or demographic expansion possibilities
+
+### Dimension 2: Positioning Alternatives
+
+Explore how the product could be positioned differently:
+- Could the product be positioned differently for greater impact?
+- Alternative framings of the value proposition
+- Category creation vs category competition — which is the stronger play?
+- Messaging angles that haven't been explored
+- What would a "10x better positioning" look like?
+
+### Dimension 3: AI-Native Rethinking
+
+If this product were conceived today with AI capabilities assumed:
+- What changes fundamentally about the product concept?
+- Features that become trivial with AI (and therefore table stakes)
+- Experiences that become possible that were previously impractical
+- Intelligence that can be embedded vs bolted on
+- How does AI change the competitive landscape for this product?
+
+### Dimension 4: Ecosystem Thinking
+
+Explore how the product fits into a broader ecosystem:
+- Partners and integrations that amplify the product's value
+- Platform effects or network effects available
+- Data advantages that compound over time
+- Build vs buy vs partner decisions at the strategic level
+- Community or marketplace opportunities
+
+### Dimension 5: Contrarian Bets
+
+Challenge the vision's assumptions:
+- What does the vision assume that most people agree with? What if the opposite were true?
+- Industry orthodoxies worth challenging
+- One genuinely contrarian strategic angle, evaluated honestly
+- "What would we do differently if we believed X?"
+- Which assumptions, if wrong, would invalidate the entire vision?
+
+### For Each Innovation Idea, Present:
+- **What**: The strategic innovation
+- **Why**: Strategic rationale and market context
+- **Impact**: How much better the product positioning gets (high / medium / low)
+- **Cost**: Implementation effort (trivial / moderate / significant)
+- **Recommendation**: Must-have for vision, or backlog for future consideration
+
+### Process
+
+1. Research competitive landscape and market trends via web search
+2. Generate innovation ideas across all 5 dimensions
+3. Use AskUserQuestionTool to present innovations grouped by dimension for user approval
+4. For each approved innovation, integrate it into the appropriate section of docs/vision.md
+5. Update tracking comment: add `<!-- scaffold:innovate-vision v1 YYYY-MM-DD -->` after the vision tracking comment
+6. Provide a summary of what was added, modified, or deferred
+
+### Quality Standards
+- Strategic-level only — feature ideas belong in innovate-prd
+- Honest about costs and risks — don't oversell
+- Respect the existing guiding principles — innovations should align, not contradict
+- Do NOT modify the vision statement without explicit user approval
+- Do NOT add approved innovations as vague one-liners — document them to the same standard as existing sections
+
+## After This Step
+
+When this step is complete, tell the user:
+
+---
+**Innovation complete** — `docs/vision.md` updated with approved strategic innovations.
+
+**Next:** Run `/scaffold:create-prd` — Translate the vision into product requirements.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---

package/pipeline/vision/review-vision.md

@@ -0,0 +1,149 @@
+---
+name: review-vision
+description: Multi-pass review of the product vision for clarity, coherence, and downstream readiness
+summary: "Stress-tests the vision across five dimensions — clarity, audience precision, competitive rigor, strategic coherence, and whether the PRD can be written from it without ambiguity — and fixes what it finds."
+phase: "vision"
+order: 020
+dependencies: [create-vision]
+outputs: [docs/reviews/vision-review-vision.md]
+conditional: null
+knowledge-base: [review-methodology, vision-craft, multi-model-review-dispatch, review-step-template, review-vision]
+---
+
+## Purpose
+Deep multi-pass review of the product vision document, targeting the specific
+failure modes of strategic vision artifacts. Identify issues, create a fix plan,
+execute fixes, and re-validate. Ensures the vision is inspiring, coherent,
+strategically sound, and ready for the PRD to consume.
+
+## Inputs
+- docs/vision.md (required) — Vision document to review
+- Project idea or brief (context from user, if available)
+
+## Expected Outputs
+- docs/reviews/vision-review-vision.md — review findings, fix plan, and resolution log
+- docs/vision.md — updated with fixes
+
+## Quality Criteria
+- (mvp) Passes 1 and 5 executed with findings documented
+- All 5 review passes executed with findings documented
+- Every finding categorized by severity (P0-P3)
+- Fix plan created for P0 and P1 findings
+- Fixes applied and re-validated
+- (mvp) Every vision section has content specific enough to derive a PRD without asking strategic clarification questions
+- (depth 4+) Multi-model review findings synthesized with consensus/disagreement analysis
+
+## Methodology Scaling
+- **deep**: All 5 review passes. Full findings report with severity
+  categorization. Fixes applied and re-validated.
+- **mvp**: Passes 1 and 5 only (Vision Clarity and Downstream Readiness).
+  Focus on blocking gaps — is the vision clear enough to write a PRD from?
+- **custom:depth(1-5)**: Depth 1-2: passes 1 and 5 only. Depth 3: passes 1,
+  2, 5 (add Audience Precision). Depth 4: passes 1-3, 5 (add Competitive
+  Rigor). Depth 5: all 5 passes.
+
+## Mode Detection
+If docs/reviews/vision-review-vision.md exists, this is a re-review. Read
+previous findings and focus on whether fixes were applied and any new issues
+introduced.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/reviews/vision-review-vision.md exists
+- **Preserve**: Findings from prior review that are still valid, resolution
+  decisions made by user
+- **Triggers for update**: Vision document changed since last review, user
+  requests re-review after edits
+- **Conflict resolution**: if a previously resolved finding reappears, note
+  it as a regression
+
+## Instructions
+
+Review docs/vision.md using a structured 5-pass approach. Each pass targets
+a specific failure mode of product vision documents.
+
+### Pass 1: Vision Clarity
+
+Evaluate the vision statement and elevator pitch for quality:
+- Is the vision statement inspiring, concise, and memorable?
+- Could someone repeat it from memory after hearing it once?
+- Does it describe positive change in the world, not a product feature?
+- Is it enduring — would it survive a pivot in approach?
+- Apply Roman Pichler's checklist: Inspiring, Shared, Ethical, Concise, Ambitious, Enduring
+- Is the elevator pitch (Geoffrey Moore template) filled in with specific, non-generic language?
+- Does the vision statement pass the "decision test" — could you evaluate a product decision against it?
+
+### Pass 2: Audience Precision
+
+Evaluate whether the target audience is defined well enough for product decisions:
+- Are personas defined by behaviors and motivations, not demographics?
+- Is the primary persona clearly identified and distinct from secondary personas?
+- Could two people read the persona descriptions and agree on design decisions?
+- Are "context of use" descriptions specific enough to inform UX decisions?
+- Is there an implicit "Everything User" persona (contradictory needs)?
+
+### Pass 3: Competitive Rigor
+
+Evaluate the competitive analysis for honesty and completeness:
+- Are direct competitors identified with specific strengths and weaknesses?
+- Are indirect alternatives considered (different approaches to the same problem)?
+- Is the "do nothing" option considered as a competitor?
+- Is differentiation genuine or wishful thinking?
+- Are competitor strengths acknowledged honestly, not dismissed?
+- Is the market gap validated with evidence, not just asserted?
+
+### Pass 4: Strategic Coherence
+
+Evaluate whether the strategic elements hold together:
+- Do guiding principles actually constrain decisions (or are they platitudes)?
+- Would a reasonable team choose the opposite of each principle?
+- Does the anti-vision name specific traps, not just vague disclaimers?
+- Are success criteria measurable and time-bound?
+- Does the business model intuition hold together with the target audience and value proposition?
+- Are strategic risks honest about severity, with actual mitigation thinking?
+- Do all sections tell a consistent story about the same product?
+
+### Pass 5: Downstream Readiness
+
+Evaluate whether the PRD can be written from this vision:
+- Can the PRD's problem statement be derived directly from the Problem Space section?
+- Is the target audience clear enough to write user personas and stories?
+- Are guiding principles concrete enough to inform tech stack and architecture decisions?
+- Is there enough competitive context to differentiate features?
+- Are there unresolved Open Questions that would block product definition?
+- Could an AI agent write a PRD from this vision without asking strategic questions?
+
+### Review Process
+
+1. Execute each pass, documenting findings with severity (P0-P3):
+   - P0: Vision is fundamentally unclear or contradictory — blocks all downstream work
+   - P1: Significant gap that would cause PRD to make wrong assumptions
+   - P2: Minor gap or vagueness that could be improved
+   - P3: Nitpick or style suggestion
+2. Create a fix plan for all P0 and P1 findings
+3. Present the fix plan to the user for approval
+4. Apply approved fixes to docs/vision.md
+5. Re-validate that fixes resolved the issues
+6. Document all findings and resolutions in the review report
+
+### Output Format
+
+Create docs/reviews/vision-review-vision.md with:
+
+| Pass | Finding | Severity | Fix | Status |
+|------|---------|----------|-----|--------|
+| 1 | Vision statement references a feature ("AI-powered...") | P1 | Reframe around positive change | Fixed |
+| ... | ... | ... | ... | ... |
+
+## After This Step
+
+When this step is complete, tell the user:
+
+---
+**Review complete** — `docs/reviews/vision-review-vision.md` created, fixes applied to `docs/vision.md`.
+
+**Next:** Run `/scaffold:innovate-vision` (optional) — Explore strategic innovation opportunities.
+Or skip to: `/scaffold:create-prd` — Start product requirements.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---

package/skills/multi-model-dispatch/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: multi-model-dispatch
+description: Correct patterns for invoking Codex CLI and Gemini CLI as independent reviewers from Claude Code. Covers headless invocation, context bundling, output parsing, dual-model reconciliation, and fallback handling.
+---
+
+# Multi-Model Dispatch
+
+This skill teaches Claude Code how to correctly invoke Codex and Gemini CLIs for independent review of artifacts. Use this whenever a pipeline step needs multi-model validation at depth 4-5.
+
+## When This Skill Activates
+
+- A review or validation step is running at depth 4+ and wants independent model validation
+- User asks to "run multi-model review" or "get a second opinion from Codex/Gemini"
+- The `automated-pr-review` step is using local CLI review mode
+- The `implementation-plan-review` step dispatches to external CLIs at depth 4+
+
+## CLI Detection & Auth Verification
+
+Before attempting any dispatch, detect what's available AND verify authentication. A CLI that's installed but not authenticated is useless in headless mode — it will hang on an interactive auth prompt or fail silently.
+
+### Step 1: Check CLI Installation
+
+```bash
+command -v codex && echo "codex installed" || echo "codex not found"
+command -v gemini && echo "gemini installed" || echo "gemini not found"
+```
+
+### Step 2: Verify Authentication
+
+**CRITICAL: Do not skip this step.** Auth tokens expire mid-session. A CLI that worked 30 minutes ago may fail now.
+
+**CRITICAL: Previous auth failures do NOT exempt subsequent dispatches.** Auth tokens refresh — a CLI that failed auth during user story review may work fine for domain modeling review. Always re-check auth before EACH review step, not once per session.
+
+**Codex auth check** (has a built-in status command):
+```bash
+codex login status 2>/dev/null && echo "codex authenticated" || echo "codex NOT authenticated"
+```
+
+**Gemini auth check** (no built-in status command — use a minimal prompt):
+```bash
+GEMINI_AUTH_CHECK=$(NO_BROWSER=true gemini -p "respond with ok" -o json 2>&1)
+GEMINI_EXIT=$?
+if [ "$GEMINI_EXIT" -eq 0 ]; then
+  echo "gemini authenticated"
+elif [ "$GEMINI_EXIT" -eq 41 ]; then
+  echo "gemini NOT authenticated (exit 41: auth error)"
+else
+  echo "gemini auth unknown (exit $GEMINI_EXIT)"
+fi
+```
+
+**Why `NO_BROWSER=true`?** Gemini CLI relaunches itself as a child process for memory management. During the relaunch, it shows a "Do you want to continue? [Y/n]" consent prompt that hangs when stdin is not a TTY (as in Claude Code's Bash tool). `NO_BROWSER=true` suppresses this prompt and uses cached credentials directly.
+
+### Step 3: Handle Auth Failures
+
+**If a CLI fails auth, do NOT silently fall back.** Instead:
+
+1. **Tell the user** which CLI failed auth and why
+2. **Offer interactive recovery**: Ask the user to run the auth command in their terminal:
+   - **Codex**: `! codex login` (opens browser for OAuth) or set `CODEX_API_KEY` env var
+   - **Gemini**: `! gemini -p "hello"` (triggers OAuth flow) or set `GEMINI_API_KEY` env var
+3. **After recovery**: Re-run the auth check. If it passes, proceed with dispatch.
+4. **If user declines**: Fall back to the other CLI or Claude-only review, but **document the auth failure** in the review summary.
+
+The `!` prefix runs the command in the user's terminal session, allowing interactive auth flows (browser OAuth, Y/n prompts) that can't work in headless mode.
+
+**If neither CLI is available or authenticated**: Fall back to structured Claude-only self-review. Re-read the artifact with an adversarial lens — actively try to find issues the initial review missed. Document this as "single-model review (no external CLIs available)."
+
+## Correct Invocation Patterns
+
+### Codex CLI (`codex exec`)
+
+**CRITICAL: Use `codex exec`, NOT `codex` directly.** The bare `codex` command launches an interactive TUI that requires a TTY and will fail with "stdin is not a terminal" when run from Claude Code.
+
+**CRITICAL: Always include `--skip-git-repo-check`.** Without this flag, Codex fails with "Not inside a trusted directory" when the project hasn't initialized git yet (common early in the pipeline).
+
+```bash
+# Basic review dispatch
+codex exec --skip-git-repo-check -s read-only --ephemeral "REVIEW_PROMPT_HERE" 2>/dev/null
+
+# With specific model and reasoning effort
+codex exec --skip-git-repo-check -m o4-mini -s read-only -c model_reasoning_effort=high --ephemeral "REVIEW_PROMPT_HERE" 2>/dev/null
+
+# Reading prompt from stdin (use - flag)
+echo "$REVIEW_PROMPT" | codex exec --skip-git-repo-check -s read-only --ephemeral - 2>/dev/null
+
+# With JSON schema enforcement
+codex exec --skip-git-repo-check -s read-only --ephemeral --output-schema schema.json "REVIEW_PROMPT_HERE" 2>/dev/null
+```
+
+**Key flags:**
+| Flag | Purpose |
+|------|---------|
+| `exec` | **Required** — headless mode, no TUI, no TTY needed |
+| `--skip-git-repo-check` | **Required** — allows running outside a git repo or untrusted directory |
+| `-s read-only` | Sandbox: reviewer cannot write files (read-only analysis) |
+| `--ephemeral` | Don't persist session (one-shot review) |
+| `2>/dev/null` | Suppress thinking tokens on stderr (keeps Claude Code context clean) |
+| `--output-schema` | Enforce structured JSON output against a schema file |
+| `-c model_reasoning_effort=high` | Increase reasoning depth for complex reviews |
+
+**Output**: Progress streams to stderr (suppressed by `2>/dev/null`). Final answer prints to stdout.
+
+### Gemini CLI (`gemini -p`)
+
+**Use `-p` / `--prompt` for headless mode.** Without this flag, Gemini launches interactive mode.
+
+**CRITICAL: Always prepend `NO_BROWSER=true`.** Without this, Gemini's child process relaunch shows a consent prompt ("Do you want to continue? [Y/n]") that hangs when stdin is not a TTY. This affects ALL non-interactive contexts including Claude Code's Bash tool.
+
+```bash
+# Basic review dispatch
+NO_BROWSER=true gemini -p "REVIEW_PROMPT_HERE" --output-format json --approval-mode yolo 2>/dev/null
+
+# With specific model
+NO_BROWSER=true gemini -p "REVIEW_PROMPT_HERE" -m pro --output-format json --approval-mode yolo 2>/dev/null
+
+# Reading context from stdin
+cat artifact.md | NO_BROWSER=true gemini -p "Review this artifact for issues" --output-format json --approval-mode yolo 2>/dev/null
+
+# With sandbox (no file writes)
+NO_BROWSER=true gemini -p "REVIEW_PROMPT_HERE" --output-format json -s --approval-mode yolo 2>/dev/null
+```
+
+**Key flags:**
+| Flag | Purpose |
+|------|---------|
+| `NO_BROWSER=true` | **Required** — suppresses consent prompt that hangs in non-TTY shells |
+| `-p "prompt"` | **Required** — headless mode, no interactive UI |
+| `--output-format json` | Structured JSON output for parsing |
+| `--approval-mode yolo` | Auto-approve all tool calls (reviewer doesn't need to write) |
+| `-s` | Sandbox mode (extra safety for read-only review) |
+| `-m pro` | Use Gemini Pro model (default is auto) |
+| `2>/dev/null` | Suppress progress output |
+
+**Output**: JSON on stdout with `{ response, stats, error }` structure.
+
+## Context Bundling
+
+When dispatching a review, bundle all relevant context into the prompt. Each CLI gets the same bundle — do NOT share one model's review with the other.
+
+### Template for Artifact Review
+
+```
+You are reviewing a project artifact for quality issues. Focus on P0 (critical) and P1 (high) issues only.
+
+## Severity Definitions
+- P0: Will cause implementation failure, data loss, security vulnerability, or fundamental architectural flaw
+- P1: Will cause bugs in normal usage, inconsistency across documents, or blocks downstream work
+- Do NOT report P2/P3 issues (suggestions, style, minor improvements)
+
+## Review Standards
+[paste contents of docs/review-standards.md if it exists, otherwise use severity definitions above]
+
+## Artifact to Review
+[paste full artifact content]
+
+## Upstream References
+[paste relevant upstream docs: PRD, tech-stack, coding-standards, etc.]
+
+## Output Format
+Respond with a JSON object:
+{
+  "approved": true/false,
+  "findings": [
+    {
+      "severity": "P0" or "P1",
+      "location": "section or line reference",
+      "description": "what's wrong",
+      "suggestion": "specific fix"
+    }
+  ],
+  "summary": "one-line assessment"
+}
+
+If no P0/P1 issues found, respond with: { "approved": true, "findings": [], "summary": "No P0/P1 issues found." }
+```
+
+### Template for PR Diff Review
+
+```
+You are reviewing a pull request diff. Focus on P0 and P1 issues only.
+
+## Review Standards
+[paste docs/review-standards.md]
+
+## Project Coding Standards
+[paste docs/coding-standards.md]
+
+## Test Standards
+[paste docs/tdd-standards.md]
+
+## PR Diff
+[paste output of gh pr diff <number> or git diff origin/main...HEAD]
+
+## Output Format
+[same JSON format as above, but location = file:line]
+```
+
+### Context Size Guidelines
+
+| Artifact Type | Max Context | Strategy |
+|--------------|------------|----------|
+| PRD | Full document | Include entirely |
+| User stories | Full document | Include entirely |
+| Architecture | Full document | Include entirely |
+| Domain models | Directory listing + key files | Summarize index, include 2-3 representative files |
+| PR diff | Full diff | If >2000 lines, split into file groups |
+| Implementation plan | Task list + representative tasks | Include full task list, detail for flagged tasks |
+
+## Dual-Model Reconciliation
+
+When both CLIs produce results, reconcile findings using these rules:
+
+| Scenario | Confidence | Action |
+|----------|-----------|--------|
+| Both flag same issue | **High** | Fix immediately — two independent models agree |
+| Both approve (no findings) | **High** | Proceed confidently |
+| One flags P0, other approves | **High** | Fix it — P0 is critical enough from a single source |
+| One flags P1, other approves | **Medium** | Review the finding carefully before fixing. If the finding is specific and actionable, fix it. If vague, skip. |
+| Models contradict each other | **Low** | Present both findings to the user for adjudication |
+
+**Independence rule**: Never share one model's review output with the other. Each model must review the artifact independently to avoid confirmation bias.
+
+**Round tracking**: For iterative reviews (like PR review loops), track the round number. After 3 fix rounds, merge with a warning and create a follow-up issue for remaining findings.
+
+## Fallback Behavior
+
+| Situation | Fallback |
+|-----------|----------|
+| Neither CLI available | Structured Claude-only adversarial self-review |
+| Codex only | Single-model review with Codex |
+| Gemini only | Single-model review with Gemini |
+| **CLI auth expired** | **Surface to user with recovery command — do NOT silently fall back** |
+| One CLI fails mid-review (non-auth) | Continue with the other; note the failure in summary |
+| Both CLIs fail (non-auth) | Fall back to Claude-only self-review; warn user |
+| CLI output not parseable as JSON | Treat as text, extract findings manually |
+
+**Auth failures are NOT silent fallbacks.** The difference between "CLI not installed" (fall back quietly) and "CLI auth expired" (user action required) is critical. Auth can be fixed in 30 seconds with an interactive command — silently skipping wastes the user's review infrastructure.
+
+## Integration with Review Steps
+
+All review steps can reference this skill at depth 4-5. The pattern is:
+
+1. **Depth 1-3**: Claude-only multi-pass review (step's existing logic)
+2. **Depth 4**: Claude review + single external CLI review (if available)
+3. **Depth 5**: Claude review + dual-model CLI review with reconciliation
+
+Each review step adds a "Multi-Model Validation" section at the end that:
+1. Detects available CLIs
+2. Bundles the artifact + upstream references into a review prompt
+3. Dispatches to available CLIs using the patterns above
+4. Reconciles findings using the dual-model rules
+5. Applies fixes for high-confidence findings
+6. Presents medium/low-confidence findings to the user
+
+## Error Handling
+
+```bash
+# Capture exit code AND stderr separately (don't suppress stderr for error detection)
+CODEX_STDERR=$(mktemp)
+OUTPUT=$(codex exec --skip-git-repo-check -s read-only --ephemeral "prompt" 2>"$CODEX_STDERR") || {
+  EXIT_CODE=$?
+  STDERR_CONTENT=$(cat "$CODEX_STDERR")
+  if echo "$STDERR_CONTENT" | grep -qi "refresh token\|please re-run.*login\|sign in again\|auth"; then
+    echo "Codex auth expired. Ask user to run: ! codex login"
+    # DO NOT silently fall back — surface to user
+  else
+    echo "Codex CLI failed with exit code $EXIT_CODE"
+    # Fall back to Gemini or Claude-only
+  fi
+  rm -f "$CODEX_STDERR"
+}
+
+GEMINI_STDERR=$(mktemp)
+OUTPUT=$(NO_BROWSER=true gemini -p "prompt" --output-format json --approval-mode yolo 2>"$GEMINI_STDERR") || {
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" -eq 41 ]; then
+    echo "Gemini auth failed (exit 41). Ask user to run: ! gemini -p \"hello\""
+    # DO NOT silently fall back — surface to user
+  else
+    echo "Gemini CLI failed with exit code $EXIT_CODE"
+    # Fall back to Codex or Claude-only
+  fi
+  rm -f "$GEMINI_STDERR"
+}
+```
+
+### Exit Codes
+
+**Gemini exit codes:**
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 0 | Success | Parse output |
+| 1 | General error | Fall back to other CLI |
+| **41** | **Auth failure** | **Surface to user — offer `! gemini -p "hello"` recovery** |
+| 42 | Input error | Check prompt format |
+| 52 | Config error | Check `~/.gemini/settings.json` |
+| 53 | Turn limit exceeded | Retry with shorter prompt |
+
+**Codex exit codes:**
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 0 | Success | Parse output |
+| 1 | General failure | Check stderr for auth messages |
+
+Codex uses exit code 1 for all failures. **Check stderr** for auth-specific messages: "refresh token", "please re-run", "sign in again", "ChatGPT account ID not available".
+
+### Auth Recovery Flow
+
+When an auth failure is detected during dispatch (not during pre-flight):
+
+1. Stop the review dispatch immediately
+2. Tell the user: "Gemini/Codex auth has expired. To re-authenticate, run:"
+3. Suggest: `! codex login` or `! gemini -p "hello"` (the `!` prefix runs it interactively)
+4. After the user re-authenticates, re-run the auth check
+5. If auth succeeds, resume the review dispatch from where it stopped
+6. If the user declines, fall back to the other CLI or Claude-only review
+
+## What This Skill Does NOT Do
+
+- Does not install CLIs (user must install `codex` and `gemini` separately)
+- Does not authenticate CLIs — but it **detects auth failures** and guides the user through interactive recovery via `!` prefix commands
+- Does not replace Claude's own review passes — it adds independent validation on top
+- Does not work as an MCP server — it uses Bash tool invocations directly