@zigrivers/scaffold 2.1.1 → 2.28.1

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

package/skills/scaffold-pipeline/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: scaffold-pipeline
+description: Static reference for scaffold pipeline ordering, dependencies, and phase structure. Use ONLY for questions about pipeline design, step ordering, or dependency constraints — NOT for status, progress, or "what's next" queries (those go through scaffold-runner).
+---
+
+# Scaffold Pipeline Reference
+
+This skill is a **static reference** for pipeline ordering and dependency constraints. It does NOT handle status checks, progress queries, or navigation.
+
+**Activation boundary:** If the user asks "where am I?", "what's next?", "pipeline status", or anything about their current progress → **do not use this skill**. The `scaffold-runner` skill handles all status/navigation via the `scaffold` CLI.
+
+Use this skill ONLY when the user asks about:
+- Pipeline design: "what phases are there?", "what's the ordering?"
+- Dependency rules: "what depends on what?", "can I run X before Y?"
+- Step reference: "what commands are in phase 3?", "is design-system optional?"
+
+## Phases
+
+14 phases, each with a slug (used in frontmatter) and display name. Canonical source: `src/types/frontmatter.ts` `PHASES` constant.
+
+| # | Slug | Display Name |
+|---|------|-------------|
+| 1 | `pre` | Product Definition |
+| 2 | `foundation` | Project Foundation |
+| 3 | `environment` | Development Environment |
+| 4 | `integration` | Testing Integration |
+| 5 | `modeling` | Domain Modeling |
+| 6 | `decisions` | Architecture Decisions |
+| 7 | `architecture` | System Architecture |
+| 8 | `specification` | Specifications |
+| 9 | `quality` | Quality Gates |
+| 10 | `parity` | Platform Parity |
+| 11 | `consolidation` | Consolidation |
+| 12 | `planning` | Planning |
+| 13 | `validation` | Validation |
+| 14 | `finalization` | Finalization |
+
+## Pipeline Order
+
+| # | Phase | Command | Notes |
+|---|-------|---------|-------|
+| 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 CLAUDE.md + 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 |
+| 9 | Project Foundation | `/scaffold:project-structure` | References all Phase 2 docs |
+| 10 | Dev Environment | `/scaffold:dev-env-setup` | Creates lint/test/install commands |
+| 11 | Dev Environment | `/scaffold:design-system` | **(optional)** Frontend projects only |
+| 12 | Dev Environment | `/scaffold:git-workflow` | Branching, CI, worktrees, permissions |
+| 12.5 | Dev Environment | `/scaffold:automated-pr-review` | **(optional)** Local CLI or external reviewer |
+| 13 | Dev Environment | `/scaffold:ai-memory-setup` | Modular rules, optional MCP memory + external docs |
+| 14 | Testing Integration | `/scaffold:add-e2e-testing` | **(optional)** Playwright (web) and/or Maestro (mobile) |
+| 15 | Domain Modeling | `/scaffold:domain-modeling` | Entities, aggregates, events, bounded contexts |
+| 16 | Domain Modeling | `/scaffold:review-domain-modeling` | 10-pass domain model review |
+| 17 | Architecture Decisions | `/scaffold:adrs` | Architecture Decision Records |
+| 18 | Architecture Decisions | `/scaffold:review-adrs` | Review for contradictions, missing decisions |
+| 19 | System Architecture | `/scaffold:system-architecture` | Components, data flows, module structure |
+| 20 | System Architecture | `/scaffold:review-architecture` | Coverage gaps, constraint violations |
+| 21 | Specifications | `/scaffold:database-schema` | **(optional)** Tables, indexes, constraints |
+| 22 | Specifications | `/scaffold:review-database` | **(optional)** Schema review |
+| 23 | Specifications | `/scaffold:api-contracts` | **(optional)** Endpoints, error codes, auth |
+| 24 | Specifications | `/scaffold:review-api` | **(optional)** API contracts review |
+| 25 | Specifications | `/scaffold:ux-spec` | **(optional)** Flows, states, accessibility |
+| 26 | Specifications | `/scaffold:review-ux` | **(optional)** UX spec review |
+| 27 | Quality Gates | `/scaffold:review-testing` | Reviews TDD strategy for coverage gaps |
+| 27.5 | Quality Gates | `/scaffold:story-tests` | Tagged test skeletons from user story ACs |
+| 28 | Quality Gates | `/scaffold:create-evals` | Generates eval checks from standards docs |
+| 29 | Quality Gates | `/scaffold:operations` | Deployment, monitoring, incident response |
+| 30 | Quality Gates | `/scaffold:review-operations` | Reviews operations runbook |
+| 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: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 |
+| 39 | Validation | `/scaffold:traceability-matrix` | PRD → Stories → Architecture → Tasks |
+| 40 | Validation | `/scaffold:decision-completeness` | All decisions recorded and justified |
+| 41 | Validation | `/scaffold:critical-path-walkthrough` | End-to-end critical journey trace |
+| 42 | Validation | `/scaffold:implementability-dry-run` | Simulate agent picking up tasks |
+| 43 | Validation | `/scaffold:dependency-graph-validation` | Verify task DAG is acyclic |
+| 44 | Validation | `/scaffold:scope-creep-check` | Specs stay within PRD boundaries |
+| 45 | Finalization | `/scaffold:apply-fixes-and-freeze` | Apply findings, freeze docs |
+| 46 | Finalization | `/scaffold:developer-onboarding-guide` | "Start here" for new devs/agents |
+| 47 | Finalization | `/scaffold:implementation-playbook` | Operational guide for agent execution |
+| 48 | Execution | `/scaffold:single-agent-start` | Single-agent TDD execution loop |
+| 48 | Execution | `/scaffold:multi-agent-start` | Multi-agent — one per worktree |
+
+## Standalone Commands
+
+| Command | When to Use |
+|---------|-------------|
+| `/scaffold:single-agent-resume` | Resume work after a break |
+| `/scaffold:multi-agent-resume` | Resume multi-agent work after a break |
+| `/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:prompt-pipeline` | Show the full pipeline reference |
+| `/scaffold:dashboard` | Open visual pipeline dashboard in browser |
+
+## Execution Model
+
+### Two Parallel Tracks
+
+After Phase 1 (Product Definition), the pipeline splits into **two independent tracks** that can run concurrently. They converge at Phase 12 (Planning).
+
+```
+                           ┌─ Track A: Infrastructure ──────────────────────┐
+                           │                                                │
+Phase 1                    │  Phase 2 (foundation)                          │
+create-prd ─→ review-prd  │    tech-stack → coding-standards → tdd         │
+    ↓                      │                     ↓                          │
+user-stories               │    project-structure → dev-env-setup           │
+    ↓                      │         ↓                                      │
+review-user-stories ──┐    │    git-workflow → claude-md-optimization       │
+                      │    │         ↓              ↓                       │
+                      │    │    ai-memory-setup  workflow-audit              │
+                      │    │                                                │
+                      │    └────────────────────────────────────────────────┘
+                      │
+                      │    ┌─ Track B: Domain & Quality ───────────────────┐
+                      │    │                                                │
+                      └──→ │  Phase 5-8: domain-modeling → adrs →           │
+                           │    system-architecture → specs (DB/API/UX)     │
+                           │                                                │
+                           │  Phase 9: tdd → review-testing → operations    │
+                           │    → security (+ reviews for each)             │
+                           │                                                │
+                           └────────────────────────────────────────────────┘
+                                              ↓
+                              ┌───────────────┴───────────────┐
+                              │   Phase 12: Planning          │
+                              │   (convergence point —        │
+                              │    depends on both tracks)    │
+                              └───────────────┬───────────────┘
+                                              ↓
+                              Phase 13: Validation (7 parallel checks)
+                                              ↓
+                              Phase 14: Finalization → Execution
+```
+
+### How Order Numbers Work
+
+The `order` field is a **tiebreaker**, not a sequence number. Execution order is determined by:
+
+1. **Dependency graph** (primary) — topological sort ensures prerequisites complete first
+2. **Order field** (secondary) — when multiple steps are eligible simultaneously, lower order runs first
+
+Order numbers are **phase-aligned**: Phase N uses orders in the N00 range (Phase 1 = 100s, Phase 2 = 200s, etc.). This makes it easy to identify which phase a step belongs to from its order alone.
+
+### Which Phases Can Run in Parallel
+
+Steps within the same track that don't depend on each other can run in parallel (in separate sessions/worktrees):
+
+- **Track A** and **Track B** are fully independent until Phase 12
+- Within Track B, specification steps (Phase 8) can parallelize: DB schema, API contracts, and UX spec all depend on review-architecture but not each other
+- Validation steps (Phase 13) all depend on implementation-plan-review but not each other — all 7 can run in parallel
+
+## Critical Ordering Constraints
+
+1. **Tech Stack before Coding Standards and TDD** — they reference it
+2. **Dev Setup before Git Workflow** — Git Workflow references lint/test commands
+3. **Git Workflow before AI Memory Setup** — memory rules are extracted from project docs
+4. **User Stories before Domain Modeling** — domain models derive from stories
+5. **Domain Modeling → ADRs → Architecture** — linear chain through modeling phases
+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
+8. **TDD → Review Testing → Operations → Security** — quality gate chain
+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
+
+For all status, progress, and navigation queries, use the `scaffold-runner` skill, which delegates to the `scaffold` CLI:
+
+- `scaffold status` — current pipeline progress
+- `scaffold status --compact` — show only actionable steps (pending/in-progress)
+- `scaffold next` — next eligible steps
+- `scaffold list` — full pipeline with status indicators
+- `scaffold skip <step> [<step2>...] --reason "..."` — skip one or more steps
+- `scaffold reset <step> --force` — reset a step to re-run it