@zigrivers/scaffold 2.28.1 → 2.38.0

package/pipeline/build/single-agent-start.md

@@ -0,0 +1,207 @@
+---
+name: single-agent-start
+description: Start single-agent TDD execution loop
+summary: "Claims the next task, writes a failing test, implements until it passes, refactors, runs quality gates, commits, and repeats — following the implementation playbook."
+phase: "build"
+order: 1510
+dependencies: [implementation-playbook]
+outputs: []
+conditional: null
+stateless: true
+category: pipeline
+knowledge-base: [tdd-execution-loop, task-claiming-strategy]
+reads: [coding-standards, tdd, git-workflow]
+---
+
+## Purpose
+Start the single-agent TDD execution loop. This is the primary entry point
+for implementation work when one agent works through the task list
+sequentially. The agent claims the next available task, writes failing tests,
+implements until green, creates a PR, and repeats until all tasks are
+complete.
+
+## Inputs
+- CLAUDE.md (required) — project conventions, key commands, workflow
+- docs/implementation-playbook.md (required if exists) — primary task execution reference with wave assignments and per-task context
+- docs/implementation-plan.md (fallback) — task list when no playbook exists
+- docs/onboarding-guide.md (optional) — project context for orientation
+- docs/coding-standards.md (required) — code conventions, naming, patterns
+- docs/tdd-standards.md (required) — test categories, mocking strategy, test file locations
+- docs/project-structure.md (required) — where files live
+- tests/acceptance/ (optional) — TDD test skeletons for red-green-refactor starting points
+- tests/evals/ (optional) — project eval checks for quality gates
+- tasks/lessons.md (optional) — previous lessons learned to avoid repeating mistakes
+- .beads/ (conditional) — Beads task tracking if configured
+
+## Expected Outputs
+- Implemented features with passing tests
+- Pull requests for each completed task
+- Updated task status in playbook/plan or Beads
+
+## Quality Criteria
+- (mvp) Pre-flight checks pass before starting any implementation work
+- (mvp) Each task follows red-green-refactor TDD cycle
+- (mvp) All quality gates pass before PR creation (make check + make eval if available)
+- (mvp) Task status is updated after each completion
+- (deep) Test skeletons from tests/acceptance/ are used as starting points when available
+- (deep) lessons.md is consulted before each task for relevant anti-patterns
+- (deep) PR description includes implementation summary, assumptions, and files modified
+
+## Methodology Scaling
+- **deep**: Full pre-flight verification, read onboarding guide, consult lessons.md
+  before each task, use test skeletons, run evals, detailed PR descriptions with
+  implementation notes and assumptions.
+- **mvp**: Quick git/dependency check, read playbook or plan, pick next task,
+  TDD loop, make check, create PR. Skip onboarding guide review and detailed
+  PR annotations.
+- **custom:depth(1-5)**: Depth 1-2: minimal pre-flight, TDD loop, make check.
+  Depth 3: add lessons.md review and test skeleton usage. Depth 4: add
+  onboarding guide, eval gates, detailed PR descriptions. Depth 5: full
+  pre-flight suite, all quality gates, cross-reference with upstream docs.
+
+## Mode Detection
+This is a stateless execution command. No document is created or updated.
+- Always operates in EXECUTE MODE.
+- If work is already in progress (feature branch exists, uncommitted changes),
+  redirect to `/scaffold:single-agent-resume` instead.
+
+## Update Mode Specifics
+Not applicable — this is a stateless execution command that does not produce
+a persistent document.
+
+## Instructions
+
+### Pre-Flight Verification
+
+Before writing any code, verify the environment is ready:
+
+1. **Git state check**
+   - `git status` — working tree should be clean (no uncommitted changes)
+   - `git branch --show-current` — should be on `main` or a fresh branch
+   - If on a feature branch with changes, stop and suggest `/scaffold:single-agent-resume` instead
+
+2. **Dependency check**
+   - Run the install command from CLAUDE.md Key Commands (e.g., `npm install`, `pip install`, `bundle install`)
+   - Confirm dependencies are current
+
+3. **Test suite health**
+   - Run the project's check command from CLAUDE.md Key Commands (e.g., `make check`)
+   - If tests fail before you start, fix them first or flag to the user
+
+4. **Project orientation**
+   - Read `CLAUDE.md` for project conventions and key commands
+   - Read `docs/onboarding-guide.md` if it exists (first session orientation)
+   - Read `tasks/lessons.md` for relevant anti-patterns and gotchas
+
+### Beads Detection
+
+Check if `.beads/` directory exists.
+
+**If Beads is configured:**
+- Run `bd ready` to see available tasks
+- Pick the lowest-ID unblocked task
+- Implement following the TDD workflow below
+- After PR is merged, run `bd close <id> && bd sync`
+- Repeat with `bd ready` until no tasks remain
+
+**Without Beads:**
+1. Read `docs/implementation-playbook.md` as the primary task execution reference.
+   Fall back to `docs/implementation-plan.md` when no playbook is present.
+2. Pick the first uncompleted task that has no unfinished dependencies.
+3. Implement following the TDD workflow below.
+4. Mark the task complete in the plan/playbook.
+5. Repeat in dependency order until all tasks are done.
+
+### TDD Execution Loop
+
+For each task:
+
+1. **Claim the task**
+   - Create a feature branch: `git checkout -b <type>/<description>` (e.g., `feat/add-auth`)
+   - If Beads: branch as `bd-<id>/<desc>`
+
+2. **Red phase — write failing tests**
+   - Check `tests/acceptance/` for existing test skeletons that correspond to the task
+   - If skeletons exist, use them as your starting point
+   - Otherwise, write test cases from the task's acceptance criteria
+   - Run the test suite — confirm the new tests FAIL (red)
+
+3. **Green phase — implement**
+   - Write the minimum code to make the failing tests pass
+   - Follow conventions from `docs/coding-standards.md`
+   - Follow file placement from `docs/project-structure.md`
+   - Run tests after each meaningful change — stop when green
+
+4. **Refactor phase — clean up**
+   - Refactor for clarity, DRY, and convention compliance
+   - Run the full test suite — confirm everything still passes
+
+5. **Quality gates**
+   - Run `make check` (or equivalent from CLAUDE.md Key Commands)
+   - If `tests/evals/` exists, run `make eval` (or equivalent eval command)
+   - Fix any failures before proceeding
+
+6. **Create PR**
+   - Push the branch: `git push -u origin HEAD`
+   - Create a pull request: `gh pr create`
+   - Include in the PR description: what was implemented, key decisions, files changed
+   - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
+
+7. **Update status**
+   - If Beads: task status is managed via `bd` commands
+   - Without Beads: mark the task as complete in the plan/playbook
+
+### Recovery Procedures
+
+**Tests fail before starting:**
+- Run the test suite and read the output carefully
+- If failures are in existing tests (not your changes), fix them first
+- If failures are environment-related, run the install/setup commands from CLAUDE.md
+
+**Merge conflicts on PR:**
+- `git fetch origin && git rebase origin/main`
+- Resolve conflicts, re-run tests, force-push the branch
+
+**Quality gate failures after implementation:**
+- Read the failure output — most failures have clear fix instructions
+- Fix lint/format issues first (often auto-fixable)
+- Fix test failures next
+- Re-run the full gate before pushing
+
+**Stuck on a task:**
+- Re-read the task description, acceptance criteria, and any linked docs
+- Check `tasks/lessons.md` for similar past issues
+- If truly blocked, note the blocker and move to the next unblocked task
+
+### Process Rules
+
+1. **TDD is not optional** — Write failing tests before implementation. No exceptions.
+2. **One task at a time** — Complete the current task fully before starting the next.
+3. **Quality gates before PR** — Never create a PR with failing checks.
+4. **Update status immediately** — Mark tasks complete as soon as the PR is created.
+5. **Consult lessons.md** — Check for relevant anti-patterns before each task.
+6. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
+
+---
+
+## After This Step
+
+When this step is complete (all tasks done or session ending), tell the user:
+
+---
+**Execution session complete** — Tasks implemented with passing tests and PRs created.
+
+**Session summary:**
+- Tasks completed: [list task IDs/titles]
+- PRs created: [list PR numbers]
+- Remaining tasks: [count or "none"]
+
+**If resuming later:** Run `/scaffold:single-agent-resume` to pick up where you left off.
+
+**If all tasks are done:**
+- Review `tasks/lessons.md` and add any patterns learned during implementation.
+- Consider running `/scaffold:version-bump` for a release.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---

package/pipeline/consolidation/claude-md-optimization.md

@@ -1,10 +1,12 @@
 ---
 name: claude-md-optimization
 description: Consolidate and optimize CLAUDE.md for maximum signal density
+summary: "Removes redundancy from CLAUDE.md, fixes terminology inconsistencies, front-loads critical patterns (TDD, commit format, worktrees), and keeps it under 200 lines so agents actually read and follow it."
 phase: "consolidation"
 order: 1110
 dependencies: [git-workflow]
 outputs: [CLAUDE.md]
+reads: [create-prd, tdd, user-stories]
 conditional: null
 knowledge-base: [claude-md-patterns]
 ---
@@ -33,14 +35,14 @@ scannability.
   recovery), Browser/E2E Testing, Self-Improvement, Autonomous Behavior
 
 ## Quality Criteria
-- No duplicated instructions within CLAUDE.md
-- No verbatim repetition of content from other docs (reference instead)
-- Consistent terminology throughout (task vs. ticket, etc.)
-- Key Commands table matches actual Makefile/package.json commands
+- (mvp) No duplicated instructions within CLAUDE.md
+- (mvp) No verbatim repetition of content from other docs (reference instead)
+- (mvp) Consistent terminology throughout (task vs. ticket, etc.)
+- (mvp) Key Commands table matches actual Makefile/package.json commands
 - Critical patterns are prominent (TDD, never push to main, keep working,
   verify before commit, worktrees for parallel). If Beads: every commit needs task ID.
-- An agent can skim CLAUDE.md in 30 seconds and get the critical points
-- Workflow scenarios cover error cases (test failures, merge conflicts, CI failures,
+- (deep) CLAUDE.md is <= 200 lines or critical patterns appear in the first 50 lines
+- (deep) Workflow scenarios cover error cases (test failures, merge conflicts, CI failures,
   crashed sessions, blocked tasks)
 - Tracking comment added: <!-- scaffold:claude-md-optimization v1 YYYY-MM-DD -->
 
@@ -67,7 +69,8 @@ rules — only consolidate and clarify what already exists.
 - **Detect prior artifact**: tracking comment in CLAUDE.md with version and date
 - **Preserve**: manually-added sections, user-customized rules, project-specific
   command aliases, any content not traceable to a pipeline setup prompt
-- **Triggers for update**: new setup prompts have appended sections since last
-  optimization, terminology inconsistencies introduced by incremental additions
+- **Triggers for update**: new setup prompts completed, coding-standards updated,
+  tdd-standards updated, git-workflow updated, terminology inconsistencies
+  introduced by incremental additions
 - **Conflict resolution**: if a user-customized section conflicts with a setup
   prompt's output, keep the user version and flag the conflict in a comment

package/pipeline/consolidation/workflow-audit.md

@@ -1,11 +1,13 @@
 ---
 name: workflow-audit
 description: Verify workflow consistency across all documentation files
+summary: "Audits every document that mentions workflow (CLAUDE.md, git-workflow, coding-standards, dev-setup) and fixes any inconsistencies in commit format, branch naming, PR steps, or key commands."
 phase: "consolidation"
 order: 1120
 dependencies: [claude-md-optimization]
 outputs: [CLAUDE.md, docs/git-workflow.md]
 conditional: null
+reads: [operations]
 knowledge-base: [cross-phase-consistency]
 ---
 
@@ -34,15 +36,16 @@ inconsistent command formats. Fix all issues found.
 - tasks/lessons.md — created if missing
 
 ## Quality Criteria
-- CLAUDE.md contains complete workflow (9 steps + AI review step 4.5)
-- Commit format is consistent everywhere (If Beads: [BD-<id>] type(scope): description. Without Beads: type(scope): description)
-- Branch naming is consistent everywhere (If Beads: bd-<task-id>/<short-desc>. Without Beads: <type>/<short-desc>)
-- PR workflow includes all 8 sub-steps with --delete-branch flag
-- If Beads: task closure uses bd close (not bd update --status completed)
-- Key Commands table matches actual Makefile/package.json commands
-- Worktree cleanup between tasks documented (cannot checkout main)
-- Agent crash recovery documented
-- No document contradicts the canonical workflow
+- (mvp) CLAUDE.md contains complete workflow (9 steps + AI review step 4.5)
+- (mvp) Commit format is consistent everywhere (If Beads: [BD-<id>] type(scope): description. Without Beads: type(scope): description)
+- (mvp) Branch naming is consistent everywhere (If Beads: bd-<task-id>/<short-desc>. Without Beads: <type>/<short-desc>)
+- (mvp) PR workflow includes all 8 sub-steps with --delete-branch flag
+- (mvp) If Beads: task closure uses bd close (not bd update --status completed)
+- (mvp) Key Commands table matches actual Makefile/package.json commands
+- (deep) Worktree cleanup between tasks documented (cannot checkout main)
+- (deep) Agent crash recovery documented
+- (deep) No document contradicts the canonical workflow
+- Tracking comment matches format: `<!-- scaffold:workflow-audit v1 YYYY-MM-DD -->`
 - Tracking comment added: <!-- scaffold:workflow-audit v1 YYYY-MM-DD -->
 
 ## Methodology Scaling
@@ -67,7 +70,8 @@ manually-added workflow steps or custom CI configurations.
   and date
 - **Preserve**: custom CI jobs, user-added workflow steps, project-specific
   branch protection rules, custom PR template fields
-- **Triggers for update**: new setup prompts modified workflow docs, Makefile
-  targets added or renamed, git-workflow.md updated with new steps
+- **Triggers for update**: CI configuration changed, git-workflow.md updated,
+  new scripts added to Makefile, Makefile targets added or renamed, new setup
+  prompts modified workflow docs
 - **Conflict resolution**: if two docs disagree on workflow, the canonical
   workflow in CLAUDE.md wins; update the conflicting doc to match

package/pipeline/decisions/adrs.md

@@ -1,6 +1,7 @@
 ---
 name: adrs
 description: Document architecture decisions as ADRs
+summary: "Documents every significant design decision — what was chosen, what alternatives were considered with pros and cons, and what consequences follow — so future contributors understand why, not just what."
 phase: "decisions"
 order: 610
 dependencies: [review-domain-modeling]
@@ -25,11 +26,12 @@ ADR category — tech stack decisions are documented here.
 - docs/adrs/index.md — decision log overview
 
 ## Quality Criteria
-- Every significant decision has an ADR (technology, patterns, trade-offs)
-- Each ADR documents alternatives considered with pros/cons
-- Decisions trace to PRD requirements or domain model constraints
-- No ADR contradicts another without explicit acknowledgment
-- Technology selections include team expertise and maintenance considerations
+- (mvp) ADRs exist for: language, framework, database, ORM, deployment target, API style, authentication, and any decision referenced in system-architecture.md
+- (deep) Each ADR documents alternatives considered with pros/cons
+- (mvp) Decisions trace to PRD requirements or domain model constraints
+- (mvp) No ADR contradicts another without explicit acknowledgment
+- (deep) Technology selections include team expertise and maintenance considerations
+- (deep) Decision dependencies documented — if ADR-002 depends on ADR-001's outcome, the dependency is explicit
 
 ## Methodology Scaling
 - **deep**: Comprehensive ADR set. 3+ alternatives per decision with detailed

package/pipeline/decisions/review-adrs.md

@@ -1,12 +1,13 @@
 ---
 name: review-adrs
 description: Review ADRs for completeness, consistency, and decision quality
+summary: "Checks for contradictions between decisions, missing decisions implied by the architecture, and whether every choice has honest trade-off analysis."
 phase: "decisions"
 order: 620
 dependencies: [adrs]
 outputs: [docs/reviews/review-adrs.md, docs/reviews/adrs/review-summary.md, docs/reviews/adrs/codex-review.json, docs/reviews/adrs/gemini-review.json]
 conditional: null
-knowledge-base: [review-methodology, review-adr]
+knowledge-base: [review-methodology, review-adr, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -30,11 +31,11 @@ independent review validation.
 - docs/reviews/adrs/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- All ADR-specific review passes executed
-- Every finding categorized by severity
-- Missing decisions identified and documented
-- Contradictions resolved
-- Downstream readiness confirmed (architecture phase can proceed)
+- (mvp) All ADR-specific review passes executed
+- (mvp) Every finding categorized P0-P3 with specific ADR number, section, and issue
+- (deep) Missing decisions identified and documented
+- (mvp) Contradictions resolved
+- (mvp) Downstream readiness confirmed (architecture phase can proceed)
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
@@ -50,3 +51,10 @@ independent review validation.
 Re-review mode if previous review exists. Check which findings were addressed.
 If multi-model review artifacts exist under docs/reviews/adrs/, preserve prior
 findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-adrs.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/environment/ai-memory-setup.md

@@ -1,6 +1,7 @@
 ---
 name: ai-memory-setup
 description: Configure AI memory and context management with modular rules, optional MCP memory server, lifecycle hooks, and external context integration
+summary: "Extracts conventions from your docs into path-scoped rule files that load automatically, optimizes CLAUDE.md with a pointer pattern, and optionally sets up persistent cross-session memory."
 phase: "environment"
 order: 350
 dependencies: [git-workflow]
@@ -34,14 +35,14 @@ to prevent API hallucination. Users choose which tiers to enable.
 - (Tier 3) .claude/settings.json with external context MCP server
 
 ## Quality Criteria
-- .claude/rules/ files use valid YAML frontmatter with description and globs fields
-- Each rule file targets a specific concern (no catch-all files)
-- Total rule content stays under 500 lines across all files
-- CLAUDE.md references rules via pointer pattern, stays under 200 lines
-- Rules accurately reflect the conventions in source documents (no drift)
-- (Tier 2) MCP memory server responds to basic queries
-- (Tier 2) At least PreCompact hook is configured and functional
-- (Tier 3) Library doc server returns results for project dependencies
+- (mvp) .claude/rules/ files use valid YAML frontmatter with description and globs fields
+- (mvp) Each rule file targets a specific concern (no catch-all files)
+- (mvp) Total rule content stays under 500 lines across all files
+- (mvp) CLAUDE.md references rules via pointer pattern, stays under 200 lines
+- (mvp) Rules accurately reflect the conventions in source documents (no drift)
+- (deep) MCP memory server responds to basic queries
+- (deep) At least PreCompact hook is configured and functional
+- (deep) Library doc server returns results for project dependencies
 
 ## Methodology Scaling
 - **deep**: All three tiers offered. Tier 1 generates comprehensive rules from
@@ -53,10 +54,15 @@ to prevent API hallucination. Users choose which tiers to enable.
   full Tier 1 + offer Tier 2. Depth 4-5: all tiers with comprehensive setup.
 
 ## Mode Detection
-Update mode if .claude/rules/ directory exists. In update mode: preserve existing
-rule files and their customizations, add missing rules for new conventions,
-update rules where source docs have changed. Never delete user-customized rules.
-If MCP server already configured, verify and update rather than replace.
+Check if `.claude/rules/` directory or docs/ai-memory-setup.md exists first. If
+`.claude/rules/` exists, check for scaffold tracking comments (e.g.,
+`<!-- scaffold:ai-memory-setup -->`) in rule files for conservativeness calibration.
+- If `.claude/rules/` exists with tracking comments: UPDATE MODE — preserve existing
+  rule files and their customizations, add missing rules for new conventions,
+  update rules where source docs have changed. Never delete user-customized rules.
+  If MCP server already configured, verify and update rather than replace.
+- If `.claude/rules/` does not exist: FRESH MODE — create rules directory and generate
+  rule files from scratch.
 
 ## Update Mode Specifics
 - **Detect prior artifact**: .claude/rules/ directory exists with rule files

package/pipeline/environment/automated-pr-review.md

@@ -1,12 +1,14 @@
 ---
 name: automated-pr-review
 description: Agent-driven automated PR review with external reviewers (Codex Cloud, Gemini Code Assist, or custom)
+summary: "Configures automated code review — using Codex and/or Gemini CLIs for dual-model review when available, or an external bot — with severity definitions and review criteria tailored to your project."
 phase: "environment"
 order: 340
 dependencies: [git-workflow]
 outputs: [AGENTS.md, docs/review-standards.md]
+reads: [tdd]
 conditional: "if-needed"
-knowledge-base: [review-methodology]
+knowledge-base: [review-methodology, automated-review-tooling]
 ---
 
 ## Purpose
@@ -37,6 +39,7 @@ entire review-fix loop locally.
 - No GitHub Actions workflows created (zero Actions minutes)
 - No ANTHROPIC_API_KEY secret required
 - Legacy GitHub Actions workflows detected and cleanup offered
+- (deep) Dual-model review enabled when both CLIs available
 
 ## Methodology Scaling
 - **deep**: Full setup with local CLI review (dual-model when both available),
@@ -53,9 +56,12 @@ configured, or git-workflow.md establishes a PR-based workflow. Skip when: solo
 developer with no CI, depth < 3, or project uses a non-GitHub VCS host.
 
 ## Mode Detection
-Update mode if AGENTS.md exists. In update mode: preserve custom review rules,
-reviewer bot name, and round cap settings. Detect legacy GitHub Actions
-workflows (code-review-trigger.yml, code-review-handler.yml) and offer removal.
+Check if AGENTS.md exists first. If it exists, check for scaffold tracking comment
+(`<!-- scaffold:automated-pr-review -->`).
+- If AGENTS.md exists with tracking comment: UPDATE MODE — preserve custom review rules,
+  reviewer bot name, and round cap settings. Detect legacy GitHub Actions
+  workflows (code-review-trigger.yml, code-review-handler.yml) and offer removal.
+- If AGENTS.md does not exist: FRESH MODE — configure from scratch.
 
 ## Update Mode Specifics
 - **Detect prior artifact**: AGENTS.md exists

package/pipeline/environment/design-system.md

@@ -1,10 +1,12 @@
 ---
 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]
 ---
@@ -31,13 +33,13 @@ professional UI without requiring design expertise from the user.
 - 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)
+- (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

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

@@ -1,11 +1,13 @@
 ---
 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]
 ---
 
@@ -30,13 +32,14 @@ by the entire workflow.
 - 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
+- (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
-- Lint and test commands exist and are runnable
+- (mvp) 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)
+- (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

package/pipeline/environment/git-workflow.md

@@ -1,12 +1,13 @@
 ---
 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]
+knowledge-base: [dev-environment, git-workflow-patterns]
 ---
 
 ## Purpose
@@ -42,6 +43,7 @@ parallel agents, CI pipeline, branch protection, and conflict prevention rules.
 - 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

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

@@ -1,6 +1,7 @@
 ---
 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: 1410
 dependencies: [cross-phase-consistency, traceability-matrix, decision-completeness, critical-path-walkthrough, implementability-dry-run, dependency-graph-validation, scope-creep-check]
@@ -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,6 +1,7 @@
 ---
 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: 1420
 dependencies: [apply-fixes-and-freeze]
@@ -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