scaffold-runner

name	scaffold-runner
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

This skill provides an intelligent interactive layer between the user and the scaffold CLI. It ensures that decision points embedded in scaffold prompts are surfaced to the user before execution, and manages the full step lifecycle.

When This Skill Activates

• User says "run scaffold ", "scaffold ", or "run the next scaffold step"
• User asks "what's next?", "where am I in the pipeline?", or "scaffold status"
• User asks to run any pipeline step by name (e.g., "create the PRD", "set up testing")
• User asks to run multiple steps: "run all reviews", "run phases 5-8", "finish the pipeline", "run the next 5 steps"
• User asks to re-run groups: "re-run all reviews", "redo quality gates", "re-run from user-stories onward"
• User says "start building", "begin implementation", "run agent", "start agent"
• User asks about tools: "bump version", "create a release", "show version"
• User says "what can I build?" or "what tools are available?"
• Working in a project with a .scaffold/ directory

Core Workflow: Smart Scaffold Execution

When the user wants to run a scaffold step, follow this exact process:

Step 1: Check Eligibility

Run scaffold next to see what's eligible. If the user named a specific step, verify it appears in the eligible list. If it's not eligible, explain which dependencies are blocking it and suggest the eligible steps instead.

scaffold next

Step 2: Preview the Assembled Prompt

Capture the assembled prompt WITHOUT executing it yet:

scaffold run <step> --auto 2>&1

Save the output. This is the full 7-section prompt that includes step instructions, knowledge base content, project context, and methodology guidance. Do not execute the prompt content yet.

Step 3: Extract Decision Points

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 "Use AskUserQuestionTool for these decisions:"

Common decision categories:

• Depth/thoroughness: "depth level", "how thorough", "exhaustive vs focused"
• Strictness: "strict", "moderate", "lenient", "strictness level"
• Optional sections: "include [X]?", "optional", "skip if not needed"
• Architecture choices: "which pattern", "choose between", "select"
• Technology preferences: "framework", "library", "tool choice"
• Scope decisions: "MVP or full", "include [feature]?", "defer or include"

Decision extraction rules:

• 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 "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 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
• Include the default/recommended option based on the project's methodology preset
• Add brief context about the impact of each choice

Example presentation:

Before running this step, I need a few decisions:

1. Architecture depth: Full specification with detailed data flows, or high-level
   component overview? [Full spec (recommended for depth 5) / High-level overview]

2. Include performance benchmarks section? [Yes / No — skip for MVP]

3. Error handling strategy: Custom error classes with codes, or standard
   try/catch with logging? [Custom classes (recommended) / Standard try/catch]

If the assembled prompt has NO decision points (the step is fully automated), skip this step and proceed directly to execution.

Step 5: Execute the Prompt

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 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.

Step 6: Post-Execution

After the step completes:

1. Mark completion — If the step was run via scaffold run, it's auto-tracked. If the prompt was captured with scaffold run --auto and executed manually, mark it complete:

   scaffold complete <step>
   

   Then verify with scaffold status.

2. Show what's next — Run:

   scaffold next
   

3. Offer continuation — Tell the user:

   Step complete. Next eligible: scaffold run <next-step>
   Want me to continue with the next step?
   

Stateless Step Execution

Build phase steps (phase 15) and tools are stateless — they don't track completion state. When executing a stateless step, modify the Smart Scaffold Execution workflow:

Modified Post-Execution (replaces Step 6 for stateless steps)

After executing a stateless step:

1. Skip scaffold complete <step> — stateless steps have no completion state
2. Skip "show what's next" — build steps are always available
3. Instead: Show a brief execution summary and offer to run another build step or tool:

   Step executed. Build phase steps are always available for re-use.
   Run another? single-agent-start | quick-task | new-enhancement | ...
   

Resume Step Visibility

single-agent-resume and multi-agent-resume are conditionally shown — only offer them when evidence of prior agent activity exists:

• Feature branches (e.g., bd-* branches) in git
• In-progress tasks (Beads bd list shows in_progress, or implementation plan tasks marked started)
• Open PRs from previous agent work

If no prior activity is detected, suggest single-agent-start or multi-agent-start instead.

Tool Execution

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

• No eligibility check — tools are always available, regardless of pipeline progress
• No state tracking — tools don't appear in scaffold next or scaffold status
• Argument passthrough — tools support CLI arguments: scaffold run release --dry-run, scaffold run version-bump patch

Tool Execution Flow

1. Skip eligibility — don't run scaffold next to check
2. Preview — scaffold run <tool> --auto 2>&1 (same as pipeline steps)
3. Extract decisions — same process as pipeline steps
4. Execute — follow the assembled prompt faithfully
5. No completion — skip scaffold complete, skip "what's next"

Accessing Tools

• scaffold run <tool-name> — run a specific tool
• 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 CLI review channels (Codex CLI, Gemini CLI, Claude CLI) on tracked local code (committed branch diff + staged + unstaged — no untracked files) before commit or push, plus Superpowers code-reviewer as a complementary 4th channel
scaffold run review-pr	Run all 3 code review channels (Codex CLI, Gemini CLI, Claude CLI) on a PR, plus Superpowers code-reviewer as a complementary 4th channel
scaffold run post-implementation-review	Full codebase review (Codex CLI, Gemini CLI, Superpowers code-reviewer) after an AI agent completes all tasks
scaffold run session-analyzer	Analyze Claude Code session logs for patterns and insights

Display rules:

• 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

Track these preferences within the current session to avoid re-asking:

Preference	Example	How to Track
Default depth	"Use depth 3 for everything"	Remember and apply to all steps
Skip optional steps	"Skip design system, I don't have a frontend"	Batch skip with scaffold skip <step1> <step2> --reason "..."
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.

Pipeline Navigation Commands

Respond to these natural language requests:

User Says	Action
"What's next?" / "Next step"	Run scaffold next, present eligible steps
"Where am I?" / "Pipeline status"	Run scaffold status, present progress summary
"What does X do?"	Run scaffold info <step>, present purpose, summary, and dependencies
"Is X applicable?" / "Do I need X?"	Run scaffold check <step> to detect platform and brownfield status
"Set up memory" / "Configure AI memory" / "Add memory"	Run scaffold run ai-memory-setup — sets up modular rules, optional MCP memory server, and external context
"Set up testing" / "Add Playwright" / "Add Maestro"	Run scaffold run add-e2e-testing — auto-detects web/mobile and configures the right framework(s)
"Run multi-model review" / "Review X with all three models"	Route by target — see Multi-Model Review Routing
"Review stories with other models"	Run scaffold run review-user-stories at depth 5 (multi-model capabilities are built into review-user-stories)
"Skip X"	Run scaffold skip <step> --reason "<user's reason>"
"Skip X, Y, and Z"	Run scaffold skip <step1> <step2> <step3> --reason "<reason>"
"What's left?" / "Show remaining"	Run scaffold status --compact, show only pending/in-progress steps
"Re-run X" / "Redo X" / "Go back to X"	Reset then re-run: scaffold reset <step> --force && scaffold run <step>
"Re-run all reviews" / "Redo quality gates"	Batch re-run — see Batch Execution
"Rework phases 1-5" / "Rework through phase 5"	scaffold rework --through 5 — see Rework Mode
"Continue rework" / "Resume rework"	scaffold rework --resume — see Rework Mode
"Run phases 5-8" / "Run modeling through specs"	Batch run by phase range — see Batch Execution
"Run the next N steps" / "Finish the pipeline"	Batch forward run — see Batch Execution
"Continue the batch" / "Resume"	Resume an interrupted batch from where it stopped
"Mark X as done" / "Complete X"	Run scaffold complete <step> — marks a step as completed when executed outside scaffold run
"Reset X" / "Reset X to pending"	Run scaffold reset <step>, confirm if completed
"Show the full pipeline"	Run scaffold list, present with status indicators
"Open the dashboard"	Run scaffold dashboard
"Switch to MVP" / "Change depth"	Run scaffold init --methodology <preset>
"Start building" / "Begin implementation"	scaffold run single-agent-start
"Start multi-agent" / "Set up agents"	scaffold run multi-agent-start <agent-name>
"Quick task" / "Bug fix" / "Small fix"	scaffold run quick-task <description>
"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?"	Run scaffold list --section tools --format json, render as two-section grouped display — see 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

When the user wants to re-run a completed step (e.g., "re-run the PRD", "redo create-prd", "I want to update my user stories"):

1. Reset the step to pending: Run scaffold reset <step> --force
2. Then run it: Follow the normal Smart Scaffold Execution workflow (preview → extract decisions → ask user → execute)
3. The step will run in update mode — it detects the existing artifact and updates it rather than starting from scratch

This is useful when:

• The user wants to incorporate new requirements into an existing artifact
• A prior step was run at a shallow depth and the user wants to re-run at deeper depth
• The user modified upstream documents and wants downstream steps to reflect changes

Skipping Steps

Single skip: scaffold skip <step> --reason "reason"

Batch skip: scaffold skip <step1> <step2> <step3> --reason "reason"

Use batch skip when the user wants to skip multiple related steps at once (e.g., "skip all the optional testing steps", "I don't have a frontend — skip design-system and add-e2e-testing"). This avoids running the command multiple times and gives a single summary of newly eligible steps.

When the user says "skip" without a reason, still pass --reason with a brief reason inferred from context (e.g., --reason "no frontend", --reason "using external CI"). This aids team visibility in state.json.

If a batch skip partially fails (e.g., one step not found), the CLI skips the valid steps and reports errors for the rest. Exit code 2 indicates partial failure.

Compact Status

When the user asks "what's left?", "show remaining steps", or is deep into the pipeline, use scaffold status --compact instead of the full status view. This:

• Shows a summary line with counts (completed, skipped, pending, in progress)
• Lists only pending and in-progress steps (hides completed/skipped)
• Keeps the output focused on what's actionable

Use the full scaffold status (without --compact) when the user asks for a complete overview or wants to see what was skipped.

Depth-Aware Steps

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: 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 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 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 .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 .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
• Self-skips for backend-only projects with no frontend
• Detects brownfield (existing Playwright config or Maestro flows) and auto-enters update mode

Before running this step, you can use scaffold check add-e2e-testing to preview what it will detect without executing.

Applicability Checking

Use scaffold check <step> to check if a conditional step applies to the current project:

scaffold check add-e2e-testing
# → Applicable: yes | Platform: web | Brownfield: no | Mode: fresh

This is useful when the user asks "Do I need this step?" or when previewing which optional steps apply before running them.

Multi-Model Review Routing

When the user asks for a "multi-model review", "review this with all three models", "run MMR on X", or similar — do not assume the target is a PR. Route based on what the user is pointing at:

Target	Command
GitHub PR (explicit number or current branch's PR)	scaffold run review-pr [<PR#>]
Local uncommitted / staged code, before commit or push	scaffold run review-code
Pending edits to a tracked file (changes since HEAD)	git diff HEAD -- <path> | mmr review --diff - --sync --format json
Current contents of any file (tracked-with-no-changes, untracked, or brand-new)	(diff -u /dev/null <path> || true) | mmr review --diff - --sync --format json
A branch diff against main (or another ref)	mmr review --base <ref> --head <ref> --sync --format json
An existing patch or diff file	mmr review --diff <path.patch> --sync --format json
A diff piped from another command	<cmd> | mmr review --diff - --sync --format json (stdin)
A user-story review specifically at depth 5	scaffold run review-user-stories

If the user's target is ambiguous ("review this with MMR"), ask once which of the above applies — don't default to review-pr just because it's the most common entry point. Doc reviews and uncommitted-work reviews are equally first-class.

Pass --focus "..." to MMR when the user describes what to evaluate (clarity, completeness, security, performance, etc.). See the mmr skill for all input modes and flags.

Note on --diff: the flag requires diff-format content (path to a .patch/.diff file, or - for stdin). To review a regular document or source file, wrap it in a diff first using git diff HEAD -- <path> (tracked) or (diff -u /dev/null <path> || true) (untracked — the || true guard is required because diff exits 1 whenever files differ, which breaks pipelines under set -o pipefail) and pipe the result into mmr review --diff -.

Multi-Model Review at Depth 4-5

All review and validation steps support independent multi-model validation at depth 4-5. Two distinct paths exist — never mix them — pick based on what step is running:

Path A: MMR-backed review (PREFERRED — always use for these steps)

Applies to: scaffold run review-pr, scaffold run review-code, and any pipeline review step that invokes mmr review directly.

• Channel model: three CLIs (Codex + Gemini + Claude) dispatched and reconciled by the MMR CLI; scaffold wrappers add the Superpowers code-reviewer agent as a complementary 4th channel reconciled into the same MMR job via mmr reconcile.
• Note: scaffold run post-implementation-review follows a different channel layout (raw-CLI dispatch of Codex + Gemini + Superpowers, with optional mmr reconcile injection if a prior mmr review job exists). Treat it as its own path — consult content/tools/post-implementation-review.md for specifics.
• Invocation: go through the wrapper (scaffold run …) or call mmr review … directly. Do NOT shell out to codex/gemini/claude yourself for these steps — MMR handles dispatch, parsing, compensating passes, and verdict.
• Auth pre-flight: run mmr config test once per session — it probes all three CLIs and reports status in one call.
• If auth fails for any channel, surface recovery commands to the user: ! codex login, ! gemini -p "hello", or ! claude login. MMR will emit a compensating pass (via claude -p) for each missing external channel, labelled [compensating: Codex-equivalent] / [compensating: Gemini-equivalent]. Maximum achievable verdict in that case is degraded-pass.
• Never silently skip a CLI due to auth failure — surface it to the user.

Path B: Legacy / non-MMR direct dispatch

Applies to: some older depth-5 validation steps and any ad-hoc manual dispatch not routed through MMR. The multi-model-dispatch skill documents the raw invocation patterns:

• Codex: codex exec --skip-git-repo-check -s read-only --ephemeral "prompt" 2>/dev/null (NOT bare codex)
• Gemini: NO_BROWSER=true gemini -p "prompt" --output-format json --approval-mode yolo 2>/dev/null
• Claude CLI: claude -p "prompt" --output-format json 2>/dev/null

NO_BROWSER=true is required for all Gemini invocations from Claude Code's Bash tool. Without it, Gemini's child process relaunch shows a consent prompt that hangs in non-TTY shells.

Auth pre-flight for Path B dispatch:

1. Codex: codex login status
2. Gemini: NO_BROWSER=true gemini -p "respond with ok" -o json (exit 41 = auth failure)
3. Claude CLI: claude -p "respond with ok" (typically uses the active Claude Code session)
4. If any fail: ! codex login, ! gemini -p "hello", or ! claude login (the ! prefix runs it interactively with TTY access).
5. Never silently skip a CLI due to auth failure — surface it to the user.

The runner should surface the depth choice as a decision point for review steps, noting that depth 4-5 enables three-CLI multi-model validation when the CLIs are available.

Batch Execution

When the user asks to run multiple steps at once, the runner resolves the request into an ordered step list and executes them sequentially, continuing autonomously between steps. It only stops when a step produces a blocker that requires human intervention.

Batch Intent Resolution

Map natural language requests to concrete step lists using scaffold status output and phase/name matching:

User Says	Resolution Strategy
"Re-run all reviews"	All steps whose name starts with review- that are completed → reset + re-run each
"Run phases 5-8" / "Run modeling through specification"	All enabled steps in the named phases, in pipeline order
"Run remaining planning steps"	All pending steps in the planning phase
"Run everything from domain-modeling onward"	All enabled steps with pipeline order >= domain-modeling's order
"Run the next 5 steps"	Take the next 5 from scaffold next, execute in order
"Run all pending steps"	Loop: scaffold next → execute → repeat until nothing eligible
"Re-run all of phase 9" / "Redo quality gates"	All steps in the quality phase → reset + re-run each
"Run validation checks"	All steps in the validation phase
"Finish the pipeline"	All remaining pending steps, in dependency order

Phase name reference (for resolving phase-based requests):

Phase Name	Also Known As	Description	Steps
vision	Product Vision	Transforms your idea into a strategic vision document covering who it's for, what makes it different, and what success looks like.	create-vision, review-vision, innovate-vision
pre	Product Definition	Translates your vision into a PRD with features, personas, and success criteria, then breaks it into user stories with testable acceptance criteria.	create-prd, review-prd, innovate-prd, user-stories, review-user-stories, innovate-user-stories
foundation	Project Foundation	Researches and documents technology choices, creates coding standards with linter configs, defines testing strategy, and designs directory layout for parallel agent work.	beads, tech-stack, coding-standards, tdd, project-structure
environment	Dev Environment	Sets up local dev environment, design system (web only), git workflow with CI and worktree scripts, automated PR review, and AI memory persistence.	dev-env-setup, design-system, git-workflow, automated-pr-review, ai-memory-setup
integration	Testing Integration	Auto-detects platform and configures E2E testing — Playwright for web, Maestro for mobile. Skips for backend-only projects.	add-e2e-testing
modeling	Domain Modeling	Identifies core concepts (entities, relationships, invariants, events) and establishes a shared vocabulary across all docs and code.	domain-modeling, review-domain-modeling
decisions	Architecture Decisions	Documents every significant design decision with alternatives considered and consequences, so future contributors know why things are the way they are.	adrs, review-adrs
architecture	System Architecture	Designs the system blueprint — components, data flows, module structure, and extension points that implementation will follow.	system-architecture, review-architecture
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 {{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
build	Build	Stateless execution steps: TDD implementation loop (single/multi-agent), session resume, quick tasks, and new feature enhancements.	single-agent-start, single-agent-resume, multi-agent-start, multi-agent-resume, quick-task, new-enhancement

Resolution Process

1. Get current state: Run scaffold status to see all step statuses
2. Identify target steps: Based on the user's request, build the ordered list:
   • For phase-based: filter by phase name(s), keep pipeline order
   • For name-based: match step names (prefix matching for "all reviews" → review-*)
   • For re-runs: filter to completed steps, plan reset before each
   • For forward runs: filter to pending or eligible steps
3. Check for disabled/skipped steps: Exclude steps that are skipped or disabled by methodology unless the user explicitly names them
4. Check eligibility: For each step, verify dependencies are met. If a step has unmet dependencies AND those dependencies are in the batch list (earlier), it's fine — they'll be completed first. If dependencies are unmet and NOT in the batch, flag it.
5. Present the plan: Show the user what will be executed:

Batch plan: 7 steps to execute sequentially

  1. ○ review-testing (pending → run)
  2. ○ create-evals (pending → run)
  3. ○ operations (pending → run)
  4. ○ review-operations (pending → run)
  5. ○ security (pending → run)
  6. ○ review-security (pending → run)
  7. ✓ review-architecture (completed → reset + re-run)

Session preferences: depth 4, carry forward decisions
Estimated: autonomous execution, stops only on blockers

Proceed? [Yes / Yes, but ask me before each step / Modify list]

6. Get confirmation: Wait for the user to approve the plan before starting execution.

Execution Protocol

For each step in the batch:

A. Pre-Step

1. Report progress: Use the step's summary from scaffold info <step> for context: "Step 3/7: operations — Designs your deployment pipeline, defines monitoring metrics with alert thresholds, and writes incident response procedures."
2. If re-run: Reset the step first: scaffold reset <step> --force
3. Check eligibility: Run scaffold next and verify the step is eligible. If not, report the blocker and either:
   • Wait for user input (if the blocker is external)
   • Skip this step and continue (if the user pre-approved skipping blockers)

B. Execution

4. Capture prompt: scaffold run <step> --auto 2>&1
5. Extract decisions: Scan for decision points (same as single-step workflow)
6. Apply session preferences: If the user already set depth, strictness, or other preferences earlier in the batch (or in session preferences), substitute those answers without re-asking
7. Surface NEW decisions only: If this step has decision points not covered by session preferences, ask the user. Group up to 4 questions per call.
8. Execute the prompt: Follow the assembled prompt faithfully

C. Post-Step

9. Mark completion: scaffold complete <step>
10. Brief status report: One-line summary of what was produced:

    ✓ operations complete — created docs/operations-runbook.md
    

11. Check for issues: If the step surfaced warnings, unresolved questions, or quality concerns — report them briefly but continue to the next step unless they are blockers.

D. Continue or Stop

Continue automatically when:

• Step completed successfully
• Step produced warnings or non-critical issues (report them, keep going)
• Step produced artifacts that downstream steps need (they're on disk now)

Stop and ask the user when:

• Step failed with an error (CLI error, missing file, broken prerequisite)
• Step requires a decision that can't be resolved from session preferences
• Step produced a critical finding that changes the batch plan (e.g., "the PRD is missing a key requirement that affects all downstream work")
• The user asked for "ask me before each step" mode

Decision Carry-Forward

Within a batch, decisions made for early steps carry forward to later steps:

Decision	Scope	How It Carries
Depth level	All steps	"Use depth 4" applies to every step in the batch
Strictness	All review steps	"Be strict" applies to all reviews
Optional sections	Per-step	"Include performance benchmarks" applies only to the step where asked
Technology choices	All steps	"Use PostgreSQL" remembered for all steps that ask about DB
Skip patterns	All steps	"Skip frontend sections" applied wherever relevant

When a new step has a decision point that matches a carried-forward preference, substitute the answer silently. Only surface the decision if it's genuinely new or if context has changed (e.g., a previous step's output contradicts an earlier decision).

Batch Summary

After all steps complete (or the batch is interrupted), present a summary:

Batch complete: 6/7 steps executed

  ✓ review-testing — reviewed TDD strategy (2 findings, both fixed)
  ✓ create-evals — generated 12 eval checks
  ✓ operations — created operations runbook
  ✓ review-operations — reviewed operations (1 P1 finding, fixed)
  ✓ 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"

Next eligible after batch: cross-phase-consistency, traceability-matrix

Resuming an Interrupted Batch

If the batch was interrupted (blocker, user stopped it, session ended), the user can resume:

User Says	Action
"Continue the batch" / "Resume"	Pick up from where the batch stopped, re-check eligibility
"Skip that step and continue"	Skip the blocked step, continue with the next
"Stop the batch"	End batch execution, show summary of what completed
"Restart the batch"	Re-run the entire original batch plan from the beginning

To resume, re-read the batch plan (kept in conversation context) and find the first incomplete step. Check eligibility and continue from there.

Batch + Re-run Patterns

Common batch patterns for re-running groups of steps:

"Re-run all reviews" — Useful when upstream docs changed:

Steps: review-prd, review-user-stories, review-domain-modeling, review-adrs,
       review-architecture, review-database, review-api, review-ux,
       review-testing, review-operations, review-security,
       implementation-plan-review
Action: reset each → re-run in pipeline order
Note: Each runs in update mode (detects existing artifact)

"Re-run from user-stories onward" — Useful when PRD changed significantly:

Steps: All steps with order >= user-stories, filtered to completed/pending
Action: reset completed ones → run all in pipeline order
Warning: This is a large batch — confirm with user

"Run all validation checks" — Useful before implementation:

Steps: cross-phase-consistency, traceability-matrix, decision-completeness,
       critical-path-walkthrough, implementability-dry-run,
       dependency-graph-validation, scope-creep-check
Action: These are independent (no deps between them) — run sequentially
Note: These are quick, low-decision steps — usually fully autonomous

Rework Mode

Rework mode enables systematic re-execution of entire phases for depth improvement or quality cleanup. It uses a persistent session file (.scaffold/rework.json) that survives context resets.

Detection

On activation, check for an active rework session:

cat .scaffold/rework.json 2>/dev/null

If present, enter rework mode automatically and show status: "Active rework: 15/23 steps completed, currently in Phase 3".

Natural Language Triggers

User Says	Action
"rework phases 1-5"	scaffold rework --through 5 → enter rework mode
"rework everything"	scaffold rework (requires --phases or --through flag)
"rework phases 1-3 excluding 2"	scaffold rework --through 3 --exclude 2
"continue rework" / "resume rework"	scaffold rework --resume → continue from where it stopped
"stop rework" / "cancel rework"	scaffold rework --clear
"rework status"	Read .scaffold/rework.json, show progress

Creating a Rework Session

When the user requests a rework:

1. Run scaffold rework --phases <list> --auto --format json (or --through N)
2. The CLI creates .scaffold/rework.json with the execution plan and resets selected steps in state.json
3. Show the plan summary: step count, phases, depth

Executing Rework Steps

For each step in the rework session:

1. Read the current rework session: scaffold rework --resume --format json
2. Identify the next pending step from the session
3. If config.fix is true and step name starts with review-: Add auto-fix instruction

   scaffold run <step> --auto --instructions "Apply fixes directly to the reviewed artifact instead of just listing issues. Summarize what you changed." 2>&1
   

4. Otherwise: Run normally

   scaffold run <step> --auto 2>&1
   

5. Follow the normal Smart Scaffold Execution workflow (preview → extract decisions → execute)
6. After completion:

   scaffold rework --advance <step>    # Update rework session
   scaffold complete <step>             # Update pipeline state
   

Fresh Mode

If the rework config has fresh: true, delete the existing artifact before running the step:

• Read the step's produces paths from the assembled prompt metadata
• Delete those files before executing the step
• The step will run in fresh mode (no existing artifact detected)

Phase Boundary Pauses

When config.auto is false (the default):

• After completing the last step in a phase, pause execution
• Show a phase summary (use the phase description from the reference table for context):

  Phase 1 (Product Definition) complete: 3/3 steps
  Translates your vision into a PRD with features, personas, and success criteria,
  then breaks it into user stories with testable acceptance criteria.
    ✓ create-prd — updated docs/plan.md
    ✓ review-prd — 2 issues found and fixed
    ✓ innovate-prd — added competitive analysis
  
  Next: Phase 2 (Project Foundation) — Researches and documents technology choices,
  creates coding standards with linter configs, defines testing strategy, and designs
  directory layout for parallel agent work.
  
  Continue? [Yes / Stop here]
  

• Wait for user confirmation before proceeding to the next phase

When config.auto is true, skip pauses and continue through all steps.

Completion

When scaffold rework --advance reports all steps done (returns all_done: true in JSON):

1. Show the full rework summary (similar to batch summary)
2. The session file is automatically cleaned up by the CLI
3. Show overall pipeline status via scaffold status

Error Handling

Situation	Response
Step not eligible	Show blocking dependencies. Suggest running them first or skipping with scaffold skip.
scaffold CLI not installed	Tell user: "Install with npm install -g @zigrivers/scaffold"
No .scaffold/ directory	Tell user: "Run scaffold init to initialize this project"
Step fails during execution	Show the error, suggest checking docs/prerequisites, offer to retry
Assembled prompt is empty	The step may not have knowledge entries. Fall back to running the command file directly via /scaffold:<step>
Batch step fails	Report the failure, ask whether to skip and continue or stop the batch
Batch blocker (auth, missing input)	Stop batch, report the issue, offer recovery path, allow "continue batch" after fix

What This Skill Does NOT Do

• Does not bypass the CLI — always runs scaffold run, scaffold next, scaffold status
• 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 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.