@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/validation/dependency-validation.md

@@ -8,6 +8,18 @@ topics: [validation, dependencies, graphs, cycles, ordering, parallelization]
 
 Dependency validation extracts all dependency relationships between implementation tasks, builds a graph, checks for correctness, and verifies that the ordering matches architectural constraints. A valid dependency graph ensures that tasks can be executed in an order that never requires unbuilt dependencies.
 
+## Summary
+
+- Extract dependencies from task declarations, architecture data flows, schema foreign keys, API contract prerequisites, and implicit shared resources.
+- **Cycle detection**: Use Kahn's algorithm to find tasks that can never start; resolve by splitting tasks into "define interface" and "implement interface."
+- **Completeness check**: Every referenced task ID must exist in the task list; orphaned dependencies indicate renames, removals, or typos.
+- **Ordering validation**: Dependencies should follow architectural layer ordering (infrastructure -> schema -> domain -> service -> API -> frontend -> tests).
+- **Parallel independence**: Tasks with no dependency path between them must not share mutable files, tables, or configuration.
+- **Critical path analysis**: Identify the longest sequential chain to determine minimum project duration and focus optimization efforts.
+- **Fan-in/fan-out analysis**: High fan-in tasks are blockers (prioritize and split); high fan-out tasks start late (review whether all dependencies are necessary).
+
+## Deep Guidance
+
 ## What a Dependency Graph Represents
 
 Each node in the graph is an implementation task. Each directed edge represents a "must complete before" relationship: if task A depends on task B, then B must be completed before A can start.

package/knowledge/validation/scope-management.md

@@ -8,6 +8,18 @@ topics: [validation, scope, creep, prd-alignment, gold-plating]
 
 Scope management validation compares every specification artifact against the PRD to ensure that the documented system matches what was actually requested. Features that cannot be traced to a PRD requirement are scope creep. Requirements that grew during documentation are scope inflation. Extra polish on non-critical features is gold-plating. This validation catches all three.
 
+## Summary
+
+- **Feature-to-PRD tracing**: Classify every capability as traced (maps to PRD), supporting (necessary infrastructure), or creep (no PRD justification).
+- **Scope inflation detection**: Compare each PRD requirement's original scope to its implementation scope; flag features that grew beyond what was requested.
+- **Gold-plating detection**: Over-abstraction, premature optimization, excessive error handling, and UI polish beyond requirements. Test: "If removed, would any PRD requirement be unmet?"
+- **Deferred scope leakage**: Verify explicitly deferred items (v2 features) do not appear in specifications, including partial infrastructure for deferred features.
+- **NFR scope alignment**: Implementation targets should match PRD targets, not exceed them (e.g., 99.9% uptime, not 99.99%).
+- **Decision framework**: When in doubt, defer. Scope additions are kept only if required for a PRD feature to work and do not significantly increase effort or operational complexity.
+- Run scope validation after all documentation phases and before implementation begins.
+
+## Deep Guidance
+
 ## Why Scope Grows
 
 Scope grows during the documentation pipeline for understandable reasons — but each growth increases implementation effort, risk, and timeline. Common causes:

package/knowledge/validation/traceability.md

@@ -8,6 +8,18 @@ topics: [validation, traceability, requirements, coverage]
 
 Traceability validation ensures that every requirement flows from its origin in the PRD through domain modeling, architecture decisions, system design, and into implementable tasks. A complete traceability matrix is the strongest evidence that nothing has been lost or invented during the documentation pipeline.
 
+## Summary
+
+- **Traceability matrix**: A table where each row is a requirement and columns are pipeline artifacts (domain, ADR, architecture, schema, API, UX, tasks, tests). Empty cells are gaps.
+- **Build process**: Extract all PRD requirements (functional, NFR, constraints, deferred), then trace each forward through every downstream artifact.
+- **Gap detection**: Empty cells (not N/A), orphaned artifacts tracing to no requirement, thin traces, and deferred items appearing downstream.
+- **Bidirectional tracing**: Forward (requirement -> implementation) catches gaps; backward (implementation -> requirement) catches scope creep.
+- **NFR tracing**: Performance, security, and accessibility requirements cut across components and need special tracing through architecture, schema, API, testing, and UX.
+- **Common issues**: Orphan features, assumed infrastructure, tested-but-not-specified behaviors, specified-but-not-tested requirements, and split requirements across unlinked tasks.
+- Use consistent identifiers (REQ-001, ADR-003, T-012) so traces are searchable across all artifacts.
+
+## Deep Guidance
+
 ## What a Traceability Matrix Is
 
 A traceability matrix is a table where each row represents a requirement and each column represents a pipeline artifact. A complete row means the requirement is fully traced from origin to implementation. A missing cell means a gap — either the requirement was not addressed at that phase, or it was addressed but the connection is not explicit.

package/methodology/README.md

@@ -0,0 +1,37 @@
+# Methodology Depth Levels
+
+The scaffold pipeline supports 5 depth levels that control the thoroughness of each step's output.
+
+| Depth | Name | Description |
+|-------|------|-------------|
+| 1 | Minimal | Bare minimum viable output. Just enough to start building. |
+| 2 | Light | Slightly more detail than minimal. Still focused on speed over completeness. |
+| 3 | Balanced | Recommended for most projects. Good coverage without excessive documentation. |
+| 4 | Thorough | Comprehensive output with external model validation (Codex/Gemini) when available. |
+| 5 | Exhaustive | Maximum detail with multi-model reconciliation. Best for critical or regulated projects. |
+
+## Presets
+
+| Preset | Default Depth | Philosophy |
+|--------|---------------|------------|
+| `mvp.yml` | 1 | Ship fast. Only essential steps enabled. No review cycles beyond PRD/stories. |
+| `custom-defaults.yml` | 3 | Balanced. Most steps enabled. Innovation and automated review disabled by default. |
+| `deep.yml` | 5 | Maximum quality. All steps enabled. External model dispatch at depth 4+. |
+
+## How Depth Affects Steps
+
+Each pipeline step defines a `## Methodology Scaling` section with behavior at each depth:
+- **mvp** bullet: What the step produces at depth 1-2
+- **deep** bullet: What the step produces at depth 4-5
+- **custom:depth(1-5)** bullet: Explicit per-level breakdown
+
+Depth 3 is typically the inflection point where steps add structure, cross-references, and validation beyond the basics.
+
+## Depth Tags in Quality Criteria
+
+Quality Criteria items may be tagged:
+- `(mvp)` — applies at all depths (depth 1+)
+- `(deep)` — applies only at depth 4+
+- `(depth N+)` — applies at depth N and above
+
+Untagged criteria apply at all depths by default.

package/methodology/custom-defaults.yml

@@ -3,34 +3,66 @@ name: Custom
 description: Choose which steps to include and how deep to go
 default_depth: 3
 
-# All steps enabled by default at depth 3 — user overrides individual steps
+# Most steps enabled by default at depth 3 — innovation and automated-pr-review disabled by default, user overrides individual steps
 steps:
+  # Phase 0 — Product Vision (vision)
+  create-vision: { enabled: true }
+  review-vision: { enabled: true }
+  innovate-vision: { enabled: false }
+  # 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: 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: false }
+  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 }
@@ -38,6 +70,14 @@ 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 }
+  # Phase 15 — Build (build) — stateless, on-demand execution steps
+  single-agent-start: { enabled: true }
+  single-agent-resume: { enabled: true }
+  multi-agent-start: { enabled: true }
+  multi-agent-resume: { enabled: true }
+  quick-task: { enabled: true }
+  new-enhancement: { enabled: true }

package/methodology/deep.yml

@@ -4,32 +4,64 @@ description: Comprehensive documentation for complex systems — full analysis a
 default_depth: 5
 
 steps:
+  # Phase 0 — Product Vision (vision)
+  create-vision: { enabled: true }
+  review-vision: { enabled: true }
+  innovate-vision: { enabled: true, conditional: "if-needed" }
+  # 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 +69,14 @@ 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 }
+  # Phase 15 — Build (build) — stateless, on-demand execution steps
+  single-agent-start: { enabled: true }
+  single-agent-resume: { enabled: true }
+  multi-agent-start: { enabled: true }
+  multi-agent-resume: { enabled: true }
+  quick-task: { enabled: true }
+  new-enhancement: { enabled: true }

package/methodology/mvp.yml

@@ -4,32 +4,64 @@ description: Get to code fast with minimal ceremony
 default_depth: 1
 
 steps:
+  # Phase 0 — Product Vision (vision)
+  create-vision: { enabled: true }
+  review-vision: { enabled: true }
+  innovate-vision: { enabled: false }
+  # 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 +69,14 @@ 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 }
+  # Phase 15 — Build (build) — stateless, on-demand execution steps
+  single-agent-start: { enabled: true }
+  single-agent-resume: { enabled: true }
+  multi-agent-start: { enabled: true }
+  multi-agent-resume: { enabled: true }
+  quick-task: { enabled: true }
+  new-enhancement: { enabled: true }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zigrivers/scaffold",
-  "version": "2.1.2",
+  "version": "2.38.0",
   "description": "AI-powered software project scaffolding pipeline",
   "type": "module",
   "keywords": [
@@ -26,6 +26,7 @@
     "pipeline/",
     "knowledge/",
     "methodology/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],
@@ -40,11 +41,11 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:bench": "vitest bench",
+    "test:perf": "vitest run tests/performance/",
     "lint": "eslint src/ tests/",
     "type-check": "tsc --noEmit",
     "check": "npm run lint && npm run type-check && npm test",
-    "prepublish": "bash scripts/prepublish.sh"
+    "prepublishOnly": "bash scripts/prepublish.sh"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.4.0",

package/pipeline/architecture/review-architecture.md

@@ -1,12 +1,14 @@
 ---
 name: review-architecture
 description: Review system architecture for completeness and downstream readiness
+summary: "Verifies every domain concept lands in a component, every decision constraint is respected, no components are orphaned from data flows, and the module structure minimizes merge conflicts."
 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]
+reads: [domain-modeling]
 conditional: null
-knowledge-base: [review-methodology, review-system-architecture]
+knowledge-base: [review-methodology, review-system-architecture, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -15,30 +17,51 @@ 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
-- Domain model coverage verified (every model maps to a component)
-- ADR constraint compliance verified
-- Data flow completeness verified (no orphaned components)
-- Module structure validated for practical concerns
-- Downstream readiness confirmed (specification, quality, and planning steps can proceed)
+- (mvp) Domain model coverage verified (every model maps to a component)
+- (mvp) ADR constraint compliance verified
+- (deep) All architecture-specific review passes executed
+- (deep) Data flow completeness verified (no orphaned components)
+- (deep) Module structure assessed for merge conflict risk, circular dependency risk, and import depth
+- (mvp) Downstream readiness confirmed (specification, quality, and planning steps can proceed)
+- (mvp) Every finding categorized P0-P3 with specific component, section, and issue
+- (mvp) Fix plan documented for all P0/P1 findings; fixes applied to system-architecture.md and re-validated
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## 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.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-architecture.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/architecture/system-architecture.md

@@ -1,34 +1,38 @@
 ---
 name: system-architecture
 description: Design and document system architecture
+summary: "Designs the system blueprint — which components exist, how data flows between them, where each module lives in the directory tree, and where extension points allow custom behavior."
 phase: "architecture"
-order: 11
+order: 710
 dependencies: [review-adrs]
 outputs: [docs/system-architecture.md]
+reads: [create-prd, domain-modeling, adrs]
 conditional: null
-knowledge-base: [system-architecture]
+knowledge-base: [system-architecture, domain-modeling]
 ---
 
 ## Purpose
 Design and document the system architecture, translating domain models and ADR
 decisions into a concrete component structure, data flows, and module
-organization. Project directory structure and module organization are defined here.
+organization. Project directory structure and module organization are defined
+here. This is the blueprint that agents reference when deciding where code
+lives and how components communicate.
 
 ## 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,
   data flows, module structure, and extension points
 
 ## Quality Criteria
-- Every domain model lands in a component or module
-- Every ADR constraint is respected in the architecture
-- All components appear in at least one data flow diagram
-- Extension points are both documented and designed (not just listed)
-- Project directory structure is defined with file-level granularity
+- (mvp) Every domain model lands in a component or module
+- (mvp) Every ADR constraint is respected in the architecture
+- (mvp) All components appear in at least one data flow diagram
+- (deep) Each extension point has interface definition, example usage scenario, and constraints on what can/cannot be extended
+- (mvp) Project directory structure is defined with file-level granularity
 
 ## Methodology Scaling
 - **deep**: Full architecture document. Component diagrams, data flow diagrams,
@@ -43,3 +47,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