@zigrivers/scaffold 2.28.1 → 2.38.1

package/pipeline/finalization/implementation-playbook.md

@@ -1,10 +1,12 @@
 ---
 name: implementation-playbook
 description: Create the playbook that AI agents follow during implementation
+summary: "Writes the playbook agents reference during every coding session — task execution order, which docs to read before each task, the TDD loop to follow, quality gates to pass, and the handoff format between agents."
 phase: "finalization"
 order: 1430
 dependencies: [developer-onboarding-guide]
 outputs: [docs/implementation-playbook.md]
+reads: [story-tests, create-evals, implementation-plan, database-schema, api-contracts, ux-spec, design-system, system-architecture, tdd, coding-standards, security, operations]
 conditional: null
 knowledge-base: [implementation-playbook]
 ---
@@ -19,27 +21,54 @@ format between agents, and success criteria.
 - docs/implementation-plan.md (required) — tasks to sequence
 - docs/system-architecture.md (required) — architecture context
 - docs/tdd-standards.md (required) — testing requirements
+- tests/acceptance/ (required if exists) — test skeletons agents implement during TDD
+- docs/story-tests-map.md (required if exists) — story-to-test mapping for progress tracking
+- tests/evals/ (required if exists) — project eval checks to run as quality gates
+- docs/eval-standards.md (required if exists) — what evals check and what they don't
+- docs/plan.md (optional) — PRD for requirement traceability
+- docs/user-stories.md (optional) — acceptance criteria source
+- docs/database-schema.md (optional) — for data-layer task context
+- docs/api-contracts.md (optional) — for API endpoint task context
+- docs/ux-spec.md (optional) — for UI task context
+- docs/design-system.md (optional) — for styling task context
+- docs/security-review.md (optional) — for security control task context
+- docs/operations-runbook.md (optional) — for deployment task context
+- docs/onboarding-guide.md (optional — not available in MVP) — agents should read for project context before playbook
 - All other frozen artifacts
 
 ## Expected Outputs
 - docs/implementation-playbook.md — agent implementation playbook
 
 ## Quality Criteria
-- Task execution order is clear and respects dependencies
-- Each task has context requirements (which docs to read before starting)
-- Coding standards are defined (naming, patterns, error handling)
-- Git workflow is defined (branching strategy, commit format, PR process)
-- Success criteria per task (how to know it's done)
-- Handoff format between agents (what to communicate when passing work)
-- Quality gates are defined (what must pass before a task is complete)
+- (mvp) Task execution order is clear and respects dependencies
+- (deep) Each task has context requirements (which docs to read before starting)
+- (mvp) Coding standards are defined (naming, patterns, error handling)
+- (mvp) Git workflow is defined (branching strategy, commit format, PR process)
+- (mvp) Success criteria per task (how to know it's done)
+- (deep) Handoff format between agents (what to communicate when passing work)
+- (mvp) Quality gates are defined (what must pass before a task is complete)
+- Quality gates include `make eval` (or equivalent) as a required check
+- (deep) Agent workflow references test skeleton implementation from tests/acceptance/
+- (deep) Handoff format includes at minimum: implementation summary, assumptions made, known limitations, gotchas, and files modified
 
 ## Methodology Scaling
 - **deep**: Full playbook. Detailed coding standards, git workflow with
   examples, per-task context briefs, inter-agent communication protocol,
   rollback procedures for failed tasks.
-- **mvp**: Task order, basic coding conventions, commit format, "run tests
-  before marking done."
-- **custom:depth(1-5)**: Scale detail with depth.
+- **mvp**: Minimal playbook with task execution order, basic coding conventions
+  reference, commit format, and quality gate commands from CLAUDE.md. Skip
+  per-task context blocks, wave assignments, and inter-agent handoff format.
+  Reference docs/coding-standards.md and docs/tdd-standards.md directly.
+- **custom:depth(1-5)**: Depth 1-2: task execution order, basic coding conventions reference, commit format, and quality gate commands. Depth 3: add per-task context requirements, wave assignments, and quality gates per wave. Depth 4: add inter-agent communication protocol, handoff format, and error recovery procedures. Depth 5: full playbook with rollback procedures, eval integration, and per-task minimum context blocks.
 
 ## Mode Detection
-Update mode if playbook exists.
+Check if `docs/implementation-playbook.md` already exists.
+- If exists: UPDATE MODE — read current playbook, identify changes in implementation plan or upstream docs, update per-task context blocks and wave assignments while preserving completed task status and agent allocation history.
+- If not: FRESH MODE — generate from scratch using implementation plan and all supporting docs.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/implementation-playbook.md` exists with tracking comment
+- **Preserve**: Completed task statuses, agent handoff notes, established patterns, quality gate results
+- **Triggers**: New tasks added, wave assignments changed, quality gate definitions updated
+- **Conflict resolution**: New tasks append to existing waves; never remove completed task records

package/pipeline/foundation/beads.md

@@ -1,6 +1,7 @@
 ---
 name: beads
 description: Initialize Beads task tracking with CLAUDE.md conventions and lessons file
+summary: "Sets up Beads task tracking with a lessons-learned file for cross-session learning, and creates the initial CLAUDE.md skeleton with core principles and workflow conventions."
 phase: "foundation"
 order: 210
 dependencies: []
@@ -26,14 +27,15 @@ and autonomous behavior guidelines.
   Self-Improvement, and Autonomous Behavior sections
 
 ## Quality Criteria
-- `bd ready` executes without error (Beads is initialized)
-- .beads/ directory exists and contains Beads data files
-- Beads git hooks are installed (data-sync hooks, not code-quality hooks)
-- tasks/lessons.md exists with Patterns, Anti-Patterns, and Common Gotchas sections
-- CLAUDE.md contains Core Principles with all four tenets (Simplicity, No Laziness, TDD, Prove It)
-- CLAUDE.md contains Beads command reference table
+- (mvp) `bd ready` executes without error (Beads is initialized)
+- (mvp) .beads/ directory exists and contains Beads data files
+- (mvp) Beads git hooks are installed (data-sync hooks, not code-quality hooks)
+- (mvp) tasks/lessons.md exists with Patterns, Anti-Patterns, and Common Gotchas sections
+- (mvp) CLAUDE.md contains Core Principles with all four tenets (Simplicity, No Laziness, TDD, Prove It)
+- (mvp) CLAUDE.md contains Beads command reference table
 - CLAUDE.md contains commit-message convention requiring Beads task IDs
 - Bootstrap commit uses `[BD-0]` convention
+- (deep) Cross-doc consistency verified against git-workflow.md and coding-standards.md
 
 ## Methodology Scaling
 - **deep**: Full Beads setup with all CLAUDE.md sections, detailed command reference
@@ -51,7 +53,8 @@ setup), or user explicitly enables structured task management. Skip when: user p
 GitHub Issues, Linear, or another task tracker, or explicitly declines Beads setup.
 
 ## Mode Detection
-Update mode if .beads/ directory exists. In update mode: never re-initialize
+Update mode if .beads/ contains a config.json or tasks directory (not just an
+empty directory). In update mode: never re-initialize
 .beads/ (existing task data is irreplaceable), never overwrite tasks/lessons.md
 (only add missing sections), update CLAUDE.md Beads sections in-place preserving
 project-specific customizations.

package/pipeline/foundation/coding-standards.md

@@ -1,6 +1,7 @@
 ---
 name: coding-standards
 description: Create prescriptive coding standards tailored to the project's tech stack
+summary: "Creates coding standards tailored to your tech stack — naming conventions, error handling patterns, import organization, AI-specific rules — and generates working linter and formatter config files."
 phase: "foundation"
 order: 230
 dependencies: [tech-stack]
@@ -36,8 +37,9 @@ self-review checklist.
 - AI-specific coding rules section addresses common AI mistakes (dead code,
   duplication, magic numbers, premature abstraction, unnecessary features)
 - Linter/formatter configs created and referenced from the document
-- No aspirational standards — only rules enforced from day one
-- Code review checklist is actionable (not vague)
+- Every standard has a corresponding linter rule, code review checklist item, or test pattern that enforces it
+- Every code review checklist item is a binary yes/no question
+- (mvp) Linter/formatter config files are valid (lint command runs without config errors)
 
 ## Methodology Scaling
 - **deep**: Comprehensive standards with examples for every section. Stack-specific
@@ -62,7 +64,8 @@ and CI config for references.
   project-specific patterns added by the team
 - **Triggers for update**: tech stack changed (new language or framework
   requires new patterns), new architecture patterns need coding conventions,
-  team identified recurring issues needing new rules
+  team identified recurring issues needing new rules, commit message format
+  changed in docs/git-workflow.md
 - **Conflict resolution**: if tech stack added a new framework, add its
   conventions as a new section rather than modifying existing sections;
   verify commit format consistency with git-workflow.md before any changes

package/pipeline/foundation/project-structure.md

@@ -1,11 +1,12 @@
 ---
 name: project-structure
 description: Design directory layout and scaffold the actual project structure
+summary: "Designs a directory layout optimized for parallel AI agent work (minimizing file conflicts), documents where each type of file belongs, and creates the actual directories in your project."
 phase: "foundation"
 order: 250
 dependencies: [tech-stack, coding-standards]
 outputs: [docs/project-structure.md]
-reads: [create-prd, user-stories]
+reads: [create-prd, user-stories, tdd]
 conditional: null
 knowledge-base: [project-structure-patterns]
 ---
@@ -40,6 +41,9 @@ with a Quick Reference section for file placement.
 - Test file location aligns with tdd-standards.md (if it exists)
 - .gitignore covers all generated files for the tech stack
 - Structure follows the chosen framework's conventions
+- CLAUDE.md contains Project Structure Quick Reference section with file placement table
+- (mvp) All documented directories exist on disk with .gitkeep placeholder files
+- CLAUDE.md Project Structure Quick Reference matches the directory tree in docs/project-structure.md
 
 ## Methodology Scaling
 - **deep**: Comprehensive structure with high-contention analysis, shared code

package/pipeline/foundation/tdd.md

@@ -1,11 +1,12 @@
 ---
 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]
+reads: [create-prd, system-architecture]
 conditional: null
 knowledge-base: [testing-strategy]
 ---
@@ -14,6 +15,8 @@ knowledge-base: [testing-strategy]
 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
@@ -27,18 +30,19 @@ code they write and establishes testing standards before implementation begins.
 - docs/tdd-standards.md — testing approach with coverage goals and patterns
 
 ## Quality Criteria
-- Test pyramid defined with coverage targets per layer
-- Testing patterns specified for each layer (unit, integration, e2e)
-- Quality gates defined (what must pass before merge)
+- (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
-- Performance testing approach for critical paths
+- (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)**: Scale detail with depth.
+- **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

package/pipeline/foundation/tech-stack.md

@@ -1,13 +1,14 @@
 ---
 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]
+knowledge-base: [tech-stack-selection, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -33,14 +34,13 @@ about ecosystem maturity, alternatives, and gotchas.
 - docs/reviews/tech-stack/gemini-review.json (depth 4+, if available) — raw Gemini recommendations
 
 ## Quality Criteria
-- Every PRD feature cross-referenced against the proposed stack (no capability gaps)
-- Each technology choice documents what, why, why not alternatives, and AI compatibility
-- Architecture pattern chosen and justified (monolith vs. microservices, MVC vs. clean, etc.)
-- No speculative technologies ("might need someday")
-- Every choice is a decision, not a menu of options
-- Quick Reference section lists every dependency with version
-- Stack optimizes for AI familiarity, convention over configuration, minimal dependencies,
-  strong typing, and mature ecosystem
+- (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

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

@@ -1,11 +1,12 @@
 ---
 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: [tdd, coding-standards]
+reads: [coding-standards, user-stories]
 conditional: "if-needed"
 knowledge-base: [testing-strategy]
 ---
@@ -34,13 +35,17 @@ Outputs vary by detected platform:
 - (both) All of the above
 
 ## Quality Criteria
-- Platform detection is explicit and logged (web, mobile, both, or skip)
-- (web) Playwright config uses framework-specific dev server command and port
-- (web) Smoke test passes (navigate, screenshot, close)
-- (mobile) Maestro CLI installed, sample flow executes, screenshot captured
+- (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
-- E2E section in tdd-standards.md distinguishes when to use E2E vs unit tests
+- (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,
@@ -63,3 +68,13 @@ 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,11 +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: 510
 dependencies: [review-user-stories]
 outputs: [docs/domain-models/]
-reads: [coding-standards]
+reads: [coding-standards, innovate-user-stories]
 conditional: null
 knowledge-base: [domain-modeling]
 ---
@@ -34,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

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: 520
 dependencies: [domain-modeling]
 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
@@ -29,11 +30,14 @@ independent review validation.
 - 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
@@ -52,3 +56,10 @@ If docs/reviews/review-domain-modeling.md exists, this is a re-review. Read prev
 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

@@ -1,13 +1,14 @@
 ---
 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]
+reads: [user-stories, coding-standards, tech-stack, project-structure, tdd, design-system]
 conditional: "if-needed"
-knowledge-base: [cross-phase-consistency]
+knowledge-base: [cross-phase-consistency, multi-model-review-dispatch, review-step-template, review-methodology]
 ---
 
 ## Purpose
@@ -20,6 +21,14 @@ 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
@@ -28,7 +37,7 @@ independent platform gap analysis.
 - 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) — tasks covering each platform
+- docs/implementation-plan.md (optional — not available, runs before implementation-plan) — tasks covering each platform
 - CLAUDE.md (required) — platform-specific workflow notes
 
 ## Expected Outputs
@@ -39,14 +48,15 @@ independent platform gap analysis.
 - docs/reviews/platform-parity/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- All target platforms identified from PRD and tech-stack.md
-- Every user story checked for platform-specific acceptance criteria
-- Feature parity matrix shows which features work on which platforms
-- Input pattern differences documented (touch vs. mouse, keyboard shortcuts, gestures)
-- Platform-specific testing documented (Playwright for web, Maestro for mobile)
-- Navigation patterns appropriate per platform (sidebar vs. tab bar, etc.)
-- Offline/connectivity handling addressed per platform (if applicable)
-- Web version is treated as first-class (not afterthought) if PRD specifies it
+- (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
@@ -68,3 +78,13 @@ 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

@@ -1,18 +1,20 @@
 ---
 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]
+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,
-critical path inaccuracy, and invalid parallelization assumptions. At depth 4+,
+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.
 
@@ -34,14 +36,16 @@ and produce a structured coverage matrix and review summary.
 - docs/reviews/implementation-plan/gemini-review.json — raw Gemini findings (depth 4+, if available)
 
 ## Quality Criteria
-- Architecture coverage verified (every component has tasks)
-- Dependency graph is valid DAG
-- No task is too large for a single agent session
-- Critical path is accurate
-- Parallelization assumptions are valid
-- Every acceptance criterion maps to at least one task (100% AC coverage)
-- Task descriptions are unambiguous enough for AI agents (agent-implementable)
-- At depth 4+: independent model reviews completed and reconciled
+- (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
@@ -54,3 +58,10 @@ and produce a structured coverage matrix and review summary.
 ## 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