@zigrivers/scaffold 2.1.2 → 2.38.0

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

@@ -0,0 +1,207 @@
+---
+name: single-agent-start
+description: Start single-agent TDD execution loop
+summary: "Claims the next task, writes a failing test, implements until it passes, refactors, runs quality gates, commits, and repeats — following the implementation playbook."
+phase: "build"
+order: 1510
+dependencies: [implementation-playbook]
+outputs: []
+conditional: null
+stateless: true
+category: pipeline
+knowledge-base: [tdd-execution-loop, task-claiming-strategy]
+reads: [coding-standards, tdd, git-workflow]
+---
+
+## Purpose
+Start the single-agent TDD execution loop. This is the primary entry point
+for implementation work when one agent works through the task list
+sequentially. The agent claims the next available task, writes failing tests,
+implements until green, creates a PR, and repeats until all tasks are
+complete.
+
+## Inputs
+- CLAUDE.md (required) — project conventions, key commands, workflow
+- docs/implementation-playbook.md (required if exists) — primary task execution reference with wave assignments and per-task context
+- docs/implementation-plan.md (fallback) — task list when no playbook exists
+- docs/onboarding-guide.md (optional) — project context for orientation
+- docs/coding-standards.md (required) — code conventions, naming, patterns
+- docs/tdd-standards.md (required) — test categories, mocking strategy, test file locations
+- docs/project-structure.md (required) — where files live
+- tests/acceptance/ (optional) — TDD test skeletons for red-green-refactor starting points
+- tests/evals/ (optional) — project eval checks for quality gates
+- tasks/lessons.md (optional) — previous lessons learned to avoid repeating mistakes
+- .beads/ (conditional) — Beads task tracking if configured
+
+## Expected Outputs
+- Implemented features with passing tests
+- Pull requests for each completed task
+- Updated task status in playbook/plan or Beads
+
+## Quality Criteria
+- (mvp) Pre-flight checks pass before starting any implementation work
+- (mvp) Each task follows red-green-refactor TDD cycle
+- (mvp) All quality gates pass before PR creation (make check + make eval if available)
+- (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) PR description includes implementation summary, assumptions, and files modified
+
+## Methodology Scaling
+- **deep**: Full pre-flight verification, read onboarding guide, consult lessons.md
+  before each task, use test skeletons, run evals, detailed PR descriptions with
+  implementation notes and assumptions.
+- **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.
+
+## Mode Detection
+This is a stateless execution command. No document is created or updated.
+- Always operates in EXECUTE MODE.
+- If work is already in progress (feature branch exists, uncommitted changes),
+  redirect to `/scaffold:single-agent-resume` instead.
+
+## Update Mode Specifics
+Not applicable — this is a stateless execution command that does not produce
+a persistent document.
+
+## Instructions
+
+### Pre-Flight Verification
+
+Before writing any code, verify the environment is ready:
+
+1. **Git state check**
+   - `git status` — working tree should be clean (no uncommitted changes)
+   - `git branch --show-current` — should be on `main` or a fresh branch
+   - If on a feature branch with changes, stop and suggest `/scaffold:single-agent-resume` instead
+
+2. **Dependency check**
+   - Run the install command from CLAUDE.md Key Commands (e.g., `npm install`, `pip install`, `bundle install`)
+   - Confirm dependencies are current
+
+3. **Test suite health**
+   - Run the project's check command from CLAUDE.md Key Commands (e.g., `make check`)
+   - If tests fail before you start, fix them first or flag to the user
+
+4. **Project orientation**
+   - Read `CLAUDE.md` for project conventions and key commands
+   - Read `docs/onboarding-guide.md` if it exists (first session orientation)
+   - Read `tasks/lessons.md` for relevant anti-patterns and gotchas
+
+### Beads Detection
+
+Check if `.beads/` directory exists.
+
+**If Beads is configured:**
+- Run `bd ready` to see available tasks
+- Pick the lowest-ID unblocked task
+- Implement following the TDD workflow below
+- After PR is merged, run `bd close <id> && bd sync`
+- Repeat with `bd ready` until no tasks remain
+
+**Without Beads:**
+1. Read `docs/implementation-playbook.md` as the primary task execution reference.
+   Fall back to `docs/implementation-plan.md` when no playbook is present.
+2. Pick the first uncompleted task that has no unfinished dependencies.
+3. Implement following the TDD workflow below.
+4. Mark the task complete in the plan/playbook.
+5. Repeat in dependency order until all tasks are done.
+
+### TDD Execution Loop
+
+For each task:
+
+1. **Claim the task**
+   - Create a feature branch: `git checkout -b <type>/<description>` (e.g., `feat/add-auth`)
+   - If Beads: branch as `bd-<id>/<desc>`
+
+2. **Red phase — write failing tests**
+   - 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
+   - Run the test suite — confirm the new tests FAIL (red)
+
+3. **Green phase — implement**
+   - Write the minimum code to make the failing tests pass
+   - Follow conventions from `docs/coding-standards.md`
+   - Follow file placement from `docs/project-structure.md`
+   - Run tests after each meaningful change — stop when green
+
+4. **Refactor phase — clean up**
+   - Refactor for clarity, DRY, and convention compliance
+   - Run the full test suite — confirm everything still passes
+
+5. **Quality gates**
+   - Run `make check` (or equivalent from CLAUDE.md Key Commands)
+   - If `tests/evals/` exists, run `make eval` (or equivalent eval command)
+   - Fix any failures before proceeding
+
+6. **Create PR**
+   - Push the branch: `git push -u origin HEAD`
+   - Create a pull request: `gh pr create`
+   - 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**
+   - If Beads: task status is managed via `bd` commands
+   - Without Beads: mark the task as complete in the plan/playbook
+
+### Recovery Procedures
+
+**Tests fail before starting:**
+- Run the test suite and read the output carefully
+- If failures are in existing tests (not your changes), fix them first
+- If failures are environment-related, run the install/setup commands from CLAUDE.md
+
+**Merge conflicts on PR:**
+- `git fetch origin && git rebase origin/main`
+- Resolve conflicts, re-run tests, force-push the branch
+
+**Quality gate failures after implementation:**
+- Read the failure output — most failures have clear fix instructions
+- Fix lint/format issues first (often auto-fixable)
+- Fix test failures next
+- Re-run the full gate before pushing
+
+**Stuck on a task:**
+- Re-read the task description, acceptance criteria, and any linked docs
+- Check `tasks/lessons.md` for similar past issues
+- If truly blocked, note the blocker and move to the next unblocked task
+
+### Process Rules
+
+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.
+
+---
+
+## After This Step
+
+When this step is complete (all tasks done or session ending), tell the user:
+
+---
+**Execution session complete** — Tasks implemented with passing tests and PRs created.
+
+**Session summary:**
+- Tasks completed: [list task IDs/titles]
+- PRs created: [list PR numbers]
+- Remaining tasks: [count or "none"]
+
+**If resuming later:** Run `/scaffold:single-agent-resume` to pick up where you left off.
+
+**If all tasks are done:**
+- Review `tasks/lessons.md` and add any patterns learned during implementation.
+- Consider running `/scaffold:version-bump` for a release.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---

package/pipeline/consolidation/claude-md-optimization.md

@@ -0,0 +1,76 @@
+---
+name: claude-md-optimization
+description: Consolidate and optimize CLAUDE.md for maximum signal density
+summary: "Removes redundancy from CLAUDE.md, fixes terminology inconsistencies, front-loads critical patterns (TDD, commit format, worktrees), and keeps it under 200 lines so agents actually read and follow it."
+phase: "consolidation"
+order: 1110
+dependencies: [git-workflow]
+outputs: [CLAUDE.md]
+reads: [create-prd, tdd, user-stories]
+conditional: null
+knowledge-base: [claude-md-patterns]
+---
+
+## Purpose
+Review all project documentation and consolidate CLAUDE.md into the definitive,
+optimized reference for AI agents. Eliminate redundancy from incremental additions
+by multiple setup prompts, fix inconsistencies in terminology and commands, fill
+gaps in workflow coverage, and front-load the most critical information for agent
+scannability.
+
+## Inputs
+- CLAUDE.md (required) — current state with incremental additions
+- docs/plan.md (required) — PRD for context
+- docs/tech-stack.md (required) — technology choices
+- docs/coding-standards.md (required) — code conventions
+- docs/tdd-standards.md (required) — testing approach
+- docs/git-workflow.md (required) — branching and PR workflow
+- docs/project-structure.md (required) — file placement rules
+- docs/user-stories.md (optional) — feature context
+
+## Expected Outputs
+- CLAUDE.md — restructured and consolidated with Core Principles, Git Workflow,
+  Workflow (session start through next task), Parallel Sessions, Quick Reference
+  (structure, Key Commands, doc lookup), Rules (git, code, coordination, error
+  recovery), Browser/E2E Testing, Self-Improvement, Autonomous Behavior
+
+## Quality Criteria
+- (mvp) No duplicated instructions within CLAUDE.md
+- (mvp) No verbatim repetition of content from other docs (reference instead)
+- (mvp) Consistent terminology throughout (task vs. ticket, etc.)
+- (mvp) Key Commands table matches actual Makefile/package.json commands
+- Critical patterns are prominent (TDD, never push to main, keep working,
+  verify before commit, worktrees for parallel). If Beads: every commit needs task ID.
+- (deep) CLAUDE.md is <= 200 lines or critical patterns appear in the first 50 lines
+- (deep) Workflow scenarios cover error cases (test failures, merge conflicts, CI failures,
+  crashed sessions, blocked tasks)
+- Tracking comment added: <!-- scaffold:claude-md-optimization v1 YYYY-MM-DD -->
+
+## Methodology Scaling
+- **deep**: Full four-phase analysis (redundancy, consistency, gap, priority audits)
+  with detailed changelog. Comprehensive error recovery section. All nine critical
+  patterns verified present and prominent.
+- **mvp**: Quick pass to remove obvious duplicates and ensure workflow section is
+  complete. Fix any command inconsistencies. Skip detailed audit.
+- **custom:depth(1-5)**: Depth 1-2: dedup + workflow check. Depth 3: add
+  consistency pass. Depth 4: add gap analysis. Depth 5: full four-phase audit.
+
+## Mode Detection
+Always operates in update mode (CLAUDE.md always exists by this point). Check
+for tracking comment `<!-- scaffold:claude-md-optimization v1 YYYY-MM-DD -->`
+to detect prior optimization. If present, compare current CLAUDE.md against
+the prior version date to identify sections added or changed since last
+optimization. Preserve manually-added sections (user customizations not from
+setup prompts). Only consolidate sections that originated from setup prompts —
+do not restructure user-authored content. Do not add new workflow steps or
+rules — only consolidate and clarify what already exists.
+
+## Update Mode Specifics
+- **Detect prior artifact**: tracking comment in CLAUDE.md with version and date
+- **Preserve**: manually-added sections, user-customized rules, project-specific
+  command aliases, any content not traceable to a pipeline setup prompt
+- **Triggers for update**: new setup prompts completed, coding-standards updated,
+  tdd-standards updated, git-workflow updated, terminology inconsistencies
+  introduced by incremental additions
+- **Conflict resolution**: if a user-customized section conflicts with a setup
+  prompt's output, keep the user version and flag the conflict in a comment

package/pipeline/consolidation/workflow-audit.md

@@ -0,0 +1,77 @@
+---
+name: workflow-audit
+description: Verify workflow consistency across all documentation files
+summary: "Audits every document that mentions workflow (CLAUDE.md, git-workflow, coding-standards, dev-setup) and fixes any inconsistencies in commit format, branch naming, PR steps, or key commands."
+phase: "consolidation"
+order: 1120
+dependencies: [claude-md-optimization]
+outputs: [CLAUDE.md, docs/git-workflow.md]
+conditional: null
+reads: [operations]
+knowledge-base: [cross-phase-consistency]
+---
+
+## Purpose
+Cross-reference all documentation to ensure the canonical feature workflow is
+consistently documented. Check every document that touches workflow (CLAUDE.md,
+git-workflow.md, coding-standards.md, dev-setup.md, operations-runbook.md,
+Makefile/package.json) for contradictions, stale references, missing steps, and
+inconsistent command formats. Fix all issues found.
+
+## Inputs
+- CLAUDE.md (required) — primary workflow document to audit
+- docs/git-workflow.md (required) — git workflow to verify alignment
+- docs/coding-standards.md (required) — commit format to verify
+- docs/dev-setup.md (required) — commands to verify match Key Commands
+- Makefile or package.json (required) — actual commands to match against
+- .github/ (optional) — PR templates and CI workflows to verify
+- docs/operations-runbook.md (optional) — deployment pipeline to verify doesn't contradict CI or dev-setup
+- tasks/lessons.md (optional) — verify it exists and is referenced
+
+## Expected Outputs
+- CLAUDE.md — corrected workflow section with all 9 steps + step 4.5
+- docs/git-workflow.md — any contradictions fixed
+- docs/coding-standards.md — commit format aligned
+- Makefile/package.json — missing targets added (if needed)
+- tasks/lessons.md — created if missing
+
+## Quality Criteria
+- (mvp) CLAUDE.md contains complete workflow (9 steps + AI review step 4.5)
+- (mvp) Commit format is consistent everywhere (If Beads: [BD-<id>] type(scope): description. Without Beads: type(scope): description)
+- (mvp) Branch naming is consistent everywhere (If Beads: bd-<task-id>/<short-desc>. Without Beads: <type>/<short-desc>)
+- (mvp) PR workflow includes all 8 sub-steps with --delete-branch flag
+- (mvp) If Beads: task closure uses bd close (not bd update --status completed)
+- (mvp) Key Commands table matches actual Makefile/package.json commands
+- (deep) Worktree cleanup between tasks documented (cannot checkout main)
+- (deep) Agent crash recovery documented
+- (deep) No document contradicts the canonical workflow
+- Tracking comment matches format: `<!-- scaffold:workflow-audit v1 YYYY-MM-DD -->`
+- Tracking comment added: <!-- scaffold:workflow-audit v1 YYYY-MM-DD -->
+
+## Methodology Scaling
+- **deep**: Full six-phase audit (inventory, completeness check with all
+  sub-checklists, consistency check, gap analysis, recommendations, execution).
+  Every workflow step verified in every document.
+- **mvp**: Quick consistency check of commit format, branch naming, and PR
+  workflow across CLAUDE.md and git-workflow.md. Fix obvious contradictions.
+- **custom:depth(1-5)**: Depth 1-2: CLAUDE.md workflow check only. Depth 3: add
+  cross-doc consistency. Depth 4: add gap analysis. Depth 5: full six-phase audit.
+
+## Mode Detection
+Always operates in update mode (all documents exist by this point). Check for
+tracking comment `<!-- scaffold:workflow-audit v1 YYYY-MM-DD -->` to detect
+prior audit. If present, focus on changes since that date — new docs added,
+existing docs modified, Makefile targets changed. The canonical workflow is
+the source of truth — documents align to it, not vice versa. Preserve any
+manually-added workflow steps or custom CI configurations.
+
+## Update Mode Specifics
+- **Detect prior artifact**: tracking comment in CLAUDE.md with audit version
+  and date
+- **Preserve**: custom CI jobs, user-added workflow steps, project-specific
+  branch protection rules, custom PR template fields
+- **Triggers for update**: CI configuration changed, git-workflow.md updated,
+  new scripts added to Makefile, Makefile targets added or renamed, new setup
+  prompts modified workflow docs
+- **Conflict resolution**: if two docs disagree on workflow, the canonical
+  workflow in CLAUDE.md wins; update the conflicting doc to match

package/pipeline/decisions/adrs.md

@@ -1,10 +1,12 @@
 ---
 name: adrs
 description: Document architecture decisions as ADRs
+summary: "Documents every significant design decision — what was chosen, what alternatives were considered with pros and cons, and what consequences follow — so future contributors understand why, not just what."
 phase: "decisions"
-order: 9
+order: 610
 dependencies: [review-domain-modeling]
 outputs: [docs/adrs/]
+reads: [create-prd, domain-modeling]
 conditional: null
 knowledge-base: [adr-craft]
 ---
@@ -17,18 +19,19 @@ ADR category — tech stack decisions are documented here.
 
 ## Inputs
 - docs/domain-models/ (required) — domain structure driving architecture choices
-- docs/prd.md (required) — requirements and constraints
+- docs/plan.md (required) — requirements and constraints
 
 ## Expected Outputs
 - docs/adrs/ — one ADR file per decision (ADR-NNN-title.md format)
 - docs/adrs/index.md — decision log overview
 
 ## Quality Criteria
-- Every significant decision has an ADR (technology, patterns, trade-offs)
-- Each ADR documents alternatives considered with pros/cons
-- Decisions trace to PRD requirements or domain model constraints
-- No ADR contradicts another without explicit acknowledgment
-- Technology selections include team expertise and maintenance considerations
+- (mvp) ADRs exist for: language, framework, database, ORM, deployment target, API style, authentication, and any decision referenced in system-architecture.md
+- (deep) Each ADR documents alternatives considered with pros/cons
+- (mvp) Decisions trace to PRD requirements or domain model constraints
+- (mvp) No ADR contradicts another without explicit acknowledgment
+- (deep) Technology selections include team expertise and maintenance considerations
+- (deep) Decision dependencies documented — if ADR-002 depends on ADR-001's outcome, the dependency is explicit
 
 ## Methodology Scaling
 - **deep**: Comprehensive ADR set. 3+ alternatives per decision with detailed
@@ -43,3 +46,14 @@ ADR category — tech stack decisions are documented here.
 If docs/adrs/ exists, operate in update mode: review existing ADRs against
 current domain models and requirements. Add new ADRs for undocumented decisions.
 Supersede ADRs whose context has changed.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/adrs/ directory exists with ADR files
+- **Preserve**: existing ADR numbers and titles, accepted decisions and their
+  rationale, supersession chain integrity, index.md decision log
+- **Triggers for update**: domain models changed (new architectural decisions
+  needed), requirements changed (existing decisions may need revisiting),
+  implementation revealed unforeseen trade-offs
+- **Conflict resolution**: never modify an accepted ADR — instead create a new
+  ADR that supersedes it, linking back to the original with explanation of
+  what changed

package/pipeline/decisions/review-adrs.md

@@ -1,12 +1,13 @@
 ---
 name: review-adrs
 description: Review ADRs for completeness, consistency, and decision quality
+summary: "Checks for contradictions between decisions, missing decisions implied by the architecture, and whether every choice has honest trade-off analysis."
 phase: "decisions"
-order: 10
+order: 620
 dependencies: [adrs]
-outputs: [docs/reviews/review-adrs.md]
+outputs: [docs/reviews/review-adrs.md, docs/reviews/adrs/review-summary.md, docs/reviews/adrs/codex-review.json, docs/reviews/adrs/gemini-review.json]
 conditional: null
-knowledge-base: [review-methodology, review-adr]
+knowledge-base: [review-methodology, review-adr, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -14,26 +15,46 @@ Multi-pass review of ADRs targeting ADR-specific failure modes: contradictory
 decisions, missing rationale, implied-but-unrecorded decisions, and unresolved
 trade-offs.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
 - docs/adrs/ (required) — ADRs to review
 - docs/domain-models/ (required) — for coverage checking
-- docs/prd.md (required) — for requirement tracing
+- docs/plan.md (required) — for requirement tracing
 
 ## Expected Outputs
 - docs/reviews/review-adrs.md — findings and resolution log
 - docs/adrs/ — updated with fixes
+- docs/reviews/adrs/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/adrs/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/adrs/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- All ADR-specific review passes executed
-- Every finding categorized by severity
-- Missing decisions identified and documented
-- Contradictions resolved
-- Downstream readiness confirmed (architecture phase can proceed)
+- (mvp) All ADR-specific review passes executed
+- (mvp) Every finding categorized P0-P3 with specific ADR number, section, and issue
+- (deep) Missing decisions identified and documented
+- (mvp) Contradictions resolved
+- (mvp) Downstream readiness confirmed (architecture phase can proceed)
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
-- **deep**: All review passes. Full findings report. Fixes applied and re-validated.
+- **deep**: All review passes. Full findings report. Fixes applied and
+  re-validated. Multi-model review dispatched to Codex and Gemini if available,
+  with graceful fallback to Claude-only enhanced review.
 - **mvp**: Quick consistency check for contradictions only.
-- **custom:depth(1-5)**: Scale number of review passes with depth.
+- **custom:depth(1-5)**: Depth 1-3: scale number of review passes with depth.
+  Depth 4: full review + one external model (if CLI available). Depth 5:
+  full review + multi-model with reconciliation.
 
 ## Mode Detection
 Re-review mode if previous review exists. Check which findings were addressed.
+If multi-model review artifacts exist under docs/reviews/adrs/, preserve prior
+findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-adrs.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/pipeline/environment/ai-memory-setup.md

@@ -0,0 +1,76 @@
+---
+name: ai-memory-setup
+description: Configure AI memory and context management with modular rules, optional MCP memory server, lifecycle hooks, and external context integration
+summary: "Extracts conventions from your docs into path-scoped rule files that load automatically, optimizes CLAUDE.md with a pointer pattern, and optionally sets up persistent cross-session memory."
+phase: "environment"
+order: 350
+dependencies: [git-workflow]
+outputs: [.claude/rules/, docs/ai-memory-setup.md]
+reads: [coding-standards, tech-stack]
+conditional: null
+knowledge-base: [ai-memory-management]
+---
+
+## Purpose
+Set up a tiered AI memory stack that improves agent effectiveness across sessions.
+Tier 1 (modular rules) extracts conventions from existing project docs into
+path-scoped `.claude/rules/` files, keeping CLAUDE.md lean. Tier 2 (persistent
+memory) configures an MCP memory server and lifecycle hooks for cross-session
+decision capture. Tier 3 (external context) adds library documentation servers
+to prevent API hallucination. Users choose which tiers to enable.
+
+## Inputs
+- docs/coding-standards.md (required) — source for code convention rules
+- docs/tech-stack.md (required) — source for technology-specific rules
+- docs/git-workflow.md (required) — source for workflow rules
+- CLAUDE.md (required) — will be optimized after rules extraction
+- package.json or equivalent (optional) — dependency list for Tier 3 assessment
+
+## Expected Outputs
+- .claude/rules/ directory with path-scoped rule files extracted from project docs
+- docs/ai-memory-setup.md — documentation of configured memory stack
+- CLAUDE.md updated with pointer pattern (references rules instead of inline content)
+- (Tier 2) .claude/settings.json with MCP memory server and hook configuration
+- (Tier 2) docs/decisions/ directory for structured decision logging
+- (Tier 3) .claude/settings.json with external context MCP server
+
+## Quality Criteria
+- (mvp) .claude/rules/ files use valid YAML frontmatter with description and globs fields
+- (mvp) Each rule file targets a specific concern (no catch-all files)
+- (mvp) Total rule content stays under 500 lines across all files
+- (mvp) CLAUDE.md references rules via pointer pattern, stays under 200 lines
+- (mvp) Rules accurately reflect the conventions in source documents (no drift)
+- (deep) MCP memory server responds to basic queries
+- (deep) At least PreCompact hook is configured and functional
+- (deep) Library doc server returns results for project dependencies
+
+## Methodology Scaling
+- **deep**: All three tiers offered. Tier 1 generates comprehensive rules from
+  all project docs. Tier 2 recommends hmem or Claude-Mem for thorough capture.
+  Tier 3 configured with appropriate library doc server.
+- **mvp**: Tier 1 only (modular rules). Quick extraction of essential conventions
+  into 2-3 rule files. Skip Tier 2 and 3. Minimal CLAUDE.md optimization.
+- **custom:depth(1-5)**: Depth 1-2: Tier 1 basics (2-3 rule files). Depth 3:
+  full Tier 1 + offer Tier 2. Depth 4-5: all tiers with comprehensive setup.
+
+## Mode Detection
+Check if `.claude/rules/` directory or docs/ai-memory-setup.md exists first. If
+`.claude/rules/` exists, check for scaffold tracking comments (e.g.,
+`<!-- scaffold:ai-memory-setup -->`) in rule files for conservativeness calibration.
+- If `.claude/rules/` exists with tracking comments: UPDATE MODE — preserve existing
+  rule files and their customizations, add missing rules for new conventions,
+  update rules where source docs have changed. Never delete user-customized rules.
+  If MCP server already configured, verify and update rather than replace.
+- If `.claude/rules/` does not exist: FRESH MODE — create rules directory and generate
+  rule files from scratch.
+
+## Update Mode Specifics
+- **Detect prior artifact**: .claude/rules/ directory exists with rule files
+- **Preserve**: existing rule files and their YAML frontmatter, user-customized
+  rules, MCP server configurations, hook settings, CLAUDE.md pointer patterns
+- **Triggers for update**: source docs changed (coding-standards.md, tech-stack.md,
+  git-workflow.md), new conventions added that need rule extraction, new
+  dependencies added that need Tier 3 doc servers
+- **Conflict resolution**: if a source doc changed a convention, update the
+  corresponding rule file but preserve any user-added rules in that file;
+  never exceed 500-line total rule budget without consolidating

package/pipeline/environment/automated-pr-review.md

@@ -0,0 +1,76 @@
+---
+name: automated-pr-review
+description: Agent-driven automated PR review with external reviewers (Codex Cloud, Gemini Code Assist, or custom)
+summary: "Configures automated code review — using Codex and/or Gemini CLIs for dual-model review when available, or an external bot — with severity definitions and review criteria tailored to your project."
+phase: "environment"
+order: 340
+dependencies: [git-workflow]
+outputs: [AGENTS.md, docs/review-standards.md]
+reads: [tdd]
+conditional: "if-needed"
+knowledge-base: [review-methodology, automated-review-tooling]
+---
+
+## Purpose
+Configure an agent-driven automated PR review system using local CLI reviewers
+(Codex, Gemini — runs both when available for dual-model quality) or external
+GitHub App reviewers. Zero GitHub Actions workflows. The agent manages the
+entire review-fix loop locally.
+
+## Inputs
+- docs/coding-standards.md (required) — review criteria reference
+- docs/tdd-standards.md (required) — test coverage expectations
+- docs/git-workflow.md (required) — PR workflow to integrate with
+- CLAUDE.md (required) — workflow sections to update
+
+## Expected Outputs
+- AGENTS.md — Reviewer instructions with project-specific rules
+- docs/review-standards.md — severity definitions (P0-P3) and review criteria
+- scripts/cli-pr-review.sh (local CLI mode) — dual-model review with reconciliation
+- scripts/await-pr-review.sh (external bot mode) — polling script with JSON output
+- docs/git-workflow.md updated with review loop integration
+- CLAUDE.md updated with agent-driven review workflow
+
+## Quality Criteria
+- External reviewer configured and verified (AGENTS.md created)
+- Review standards document matches project coding conventions
+- Await script handles all exit conditions (approved, findings, cap, skip, timeout)
+- CLAUDE.md workflow documents the agent-driven loop
+- No GitHub Actions workflows created (zero Actions minutes)
+- No ANTHROPIC_API_KEY secret required
+- Legacy GitHub Actions workflows detected and cleanup offered
+- (deep) Dual-model review enabled when both CLIs available
+
+## Methodology Scaling
+- **deep**: Full setup with local CLI review (dual-model when both available),
+  review-standards.md, AGENTS.md, and comprehensive CLAUDE.md workflow.
+  Falls back to external bot review if no CLIs available.
+- **mvp**: Step is disabled. Local self-review from git-workflow suffices.
+- **custom:depth(1-5)**: Depth 1-2: disabled. Depth 3: basic review-standards.md
+  + single-CLI review. Depth 4: add dual-model review. Depth 5: full suite
+  with all options and legacy cleanup.
+
+## Conditional Evaluation
+Enable when: project uses GitHub for version control, team size > 1 or CI/CD is
+configured, or git-workflow.md establishes a PR-based workflow. Skip when: solo
+developer with no CI, depth < 3, or project uses a non-GitHub VCS host.
+
+## Mode Detection
+Check if AGENTS.md exists first. If it exists, check for scaffold tracking comment
+(`<!-- scaffold:automated-pr-review -->`).
+- If AGENTS.md exists with tracking comment: UPDATE MODE — preserve custom review rules,
+  reviewer bot name, and round cap settings. Detect legacy GitHub Actions
+  workflows (code-review-trigger.yml, code-review-handler.yml) and offer removal.
+- If AGENTS.md does not exist: FRESH MODE — configure from scratch.
+
+## Update Mode Specifics
+- **Detect prior artifact**: AGENTS.md exists
+- **Preserve**: custom review rules, reviewer bot configuration, round cap
+  settings, severity definitions in docs/review-standards.md, CLI review
+  script customizations
+- **Triggers for update**: coding-standards.md changed (new review criteria),
+  tdd-standards.md changed (coverage expectations), new external reviewer
+  CLI became available, git-workflow.md changed PR workflow steps
+- **Conflict resolution**: if review criteria changed in coding-standards.md,
+  update AGENTS.md review rules to match; if both CLI reviewers are now
+  available, offer to enable dual-model review