@zigrivers/scaffold 2.1.2 → 2.38.0

package/pipeline/foundation/tdd.md

@@ -0,0 +1,64 @@
+---
+name: tdd
+description: Define testing conventions and TDD standards for the tech stack
+summary: "Defines your testing approach — which types of tests to write at each layer, coverage targets, what to mock and what not to, test data patterns — so agents write the right tests from the start."
+phase: "foundation"
+order: 240
+dependencies: [coding-standards]
+outputs: [docs/tdd-standards.md]
+reads: [create-prd, system-architecture]
+conditional: null
+knowledge-base: [testing-strategy]
+---
+
+## Purpose
+Define the project's testing conventions, TDD workflow, test pyramid, coverage
+goals, quality gates, and testing patterns. This tells agents how to test the
+code they write and establishes testing standards before implementation begins.
+Includes concrete reference examples for each test category using the project's
+actual test framework and assertion library.
+
+## Inputs
+- docs/tech-stack.md (required) — determines test runner, assertion library, and framework-specific testing patterns
+- docs/coding-standards.md (required) — naming conventions and code patterns that apply to test files
+- docs/plan.md (required) — features inform which testing scenarios matter most
+- docs/system-architecture.md (optional) — if available, layers to test
+- docs/domain-models/ (optional) — if available, business rules to verify
+- docs/adrs/ (optional) — if available, testing technology choices
+
+## Expected Outputs
+- docs/tdd-standards.md — testing approach with coverage goals and patterns
+
+## Quality Criteria
+- (mvp) Test pyramid defined with coverage targets per layer
+- (mvp) Testing patterns specified for each layer (unit, integration, e2e)
+- (mvp) Quality gates defined (what must pass before merge)
+- Edge cases from domain invariants are test scenarios
+- (deep) Performance testing approach for critical paths
+- (deep) Contract testing strategy documented for service boundaries
+
+## Methodology Scaling
+- **deep**: Comprehensive strategy. Test matrix by layer and component. Specific
+  test patterns per architecture pattern. Performance benchmarks. CI integration.
+  Test data strategy. Mutation testing approach.
+- **mvp**: Test pyramid overview. Key testing patterns. What must pass before deploy.
+- **custom:depth(1-5)**: Depth 1-2: test pyramid overview with key patterns and example test for each layer. Depth 3: add per-layer test patterns, coverage targets, CI integration, and test data strategy. Depth 4: add performance benchmarks, mutation testing approach, and cross-module integration patterns. Depth 5: full suite with contract testing, visual regression strategy, and automated quality gate calibration.
+
+## Mode Detection
+Check for docs/tdd-standards.md. If it exists, operate in update mode: read
+existing strategy and diff against current tech stack, coding standards, and
+PRD. Preserve testing patterns, layer definitions, custom assertions, and test
+data strategy. Update coverage goals if PRD scope or tech stack changed.
+Re-generate only sections affected by upstream changes — do not rewrite
+stable layer definitions or custom assertion patterns.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/tdd-standards.md exists
+- **Preserve**: test pyramid layer definitions, custom assertion helpers, test
+  data strategy, quality gate thresholds, framework-specific patterns
+- **Triggers for update**: tech-stack.md changed (new test runner or framework),
+  coding-standards.md changed (naming conventions), PRD scope expanded (new
+  features needing test scenarios)
+- **Conflict resolution**: if tech stack changed test runner, migrate pattern
+  examples to new runner syntax; preserve coverage targets unless user requests
+  adjustment

package/pipeline/foundation/tech-stack.md

@@ -0,0 +1,74 @@
+---
+name: tech-stack
+description: Research and document tech stack decisions with rationale for each choice
+summary: "Researches technology options for your project — language, framework, database, hosting, auth — evaluates each against your requirements, and documents every choice with rationale and alternatives considered."
+phase: "foundation"
+order: 220
+dependencies: []
+outputs: [docs/tech-stack.md]
+reads: [create-prd]
+conditional: null
+knowledge-base: [tech-stack-selection, multi-model-review-dispatch]
+---
+
+## Purpose
+Research frameworks, languages, databases, and tools that fit the PRD requirements,
+then document every technology choice with rationale, alternatives considered, and
+AI compatibility notes. This becomes the definitive technology reference that all
+subsequent phases depend on for framework-specific decisions.
+
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent technology research — different models have different knowledge
+about ecosystem maturity, alternatives, and gotchas.
+
+## Inputs
+- docs/plan.md (required) — PRD features, integrations, and technical requirements
+- User preferences (gathered via questions) — language, framework, deployment target, constraints
+
+## Expected Outputs
+- docs/tech-stack.md — complete technology reference with architecture overview,
+  backend, database, frontend (if applicable), infrastructure, developer tooling,
+  and third-party services sections, plus a Quick Reference dependency list
+- docs/reviews/tech-stack/review-summary.md (depth 4+) — multi-model research synthesis
+- docs/reviews/tech-stack/codex-review.json (depth 4+, if available) — raw Codex recommendations
+- docs/reviews/tech-stack/gemini-review.json (depth 4+, if available) — raw Gemini recommendations
+
+## Quality Criteria
+- (mvp) Every PRD feature cross-referenced against the proposed stack (no capability gaps)
+- (mvp) Each technology choice documents what, why, why not alternatives, and AI compatibility
+- (mvp) Architecture pattern chosen and justified (monolith vs. microservices, MVC vs. clean, etc.)
+- (mvp) No speculative technologies ("might need someday")
+- (mvp) Every choice is a decision, not a menu of options
+- (mvp) Quick Reference section lists every dependency with version
+- (deep) Each technology choice documents AI compatibility assessment (training data availability, convention strength); total direct dependencies counted and justified
+- (depth 4+) Multi-model recommendations cross-referenced — agreements flagged as high-confidence, disagreements flagged for human decision
+
+## Methodology Scaling
+- **deep**: Comprehensive research with competitive analysis for each category.
+  Detailed AI compatibility notes per library. Version pinning with upgrade
+  strategy. Infrastructure and DevOps recommendations. 10-15 pages. Multi-model
+  research dispatched to Codex and Gemini if available, with graceful fallback
+  to Claude-only enhanced research.
+- **mvp**: Core stack decisions only (language, framework, database, test runner).
+  Brief rationale. Quick Reference with versions. 2-3 pages.
+- **custom:depth(1-5)**: Depth 1-2: MVP decisions. Depth 3: add infrastructure
+  and tooling. Depth 4: add AI compatibility analysis + one external model
+  (if CLI available). Depth 5: full competitive analysis and upgrade strategy
+  + multi-model with cross-referencing.
+
+## Mode Detection
+Update mode if docs/tech-stack.md exists. In update mode: never change a
+technology choice without user approval, preserve version pins exactly, update
+Quick Reference to match any structural changes. If multi-model artifacts exist
+under docs/reviews/tech-stack/, preserve prior recommendation dispositions.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/tech-stack.md exists
+- **Preserve**: all technology choices and their rationale, version pins,
+  Quick Reference dependency list, multi-model review artifacts and dispositions
+- **Triggers for update**: PRD requirements changed (new integrations needed),
+  user requests technology swap, security vulnerability in a dependency,
+  new PRD features require capabilities not covered by current stack
+- **Conflict resolution**: if a new requirement conflicts with an existing
+  technology choice, document the conflict and propose alternatives with
+  migration cost — never silently swap a technology

package/pipeline/integration/add-e2e-testing.md

@@ -0,0 +1,80 @@
+---
+name: add-e2e-testing
+description: Configure end-to-end testing (Playwright for web, Maestro for mobile) based on detected project platform
+summary: "Detects whether your project is web or mobile, then configures Playwright (web) or Maestro (mobile) with a working smoke test, baseline screenshots, and guidance on when to use E2E vs. unit tests."
+phase: "integration"
+order: 410
+dependencies: [git-workflow, tdd]
+outputs: [tests/screenshots/, maestro/]
+reads: [coding-standards, user-stories]
+conditional: "if-needed"
+knowledge-base: [testing-strategy]
+---
+
+## Purpose
+Automatically detects project platform type from tech-stack.md and package.json
+to determine which E2E framework(s) to configure. Configures Playwright for web
+frontends, Maestro for mobile/Expo apps, or both for multi-platform projects.
+Self-skips for backend-only or library projects with no UI.
+
+## Inputs
+- docs/tech-stack.md (required) — frontend framework and rendering approach
+- docs/tdd-standards.md (required) — E2E placeholder section to fill
+- docs/coding-standards.md (required for mobile) — testID conventions to add
+- CLAUDE.md (required) — browser/mobile testing section to add
+- package.json (read-only) — dependency detection for platform and brownfield signals
+- docs/user-stories.md (optional) — key user flows for visual verification
+
+## Expected Outputs
+Outputs vary by detected platform:
+- (web) Playwright config file, tests/screenshots/ directories, CLAUDE.md and
+  tdd-standards.md browser testing sections
+- (mobile) maestro/ directory with config, flows, shared sub-flows, screenshots,
+  package.json test scripts, coding-standards.md testID conventions, CLAUDE.md
+  and tdd-standards.md mobile testing sections
+- (both) All of the above
+
+## Quality Criteria
+- (mvp) Platform detection is explicit and logged (web, mobile, both, or skip)
+- (mvp) (web) Playwright config uses framework-specific dev server command and port
+- (mvp) (web) Smoke test passes (navigate, screenshot, close)
+- (mvp) (mobile) Maestro CLI installed, sample flow executes, screenshot captured
+- (mobile) testID naming convention defined and documented
+- (mvp) E2E section in tdd-standards.md distinguishes when to use E2E vs unit tests
+- Baseline screenshots committed, current screenshots gitignored
+- CLAUDE.md contains browser/mobile testing section
+- tdd-standards.md E2E section updated with when-to-use guidance
+- (deep) CI integration configured for E2E test execution
+- (deep) Sub-flows defined for common user journeys
+
+## Methodology Scaling
+- **deep**: Full setup for all detected platforms. All visual testing patterns,
+  baseline management, responsive verification, CI integration, sub-flows for
+  common journeys, and comprehensive documentation updates.
+- **mvp**: Basic config and smoke test for detected platform. Minimal docs
+  updates. Two viewports for web, single platform for mobile.
+- **custom:depth(1-5)**: Depth 1-2: config + smoke test. Depth 3: add patterns,
+  naming, testID rules. Depth 4: add CI integration, both mobile platforms.
+  Depth 5: full suite with baseline management and sub-flows.
+
+## Conditional Evaluation
+Enable when: tech-stack.md indicates a web frontend (Playwright) or mobile app
+(Maestro). Detection signals: React/Vue/Angular/Svelte in tech-stack (web),
+Expo/React Native (mobile), or explicit UI layer in architecture. Self-skips for
+backend-only or library projects with no UI.
+
+## Mode Detection
+Check for existing E2E config: Playwright config file (playwright.config.ts or
+.js) and/or maestro/ directory. If either exists, run in update mode for that
+platform. Preserve baseline screenshots, custom viewports, existing flows,
+and environment variables.
+
+## Update Mode Specifics
+- **Detect prior artifact**: playwright.config.ts/.js exists and/or maestro/
+  directory exists with flow files
+- **Preserve**: baseline screenshots, custom viewports, existing test flows,
+  environment variables, testID naming conventions
+- **Triggers for update**: new user stories with UI interactions added,
+  platform targets changed in tech-stack.md, tdd-standards.md E2E section updated
+- **Conflict resolution**: preserve existing baselines, add new flows alongside
+  existing ones rather than replacing

package/pipeline/modeling/domain-modeling.md

@@ -1,10 +1,12 @@
 ---
 name: domain-modeling
 description: Deep domain modeling across all identified project domains
+summary: "Analyzes your user stories to identify the core concepts in your project (entities, their relationships, the rules that must always hold true), and establishes a shared vocabulary that all docs and code will use."
 phase: "modeling"
-order: 7
+order: 510
 dependencies: [review-user-stories]
 outputs: [docs/domain-models/]
+reads: [coding-standards, innovate-user-stories]
 conditional: null
 knowledge-base: [domain-modeling]
 ---
@@ -17,7 +19,7 @@ Use user stories and their acceptance criteria to discover entities, events,
 and aggregate boundaries. User actions reveal the domain model.
 
 ## Inputs
-- docs/prd.md (required) — requirements defining the problem space
+- docs/plan.md (required) — requirements defining the problem space
 - docs/reviews/pre-review-prd.md (optional) — review findings for context
 - docs/prd-innovation.md (optional) — innovation findings and approved enhancements
 - docs/user-stories.md (required) — user stories with acceptance criteria for domain discovery
@@ -33,13 +35,15 @@ and aggregate boundaries. User actions reveal the domain model.
 - docs/domain-models/index.md — overview of all domains and their relationships
 
 ## Quality Criteria
-- Every PRD feature maps to at least one domain
-- Entity relationships are explicit (not implied)
-- Aggregate boundaries are justified (why this grouping?)
-- Domain events cover all state transitions
-- Invariants are testable assertions, not vague rules
+- (mvp) Every PRD feature maps to at least one domain
+- (mvp) Entity relationships are explicit (not implied)
+- (mvp) Each aggregate boundary documents: the invariant it protects, the consistency boundary it enforces, and why included entities must change together
+- (deep) Domain events cover all state transitions
+- (deep) Each invariant is phrased as a boolean condition checkable in code (e.g., `order.total >= 0`, `user.email matches /^[^@]+@[^@]+$/`), not a narrative description
 - Ubiquitous language is consistent across all domain models
-- Cross-domain relationships are documented at context boundaries
+- (mvp) All entity and concept names used consistently across domain model files (ubiquitous language enforced)
+- (deep) Cross-aggregate event flows documented for every state change that crosses aggregate boundaries
+- (deep) Cross-domain relationships are documented at context boundaries
 
 ## Methodology Scaling
 - **deep**: Full DDD tactical patterns. Detailed entity specs with TypeScript-style
@@ -55,3 +59,14 @@ and aggregate boundaries. User actions reveal the domain model.
 If docs/domain-models/ exists, operate in update mode: read existing models,
 identify changes needed based on updated PRD or new understanding. Preserve
 existing decisions unless explicitly revisiting them.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/domain-models/ directory exists with model files
+- **Preserve**: existing entity definitions, aggregate boundaries, domain events,
+  invariants, ubiquitous language terms, bounded context interfaces
+- **Triggers for update**: PRD features added or changed, user stories revealed
+  new domain concepts, innovation suggestions accepted new capabilities,
+  implementation revealed modeling gaps
+- **Conflict resolution**: if a new feature introduces an entity name that
+  conflicts with existing ubiquitous language, resolve by renaming the new
+  entity and documenting the distinction; never silently merge aggregates

package/pipeline/modeling/review-domain-modeling.md

@@ -1,12 +1,13 @@
 ---
 name: review-domain-modeling
 description: Review domain models for completeness, consistency, and downstream readiness
+summary: "Verifies every PRD feature maps to a domain entity, checks that business rules are enforceable, and ensures the shared vocabulary is consistent across all project files."
 phase: "modeling"
-order: 8
+order: 520
 dependencies: [domain-modeling]
-outputs: [docs/reviews/review-domain-modeling.md]
+outputs: [docs/reviews/review-domain-modeling.md, docs/reviews/domain-modeling/review-summary.md, docs/reviews/domain-modeling/codex-review.json, docs/reviews/domain-modeling/gemini-review.json]
 conditional: null
-knowledge-base: [review-methodology, review-domain-modeling]
+knowledge-base: [review-methodology, review-domain-modeling, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -14,28 +15,51 @@ Deep multi-pass review of the domain models, targeting the specific failure mode
 of domain modeling artifacts. Identify issues, create a fix plan, execute fixes,
 and re-validate.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
 - docs/domain-models/ (required) — domain models to review
-- docs/prd.md (required) — source requirements for coverage checking
+- docs/plan.md (required) — source requirements for coverage checking
 
 ## Expected Outputs
 - docs/reviews/review-domain-modeling.md — review findings, fix plan, and resolution log
 - docs/domain-models/ — updated with fixes
+- docs/reviews/domain-modeling/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/domain-modeling/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/domain-modeling/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- All review passes executed with findings documented
-- Every finding categorized by severity (P0-P3)
-- Fix plan created for P0 and P1 findings
-- Fixes applied and re-validated
-- Downstream readiness confirmed (decisions phase can proceed)
+- (mvp) All review passes executed with findings documented
+- (mvp) Every finding categorized by severity (P0-P3)
+- (mvp) Fix plan created for P0 and P1 findings
+- (mvp) Fixes applied and re-validated
+- (mvp) Downstream readiness confirmed (decisions phase can proceed)
+- (mvp) Entity coverage verified (every PRD feature maps to at least one entity)
+- (deep) Aggregate boundaries verified (each aggregate protects at least one invariant)
+- (deep) Ubiquitous language consistency verified across all domain model files
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
 - **deep**: All review passes from the knowledge base. Full findings report
-  with severity categorization. Fixes applied and re-validated.
+  with severity categorization. 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. Focus on blocking issues only.
 - **custom:depth(1-5)**: Depth 1-2: blocking issues only. Depth 3: add coverage
-  and consistency passes. Depth 4-5: full multi-pass review.
+  and consistency passes. Depth 4: full multi-pass review + one external model
+  (if CLI available). Depth 5: full multi-pass review + multi-model with
+  reconciliation.
 
 ## Mode Detection
 If docs/reviews/review-domain-modeling.md exists, this is a re-review. Read previous
 findings, check which were addressed, run review passes again on updated models.
+If multi-model review artifacts exist under docs/reviews/domain-modeling/,
+preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-domain-modeling.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/parity/platform-parity-review.md

@@ -0,0 +1,90 @@
+---
+name: platform-parity-review
+description: Audit all documentation for platform-specific gaps across target platforms
+summary: "Audits all documentation for platform-specific gaps — features missing on one platform, input pattern differences (touch vs. mouse), and platform-specific testing coverage."
+phase: "parity"
+order: 1010
+dependencies: [review-architecture, review-database, review-api, review-ux]
+outputs: [docs/reviews/platform-parity-review.md, docs/reviews/platform-parity/review-summary.md, docs/reviews/platform-parity/codex-review.json, docs/reviews/platform-parity/gemini-review.json]
+reads: [user-stories, coding-standards, tech-stack, project-structure, tdd, design-system]
+conditional: "if-needed"
+knowledge-base: [cross-phase-consistency, multi-model-review-dispatch, review-step-template, review-methodology]
+---
+
+## Purpose
+When the project targets multiple platforms (web, iOS, Android, desktop), audit
+all documentation to ensure every target platform is thoroughly addressed.
+Identify gaps where one platform was assumed but another was not considered,
+verify feature parity across targets, and ensure platform-specific testing,
+input patterns, and UX considerations are documented.
+
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent platform gap analysis.
+
+## Conditional Evaluation
+This step is conditional ("if-needed"). Enable when:
+- The project targets 2+ platforms (e.g., web + mobile, iOS + Android)
+- `docs/tech-stack.md` lists a cross-platform framework (React Native, Flutter, Expo)
+- `docs/plan.md` mentions multiple deployment targets
+
+Skip when the project targets a single platform only.
+
+## Inputs
+- docs/plan.md (required) — target platforms and version requirements
+- docs/tech-stack.md (required) — cross-platform framework and build approach
+- docs/user-stories.md (required) — stories to check for platform coverage
+- docs/coding-standards.md (required) — platform-specific conventions
+- docs/project-structure.md (optional) — platform-specific file organization
+- docs/tdd-standards.md (optional) — platform-specific testing approach
+- docs/design-system.md (optional) — responsive breakpoints and platform patterns
+- docs/implementation-plan.md (optional — not available, runs before implementation-plan) — tasks covering each platform
+- CLAUDE.md (required) — platform-specific workflow notes
+
+## Expected Outputs
+- docs/reviews/platform-parity-review.md — platform gap analysis report with
+  findings per document, feature parity matrix, and recommended fixes
+- docs/reviews/platform-parity/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/platform-parity/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/platform-parity/gemini-review.json (depth 4+, if available) — raw Gemini findings
+
+## Quality Criteria
+- (mvp) All target platforms identified from PRD and tech-stack.md
+- (mvp) Every user story checked for platform-specific acceptance criteria
+- (deep) Feature parity matrix shows which features work on which platforms
+- (deep) Input pattern differences documented (touch vs. mouse, keyboard shortcuts, gestures)
+- (deep) Platform-specific testing documented (Playwright for web, Maestro for mobile)
+- (deep) Navigation patterns appropriate per platform (sidebar vs. tab bar, etc.)
+- (deep) Offline/connectivity handling addressed per platform (if applicable)
+- (deep) Web version is treated as first-class (not afterthought) if PRD specifies it
+- Fix plan documented for all P0/P1 findings with specific document and section to update
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
+
+## Methodology Scaling
+- **deep**: Comprehensive platform audit across all documents, feature parity
+  matrix, input pattern analysis, navigation pattern review, offline handling,
+  accessibility per platform, and detailed fix recommendations. Multi-model
+  review dispatched to Codex and Gemini if available, with graceful fallback
+  to Claude-only enhanced review.
+- **mvp**: Quick check of user stories and tech-stack for platform coverage.
+  Identify top 3 platform gaps. Skip detailed feature parity matrix.
+- **custom:depth(1-5)**: Depth 1-2: user stories platform check. Depth 3: add
+  tech-stack and coding-standards. Depth 4: add feature parity matrix + one
+  external model (if CLI available). Depth 5: full suite across all documents
+  + multi-model with reconciliation.
+
+## Mode Detection
+Update mode if docs/reviews/platform-parity-review.md exists. In update mode:
+re-run audit against current documents, preserve prior findings still valid,
+note which gaps have been addressed since last review. If multi-model review
+artifacts exist under docs/reviews/platform-parity/, preserve prior findings
+still valid.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/reviews/platform-parity-review.md exists
+- **Preserve**: existing parity findings still valid, platform-specific decisions,
+  feature parity matrix entries for unchanged features
+- **Triggers for update**: specification changes (tech-stack.md, user-stories.md,
+  system-architecture.md updated), new target platform added to PRD, platform-specific
+  coding standards changed
+- **Conflict resolution**: preserve platform-specific decisions already made,
+  merge new findings alongside existing ones rather than replacing

package/pipeline/planning/implementation-plan-review.md

@@ -0,0 +1,67 @@
+---
+name: implementation-plan-review
+description: Review implementation tasks for coverage, feasibility, and multi-model validation
+summary: "Verifies every feature has implementation tasks, no task is too large for one session, the dependency graph has no cycles, and every acceptance criterion maps to at least one task."
+phase: "planning"
+order: 1220
+dependencies: [implementation-plan]
+outputs: [docs/reviews/review-tasks.md, docs/reviews/implementation-plan/task-coverage.json, docs/reviews/implementation-plan/review-summary.md]
+conditional: null
+knowledge-base: [review-methodology, review-implementation-tasks, task-decomposition, multi-model-review-dispatch, review-step-template]
+---
+
+## Purpose
+Review implementation tasks targeting task-specific failure modes: architecture
+coverage gaps, missing dependencies, tasks too large or too vague for agents,
+agent executability violations, critical path inaccuracy, and invalid
+parallelization assumptions. At depth 4+,
+dispatch to independent AI models (Codex/Gemini CLIs) for multi-model validation
+and produce a structured coverage matrix and review summary.
+
+## Inputs
+- docs/implementation-plan.md (required) — tasks to review
+- docs/system-architecture.md (required) — for coverage checking
+- docs/domain-models/ (required) — for completeness
+- docs/user-stories.md (required) — for AC coverage mapping
+- docs/plan.md (required) — for traceability
+- docs/project-structure.md (required) — for file contention analysis
+- docs/tdd-standards.md (required) — for test requirement verification
+
+## Expected Outputs
+- docs/reviews/review-tasks.md — findings and resolution log
+- docs/implementation-plan.md — updated with fixes
+- docs/reviews/implementation-plan/task-coverage.json — AC-to-task coverage matrix (depth 3+)
+- docs/reviews/implementation-plan/review-summary.md — multi-model review summary (depth 4+)
+- docs/reviews/implementation-plan/codex-review.json — raw Codex findings (depth 4+, if available)
+- docs/reviews/implementation-plan/gemini-review.json — raw Gemini findings (depth 4+, if available)
+
+## Quality Criteria
+- (mvp) Architecture coverage verified (every component has tasks)
+- (mvp) Dependency graph is valid DAG
+- (mvp) No task is too large for a single agent session
+- (deep) Critical path is accurate
+- (deep) Parallelization assumptions are valid
+- (deep) Every acceptance criterion maps to at least one task (100% AC coverage)
+- (deep) Every task has verb-first description, >= 1 input file reference, >= 1 acceptance criterion, and defined output artifact
+- (mvp) Every task complies with agent executability rules (3-file, 150-line, single-concern, decision-free, test co-location)
+- (mvp) Tasks exceeding limits have explicit `<!-- agent-size-exception -->` justification
+- (depth 4+) Independent model reviews completed and reconciled
+
+## Methodology Scaling
+- **deep**: Full multi-pass review with multi-model validation. AC coverage
+  matrix. Independent Codex/Gemini dispatches. Detailed reconciliation report.
+- **mvp**: Coverage check only. No external model dispatch.
+- **custom:depth(1-5)**: Depth 1-2: coverage check. Depth 3: add dependency
+  analysis and AC coverage matrix. Depth 4: add one external model. Depth 5:
+  full multi-model with reconciliation.
+
+## Mode Detection
+Re-review mode if previous review exists. If multi-model review artifacts exist
+under docs/reviews/implementation-plan/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-implementation-plan.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/planning/implementation-plan.md

@@ -0,0 +1,110 @@
+---
+name: implementation-plan
+description: Break architecture into implementable tasks with dependencies
+summary: "Breaks your user stories and architecture into concrete tasks — each scoped to ~150 lines of code and 3 files max, with clear acceptance criteria, no ambiguous decisions, and explicit dependencies."
+phase: "planning"
+order: 1210
+dependencies: [tdd, operations, security, review-architecture, create-evals]
+outputs: [docs/implementation-plan.md]
+reads: [create-prd, story-tests, database-schema, api-contracts, ux-spec]
+conditional: null
+knowledge-base: [task-decomposition]
+---
+
+## Purpose
+Decompose user stories and system architecture into concrete, implementable
+tasks suitable for AI agents. Each task should be independently executable,
+have clear inputs/outputs, and be small enough for a single agent session.
+The primary mapping is Story → Task(s), with PRD as the traceability root.
+
+## Inputs
+- docs/system-architecture.md (optional — not available in MVP) — components to implement
+- docs/domain-models/ (optional — not available in MVP) — domain logic to implement
+- docs/adrs/ (optional — not available in MVP) — technology constraints
+- docs/plan.md (required) — features to trace tasks back to
+- docs/user-stories.md (required) — stories to derive tasks from
+- docs/tdd-standards.md (required) — testing requirements to incorporate into tasks
+- docs/operations-runbook.md (optional) — ops requirements to incorporate into tasks
+- docs/security-review.md (optional) — security requirements to incorporate into tasks
+- docs/database-schema.md (optional) — data layer tasks
+- docs/api-contracts.md (optional) — API implementation tasks
+- docs/ux-spec.md (optional) — frontend tasks
+- tests/acceptance/ (optional) — test skeletons to reference in task descriptions
+- docs/story-tests-map.md (optional) — AC-to-test mapping for task coverage verification
+
+## Expected Outputs
+- docs/implementation-plan.md — task list with dependencies, sizing, and
+  assignment recommendations
+
+## Quality Criteria
+- (mvp) Every architecture component has implementation tasks
+- (mvp) Task dependencies form a valid DAG (no cycles)
+- (mvp) Each task produces ~150 lines of net-new application code (excluding tests and generated files)
+- (mvp) Tasks include acceptance criteria (how to know it's done)
+- (mvp) Tasks incorporate testing requirements from the testing strategy
+- (deep) Tasks reference corresponding test skeletons from tests/acceptance/ where applicable
+- (deep) Tasks incorporate security controls from the security review where applicable
+- (deep) Tasks incorporate operational requirements (monitoring, deployment) where applicable
+- (deep) Critical path is identified
+- (deep) Parallelization opportunities are marked with wave plan
+- (mvp) Every user story maps to at least one task
+- (deep) High-risk tasks are flagged with risk type and mitigation
+- (deep) Wave summary produced with agent allocation recommendation
+- (mvp) No task modifies more than 3 application files (test files excluded; exceptions require justification)
+- (mvp) No task contains unresolved design decisions (agents implement, they don't architect)
+- (mvp) Every code-producing task includes co-located test requirements
+- (deep) Critical path identified with estimated total duration
+
+## Methodology Scaling
+- **deep**: Detailed task breakdown with story-to-task tracing. Dependency graph.
+  Sizing estimates. Parallelization plan. Agent context requirements per task.
+  Phased delivery milestones.
+- **mvp**: Ordered task list derived from PRD features and user stories only
+  (architecture, domain models, and ADRs are not available at this depth).
+  Each task has a brief description, rough size estimate, and key dependency.
+  Enough to start working sequentially. Skip architecture decomposition —
+  work directly from user story acceptance criteria.
+- **custom:depth(1-5)**: Depth 1-2: ordered list. Depth 3: add dependencies
+  and sizing. Depth 4-5: full breakdown with parallelization.
+
+## Mode Detection
+Check for docs/implementation-plan.md. If it exists, operate in update mode:
+read existing task list and diff against current architecture, user stories,
+and specification documents. Preserve completed task statuses and existing
+dependency relationships. Add new tasks for new stories or architecture
+components. Re-derive wave plan if dependencies changed. Never remove tasks
+that are in-progress or completed.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/implementation-plan.md exists
+- **Preserve**: completed and in-progress task statuses, existing task IDs,
+  dependency relationships for stable tasks, wave assignments for tasks
+  already started, agent allocation history, architecture decisions,
+  component boundaries
+- **Triggers for update**: architecture changed (new components need tasks),
+  user stories added or changed, security review identified new requirements,
+  operations runbook added deployment tasks, specification docs changed
+- **Conflict resolution**: if architecture restructured a component that has
+  in-progress tasks, flag for user review rather than silently reassigning;
+  re-derive critical path only for unstarted tasks
+
+## Task Size Constraints
+
+Before finalizing the implementation plan, scan every task against the five agent
+executability rules from the task-decomposition knowledge base:
+
+1. **Three-File Rule** — Count application files each task modifies (exclude test files).
+   Any task touching 4+ files must be split by layer or concern.
+2. **150-Line Budget** — Estimate net-new application code lines per task. Any task
+   likely to produce 200+ lines must be split by feature slice or entity.
+3. **Single-Concern Rule** — Check each task description for "and" connecting unrelated
+   work. Split if the task spans multiple architectural layers or feature domains.
+4. **Decision-Free Execution** — Verify all design decisions are resolved in the task
+   description. No "choose", "determine", "decide", or "evaluate options" language.
+   Resolve decisions inline before presenting the plan.
+5. **Test Co-location** — Confirm every code-producing task includes its test
+   requirements. No "write tests later" aggregation tasks.
+
+Tasks that fail any rule should be split inline. If a task genuinely can't be split
+further, annotate with `<!-- agent-size-exception: reason -->`. The implementation
+plan review will flag unjustified exceptions.