@zigrivers/scaffold 2.1.2 → 2.38.0

package/pipeline/environment/design-system.md

@@ -0,0 +1,75 @@
+---
+name: design-system
+description: Create a cohesive design system with tokens and component patterns for frontend
+summary: "Creates a visual language — color palette (WCAG-compliant), typography scale, spacing system, component patterns — and generates working theme config files for your frontend framework."
+phase: "environment"
+order: 320
+dependencies: [dev-env-setup]
+outputs: [docs/design-system.md]
+reads: [create-prd]
+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
+- (mvp) All colors meet WCAG AA contrast requirements
+- (mvp) Typography scale uses a consistent modular ratio; body text >= 16px; line height >= 1.5 for body text
+- (mvp) Spacing uses a consistent base unit (e.g., 4px increments)
+- (deep) Component patterns cover buttons, forms, cards, feedback, navigation, data display
+- (mvp) Theme configuration files actually work (verified by running dev server)
+- (deep) Both light and dark mode token values provided (if dark mode requested)
+- (deep) 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,68 @@
+---
+name: dev-env-setup
+description: Configure local dev environment with live reload and simple commands
+summary: "Configures your project so a single command starts everything — dev server with live reload, local database, environment variables — and documents the setup in a getting-started guide."
+phase: "environment"
+order: 310
+dependencies: [project-structure]
+outputs: [docs/dev-setup.md]
+conditional: null
+reads: [tdd]
+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
+- (mvp) Dev server starts with a single command and supports live/hot reloading
+- (deep) Local database setup is scripted (if applicable)
+- (deep) .env.example documents all variables with comments
+- Key Commands table in CLAUDE.md matches actual Makefile/package.json commands
+- (mvp) Lint and test commands exist and are runnable
+- Verification checklist passes (install, dev server, browser, live reload, tests, db)
+- (mvp) Setup process works for first-time clone (max 5 steps)
+- (mvp) Makefile/package.json includes at minimum: dev, test, lint targets
+
+## 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,73 @@
+---
+name: git-workflow
+description: Configure git workflow with branching, PRs, CI, and worktree scripts for parallel agents
+summary: "Sets up your branching strategy, commit message format, PR workflow, CI pipeline with lint and test jobs, and worktree scripts so multiple AI agents can work in parallel without conflicts."
+phase: "environment"
+order: 330
+dependencies: [dev-env-setup]
+outputs: [docs/git-workflow.md]
+conditional: null
+knowledge-base: [dev-environment, git-workflow-patterns]
+---
+
+## 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
+- (mvp) CI workflow YAML is valid and references commands from Key Commands table
+
+## 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

@@ -1,8 +1,9 @@
 ---
 name: apply-fixes-and-freeze
 description: Apply validation findings and freeze documentation
+summary: "Applies all findings from the validation phase, fixes blocking issues, and freezes every document with a version marker — signaling that specs are implementation-ready."
 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
@@ -25,15 +26,25 @@ issue is discovered during implementation.
 - Freeze marker added to each document (tracking comment)
 
 ## Quality Criteria
-- All P0 and P1 validation findings addressed
-- P2 findings addressed or explicitly deferred with rationale
+- (mvp) All P0 and P1 validation findings addressed
+- (deep) P2 findings addressed or explicitly deferred with rationale
 - Fix log documents what changed and why
-- All documents pass a final consistency check after fixes
+- (deep) Cross-phase-consistency validation re-run after fixes yields no new P0 or P1 findings
+- Every frozen document contains a tracking comment matching `<!-- scaffold:step-name vN YYYY-MM-DD -->`
 
 ## Methodology Scaling
 - **deep**: All findings addressed. Full fix log. Final consistency check.
 - **mvp**: P0 findings only. Brief fix log.
-- **custom:depth(1-5)**: Scale with depth.
+- **custom:depth(1-5)**: Depth 1-2: address P0 findings only with brief fix log. Depth 3: address P0-P1 findings with detailed fix log and deferred rationale. Depth 4: address P0-P2 with full deferred rationale and re-validation passes. Depth 5: all findings addressed, final consistency re-check, and freeze verification audit.
 
 ## Mode Detection
-Not applicable — this step runs once after validation.
+Check if `docs/validation/fix-log.md` already exists.
+- If exists: UPDATE MODE — read existing fix log, identify newly introduced validation findings, apply incremental fixes, preserve previously applied fixes and their verification status.
+- If not: FRESH MODE — apply all validation findings from scratch.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/validation/fix-log.md` exists with tracking comment
+- **Preserve**: Previous fix decisions, deferred rationale, freeze markers on already-frozen documents
+- **Triggers**: New validation findings since last freeze, documents modified after freeze
+- **Conflict resolution**: Re-frozen documents with new changes require updated freeze markers and fix-log entries

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

@@ -1,8 +1,9 @@
 ---
 name: developer-onboarding-guide
 description: Create a guide for developers (human or AI) joining the project
+summary: "Synthesizes all frozen docs into a single onboarding narrative — project purpose, architecture overview, top coding patterns, key commands, and a quick-start checklist — so anyone joining the project knows exactly where to begin."
 phase: "finalization"
-order: 35
+order: 1420
 dependencies: [apply-fixes-and-freeze]
 outputs: [docs/onboarding-guide.md]
 conditional: null
@@ -12,7 +13,9 @@ knowledge-base: [developer-onboarding]
 ## Purpose
 Create a comprehensive onboarding guide that gives any developer (human or AI
 agent) everything they need to understand the project and start contributing.
-This is the "start here" document.
+This is the "start here" document. It synthesizes information from all frozen
+artifacts into a single coherent narrative that new contributors can read
+before their first task.
 
 ## Inputs
 - All frozen phase artifacts
@@ -21,16 +24,27 @@ This is the "start here" document.
 - docs/onboarding-guide.md — developer onboarding guide
 
 ## Quality Criteria
-- Covers: project purpose, architecture overview, key patterns, where to find what
-- A new developer can set up and run the project following this guide
-- Key architectural decisions are summarized (with pointers to ADRs)
-- Development workflow is clear (branch, code, test, PR)
+- (mvp) Contains sections for: project purpose, architecture overview (with component diagram reference), top 3 coding patterns with examples, and a file/doc lookup table
+- (mvp) Guide includes clone instructions, dependency install command, dev server start command, and test run command; every ADR referenced by number with one-sentence summary
+- (deep) Key architectural decisions are summarized (with pointers to ADRs)
+- (mvp) Development workflow is clear (branch, code, test, PR)
 
 ## Methodology Scaling
 - **deep**: Comprehensive guide. Architecture walkthrough, key pattern explanations,
   common tasks with examples, troubleshooting section.
-- **mvp**: Quick start. Setup instructions, key files, how to run tests.
-- **custom:depth(1-5)**: Scale detail with depth.
+- **mvp**: Quick-start guide with: clone command, dependency install, dev server
+  start, test run command. Skip architecture overview, key patterns, and
+  troubleshooting sections.
+- **custom:depth(1-5)**: Depth 1-2: quick start with setup and test commands only. Depth 3: add architecture overview, key patterns, and common tasks. Depth 4: add troubleshooting section, entry points documentation, and development workflow detail. Depth 5: full guide with architecture walkthrough, decision rationale, and team-specific onboarding paths.
 
 ## Mode Detection
-Update mode if guide exists.
+Check if `docs/onboarding-guide.md` already exists.
+- If exists: UPDATE MODE — read current guide, diff against upstream docs for changes, propose targeted updates while preserving project-specific customizations and environment-specific instructions.
+- If not: FRESH MODE — generate from scratch using all pipeline artifacts.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/onboarding-guide.md` exists with tracking comment
+- **Preserve**: Team-specific customizations, troubleshooting entries added from experience, getting-started verification results
+- **Triggers**: Architecture changes, new tooling, new patterns established
+- **Conflict resolution**: Merge new sections with existing customizations; never remove team-contributed troubleshooting entries

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: 36
+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]
 ---
@@ -16,30 +18,57 @@ 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
+- 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

@@ -0,0 +1,71 @@
+---
+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: []
+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
+- (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
+  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/ 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.
+
+## 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,71 @@
+---
+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]
+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
+- 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
+  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, 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

@@ -0,0 +1,73 @@
+---
+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, tdd]
+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
+- 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
+  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