@zigrivers/scaffold 3.1.0 → 3.4.0

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

@@ -0,0 +1,327 @@
+---
+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. Report P0 (critical), P1 (high), and P2 (medium) issues.
+
+## 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
+- P2: Improvement opportunity — style, naming, documentation, minor optimization
+- Do NOT report P3 issues (personal preference, trivial nits)
+
+## 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" or "P2",
+      "location": "section or line reference",
+      "description": "what's wrong",
+      "suggestion": "specific fix"
+    }
+  ],
+  "summary": "one-line assessment"
+}
+
+If no P0/P1/P2 issues found, respond with: { "approved": true, "findings": [], "summary": "No issues found." }
+```
+
+### Template for PR Diff Review
+
+```
+You are reviewing a pull request diff. Report P0, P1, and P2 issues.
+
+## 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

package/{agent-skills → content/skills}/scaffold-pipeline/SKILL.md

@@ -31,7 +31,7 @@ Use this skill ONLY when the user asks about:
 | 8 | `specification` | Specifications | Creates interface specs: database schema with constraints, API contracts with error codes, UX flows with accessibility. Each conditional. |
 | 9 | `quality` | Quality Gates | Reviews testing, generates test skeletons, creates eval checks, designs deployment pipeline, and conducts security review. |
 | 10 | `parity` | Platform Parity | Audits documentation for platform-specific gaps. Skips for single-platform projects. |
-| 11 | `consolidation` | Consolidation | Optimizes AGENTS.md under 200 lines and audits all workflow docs for consistency. |
+| 11 | `consolidation` | Consolidation | Optimizes {{INSTRUCTIONS_FILE}} under 200 lines and audits all workflow docs for consistency. |
 | 12 | `planning` | Planning | Decomposes stories into concrete tasks scoped to ~150 lines and 3 files max, with clear acceptance criteria. |
 | 13 | `validation` | Validation | Seven cross-cutting audits: scope creep, dependency cycles, implementability, traceability, naming drift, broken handoffs, decision completeness. |
 | 14 | `finalization` | Finalization | Applies validation findings, freezes docs, creates onboarding guide, and writes the implementation playbook. |
@@ -41,13 +41,16 @@ Use this skill ONLY when the user asks about:
 
 | # | Phase | Command | Notes |
 |---|-------|---------|-------|
+| 0.1 | Product Vision | `/scaffold:create-vision` | Interactive — requires user input |
+| 0.2 | Product Vision | `/scaffold:review-vision` | Multi-pass vision review |
+| 0.3 | Product Vision | `/scaffold:innovate-vision` | **(optional)** Strategic innovation |
 | 1 | Product Definition | `/scaffold:create-prd` | Interactive — requires user input |
 | 2 | Product Definition | `/scaffold:review-prd` | Multi-pass PRD review |
 | 2.5 | Product Definition | `/scaffold:innovate-prd` | **(optional)** Feature-level innovation |
 | 3 | Product Definition | `/scaffold:user-stories` | Covers every PRD feature |
 | 4 | Product Definition | `/scaffold:review-user-stories` | Multi-pass story review; depth 4+ adds requirements index |
 | 4.5 | Product Definition | `/scaffold:innovate-user-stories` | **(optional)** UX-level enhancements |
-| 5 | Project Foundation | `/scaffold:beads` | **(optional)** Creates AGENTS.md + task tracking |
+| 5 | Project Foundation | `/scaffold:beads` | **(optional)** Creates {{INSTRUCTIONS_FILE}} + task tracking |
 | 6 | Project Foundation | `/scaffold:tech-stack` | Drives all technical decisions |
 | 7 | Project Foundation | `/scaffold:coding-standards` | References tech-stack.md |
 | 8 | Project Foundation | `/scaffold:tdd` | References tech-stack.md + coding-standards.md |
@@ -78,8 +81,8 @@ Use this skill ONLY when the user asks about:
 | 31 | Quality Gates | `/scaffold:security` | Threat model, auth, data protection |
 | 32 | Quality Gates | `/scaffold:review-security` | Reviews security posture |
 | 33 | Platform Parity | `/scaffold:platform-parity-review` | **(optional)** Multi-platform projects |
-| 34 | Consolidation | `/scaffold:Codex-md-optimization` | Run BEFORE workflow-audit |
-| 35 | Consolidation | `/scaffold:workflow-audit` | Run AFTER Codex-md-optimization |
+| 34 | Consolidation | `/scaffold:claude-md-optimization` | Run BEFORE workflow-audit |
+| 35 | Consolidation | `/scaffold:workflow-audit` | Run AFTER claude-md-optimization |
 | 36 | Planning | `/scaffold:implementation-plan` | Creates full task graph |
 | 37 | Planning | `/scaffold:implementation-plan-review` | Second pass for quality + multi-model validation (depth 4+) |
 | 38 | Validation | `/scaffold:cross-phase-consistency` | Naming, assumptions, interfaces |
@@ -117,7 +120,7 @@ Use this skill ONLY when the user asks about:
 | `/scaffold:new-enhancement` | Add a feature to an existing project |
 | `/scaffold:quick-task` | Create a focused task for a bug fix, refactor, or small improvement |
 | `/scaffold:version-bump` | Bump version and update changelog without tagging or releasing |
-| `/scaffold:release` | Create a versioned release with changelog and GitHub release |
+| `/scaffold:release` | Run the target project's release ceremony with changelog generation and project-specific release artifacts |
 | `/scaffold:prompt-pipeline` | Show the full pipeline reference |
 | `/scaffold:dashboard` | Open visual pipeline dashboard in browser |
 
@@ -135,7 +138,7 @@ create-prd ─→ review-prd  │    tech-stack → coding-standards → tdd
     ↓                      │                     ↓                          │
 user-stories               │    project-structure → dev-env-setup           │
     ↓                      │         ↓                                      │
-review-user-stories ──┐    │    git-workflow → Codex-md-optimization       │
+review-user-stories ──┐    │    git-workflow → claude-md-optimization       │
                       │    │         ↓              ↓                       │
                       │    │    ai-memory-setup  workflow-audit              │
                       │    │                                                │
@@ -189,8 +192,11 @@ Steps within the same track that don't depend on each other can run in parallel
 6. **Architecture before Specification** — DB, API, UX specs derive from architecture (can parallelize)
 7. **TDD → Review Testing → Operations → Security** — quality gate chain
 8. **Both tracks converge at Implementation Plan** — depends on tdd, operations, security, AND review-architecture
-9. **All 7 Validation checks before Apply Fixes & Freeze** — freeze requires all findings
-10. **Finalization before Execution** — agents need frozen docs and playbook
+9. **Quality Gates before Consolidation** — consolidation verifies all docs including operations/security
+10. **Claude.md Optimization before Workflow Audit** — optimize first, verify second
+11. **Implementation Plan Review before Validation** — 7 checks run after plan review
+12. **All 7 Validation checks before Apply Fixes & Freeze** — freeze requires all findings
+13. **Finalization before Execution** — agents need frozen docs and playbook
 
 ## Status & Navigation
 

package/{agent-skills → content/skills}/scaffold-runner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scaffold-runner
-description: Interactive wrapper for the scaffold CLI that surfaces decision points, manages pipeline execution, and provides a seamless scaffold workflow inside a host coding agent.
+description: Interactive wrapper for the scaffold CLI that surfaces decision points, manages pipeline execution, and provides a seamless scaffold workflow inside Claude Code.
 ---
 
 # Scaffold Runner
@@ -46,9 +46,9 @@ Save the output. This is the full 7-section prompt that includes step instructio
 Scan the assembled prompt for user-facing questions. Look for these patterns:
 
 **Explicit question markers:**
+- Lines containing `AskUserQuestionTool` or `AskUserQuestion`
 - Lines containing "ask the user" or "ask me"
-- Lines containing a structured question prompt from the host agent
-- Lines that clearly list decision options for the user
+- Lines containing "Use AskUserQuestionTool for these decisions:"
 
 **Common decision categories:**
 - **Depth/thoroughness**: "depth level", "how thorough", "exhaustive vs focused"
@@ -62,11 +62,11 @@ Scan the assembled prompt for user-facing questions. Look for these patterns:
 - Group related questions together (don't ask one at a time)
 - Provide the options mentioned in the prompt text
 - Include your recommendation based on the project context
-- If the prompt says to collect user decisions in a structured list, extract each bullet as a separate question
+- If the prompt says "use AskUserQuestionTool for these decisions:" followed by a bulleted list, extract each bullet as a separate question
 
 ### Step 4: Surface Decisions to the User
 
-Present all extracted decision points to the user using the host agent's interactive question flow. Group them into a single prompt with up to 4 questions. If there are more than 4, batch them into multiple prompts.
+Present all extracted decision points to the user using AskUserQuestion. Group them into a single call with up to 4 questions. If there are more than 4, batch them into multiple calls.
 
 For each decision:
 - Frame it as a clear choice with concrete options
@@ -95,7 +95,7 @@ Now execute the assembled prompt as your working instructions. This means:
 1. Read the assembled prompt output from Step 2
 2. Follow its instructions section by section
 3. Where the prompt says "ask the user about X", substitute the answer from Step 4
-4. Where the prompt asks for user decisions through the host's question flow, use the pre-collected answer instead
+4. Where the prompt says "use AskUserQuestionTool", use the pre-collected answer instead
 5. Perform all file operations, artifact creation, and validation the prompt describes
 
 **Critical: Execute the FULL prompt faithfully.** Don't skip sections, don't summarize, don't take shortcuts. The assembled prompt was carefully constructed with knowledge base content and project context — every section matters.
@@ -148,7 +148,7 @@ If no prior activity is detected, suggest `single-agent-start` or `multi-agent-s
 
 ## Tool Execution
 
-Tools (version-bump, release, version, update, dashboard, prompt-pipeline, session-analyzer, review-pr) are utility commands orthogonal to the pipeline.
+Tools (version-bump, release, version, update, dashboard, prompt-pipeline, session-analyzer, review-code, review-pr, post-implementation-review) are utility commands orthogonal to the pipeline.
 
 ### Differences from Pipeline Steps
 
@@ -167,7 +167,51 @@ Tools (version-bump, release, version, update, dashboard, prompt-pipeline, sessi
 ### Accessing Tools
 
 - `scaffold run <tool-name>` — run a specific tool
-- `scaffold list --tools` — show available tools (when implemented)
+- `scaffold list --section tools` — show available tools (compact)
+- `scaffold list --section tools --verbose` — show with argument hints
+- `scaffold list --section tools --format json` — machine-readable output
+
+## Tool Listing
+
+When the user asks "what tools are available?", "what can I build?", or "show me the tools":
+
+1. Run `scaffold list --section tools --format json`
+2. Parse the JSON: `data.tools.build` (build phase steps) and `data.tools.utility` (utility tools)
+3. Render as two grouped sections:
+
+**Build Phase (Phase 15)**
+> These are stateless pipeline steps — they appear in `scaffold next` once Phase 14 is complete and can be run repeatedly.
+
+| Command | When to Use |
+|---------|-------------|
+| `scaffold run single-agent-start` | Start the autonomous TDD implementation loop — Claude picks up tasks and builds |
+| `scaffold run single-agent-resume` | Resume where you left off after closing Claude Code |
+| `scaffold run multi-agent-start` | Start parallel implementation with multiple agents in worktrees |
+| `scaffold run multi-agent-resume` | Resume parallel agent work after a break |
+| `scaffold run quick-task` | Create a focused task for a bug fix, refactor, or small improvement |
+| `scaffold run new-enhancement` | Add a new feature to an already-scaffolded project |
+
+**Utility Tools**
+> These are orthogonal to the pipeline — usable at any time, not tied to pipeline state.
+
+| Command | When to Use |
+|---------|-------------|
+| `scaffold run version-bump` | Mark a milestone with a version number without the full release ceremony |
+| `scaffold run release` | Run the target project's release ceremony — changelog plus whatever release artifacts that project defines. Supports `--dry-run`, `current`, and `rollback` |
+| `scaffold run version` | Show the current scaffold version |
+| `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 session-analyzer` | Analyze Claude Code session logs for patterns and insights |
+
+**Display rules:**
+- The tool list comes from CLI output (always complete and up-to-date)
+- The "When to Use" column comes from the table above (stable prose)
+- If the CLI returns a tool not in the table above, display it using its `description` field from the CLI output — graceful degradation
+- For verbose detail (`--verbose`), call `scaffold list --section tools --verbose --format json` and add an Arguments column using the `argumentHint` values
 
 ## Session Preferences
 
@@ -180,6 +224,7 @@ Track these preferences within the current session to avoid re-asking:
 | Methodology | "I'm using MVP" | Informs default recommendations |
 | Batch mode | "Run the next 3 steps" | Execute sequentially, surface decisions for each |
 | Compact status | User is mid-pipeline, only cares about remaining work | Default to `scaffold status --compact` |
+| Pre-push review | "Run review-code before committing and pushing" | Remember to insert `scaffold run review-code` before `git push` in build flows |
 
 When the user sets a preference, acknowledge it and apply it to subsequent steps. Don't ask about it again unless the context changes.
 
@@ -217,8 +262,9 @@ Respond to these natural language requests:
 | "New feature" / "Add enhancement" | `scaffold run new-enhancement <description>` |
 | "Bump version" / "Version bump" | `scaffold run version-bump` |
 | "Create release" / "Release" | `scaffold run release` |
-| "What tools are available?" | `scaffold list --tools` |
+| "What tools are available?" | Run `scaffold list --section tools --format json`, render as two-section grouped display — see [Tool Listing](#tool-listing) |
 | "Show version" | `scaffold run version` |
+| "Review local code" / "Review before push" / "Review before committing and pushing" | `scaffold run review-code` |
 | "Review PR" / "Run code review" | `scaffold run review-pr` |
 
 ### Re-running Steps
@@ -261,18 +307,18 @@ Use the full `scaffold status` (without `--compact`) when the user asks for a co
 Some steps behave significantly differently at higher depths. When running these steps, surface the depth choice as a decision point:
 
 **`review-user-stories`** — The review step scales with depth:
-- Depth 1-3: Codex-only multi-pass review (6 review passes)
+- Depth 1-3: Claude-only multi-pass review (6 review passes)
 - Depth 4: Adds requirements index (REQ-xxx IDs) and coverage matrix (coverage.json) for formal PRD traceability
-- Depth 5: Adds multi-model dispatch to Codex/Gemini CLI for independent validation, with graceful fallback to Codex-only enhanced review if CLIs aren't available
+- Depth 5: Adds multi-model dispatch to Codex/Gemini CLI for independent validation, with graceful fallback to Claude-only enhanced review if CLIs aren't available
 
-When running `review-user-stories` at depth 5, check if `codex` or `gemini` CLI is available (`command -v codex`, `command -v gemini`). If neither is available, inform the user that the step will fall back to a Codex-only adversarial self-review — still valuable but less thorough than multi-model review.
+When running `review-user-stories` at depth 5, check if `codex` or `gemini` CLI is available (`command -v codex`, `command -v gemini`). If neither is available, inform the user that the step will fall back to a Claude-only adversarial self-review — still valuable but less thorough than multi-model review.
 
 **`ai-memory-setup`** — Three-tier AI memory configuration:
-- Tier 1 (Modular Rules): Extracts conventions from coding-standards.md, tech-stack.md, git-workflow.md into path-scoped `.Codex/rules/` files. Always recommended.
+- Tier 1 (Modular Rules): Extracts conventions from coding-standards.md, tech-stack.md, git-workflow.md into path-scoped `.claude/rules/` files. Always recommended.
 - Tier 2 (Persistent Memory): Configures MCP Knowledge Graph server (`@modelcontextprotocol/server-memory`), lifecycle hooks (PreCompact, Stop), and decision logging in `docs/decisions/`.
 - Tier 3 (External Context): Adds library documentation server (Context7/Nia/Docfork) to prevent API hallucination. Only relevant for projects with external dependencies.
 
-The step auto-detects installed MCP servers and presents tier choices as decision points. Brownfield detection: if `.Codex/rules/` exists, enters update mode preserving user customizations.
+The step auto-detects installed MCP servers and presents tier choices as decision points. Brownfield detection: if `.claude/rules/` exists, enters update mode preserving user customizations.
 
 **`add-e2e-testing`** — Unified E2E testing step that auto-detects the platform:
 - Reads `docs/tech-stack.md` and `package.json` to determine web (Playwright), mobile (Maestro), or both
@@ -299,7 +345,7 @@ All review and validation steps now support independent multi-model validation a
 - **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`
 
-**`NO_BROWSER=true` is required for all Gemini invocations** from non-interactive host-agent shells. Without it, Gemini's child process relaunch shows a consent prompt that hangs in non-TTY shells.
+**`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.
 
 **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`
@@ -311,7 +357,7 @@ 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 Codex-only adversarial self-review
+4. If neither available, fall back to Claude-only adversarial self-review
 
 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.
 
@@ -350,7 +396,7 @@ Map natural language requests to concrete step lists using `scaffold status` out
 | specification | Specifications | Creates interface specs for each system layer: database schema with constraints, API contracts with endpoints and error codes, UX flows with accessibility. Each conditional. | database-schema, review-database, api-contracts, review-api, ux-spec, review-ux |
 | quality | Quality Gates | Reviews testing strategy, generates test skeletons from acceptance criteria, creates eval checks, designs deployment pipeline, and conducts OWASP security review. | review-testing, story-tests, create-evals, operations, review-operations, security, review-security |
 | parity | Platform Parity | Audits documentation for platform-specific gaps across target platforms. Skips for single-platform projects. | platform-parity-review |
-| consolidation | Consolidation | Optimizes AGENTS.md under 200 lines with critical patterns front-loaded, then audits all workflow docs for consistency. | Codex-md-optimization, workflow-audit |
+| consolidation | Consolidation | Optimizes {{INSTRUCTIONS_FILE}} under 200 lines with critical patterns front-loaded, then audits all workflow docs for consistency. | claude-md-optimization, workflow-audit |
 | planning | Planning | Decomposes stories and architecture into concrete tasks scoped to ~150 lines of code and 3 files max, with clear acceptance criteria. | implementation-plan, implementation-plan-review |
 | validation | Validation | Seven cross-cutting audits catching scope creep, dependency cycles, implementability ambiguities, traceability gaps, naming drift, and broken handoffs. | cross-phase-consistency, traceability-matrix, decision-completeness, critical-path-walkthrough, implementability-dry-run, dependency-graph-validation, scope-creep-check |
 | finalization | Finalization | Applies validation findings, freezes docs, creates developer onboarding guide, and writes the implementation playbook agents follow during every coding session. | apply-fixes-and-freeze, developer-onboarding-guide, implementation-playbook |
@@ -457,7 +503,6 @@ Batch complete: 6/7 steps executed
   ✓ security — created security review
   ✗ review-security — STOPPED: Codex CLI auth expired (needs: ! codex login)
   ○ review-architecture — not reached
-```
 
 Issues requiring attention:
   1. review-security blocked on Codex auth — run `! codex login` to fix, then "continue batch"
@@ -617,5 +662,5 @@ When `scaffold rework --advance` reports all steps done (returns `all_done: true
 - **Does not modify .scaffold/config.json** — reads only (unless user explicitly asks to change methodology)
 - **Does not invent pipeline steps** — the pipeline defines what runs; this skill executes it
 - **Does not suppress questions** — every decision point gets surfaced. Silent defaults defeat the purpose.
-- **Does not cache preferences across sessions** — each host-agent session starts fresh
+- **Does not cache preferences across sessions** — each Claude Code session starts fresh
 - **Does not run steps in parallel** — batch execution is always sequential (one step at a time per ADR-021). Parallel execution is for the implementation phase via separate worktrees.

package/{tools → content/tools}/post-implementation-review.md

@@ -34,7 +34,7 @@ The three channels are:
 - `docs/user-stories.md` (required) — user stories with acceptance criteria; organizing manifest for Phase 2
 - `docs/implementation-plan.md` (optional) — implementation tasks; used to cross-check that all planned deliverables were built
 - `docs/coding-standards.md` (required) — coding conventions for review context
-- `docs/architecture.md` (optional) — used for architecture alignment checks
+- `docs/system-architecture.md` (optional) — used for architecture alignment checks
 - `docs/adrs/` (optional) — architecture decision records for alignment checks
 - `docs/tdd-standards.md` (optional) — test coverage expectations
 - `docs/review-standards.md` (optional) — severity definitions and review criteria
@@ -120,7 +120,7 @@ find . -type f \
 
 **Read architecture docs (if present):**
 
-Read `docs/architecture.md` if it exists. Read all files in `docs/adrs/` if
+Read `docs/system-architecture.md` if it exists. Read all files in `docs/adrs/` if
 the directory exists. Combine into a single architecture context string. If
 neither exists, use an empty string and note "Architecture docs not found."
 

package/{tools → content/tools}/prompt-pipeline.md

@@ -30,6 +30,13 @@ Print the following reference directly. Do not read any files or run any command
 | Install Beads | `npm install -g @beads/bd` or `brew install beads` **(optional)** |
 | Install Playwright MCP | `claude mcp add playwright npx @playwright/mcp@latest` **(optional — web apps only)** |
 
+### Phase 0 — Product Vision (`vision`)
+| # | Prompt | Command | Notes |
+|---|--------|---------|-------|
+| 0.1 | **Product Vision** | `/scaffold:create-vision` | Interactive — requires user input |
+| 0.2 | **Review Vision** | `/scaffold:review-vision` | Multi-pass vision review |
+| 0.3 | **Innovate Vision** | `/scaffold:innovate-vision` | **(optional)** Strategic innovation |
+
 ### Phase 1 — Product Definition (`pre`)
 | # | Prompt | Command | Notes |
 |---|--------|---------|-------|

package/dist/cli/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,OAAO,CAAA;AAKhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAgBzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzD,MAAM,WAAW,SAAS;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,UAAU,eAAe;IACvB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,QAAA,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAoBnE,CAAA;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAwMrG;AAED,eAAe,YAAY,CAAA"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,OAAO,CAAA;AAKhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAgBzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzD,MAAM,WAAW,SAAS;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,UAAU,eAAe;IACvB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,QAAA,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAoBnE,CAAA;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAwNrG;AAED,eAAe,YAAY,CAAA"}