@zigrivers/scaffold 2.38.1 → 2.44.2

package/knowledge/tools/post-implementation-review-methodology.md

@@ -0,0 +1,107 @@
+---
+name: post-implementation-review-methodology
+description: Two-phase whole-codebase review methodology for post-implementation quality validation
+topics: [review, code-review, multi-model, post-implementation, methodology]
+---
+
+# Post-Implementation Review Methodology
+
+A systematic approach for reviewing an entire scaffold-generated codebase after
+an AI agent has completed all implementation tasks. Differs from PR review in
+that it covers the full codebase against requirements, not just a diff.
+
+## Summary
+
+Post-implementation review is a whole-codebase quality validation that runs after all implementation tasks are complete. It uses two sequential phases — a cross-cutting systemic sweep followed by a parallel user-story review — because cross-cutting issues (security, error handling, architecture alignment) must be identified and framed before diving into feature-level requirement satisfaction. Running cross-cutting first sets the context for every downstream fix.
+
+## Deep Guidance
+
+## Why Two Phases
+
+Cross-cutting issues — security architecture, error handling patterns, test
+coverage gaps — must be identified before diving into feature-level review.
+Fixing a systemic security pattern affects how you write feature-level fixes.
+Running cross-cutting first sets the frame for everything that follows.
+
+Phase 1 catches what story-level review misses (systemic problems).
+Phase 2 catches what cross-cutting review misses (requirement satisfaction gaps).
+
+## Phase 1: Cross-Cutting Sweep
+
+Review the whole codebase for systemic concerns:
+
+| Category | What to Check |
+|----------|---------------|
+| Architecture alignment | Does code match architecture docs and ADRs? Are layers respected? |
+| Security | Auth, input validation, secrets in code, OWASP Top 10 |
+| Error handling | Consistent patterns? Errors swallowed silently? |
+| Test coverage | Critical paths tested? Obvious gaps in high-risk code? |
+| Complexity | Over-engineered areas, dead code, unnecessary abstractions |
+| Dependencies | Unused deps, obviously outdated packages |
+
+### Context Bundle for CLI Channels
+
+Codex and Gemini cannot read files directly. Build a context bundle:
+
+1. Full file tree (excluding node_modules, .git, dist, build, coverage)
+2. Architecture docs (docs/architecture.md, docs/adrs/*.md if present)
+3. Coding standards (docs/coding-standards.md)
+4. Up to 15 strategically selected files:
+   - Entry points (main.*, index.*, app.*, server.* at root/src level)
+   - Core services (src/services/, src/lib/, src/core/)
+   - Auth layer (files with auth, login, session, token in name/path)
+   - Database layer (files with db, model, schema, migration in name/path)
+   - 2-3 test files from different areas
+
+Superpowers code-reviewer subagent has full tool access and reads files
+directly — no bundling needed.
+
+## Phase 2: Parallel User Story Review
+
+Use docs/user-stories.md as the organizing manifest. For each story:
+
+1. Parse the story title, description, and acceptance criteria
+2. Map the story to relevant code files:
+   - Read acceptance criteria for domain keywords
+   - Match keywords to file/directory names in the codebase
+   - Include files from the same module as matched files
+   - When uncertain, include more files rather than fewer
+3. Dispatch a parallel subagent per story (or thematic group for small projects)
+4. Each subagent runs all three channels independently on its story's files
+
+### Grouping Rules
+
+- **Small project (fewer than 5 stories):** Group into 2-3 thematic batches
+- **Normal (5-20 stories):** One subagent per story
+- **Large story (maps to more than 20 files):** The subagent splits its review
+  by layer (backend files first, frontend second) within a single subagent
+
+## Phase 3: Finding Consolidation & Fix Execution
+
+1. Flatten all findings from all channels across both phases into one list
+2. Deduplicate: same `file` + matching issue type/description = one finding;
+   record all source channels in a `sources` array
+3. Multi-source (2+ channels): tag as `high_confidence: true`
+4. Sort: P0 → P1 → P2 → P3
+5. P3 findings go into the report but NOT into the fix queue
+
+## Update Mode
+
+When docs/reviews/post-implementation-review.md already exists and
+--report-only is not set:
+
+- Load prior findings directly — skip Phase 1 and Phase 2
+- Surface previously-unresolved findings (those in "Remaining Findings") to
+  the user immediately before starting fix execution
+- Only retry a previously-failed finding if the user explicitly says to
+
+This shortcut is safe because the user ran --report-only first to validate
+the findings before approving fix execution.
+
+## Fix Execution Rules
+
+- Fix high-confidence (multi-source) findings first within each severity tier
+- Verify immediately after each fix (run relevant tests)
+- 3-round limit per finding before surfacing to user for direction
+- After all fixes: run Superpowers code-reviewer on modified files only
+- Full 3-channel re-review only if the Superpowers pass finds new P0/P1 findings

package/knowledge/validation/critical-path-analysis.md

@@ -8,6 +8,19 @@ topics: [validation, critical-path, user-journeys, end-to-end, gap-analysis]
 
 Critical path analysis walks through the most important user journeys end-to-end across every specification artifact. For each journey, it verifies that every component, endpoint, query, screen, and task needed to make the journey work actually exists and is consistent.
 
+## Summary
+
+- **Critical paths** are user journeys representing core functionality — the features that, if broken, would make the product unusable or fail its primary value proposition.
+- **Sources for identifying journeys**: PRD success criteria, user stories, personas, architecture data flows, and revenue/value paths.
+- **Trace 5-10 journeys** per project; more than 15 suggests scope is too broad or granularity too fine.
+- **Four-step tracing process**: define the journey steps, map each step to specification artifacts (UX, API, architecture, data, tasks), check each mapping for existence/completeness/connectivity/error handling, and identify gaps.
+- **Gap types**: missing components, missing endpoints, missing queries, missing screens, missing tasks, broken connections between steps, and missing error paths.
+- **Common gap patterns**: handoff gaps at bounded-context boundaries, state transition gaps for entity lifecycle, async gaps for background processing, first-time user gaps for empty states, and permission gaps for authorization.
+- **Output**: a summary table of all journeys with gap counts and assessments, plus detailed findings with impact analysis and recommended fixes.
+- **When to run**: after all pipeline steps are complete, before implementation tasks are finalized, when PRD changes significantly, and as a final check before freezing docs.
+
+## Deep Guidance
+
 ## What a Critical Path Is
 
 A critical path is a user journey that represents core functionality — the features that, if broken, would make the product unusable or fail its primary value proposition. These are not edge cases. They are the main flows that most users will execute most of the time.

package/knowledge/validation/implementability-review.md

@@ -8,6 +8,20 @@ topics: [validation, implementability, ambiguity, agent-readiness, dry-run]
 
 An implementability review reads every specification as if you were an AI agent about to implement it. For each task, the question is: "Do I have everything I need to start coding right now?" Every question you would need to ask is a gap. Every ambiguity you would need to resolve is a defect. This is the most practical validation — it tests whether the specs actually work for their intended consumer.
 
+## Summary
+
+- **Core question per task**: "Do I have everything I need to start coding right now?" — every unanswered question is a gap, every ambiguity is a defect.
+- **Agent constraints to account for**: no institutional memory, no ability to ask clarifying questions, literal interpretation of specs, context window limits, and no ability to infer patterns from existing code.
+- **Five check dimensions**: task-level completeness (inputs, outputs, scope, dependencies), ambiguity detection, error case coverage, data shape precision, and pattern/convention specification.
+- **Ambiguity patterns**: vague adjectives ("fast", "secure", "appropriate"), missing specifics (pagination, notification channels, log levels), and implicit behavior (auth redirects, i18n fallbacks, cache invalidation).
+- **Error cases to verify**: input validation, business logic violations, infrastructure failures, and concurrency conflicts — each needing defined response format, retry behavior, user feedback, and logging level.
+- **Data shape precision**: types beyond primitives (email vs. free text), optional vs. nullable distinction, exhaustive enum values, and format standards (dates, money, IDs).
+- **Review method**: role-play as the implementing agent, read only what the task references, attempt pseudocode, and record every question or assumption.
+- **Scoring**: 5/5 (fully implementable) to 1/5 (not implementable); target all tasks at 4/5+ before implementation begins.
+- **Most frequently missing**: error response formats, logging conventions, edge-case validation rules, concurrency handling, and empty-state behavior.
+
+## Deep Guidance
+
 ## The Implementing Agent Perspective
 
 AI agents implementing tasks have specific constraints that make implementability review different from a human code review:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zigrivers/scaffold",
-  "version": "2.38.1",
+  "version": "2.44.2",
   "description": "AI-powered software project scaffolding pipeline",
   "type": "module",
   "keywords": [
@@ -24,6 +24,7 @@
   "files": [
     "dist/",
     "pipeline/",
+    "tools/",
     "knowledge/",
     "methodology/",
     "skills/",

package/pipeline/architecture/review-architecture.md

@@ -40,9 +40,9 @@ independent review validation.
 - (deep) Data flow completeness verified (no orphaned components)
 - (deep) Module structure assessed for merge conflict risk, circular dependency risk, and import depth
 - (mvp) Downstream readiness confirmed (specification, quality, and planning steps can proceed)
-- (mvp) Every finding categorized P0-P3 with specific component, section, and issue
+- (mvp) Every finding categorized P0-P3 with specific component, section, and issue. Severity definitions: P0 = Breaks downstream work. P1 = Prevents quality milestone. P2 = Known tech debt. P3 = Polish.
 - (mvp) Fix plan documented for all P0/P1 findings; fixes applied to system-architecture.md and re-validated
-- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
+- (depth 4+) Multi-model findings synthesized: Consensus (all models agree), Majority (2+ models agree), or Divergent (models disagree — present to user for decision)
 
 ## Methodology Scaling
 - **deep**: All 10 review passes (coverage, constraints, data flows, module
@@ -51,9 +51,12 @@ independent review validation.
   review dispatched to Codex and Gemini if available, with graceful fallback
   to Claude-only enhanced review.
 - **mvp**: Domain coverage and ADR compliance checks only.
-- **custom:depth(1-5)**: Depth 1-3: scale number of passes with depth.
-  Depth 4: all passes + one external model (if CLI available). Depth 5:
-  all passes + multi-model with reconciliation.
+- **custom:depth(1-5)**:
+  - Depth 1: two passes — domain coverage and ADR compliance only.
+  - Depth 2: four passes — domain coverage, ADR compliance, data flow completeness, and internal consistency.
+  - Depth 3: seven passes — add module structure, state consistency, and diagram integrity.
+  - Depth 4: all 10 passes + one external model (if CLI available).
+  - Depth 5: all 10 passes + multi-model with reconciliation.
 
 ## Mode Detection
 Re-review mode if previous review exists. If multi-model review artifacts exist

package/pipeline/architecture/system-architecture.md

@@ -32,7 +32,9 @@ lives and how components communicate.
 - (mvp) Every ADR constraint is respected in the architecture
 - (mvp) All components appear in at least one data flow diagram
 - (deep) Each extension point has interface definition, example usage scenario, and constraints on what can/cannot be extended
-- (mvp) Project directory structure is defined with file-level granularity
+- (mvp) System components map to modules defined in docs/project-structure.md
+- (deep) Component diagram shows all system components from domain models plus infrastructure
+- (deep) Data flow diagrams cover all happy-path user journeys from Must-have stories
 
 ## Methodology Scaling
 - **deep**: Full architecture document. Component diagrams, data flow diagrams,
@@ -40,8 +42,12 @@ lives and how components communicate.
   point inventory, deployment topology.
 - **mvp**: High-level component overview. Key data flows. Enough structure for
   an agent to start building without ambiguity.
-- **custom:depth(1-5)**: Depth 1-2: MVP-style. Depth 3: add component diagrams
-  and module boundaries. Depth 4-5: full architecture approach.
+- **custom:depth(1-5)**:
+  - Depth 1: high-level component overview with key data flows.
+  - Depth 2: component overview with module boundaries and primary data flows.
+  - Depth 3: add component diagrams, module boundaries, and state management design.
+  - Depth 4: full architecture with extension point inventory, deployment topology, and file-level module detail.
+  - Depth 5: full architecture with cross-cutting concern analysis, failure mode documentation, and scalability annotations.
 
 ## Mode Detection
 If outputs already exist, operate in update mode: read existing content, diff

package/pipeline/build/multi-agent-resume.md

@@ -55,10 +55,12 @@ loop from where the agent left off.
   eval gates, detailed PR descriptions, between-task cleanup.
 - **mvp**: Verify worktree, check branch state, finish in-progress work or
   pick next task, TDD loop, make check, create PR.
-- **custom:depth(1-5)**: Depth 1-2: check branch and continue. Depth 3: add
-  PR reconciliation, lessons.md review, sync with origin. Depth 4: add
-  rebase, eval gates, between-task cleanup. Depth 5: full state audit with
-  actor verification and branch cleanup.
+- **custom:depth(1-5)**:
+  - Depth 1: verify worktree and check current branch, continue in-progress work.
+  - Depth 2: add git status assessment and Beads identity verification.
+  - Depth 3: add PR reconciliation, lessons.md review, sync with origin.
+  - Depth 4: add rebase, eval gates, between-task cleanup.
+  - Depth 5: full state audit with actor verification and branch cleanup.
 
 ## Mode Detection
 This is a stateless execution command. No document is created or updated.
@@ -166,11 +168,22 @@ Once in-progress work is complete (or if there was none):
    - Create a pull request: `gh pr create`
    - Include agent name in PR description for traceability
 
-3. **Between-task cleanup**
+3. **Run code reviews (MANDATORY)**
+   - Run the review-pr tool: `scaffold run review-pr` (CLI) or `/scaffold:review-pr` (plugin)
+   - This runs **all three** review channels on the PR diff:
+     1. **Codex CLI**: `codex exec --skip-git-repo-check -s read-only --ephemeral "REVIEW_PROMPT" 2>/dev/null`
+     2. **Gemini CLI**: `NO_BROWSER=true gemini -p "REVIEW_PROMPT" --output-format json --approval-mode yolo 2>/dev/null`
+     3. **Superpowers code-reviewer**: dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
+   - Verify auth before each CLI (`codex login status`, `NO_BROWSER=true gemini -p "respond with ok" -o json`)
+   - All three channels must execute (skip only if a tool is genuinely not installed)
+   - Fix any P0/P1/P2 findings before proceeding
+   - Do NOT move to the next task until all channels have run
+
+4. **Between-task cleanup**
    - `git fetch origin --prune && git clean -fd`
    - Run the install command from CLAUDE.md Key Commands
 
-4. **Claim next task**
+5. **Claim next task**
    - Branch from remote: `git fetch origin && git checkout -b <branch-name> origin/main`
    - Pick the next task following the same process as `/scaffold:multi-agent-start`
    - Continue the TDD execution loop
@@ -217,7 +230,8 @@ Once in-progress work is complete (or if there was none):
 4. **Clean between tasks** — Run cleanup after each task to prevent state leakage.
 5. **TDD is not optional** — Continue the red-green-refactor cycle for any in-progress work.
 6. **Quality gates before PR** — Never create a PR with failing checks.
-7. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
+7. **Code review before next task** — After creating a PR, run all three review channels (Codex CLI, Gemini CLI, Superpowers code-reviewer) and fix all P0/P1/P2 findings before moving on.
+8. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
 
 ---
 

package/pipeline/build/multi-agent-start.md

@@ -54,10 +54,12 @@ work on different tasks simultaneously without stepping on each other.
   PR descriptions, between-task cleanup with dependency reinstall.
 - **mvp**: Verify worktree, pick next task, TDD loop, make check, create PR.
   Skip onboarding review and between-task reinstalls if not needed.
-- **custom:depth(1-5)**: Depth 1-2: verify worktree, TDD loop, make check.
-  Depth 3: add lessons.md review and test skeleton usage. Depth 4: add
-  onboarding guide, eval gates, between-task cleanup. Depth 5: full
-  pre-flight suite, all quality gates, actor verification.
+- **custom:depth(1-5)**:
+  - Depth 1: verify worktree environment, TDD loop, make check.
+  - Depth 2: add dependency check and Beads identity verification.
+  - Depth 3: add lessons.md review and test skeleton usage.
+  - Depth 4: add onboarding guide, eval gates, between-task cleanup.
+  - Depth 5: full pre-flight suite, all quality gates, actor verification.
 
 ## Mode Detection
 This is a stateless execution command. No document is created or updated.
@@ -143,6 +145,7 @@ For each task:
    - If Beads: use `bd-<id>/<desc>` naming
 
 2. **Red phase — write failing tests**
+   - Check `docs/story-tests-map.md` (if it exists) to find test skeletons that correspond to this task's user stories
    - Check `tests/acceptance/` for existing test skeletons that correspond to the task
    - If skeletons exist, use them as your starting point
    - Otherwise, write test cases from the task's acceptance criteria
@@ -169,7 +172,18 @@ For each task:
    - Include in the PR description: what was implemented, key decisions, files changed, agent name
    - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
 
-7. **Between-task cleanup**
+7. **Run code reviews (MANDATORY)**
+   - Run the review-pr tool: `scaffold run review-pr` (CLI) or `/scaffold:review-pr` (plugin)
+   - This runs **all three** review channels on the PR diff:
+     1. **Codex CLI**: `codex exec --skip-git-repo-check -s read-only --ephemeral "REVIEW_PROMPT" 2>/dev/null`
+     2. **Gemini CLI**: `NO_BROWSER=true gemini -p "REVIEW_PROMPT" --output-format json --approval-mode yolo 2>/dev/null`
+     3. **Superpowers code-reviewer**: dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
+   - Verify auth before each CLI (`codex login status`, `NO_BROWSER=true gemini -p "respond with ok" -o json`)
+   - All three channels must execute (skip only if a tool is genuinely not installed)
+   - Fix any P0/P1/P2 findings before proceeding
+   - Do NOT move to the next task until all channels have run
+
+8. **Between-task cleanup**
    - `git fetch origin --prune && git clean -fd`
    - Run the install command from CLAUDE.md Key Commands
    - This ensures a clean state before the next task
@@ -208,8 +222,9 @@ For each task:
 3. **Clean between tasks** — Run cleanup after each task to prevent state leakage.
 4. **TDD is not optional** — Write failing tests before implementation. No exceptions.
 5. **Quality gates before PR** — Never create a PR with failing checks.
-6. **Avoid task conflicts** — Check what other agents are working on before claiming.
-7. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
+6. **Code review before next task** — After creating a PR, run all three review channels (Codex CLI, Gemini CLI, Superpowers code-reviewer) and fix all P0/P1/P2 findings before moving on.
+7. **Avoid task conflicts** — Check what other agents are working on before claiming.
+8. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
 
 ---
 

package/pipeline/build/new-enhancement.md

@@ -10,7 +10,7 @@ conditional: null
 stateless: true
 category: pipeline
 knowledge-base: [enhancement-workflow, task-claiming-strategy]
-reads: [create-prd, user-stories, coding-standards, tdd, project-structure]
+reads: [create-prd, user-stories, coding-standards, tdd, project-structure, system-architecture, domain-modeling, adrs, api-contracts, database-schema, ux-spec, implementation-plan]
 argument-hint: "<enhancement description>"
 ---
 
@@ -31,6 +31,7 @@ This is the full-weight entry point for work that goes beyond a quick fix.
 - docs/design-system.md (optional) — design tokens, component patterns (if frontend changes)
 - CLAUDE.md (required) — project conventions, key commands, workflow
 - .beads/ (conditional) — Beads task tracking if configured
+- docs/implementation-plan.md (required) — existing tasks and task numbering
 - Relevant source code if needed to understand current implementation
 
 ## Expected Outputs
@@ -41,7 +42,7 @@ This is the full-weight entry point for work that goes beyond a quick fix.
 
 ## Quality Criteria
 - (mvp) Impact analysis completed before documentation changes
-- (mvp) PRD feature description is thorough enough for an AI agent to build without follow-up questions
+- (mvp) PRD feature description includes: what the feature does, which persona it serves, at least 2 acceptance criteria, and scope boundary (what it does NOT include)
 - (mvp) User stories follow INVEST criteria
 - (mvp) Acceptance criteria are testable Given/When/Then scenarios
 - (mvp) Task dependencies are identified and documented
@@ -57,15 +58,16 @@ This is the full-weight entry point for work that goes beyond a quick fix.
 - **mvp**: Streamlined discovery, basic impact analysis, PRD feature addition,
   minimal user stories with acceptance criteria, task list with dependencies.
   Skip innovation pass, competitive analysis, and follow-up recommendations.
-- **custom:depth(1-5)**: Depth 1-2: basic impact check, PRD update, stories,
-  task creation. Depth 3: add impact analysis, dependency management, cross-
-  reference check. Depth 4: add innovation pass, frozen artifact handling,
-  migration considerations. Depth 5: full workflow with competitive analysis,
-  AI-native possibilities, and follow-up review recommendations.
+- **custom:depth(1-5)**:
+  - Depth 1: basic PRD feature addition, minimal user stories, task creation.
+  - Depth 2: add impact check and dependency identification.
+  - Depth 3: add detailed impact analysis, dependency management, cross-reference check.
+  - Depth 4: add innovation pass, frozen artifact handling, migration considerations.
+  - Depth 5: full workflow with competitive analysis, AI-native possibilities, and follow-up review recommendations.
 
 ## Mode Detection
-This is a stateless execution command. It updates existing documents (plan.md,
-user-stories.md) but does not create a new standalone output document.
+This is a document-modifying execution command. It updates existing documents
+(plan.md, user-stories.md) in place but does not create a new standalone output.
 - Always operates in ENHANCEMENT MODE.
 - PRD and user stories are updated in place (append, do not replace).
 
@@ -351,7 +353,7 @@ bd ready  # Show what's available to work on now
 #### 7. Consider Follow-Up Reviews
 
 Depending on the enhancement scope, you may want to re-run these prompts:
-- **Implementation Plan Review**: If you created 5+ tasks, run it to verify sizing, dependencies, and coverage
+- **Implementation Plan Review**: If you created 3+ tasks, run it to verify sizing, dependencies, and coverage
 - **Platform Parity Review**: If the enhancement has platform-specific behavior (web vs. mobile differences), re-run to check platform coverage
 - **Workflow Audit**: Only if the enhancement changed project infrastructure or conventions (rare)
 
@@ -425,6 +427,8 @@ This is appropriate when:
 
 ### Phase 5: Version Release
 
+**Note**: Version release should happen after implementation is complete, not after this documentation step. If going straight to implementation, skip to "After This Step" guidance below.
+
 After all changes are applied and verified:
 
 1. Determine release type based on change scope:
@@ -444,11 +448,15 @@ When this step is complete, tell the user:
 **Enhancement documented** — PRD updated, user stories created, tasks ready.
 
 **Next (if applicable):**
-- If `docs/implementation-playbook.md` exists: Run `/scaffold:implementation-playbook` — Update wave assignments and add per-task context blocks for new tasks.
-- If you created **5+ tasks**: Run `/scaffold:implementation-plan-review` — Review task quality, coverage, and dependencies.
+- If `docs/implementation-playbook.md` exists: Run `/scaffold:implementation-playbook` to update wave assignments and add per-task context blocks for new tasks. **This is required** to keep the playbook in sync with the implementation plan.
+- If you created **3+ tasks**: Run `/scaffold:implementation-plan-review` — Review task quality, coverage, and dependencies.
 - If the enhancement has **platform-specific behavior**: Run `/scaffold:platform-parity-review` — Check platform coverage.
 - If user stories were added or changed: Run `/scaffold:story-tests` — Regenerate test skeletons for new user stories.
 - If scope changed materially: Run `/scaffold:create-evals` — Update eval checks for new scope.
+- If impact analysis identified **Data Model changes**: Run `/scaffold:database-schema` to update the schema.
+- If impact analysis identified **API changes**: Run `/scaffold:api-contracts` to update contracts.
+- If impact analysis identified **UI changes**: Run `/scaffold:ux-spec` to update the UX specification.
+- If impact analysis identified **Architecture changes**: Run `/scaffold:system-architecture` to update architecture.
 - Otherwise: Run `/scaffold:single-agent-start` or `/scaffold:single-agent-resume` to begin implementation (or `/scaffold:multi-agent-start <agent-name>` / `/scaffold:multi-agent-resume <agent-name>` for worktree agents).
 
 **Pipeline reference:** `/scaffold:prompt-pipeline`

package/pipeline/build/quick-task.md

@@ -30,6 +30,8 @@ prompt.
 - docs/tdd-standards.md (required) — test categories, mocking strategy, test file locations
 - docs/project-structure.md (required) — where files live, module organization
 - docs/implementation-playbook.md (optional) — quality gates section for project-specific gates
+- docs/system-architecture.md (optional) — for bug fixes involving component boundaries or layer violations
+- docs/domain-models/ (optional) — for bug fixes involving domain logic or entity relationships
 - tasks/lessons.md (optional) — previous lessons learned
 - .beads/ (conditional) — Beads task tracking if configured
 - Relevant source code — files that will be modified
@@ -58,16 +60,18 @@ prompt.
 - **mvp**: Complexity gate, basic acceptance criteria (happy path + one edge
   case), test plan with category and cases, file list. Skip duplicate check
   and detailed implementation notes.
-- **custom:depth(1-5)**: Depth 1-2: complexity gate, basic AC, test cases,
-  file list. Depth 3: add duplicate check, lessons.md review, regression
-  guards. Depth 4: add mocking strategy, specific coding standard references.
-  Depth 5: full analysis with innovation suggestions and cross-module impact.
+- **custom:depth(1-5)**:
+  - Depth 1: complexity gate, basic acceptance criteria (happy path only), and file list.
+  - Depth 2: add one edge case to AC, test cases mapped to criteria, and test file locations.
+  - Depth 3: add duplicate check, lessons.md review, regression guards.
+  - Depth 4: add mocking strategy, specific coding standard references.
+  - Depth 5: full analysis with innovation suggestions and cross-module impact.
 
 ## Mode Detection
-This is a stateless execution command. No persistent document is created.
-- Always operates in CREATE MODE — produces a task definition.
-- If Beads is configured, the task is created via `bd create`.
-- If not, the task is documented inline and implementation begins.
+This is a task-creation execution command. Task persistence depends on context:
+- If Beads is configured, the task is persistent via `bd create`.
+- If not, the task is documented inline for immediate execution (not persistent).
+- Always operates in CREATE MODE — produces a task definition each time.
 
 ## Update Mode Specifics
 Not applicable — this creates a new task each time. If a similar task already
@@ -110,7 +114,7 @@ Before asking questions, review:
 - `docs/coding-standards.md` — Code conventions, naming, patterns
 - `docs/tdd-standards.md` — Test categories, mocking strategy, test file locations
 - `docs/project-structure.md` — Where files live, module organization
-- `tasks/lessons.md` — Previous lessons learned (extract any relevant to this task)
+- `tasks/lessons.md` (if it exists) — Previous lessons learned (extract any relevant to this task)
 - If `docs/implementation-playbook.md` exists, check its quality gates section for project-specific gates
 - Relevant source code — Read the files that will be modified
 
@@ -121,7 +125,7 @@ Before asking questions, review:
 - If proceeding, note the relationship in the new task's description
 
 #### Extract Relevant Lessons
-Review `tasks/lessons.md` for anti-patterns, gotchas, or conventions related to:
+Review `tasks/lessons.md` (if it exists) for anti-patterns, gotchas, or conventions related to:
 - The area of code being modified
 - The type of change (fix, refactor, perf, etc.)
 - Similar past mistakes to avoid
@@ -269,7 +273,7 @@ Present the task summary:
 1. **Respect the complexity gate** — If it is bigger than a quick task, redirect immediately. Do not try to squeeze a feature into the quick task format.
 2. **One task only** — Quick Task creates exactly one Beads task. If you need multiple, use the Enhancement prompt.
 3. **Check for duplicates first** — Run `bd list` before creating. Do not create tasks that already exist.
-4. **Lessons.md is required reading** — Always check `tasks/lessons.md` for relevant anti-patterns before defining the task.
+4. **Lessons.md is required reading** — Always check `tasks/lessons.md` (if it exists) for relevant anti-patterns before defining the task.
 5. **Acceptance criteria drive tests** — Every criterion must map to at least one test case. If you cannot test it, rewrite the criterion.
 6. **Conventional commit titles** — Always use `type(scope): description` format. This feeds directly into commit messages.
 
@@ -306,6 +310,9 @@ Present the task summary:
 - Naming follows project patterns
 - Implementation notes reference specific standards, not generic advice
 
+#### Quality Gates
+- Quick tasks follow the same quality gates as all other tasks — see `docs/implementation-playbook.md` § Quality Gates
+
 #### Eval Gate
 - If `tests/evals/` exists, run `make eval` (or equivalent eval command from CLAUDE.md Key Commands) as a required pre-commit check
 

package/pipeline/build/single-agent-resume.md

@@ -51,10 +51,12 @@ continues the TDD execution loop from where you left off.
   guide, consult lessons.md, reconcile all open PRs, detailed PR descriptions.
 - **mvp**: Quick git state check, identify in-progress work, finish or pick
   next task, TDD loop, make check, create PR.
-- **custom:depth(1-5)**: Depth 1-2: check branch and continue. Depth 3: add
-  PR reconciliation and lessons.md review. Depth 4: add rebase, full test
-  suite validation, onboarding review. Depth 5: full state audit with branch
-  cleanup and eval gates.
+- **custom:depth(1-5)**:
+  - Depth 1: check current branch and continue in-progress work.
+  - Depth 2: add git status assessment and uncommitted change detection.
+  - Depth 3: add PR reconciliation and lessons.md review.
+  - Depth 4: add rebase, full test suite validation, onboarding review.
+  - Depth 5: full state audit with branch cleanup and eval gates.
 
 ## Mode Detection
 This is a stateless execution command. No document is created or updated.
@@ -143,7 +145,18 @@ Once in-progress work is complete (or if there was none):
    - Create a pull request: `gh pr create`
    - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
 
-3. **Claim next task**
+3. **Run code reviews (MANDATORY)**
+   - Run the review-pr tool: `scaffold run review-pr` (CLI) or `/scaffold:review-pr` (plugin)
+   - This runs **all three** review channels on the PR diff:
+     1. **Codex CLI**: `codex exec --skip-git-repo-check -s read-only --ephemeral "REVIEW_PROMPT" 2>/dev/null`
+     2. **Gemini CLI**: `NO_BROWSER=true gemini -p "REVIEW_PROMPT" --output-format json --approval-mode yolo 2>/dev/null`
+     3. **Superpowers code-reviewer**: dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
+   - Verify auth before each CLI (`codex login status`, `NO_BROWSER=true gemini -p "respond with ok" -o json`)
+   - All three channels must execute (skip only if a tool is genuinely not installed)
+   - Fix any P0/P1/P2 findings before proceeding
+   - Do NOT move to the next task until all channels have run
+
+4. **Claim next task**
    - Return to main: `git checkout main && git pull origin main`
    - Pick the next task following the same process as `/scaffold:single-agent-start`
    - Continue the TDD execution loop
@@ -182,7 +195,8 @@ Once in-progress work is complete (or if there was none):
 3. **Reconcile task status** — Merged PRs must be reflected in the task tracker.
 4. **TDD is not optional** — Continue the red-green-refactor cycle for any in-progress work.
 5. **Quality gates before PR** — Never create a PR with failing checks.
-6. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
+6. **Code review before next task** — After creating a PR, run all three review channels (Codex CLI, Gemini CLI, Superpowers code-reviewer) and fix all P0/P1/P2 findings before moving on.
+7. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
 
 ---
 

package/pipeline/build/single-agent-start.md

@@ -45,6 +45,7 @@ complete.
 - (mvp) Task status is updated after each completion
 - (deep) Test skeletons from tests/acceptance/ are used as starting points when available
 - (deep) lessons.md is consulted before each task for relevant anti-patterns
+- (deep) Before starting each task, agent consults tasks/lessons.md and documents which lesson was applied
 - (deep) PR description includes implementation summary, assumptions, and files modified
 
 ## Methodology Scaling
@@ -54,10 +55,12 @@ complete.
 - **mvp**: Quick git/dependency check, read playbook or plan, pick next task,
   TDD loop, make check, create PR. Skip onboarding guide review and detailed
   PR annotations.
-- **custom:depth(1-5)**: Depth 1-2: minimal pre-flight, TDD loop, make check.
-  Depth 3: add lessons.md review and test skeleton usage. Depth 4: add
-  onboarding guide, eval gates, detailed PR descriptions. Depth 5: full
-  pre-flight suite, all quality gates, cross-reference with upstream docs.
+- **custom:depth(1-5)**:
+  - Depth 1: git status check, TDD loop, make check.
+  - Depth 2: add dependency check and test suite health verification before starting.
+  - Depth 3: add lessons.md review and test skeleton usage.
+  - Depth 4: add onboarding guide, eval gates, detailed PR descriptions.
+  - Depth 5: full pre-flight suite, all quality gates, cross-reference with upstream docs.
 
 ## Mode Detection
 This is a stateless execution command. No document is created or updated.
@@ -121,6 +124,7 @@ For each task:
    - If Beads: branch as `bd-<id>/<desc>`
 
 2. **Red phase — write failing tests**
+   - Check `docs/story-tests-map.md` (if it exists) to find test skeletons that correspond to this task's user stories
    - Check `tests/acceptance/` for existing test skeletons that correspond to the task
    - If skeletons exist, use them as your starting point
    - Otherwise, write test cases from the task's acceptance criteria
@@ -147,7 +151,18 @@ For each task:
    - Include in the PR description: what was implemented, key decisions, files changed
    - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
 
-7. **Update status**
+7. **Run code reviews (MANDATORY)**
+   - Run the review-pr tool: `scaffold run review-pr` (CLI) or `/scaffold:review-pr` (plugin)
+   - This runs **all three** review channels on the PR diff:
+     1. **Codex CLI**: `codex exec --skip-git-repo-check -s read-only --ephemeral "REVIEW_PROMPT" 2>/dev/null`
+     2. **Gemini CLI**: `NO_BROWSER=true gemini -p "REVIEW_PROMPT" --output-format json --approval-mode yolo 2>/dev/null`
+     3. **Superpowers code-reviewer**: dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
+   - Verify auth before each CLI (`codex login status`, `NO_BROWSER=true gemini -p "respond with ok" -o json`)
+   - All three channels must execute (skip only if a tool is genuinely not installed)
+   - Fix any P0/P1/P2 findings before proceeding
+   - Do NOT move to the next task until all channels have run
+
+8. **Update status**
    - If Beads: task status is managed via `bd` commands
    - Without Beads: mark the task as complete in the plan/playbook
 
@@ -178,9 +193,10 @@ For each task:
 1. **TDD is not optional** — Write failing tests before implementation. No exceptions.
 2. **One task at a time** — Complete the current task fully before starting the next.
 3. **Quality gates before PR** — Never create a PR with failing checks.
-4. **Update status immediately** — Mark tasks complete as soon as the PR is created.
-5. **Consult lessons.md** — Check for relevant anti-patterns before each task.
-6. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
+4. **Code review before next task** — After creating a PR, run all three review channels (Codex CLI, Gemini CLI, Superpowers code-reviewer) and fix all P0/P1/P2 findings before moving on.
+5. **Update status immediately** — Mark tasks complete as soon as review passes.
+6. **Consult lessons.md** — Check for relevant anti-patterns before each task.
+7. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
 
 ---