@zigrivers/scaffold 2.28.1 → 2.38.0

package/pipeline/vision/review-vision.md

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

package/skills/scaffold-pipeline/SKILL.md

@@ -16,24 +16,26 @@ Use this skill ONLY when the user asks about:
 
 ## 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 |
+16 phases, each with a slug (used in frontmatter) and display name. Canonical source: `src/types/frontmatter.ts` `PHASES` constant.
+
+| # | Slug | Display Name | Description |
+|---|------|-------------|-------------|
+| 0 | `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. |
+| 1 | `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. |
+| 2 | `foundation` | Project Foundation | Researches and documents technology choices, creates coding standards with linter configs, defines testing strategy, and designs directory layout. |
+| 3 | `environment` | Development Environment | Sets up local dev environment, design system (web only), git workflow with CI and worktrees, automated PR review, and AI memory persistence. |
+| 4 | `integration` | Testing Integration | Auto-detects platform and configures E2E testing — Playwright for web, Maestro for mobile. Skips for backend-only. |
+| 5 | `modeling` | Domain Modeling | Identifies core concepts (entities, relationships, invariants, events) and establishes a shared vocabulary across all docs and code. |
+| 6 | `decisions` | Architecture Decisions | Documents every significant design decision with alternatives and consequences, so future contributors know why. |
+| 7 | `architecture` | System Architecture | Designs the system blueprint — components, data flows, module structure, and extension points. |
+| 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 CLAUDE.md 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. |
+| 15 | `build` | Build | Stateless TDD execution: single/multi-agent modes, session resume, quick tasks, and new feature enhancements. |
 
 ## Pipeline Order
 
@@ -93,6 +95,19 @@ Use this skill ONLY when the user asks about:
 | 48 | Execution | `/scaffold:single-agent-start` | Single-agent TDD execution loop |
 | 48 | Execution | `/scaffold:multi-agent-start` | Multi-agent — one per worktree |
 
+### Phase 15 — Build (stateless, on-demand)
+
+6 steps. Available once Phase 14 is complete. These steps are **stateless** — they don't track completion state and are always available for repeated use.
+
+| Order | Step | Description |
+|-------|------|-------------|
+| 1510 | single-agent-start | Start single-agent TDD execution loop |
+| 1520 | single-agent-resume | Resume single-agent work after a break |
+| 1530 | multi-agent-start | Start multi-agent execution loop in a worktree |
+| 1540 | multi-agent-resume | Resume multi-agent work after a break |
+| 1550 | quick-task | Create a focused task for a bug fix, refactor, or small improvement |
+| 1560 | new-enhancement | Add a new feature to an existing project |
+
 ## Standalone Commands
 
 | Command | When to Use |

package/skills/scaffold-runner/SKILL.md

@@ -14,6 +14,9 @@ This skill provides an intelligent interactive layer between the user and the `s
 - 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
@@ -118,6 +121,54 @@ After the step completes:
    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) 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 --tools` — show available tools (when implemented)
+
 ## Session Preferences
 
 Track these preferences within the current session to avoid re-asking:
@@ -140,7 +191,7 @@ Respond to these natural language requests:
 |---|---|
 | "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 and dependencies |
+| "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) |
@@ -150,6 +201,8 @@ Respond to these natural language requests:
 | "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](#batch-execution) |
+| "Rework phases 1-5" / "Rework through phase 5" | `scaffold rework --through 5` — see [Rework Mode](#rework-mode) |
+| "Continue rework" / "Resume rework" | `scaffold rework --resume` — see [Rework Mode](#rework-mode) |
 | "Run phases 5-8" / "Run modeling through specs" | Batch run by phase range — see [Batch Execution](#batch-execution) |
 | "Run the next N steps" / "Finish the pipeline" | Batch forward run — see [Batch Execution](#batch-execution) |
 | "Continue the batch" / "Resume" | Resume an interrupted batch from where it stopped |
@@ -158,6 +211,14 @@ Respond to these natural language requests:
 | "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?" | `scaffold list --tools` |
+| "Show version" | `scaffold run version` |
 
 ### Re-running Steps
 
@@ -275,22 +336,24 @@ Map natural language requests to concrete step lists using `scaffold status` out
 
 **Phase name reference** (for resolving phase-based requests):
 
-| Phase Name | Also Known As | Steps |
-|---|---|---|
-| pre | Product Definition | create-prd, review-prd, innovate-prd, user-stories, review-user-stories, innovate-user-stories |
-| foundation | Project Foundation | beads, tech-stack, coding-standards, tdd, project-structure |
-| environment | Dev Environment | dev-env-setup, design-system, git-workflow, automated-pr-review, ai-memory-setup |
-| integration | Testing Integration | add-e2e-testing |
-| modeling | Domain Modeling | domain-modeling, review-domain-modeling |
-| decisions | Architecture Decisions | adrs, review-adrs |
-| architecture | System Architecture | system-architecture, review-architecture |
-| specification | Specifications | database-schema, review-database, api-contracts, review-api, ux-spec, review-ux |
-| quality | Quality Gates | review-testing, story-tests, create-evals, operations, review-operations, security, review-security |
-| parity | Platform Parity | platform-parity-review |
-| consolidation | Consolidation | claude-md-optimization, workflow-audit |
-| planning | Planning | implementation-plan, implementation-plan-review |
-| validation | Validation | cross-phase-consistency, traceability-matrix, decision-completeness, critical-path-walkthrough, implementability-dry-run, dependency-graph-validation, scope-creep-check |
-| finalization | Finalization | apply-fixes-and-freeze, developer-onboarding-guide, implementation-playbook |
+| 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 CLAUDE.md 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
 
@@ -329,7 +392,7 @@ For each step in the batch:
 
 #### A. Pre-Step
 
-1. **Report progress**: `"Step 3/7: operations — Deployment, monitoring, incident response"`
+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)
@@ -443,6 +506,97 @@ 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:
+
+```bash
+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
+   ```bash
+   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
+   ```bash
+   scaffold run <step> --auto 2>&1
+   ```
+5. Follow the normal Smart Scaffold Execution workflow (preview → extract decisions → execute)
+6. After completion:
+   ```bash
+   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 |