@zigrivers/scaffold 2.1.1 → 2.28.1

package/methodology/deep.yml

@@ -4,32 +4,60 @@ description: Comprehensive documentation for complex systems — full analysis a
 default_depth: 5
 
 steps:
+  # Phase 1 — Product Definition (pre)
   create-prd: { enabled: true }
   review-prd: { enabled: true }
   innovate-prd: { enabled: true, conditional: "if-needed" }
   user-stories: { enabled: true }
   review-user-stories: { enabled: true }
   innovate-user-stories: { enabled: true, conditional: "if-needed" }
+  # Phase 2 — Project Foundation (foundation)
+  beads: { enabled: true, conditional: "if-needed" }
+  tech-stack: { enabled: true }
+  coding-standards: { enabled: true }
+  tdd: { enabled: true }
+  project-structure: { enabled: true }
+  # Phase 3 — Development Environment (environment)
+  dev-env-setup: { enabled: true }
+  design-system: { enabled: true, conditional: "if-needed" }
+  git-workflow: { enabled: true }
+  automated-pr-review: { enabled: true, conditional: "if-needed" }
+  ai-memory-setup: { enabled: true }
+  # Phase 4 — Testing Integration (integration)
+  add-e2e-testing: { enabled: true, conditional: "if-needed" }
+  # Phase 5 — Domain Modeling (modeling)
   domain-modeling: { enabled: true }
   review-domain-modeling: { enabled: true }
+  # Phase 6 — Architecture Decisions (decisions)
   adrs: { enabled: true }
   review-adrs: { enabled: true }
+  # Phase 7 — System Architecture (architecture)
   system-architecture: { enabled: true }
   review-architecture: { enabled: true }
+  # Phase 8 — Specifications (specification)
   database-schema: { enabled: true, conditional: "if-needed" }
   review-database: { enabled: true, conditional: "if-needed" }
   api-contracts: { enabled: true, conditional: "if-needed" }
   review-api: { enabled: true, conditional: "if-needed" }
   ux-spec: { enabled: true, conditional: "if-needed" }
   review-ux: { enabled: true, conditional: "if-needed" }
-  testing-strategy: { enabled: true }
+  # Phase 9 — Quality Gates (quality)
   review-testing: { enabled: true }
+  story-tests: { enabled: true }
+  create-evals: { enabled: true }
   operations: { enabled: true }
   review-operations: { enabled: true }
   security: { enabled: true }
   review-security: { enabled: true }
-  implementation-tasks: { enabled: true }
-  review-tasks: { enabled: true }
+  # Phase 10 — Platform Parity (parity)
+  platform-parity-review: { enabled: true, conditional: "if-needed" }
+  # Phase 11 — Consolidation (consolidation)
+  claude-md-optimization: { enabled: true }
+  workflow-audit: { enabled: true }
+  # Phase 12 — Planning (planning)
+  implementation-plan: { enabled: true }
+  implementation-plan-review: { enabled: true }
+  # Phase 13 — Validation (validation)
   cross-phase-consistency: { enabled: true }
   traceability-matrix: { enabled: true }
   decision-completeness: { enabled: true }
@@ -37,6 +65,7 @@ steps:
   implementability-dry-run: { enabled: true }
   dependency-graph-validation: { enabled: true }
   scope-creep-check: { enabled: true }
+  # Phase 14 — Finalization (finalization)
   apply-fixes-and-freeze: { enabled: true }
   developer-onboarding-guide: { enabled: true }
   implementation-playbook: { enabled: true }

package/methodology/mvp.yml

@@ -4,32 +4,60 @@ description: Get to code fast with minimal ceremony
 default_depth: 1
 
 steps:
+  # Phase 1 — Product Definition (pre)
   create-prd: { enabled: true }
   review-prd: { enabled: true }
   innovate-prd: { enabled: false }
   user-stories: { enabled: true }
   review-user-stories: { enabled: true }
   innovate-user-stories: { enabled: false }
+  # Phase 2 — Project Foundation (foundation)
+  beads: { enabled: false }
+  tech-stack: { enabled: true }
+  coding-standards: { enabled: true }
+  tdd: { enabled: true }
+  project-structure: { enabled: true }
+  # Phase 3 — Development Environment (environment)
+  dev-env-setup: { enabled: true }
+  design-system: { enabled: false }
+  git-workflow: { enabled: false }
+  automated-pr-review: { enabled: false }
+  ai-memory-setup: { enabled: false }
+  # Phase 4 — Testing Integration (integration)
+  add-e2e-testing: { enabled: false }
+  # Phase 5 — Domain Modeling (modeling)
   domain-modeling: { enabled: false }
   review-domain-modeling: { enabled: false }
+  # Phase 6 — Architecture Decisions (decisions)
   adrs: { enabled: false }
   review-adrs: { enabled: false }
+  # Phase 7 — System Architecture (architecture)
   system-architecture: { enabled: false }
   review-architecture: { enabled: false }
+  # Phase 8 — Specifications (specification)
   database-schema: { enabled: false }
   review-database: { enabled: false }
   api-contracts: { enabled: false }
   review-api: { enabled: false }
   ux-spec: { enabled: false }
   review-ux: { enabled: false }
-  testing-strategy: { enabled: true }
+  # Phase 9 — Quality Gates (quality)
   review-testing: { enabled: false }
+  story-tests: { enabled: false }
+  create-evals: { enabled: false }
   operations: { enabled: false }
   review-operations: { enabled: false }
   security: { enabled: false }
   review-security: { enabled: false }
-  implementation-tasks: { enabled: true }
-  review-tasks: { enabled: false }
+  # Phase 10 — Platform Parity (parity)
+  platform-parity-review: { enabled: false }
+  # Phase 11 — Consolidation (consolidation)
+  claude-md-optimization: { enabled: false }
+  workflow-audit: { enabled: false }
+  # Phase 12 — Planning (planning)
+  implementation-plan: { enabled: true }
+  implementation-plan-review: { enabled: false }
+  # Phase 13 — Validation (validation)
   cross-phase-consistency: { enabled: false }
   traceability-matrix: { enabled: false }
   decision-completeness: { enabled: false }
@@ -37,6 +65,7 @@ steps:
   implementability-dry-run: { enabled: false }
   dependency-graph-validation: { enabled: false }
   scope-creep-check: { enabled: false }
+  # Phase 14 — Finalization (finalization)
   apply-fixes-and-freeze: { enabled: false }
   developer-onboarding-guide: { enabled: false }
   implementation-playbook: { enabled: true }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zigrivers/scaffold",
-  "version": "2.1.1",
+  "version": "2.28.1",
   "description": "AI-powered software project scaffolding pipeline",
   "type": "module",
   "keywords": [
@@ -26,6 +26,7 @@
     "pipeline/",
     "knowledge/",
     "methodology/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],

package/pipeline/architecture/review-architecture.md

@@ -2,9 +2,9 @@
 name: review-architecture
 description: Review system architecture for completeness and downstream readiness
 phase: "architecture"
-order: 12
+order: 720
 dependencies: [system-architecture]
-outputs: [docs/reviews/review-architecture.md]
+outputs: [docs/reviews/review-architecture.md, docs/reviews/architecture/review-summary.md, docs/reviews/architecture/codex-review.json, docs/reviews/architecture/gemini-review.json]
 conditional: null
 knowledge-base: [review-methodology, review-system-architecture]
 ---
@@ -15,15 +15,21 @@ failure modes: domain coverage gaps, ADR constraint violations, data flow
 orphans, module structure issues, state inconsistencies, diagram/prose drift,
 and downstream readiness.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
 - docs/system-architecture.md (required) — architecture to review
 - docs/domain-models/ (required) — for coverage checking
 - docs/adrs/ (required) — for constraint compliance
-- docs/prd.md (required) — for requirement tracing
+- docs/plan.md (required) — for requirement tracing
 
 ## Expected Outputs
 - docs/reviews/review-architecture.md — findings and resolution log
 - docs/system-architecture.md — updated with fixes
+- docs/reviews/architecture/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/architecture/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/architecture/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
 - All architecture-specific review passes executed
@@ -32,13 +38,19 @@ and downstream readiness.
 - Data flow completeness verified (no orphaned components)
 - Module structure validated for practical concerns
 - Downstream readiness confirmed (specification, quality, and planning steps can proceed)
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
 - **deep**: All 10 review passes (coverage, constraints, data flows, module
   structure, state consistency, diagram integrity, extension points,
-  invariants, downstream readiness, internal consistency).
+  invariants, downstream readiness, internal consistency). Multi-model
+  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)**: Scale number of passes with depth.
+- **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.
 
 ## Mode Detection
-Re-review mode if previous review exists.
+Re-review mode if previous review exists. If multi-model review artifacts exist
+under docs/reviews/architecture/, preserve prior findings still valid.

package/pipeline/architecture/system-architecture.md

@@ -2,9 +2,10 @@
 name: system-architecture
 description: Design and document system architecture
 phase: "architecture"
-order: 11
+order: 710
 dependencies: [review-adrs]
 outputs: [docs/system-architecture.md]
+reads: [create-prd]
 conditional: null
 knowledge-base: [system-architecture]
 ---
@@ -17,7 +18,7 @@ organization. Project directory structure and module organization are defined he
 ## Inputs
 - docs/domain-models/ (required) — domain models from modeling phase
 - docs/adrs/ (required) — architecture decisions from decisions phase
-- docs/prd.md (required) — requirements driving architecture
+- docs/plan.md (required) — requirements driving architecture
 
 ## Expected Outputs
 - docs/system-architecture.md — architecture document with component design,
@@ -43,3 +44,14 @@ organization. Project directory structure and module organization are defined he
 If outputs already exist, operate in update mode: read existing content, diff
 against current project state and new ADRs, propose targeted updates rather
 than regenerating.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/system-architecture.md exists
+- **Preserve**: component structure, data flow diagrams, module organization,
+  extension points, deployment topology decisions
+- **Triggers for update**: new ADRs introduced (technology or pattern changes),
+  domain models added new bounded contexts, PRD requirements changed system
+  boundaries, implementation revealed architectural gaps
+- **Conflict resolution**: if a new ADR contradicts the current architecture,
+  update the affected components and data flows while preserving unaffected
+  sections; flag breaking changes for user review

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

@@ -0,0 +1,73 @@
+---
+name: claude-md-optimization
+description: Consolidate and optimize CLAUDE.md for maximum signal density
+phase: "consolidation"
+order: 1110
+dependencies: [git-workflow]
+outputs: [CLAUDE.md]
+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
+- No duplicated instructions within CLAUDE.md
+- No verbatim repetition of content from other docs (reference instead)
+- Consistent terminology throughout (task vs. ticket, etc.)
+- 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.
+- An agent can skim CLAUDE.md in 30 seconds and get the critical points
+- 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 have appended sections since last
+  optimization, 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,73 @@
+---
+name: workflow-audit
+description: Verify workflow consistency across all documentation files
+phase: "consolidation"
+order: 1120
+dependencies: [claude-md-optimization]
+outputs: [CLAUDE.md, docs/git-workflow.md]
+conditional: null
+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
+- CLAUDE.md contains complete workflow (9 steps + AI review step 4.5)
+- Commit format is consistent everywhere (If Beads: [BD-<id>] type(scope): description. Without Beads: type(scope): description)
+- Branch naming is consistent everywhere (If Beads: bd-<task-id>/<short-desc>. Without Beads: <type>/<short-desc>)
+- PR workflow includes all 8 sub-steps with --delete-branch flag
+- If Beads: task closure uses bd close (not bd update --status completed)
+- Key Commands table matches actual Makefile/package.json commands
+- Worktree cleanup between tasks documented (cannot checkout main)
+- Agent crash recovery documented
+- No document contradicts the canonical workflow
+- 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**: new setup prompts modified workflow docs, Makefile
+  targets added or renamed, git-workflow.md updated with new steps
+- **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

@@ -2,9 +2,10 @@
 name: adrs
 description: Document architecture decisions as ADRs
 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,7 +18,7 @@ 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)
@@ -43,3 +44,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

@@ -2,9 +2,9 @@
 name: review-adrs
 description: Review ADRs for completeness, consistency, and decision quality
 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]
 ---
@@ -14,14 +14,20 @@ 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
@@ -29,11 +35,18 @@ trade-offs.
 - Missing decisions identified and documented
 - Contradictions resolved
 - 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.

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

@@ -0,0 +1,70 @@
+---
+name: ai-memory-setup
+description: Configure AI memory and context management with modular rules, optional MCP memory server, lifecycle hooks, and external context integration
+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
+- .claude/rules/ files use valid YAML frontmatter with description and globs fields
+- Each rule file targets a specific concern (no catch-all files)
+- Total rule content stays under 500 lines across all files
+- CLAUDE.md references rules via pointer pattern, stays under 200 lines
+- Rules accurately reflect the conventions in source documents (no drift)
+- (Tier 2) MCP memory server responds to basic queries
+- (Tier 2) At least PreCompact hook is configured and functional
+- (Tier 3) 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
+Update mode if .claude/rules/ directory exists. In 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.
+
+## 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,70 @@
+---
+name: automated-pr-review
+description: Agent-driven automated PR review with external reviewers (Codex Cloud, Gemini Code Assist, or custom)
+phase: "environment"
+order: 340
+dependencies: [git-workflow]
+outputs: [AGENTS.md, docs/review-standards.md]
+conditional: "if-needed"
+knowledge-base: [review-methodology]
+---
+
+## 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
+
+## 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
+Update mode if AGENTS.md exists. In 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.
+
+## 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