@zigrivers/scaffold 2.1.2 → 2.28.1

package/pipeline/environment/design-system.md

@@ -0,0 +1,73 @@
+---
+name: design-system
+description: Create a cohesive design system with tokens and component patterns for frontend
+phase: "environment"
+order: 320
+dependencies: [dev-env-setup]
+outputs: [docs/design-system.md]
+conditional: "if-needed"
+knowledge-base: [design-system-tokens]
+---
+
+## Purpose
+Define a complete visual language (colors, typography, spacing, borders, shadows)
+and configure the frontend framework's theme with these design tokens. Document
+reusable component patterns so all AI agents build consistent, accessible,
+professional UI without requiring design expertise from the user.
+
+## Inputs
+- docs/tech-stack.md (required) — frontend framework and UI library choices
+- docs/plan.md (required) — application purpose and target users inform design direction
+- User preferences (gathered via questions) — overall feel, color preferences,
+  reference apps, dark mode requirement
+
+## Expected Outputs
+- docs/design-system.md — color palette, typography scale, spacing scale, border
+  radius, shadows, component patterns (buttons, forms, cards, feedback, navigation,
+  data display), layout system, and do's/don'ts
+- Theme configuration files (tailwind.config.js, theme.ts, CSS custom properties, etc.)
+- Example implementation page demonstrating the design system
+- docs/coding-standards.md updated with Styling / Design System section
+- CLAUDE.md updated with Design System section and quick reference
+
+## Quality Criteria
+- All colors meet WCAG AA contrast requirements
+- Typography scale is consistent and readable
+- Spacing uses a consistent base unit (e.g., 4px increments)
+- Component patterns cover buttons, forms, cards, feedback, navigation, data display
+- Theme configuration files actually work (verified by running dev server)
+- Both light and dark mode token values provided (if dark mode requested)
+- Responsive breakpoints defined (mobile, tablet, desktop)
+- No arbitrary hex values or pixel values in component examples (all use tokens)
+
+## Methodology Scaling
+- **deep**: Full design system with all component categories, dark mode support,
+  responsive breakpoints, animation guidelines, accessibility audit, and example
+  page demonstrating all patterns. 15-20 pages.
+- **mvp**: Color palette, typography, spacing scale, and button/form/card patterns.
+  No dark mode. Basic theme config. 3-5 pages.
+- **custom:depth(1-5)**: Depth 1-2: colors + typography + buttons. Depth 3: add
+  forms, cards, spacing. Depth 4: add navigation, data display, layout. Depth 5:
+  full suite with dark mode and accessibility.
+
+## Conditional Evaluation
+Enable when: tech-stack.md includes a frontend framework (React, Vue, Angular, Svelte,
+etc.), plan.md describes a UI-based application, or project targets web/mobile
+platforms. Skip when: project is backend-only, a CLI tool, or a library with no UI.
+
+## Mode Detection
+Update mode if docs/design-system.md exists. In update mode: never change color
+values, font families, or spacing scales without user approval. Preserve all
+theme config file customizations.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/design-system.md exists
+- **Preserve**: color palette, typography scale, spacing scale, existing
+  component patterns, theme configuration files, dark mode token values,
+  responsive breakpoint definitions
+- **Triggers for update**: new UI features need new component patterns, UX spec
+  requires additional interaction states, accessibility audit identified contrast
+  issues, user requests design direction change
+- **Conflict resolution**: if a new component pattern conflicts with existing
+  token usage, extend the token set rather than modifying existing values;
+  always verify WCAG AA compliance after any color changes

package/pipeline/environment/dev-env-setup.md

@@ -0,0 +1,65 @@
+---
+name: dev-env-setup
+description: Configure local dev environment with live reload and simple commands
+phase: "environment"
+order: 310
+dependencies: [project-structure]
+outputs: [docs/dev-setup.md]
+conditional: null
+knowledge-base: [dev-environment]
+---
+
+## Purpose
+Set up a complete local development environment with a one-command dev experience,
+live/hot reloading, local database configuration, environment variable management,
+and beginner-friendly documentation. Populates the CLAUDE.md Key Commands table
+which becomes the single source of truth for project-specific commands referenced
+by the entire workflow.
+
+## Inputs
+- docs/tech-stack.md (required) — determines dev server, database, and tooling
+- docs/project-structure.md (required) — where config files live
+- docs/coding-standards.md (optional) — linter/formatter already configured
+- docs/tdd-standards.md (optional) — test runner, flags, coverage thresholds, quality gates
+
+## Expected Outputs
+- docs/dev-setup.md — getting started guide, daily development, common tasks,
+  troubleshooting, and AI agent instructions
+- Makefile or package.json scripts (dev, test, test:watch, lint, db-setup, db-reset)
+- .env.example with all required variables and sensible local defaults
+- CLAUDE.md updated with Key Commands table and Dev Environment section
+
+## Quality Criteria
+- Dev server starts with a single command and supports live/hot reloading
+- Local database setup is scripted (if applicable)
+- .env.example documents all variables with comments
+- Key Commands table in CLAUDE.md matches actual Makefile/package.json commands
+- Lint and test commands exist and are runnable
+- Verification checklist passes (install, dev server, browser, live reload, tests, db)
+- Setup process works for first-time clone (max 5 steps)
+
+## Methodology Scaling
+- **deep**: Full environment with database setup, seed data, Docker Compose (if
+  needed), watch mode tests, multi-platform instructions (Mac, Linux, WSL),
+  troubleshooting section. Complete Key Commands table.
+- **mvp**: Dev server with live reload, basic lint and test commands, .env.example.
+  Minimal docs. Key Commands table with essentials only.
+- **custom:depth(1-5)**: Depth 1-2: dev server + test command. Depth 3: add
+  database and env vars. Depth 4: add troubleshooting. Depth 5: full docs with
+  multi-platform support.
+
+## Mode Detection
+Update mode if docs/dev-setup.md exists. In update mode: preserve port assignments,
+custom scripts, .env variable names, database configuration, and Makefile
+customizations. Update CLAUDE.md Key Commands section in-place.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/dev-setup.md exists
+- **Preserve**: port assignments, .env variable names and defaults, database
+  connection strings, custom Makefile targets, troubleshooting entries
+- **Triggers for update**: tech stack changed (new dev server or database),
+  project structure changed (new config file locations), new dependencies
+  require setup steps, tdd-standards.md changed test commands
+- **Conflict resolution**: if a new dependency conflicts with an existing port
+  or env var, propose a non-breaking alternative; always update CLAUDE.md Key
+  Commands table to match actual Makefile/package.json after changes

package/pipeline/environment/git-workflow.md

@@ -0,0 +1,71 @@
+---
+name: git-workflow
+description: Configure git workflow with branching, PRs, CI, and worktree scripts for parallel agents
+phase: "environment"
+order: 330
+dependencies: [dev-env-setup]
+outputs: [docs/git-workflow.md]
+conditional: null
+knowledge-base: [dev-environment]
+---
+
+## Purpose
+Configure the repository for parallel Claude Code sessions working simultaneously.
+Define branching strategy (one task = one branch = one PR), commit standards
+(with Beads task IDs if configured, conventional commits otherwise), rebase
+strategy, PR workflow with squash-merge and auto-merge, worktree setup for
+parallel agents, CI pipeline, branch protection, and conflict prevention rules.
+
+## Inputs
+- CLAUDE.md (required) — Key Commands table for lint/test/install commands
+- docs/tech-stack.md (required) — CI environment setup (language, runtime)
+- docs/coding-standards.md (required) — commit message format reference
+
+## Expected Outputs
+- docs/git-workflow.md — branching strategy, commit standards, rebase strategy,
+  PR workflow (8 sub-steps), task closure, agent crash recovery, branch protection,
+  conflict prevention, and worktree documentation
+- scripts/setup-agent-worktree.sh — permanent worktree creation script
+- .github/workflows/ci.yml — CI workflow with lint and test jobs
+- .github/pull_request_template.md — PR template with task ID format
+- CLAUDE.md updated with Committing/PR Workflow, Task Closure, Parallel Sessions,
+  Worktree Awareness, and Code Review sections
+
+## Quality Criteria
+- Branch naming format is consistent (Beads: bd-<task-id>/<desc>. Non-Beads: <type>/<desc>)
+- Commit format is consistent (Beads: [BD-<id>] type(scope): desc. Non-Beads: type(scope): desc)
+- PR workflow includes all 8 sub-steps (commit, AI review, rebase, push, create,
+  auto-merge with --delete-branch, watch CI, confirm merge)
+- Worktree script creates permanent worktrees with workspace branches
+- If Beads: BD_ACTOR environment variable documented for agent identity
+- CI workflow job name matches branch protection context
+- Branch cleanup documented for both single-agent and worktree-agent variants
+- Agent crash recovery procedure documented
+- Conflict prevention rule: don't parallelize tasks touching same files
+
+## Methodology Scaling
+- **deep**: Full git workflow with all sections, CI pipeline, branch protection
+  via gh api, worktree script, PR template, agent crash recovery, batch branch
+  cleanup, and comprehensive CLAUDE.md updates.
+- **mvp**: Branching strategy, commit format, basic PR workflow, CI config.
+  Skip worktree script and crash recovery. Minimal CLAUDE.md updates.
+- **custom:depth(1-5)**: Depth 1-2: branching + commits + CI. Depth 3: add PR
+  workflow and branch protection. Depth 4: add worktrees and crash recovery.
+  Depth 5: full suite with all sections.
+
+## Mode Detection
+Update mode if docs/git-workflow.md exists. In update mode: never rename CI jobs
+without checking branch protection rules, preserve worktree directory naming,
+keep setup-agent-worktree.sh customizations intact.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/git-workflow.md exists
+- **Preserve**: branch naming convention, commit message format, CI job names,
+  branch protection rules, worktree directory structure, PR template fields,
+  setup-agent-worktree.sh customizations
+- **Triggers for update**: coding-standards.md changed commit format, new CI
+  stages needed (e.g., evals added), Beads status changed (added or removed),
+  new worktree patterns needed for parallel execution
+- **Conflict resolution**: if CI job rename is required, update branch
+  protection rules in the same operation; verify CLAUDE.md workflow section
+  stays consistent after any changes

package/pipeline/finalization/apply-fixes-and-freeze.md

@@ -2,7 +2,7 @@
 name: apply-fixes-and-freeze
 description: Apply validation findings and freeze documentation
 phase: "finalization"
-order: 34
+order: 1410
 dependencies: [cross-phase-consistency, traceability-matrix, decision-completeness, critical-path-walkthrough, implementability-dry-run, dependency-graph-validation, scope-creep-check]
 outputs: [docs/validation/fix-log.md]
 conditional: null

package/pipeline/finalization/developer-onboarding-guide.md

@@ -2,7 +2,7 @@
 name: developer-onboarding-guide
 description: Create a guide for developers (human or AI) joining the project
 phase: "finalization"
-order: 35
+order: 1420
 dependencies: [apply-fixes-and-freeze]
 outputs: [docs/onboarding-guide.md]
 conditional: null

package/pipeline/finalization/implementation-playbook.md

@@ -2,7 +2,7 @@
 name: implementation-playbook
 description: Create the playbook that AI agents follow during implementation
 phase: "finalization"
-order: 36
+order: 1430
 dependencies: [developer-onboarding-guide]
 outputs: [docs/implementation-playbook.md]
 conditional: null
@@ -16,9 +16,9 @@ per task, coding standards, git workflow (branching/PR strategy), handoff
 format between agents, and success criteria.
 
 ## Inputs
-- docs/implementation-tasks.md (required) — tasks to sequence
+- docs/implementation-plan.md (required) — tasks to sequence
 - docs/system-architecture.md (required) — architecture context
-- docs/testing-strategy.md (required) — testing requirements
+- docs/tdd-standards.md (required) — testing requirements
 - All other frozen artifacts
 
 ## Expected Outputs

package/pipeline/foundation/beads.md

@@ -0,0 +1,68 @@
+---
+name: beads
+description: Initialize Beads task tracking with CLAUDE.md conventions and lessons file
+phase: "foundation"
+order: 210
+dependencies: []
+outputs: [.beads/, tasks/lessons.md, CLAUDE.md]
+conditional: "if-needed"
+knowledge-base: [task-tracking]
+---
+
+## Purpose
+Initialize the Beads issue tracker for AI-friendly task tracking, create the
+lessons-learned file for cross-session memory, and establish the initial CLAUDE.md
+skeleton with core principles, task management commands, self-improvement rules,
+and autonomous behavior guidelines.
+
+## Inputs
+- Project root directory (required) — must be a git repository
+- Existing CLAUDE.md (optional) — if present, operates in update mode
+
+## Expected Outputs
+- .beads/ directory — initialized Beads data store with git hooks
+- tasks/lessons.md — patterns and anti-patterns file for cross-session learning
+- CLAUDE.md — initial skeleton with Core Principles, Task Management (Beads),
+  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
+- CLAUDE.md contains commit-message convention requiring Beads task IDs
+- Bootstrap commit uses `[BD-0]` convention
+
+## Methodology Scaling
+- **deep**: Full Beads setup with all CLAUDE.md sections, detailed command reference
+  table, priority level documentation, and cross-doc consistency checks against
+  existing git-workflow.md and coding-standards.md.
+- **mvp**: Initialize Beads, create tasks/lessons.md, add minimal CLAUDE.md
+  sections (Core Principles + Beads commands). Skip cross-doc checks.
+- **custom:depth(1-5)**: Depth 1-2: MVP Beads init + minimal CLAUDE.md. Depth 3:
+  add full command table and priority docs. Depth 4-5: full setup with cross-doc
+  consistency and detailed autonomous behavior rules.
+
+## Conditional Evaluation
+Enable when: project uses Beads task tracking methodology (user selects Beads during
+setup), or user explicitly enables structured task management. Skip when: user prefers
+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
+.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.
+
+## Update Mode Specifics
+- **Detect prior artifact**: .beads/ directory exists with data files
+- **Preserve**: all existing task data in .beads/, tasks/lessons.md content
+  (patterns, anti-patterns, gotchas), CLAUDE.md Beads command table
+  customizations, git hook configurations
+- **Triggers for update**: new CLAUDE.md sections need Beads references,
+  Beads CLI version changed requiring command updates, git hooks need
+  reconfiguration after workflow changes
+- **Conflict resolution**: if CLAUDE.md Beads section was manually customized,
+  merge new content around existing customizations rather than replacing

package/pipeline/foundation/coding-standards.md

@@ -0,0 +1,68 @@
+---
+name: coding-standards
+description: Create prescriptive coding standards tailored to the project's tech stack
+phase: "foundation"
+order: 230
+dependencies: [tech-stack]
+outputs: [docs/coding-standards.md]
+reads: [create-prd]
+conditional: null
+knowledge-base: [coding-conventions]
+---
+
+## Purpose
+Define the project's coding conventions with concrete, stack-specific examples
+that AI agents reference during every implementation task. Covers project
+structure conventions, code patterns, type safety, security, database access,
+API design, logging, AI-specific pitfalls, commit message format, and a
+self-review checklist.
+
+## Inputs
+- docs/tech-stack.md (required) — determines which languages, frameworks, and tools
+  the standards apply to
+- docs/plan.md (required) — application domain informs which patterns matter most
+
+## Expected Outputs
+- docs/coding-standards.md — prescriptive standards document with sections for
+  project structure, code patterns, type safety, security, database access, API
+  design, logging, AI-specific rules, commit messages, and code review checklist
+- Linter/formatter config files (e.g., .eslintrc, .prettierrc, ruff.toml) created
+  alongside the standards doc
+
+## Quality Criteria
+- Every standard references the specific tech stack, not generic principles
+- Includes runnable code examples showing the RIGHT way for the stack
+- Commit message format is [BD-<id>] type(scope): description
+- 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)
+
+## Methodology Scaling
+- **deep**: Comprehensive standards with examples for every section. Stack-specific
+  security patterns. Detailed error handling strategy with code samples. Full
+  linter/formatter configuration with custom rules. 15-20 pages.
+- **mvp**: Core naming conventions, commit format, import ordering, error handling
+  approach, and AI-specific rules. Basic linter config. 3-5 pages.
+- **custom:depth(1-5)**: Depth 1-2: MVP conventions. Depth 3: add security and
+  database patterns. Depth 4: add API design and logging. Depth 5: full suite
+  with all sections and custom linter rules.
+
+## Mode Detection
+Update mode if docs/coding-standards.md exists. In update mode: preserve naming
+conventions, lint rule customizations, commit message format, and project-specific
+patterns. Never change commit message format without checking git-workflow.md
+and CI config for references.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/coding-standards.md exists
+- **Preserve**: naming conventions, commit message format, lint/formatter
+  configurations, AI-specific coding rules, code review checklist, any
+  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
+- **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

@@ -0,0 +1,69 @@
+---
+name: project-structure
+description: Design directory layout and scaffold the actual project structure
+phase: "foundation"
+order: 250
+dependencies: [tech-stack, coding-standards]
+outputs: [docs/project-structure.md]
+reads: [create-prd, user-stories]
+conditional: null
+knowledge-base: [project-structure-patterns]
+---
+
+## Purpose
+Design the directory layout optimized for parallel AI agent work (minimizing
+merge conflicts and maximizing task independence), document file placement rules,
+and scaffold the actual directories and placeholder files. Updates CLAUDE.md
+with a Quick Reference section for file placement.
+
+## Inputs
+- docs/tech-stack.md (required) — framework conventions determine structure
+- docs/coding-standards.md (required) — naming and organization conventions
+- docs/tdd-standards.md (optional) — test co-location rules
+- docs/plan.md (required) — features inform organization strategy choice
+
+## Expected Outputs
+- docs/project-structure.md — complete directory tree with purpose annotations,
+  module organization strategy, file placement rules, shared code strategy,
+  import conventions, barrel file policy, test file location, and generated
+  vs. committed file rules
+- Scaffolded directories with .gitkeep files
+- Updated .gitignore for the tech stack
+- CLAUDE.md updated with Project Structure Quick Reference section
+
+## Quality Criteria
+- Module organization strategy chosen and justified (feature-based, layer-based, or hybrid)
+- File placement table covers all file types (routes, services, models, types, utils, tests)
+- High-contention files identified with merge-conflict mitigation strategies
+- Shared utilities rule enforced (2+ features before promoting to shared)
+- Import conventions defined with ordering rules
+- 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
+
+## Methodology Scaling
+- **deep**: Comprehensive structure with high-contention analysis, shared code
+  strategy, import path aliases, barrel file policy, responsive breakpoints for
+  screenshots, and generated vs. committed file inventory.
+- **mvp**: Directory tree with annotations, basic file placement table, .gitignore.
+  Skip shared code strategy and high-contention analysis.
+- **custom:depth(1-5)**: Depth 1-2: tree + placement table. Depth 3: add shared
+  code rules. Depth 4: add contention analysis. Depth 5: full suite with barrel
+  policy and import aliases.
+
+## Mode Detection
+Update mode if docs/project-structure.md exists. In update mode: never delete
+existing directories (only add new ones), preserve module organization strategy
+choice, update CLAUDE.md Quick Reference section in-place.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/project-structure.md exists
+- **Preserve**: module organization strategy (feature-based, layer-based, hybrid),
+  existing directory tree, file placement rules, import conventions, barrel file
+  policy, .gitignore entries
+- **Triggers for update**: new features require new directories, architecture
+  changed module boundaries, tech stack added new file types needing placement
+  rules, tdd-standards.md changed test co-location rules
+- **Conflict resolution**: if architecture restructured modules, add new
+  directories but do not remove existing ones until migration is complete;
+  update CLAUDE.md Quick Reference to reflect additions

package/pipeline/foundation/tdd.md

@@ -0,0 +1,60 @@
+---
+name: tdd
+description: Define testing conventions and TDD standards for the tech stack
+phase: "foundation"
+order: 240
+dependencies: [coding-standards]
+outputs: [docs/tdd-standards.md]
+reads: [create-prd]
+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.
+
+## 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
+- 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)
+- Edge cases from domain invariants are test scenarios
+- Performance testing approach for critical paths
+
+## 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.
+
+## 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
+phase: "foundation"
+order: 220
+dependencies: []
+outputs: [docs/tech-stack.md]
+reads: [create-prd]
+conditional: null
+knowledge-base: [tech-stack-selection]
+---
+
+## 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
+- 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
+- (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,65 @@
+---
+name: add-e2e-testing
+description: Configure end-to-end testing (Playwright for web, Maestro for mobile) based on detected project platform
+phase: "integration"
+order: 410
+dependencies: [git-workflow, tdd]
+outputs: [tests/screenshots/, maestro/]
+reads: [tdd, coding-standards]
+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
+- 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
+- (mobile) testID naming convention defined and documented
+- E2E section in tdd-standards.md distinguishes when to use E2E vs unit tests
+- Baseline screenshots committed, current screenshots gitignored
+
+## 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.