vinta-ai-workflows 0.2.0-alpha7 → 0.3.0

package/CHANGELOG.md

@@ -5,7 +5,125 @@ All notable changes to `vinta-ai-workflows` are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.2.0] — YYYY-MM-DD
+## [0.3.0] — 2026-07-17
+
+### Fixed
+
+- **`prepare-worktree` — data-corruption bug: `COMPOSE_PROJECT_NAME` alone does
+  NOT isolate a per-worktree docker-compose stack, so worktrees could run a
+  second database server against the main checkout's data volume.** Step 4
+  assumed `COMPOSE_PROJECT_NAME` fully isolates a compose stack. It does not for
+  two very common patterns: (1) volumes declared `external: true` and/or pinned
+  to a fixed top-level `name:` — the project name namespaces containers and
+  networks but NOT these volumes, so every worktree's `db` service mounted the
+  **same physical volume**; and (2) fixed host port bindings
+  (`ports: - "5432:5432"`) — published to the same host port across compose
+  projects. On a Django + docker-compose project (2026-07-17) this ran two
+  Postgres postmasters against one PGDATA for a whole test run; when the
+  worktree stack was `docker compose down`'d, its Postgres removed the shared
+  `postmaster.pid` and the **main checkout's database self-terminated**
+  (recovered on restart — luck, not safety). The fix also corrects a deeper
+  conceptual error: Step 3a's "share the DB (don't fork)" is now explicit that
+  *share* means share a **connection to a single already-running server** — for
+  a compose-delivered DB the data volumes are **always forked, independent of
+  `schema_change` / `test_db_strategy`**, because the worktree runs its own
+  server and two servers on one volume is corruption.
+
+  **User impact / migration:** existing worktrees provisioned before this fix
+  are **unsafe to boot their DB compose stack while the main stack is up** —
+  they share main's data volume. For an already-provisioned worktree, regenerate
+  the override without re-running the whole skill:
+
+  ```bash
+  ai-tools/skills/prepare-worktree/scripts/gen-compose-worktree-override.sh \
+    --main <main-checkout-root> --worktree <worktree-path> --name <name> \
+    --out <summary_dir>/<name>.docker-compose.override.yml
+  echo "COMPOSE_FILE=<base-compose-file>:<override-path>" >> <worktree>/.env
+  ```
+
+  Then confirm the worktree's resolved DB volume name differs from main's before
+  booting its stack. **Consumers**: re-sync (`vinta-sync-ai-tools`) to pick up
+  the new script, the reworked Step 4/Step 3a, and the `shared_volumes` config.
+
+### Added
+
+- **`prepare-worktree` bundled script
+  `scripts/gen-compose-worktree-override.sh`.** Detects the compose isolation
+  leaks above entirely from `docker compose config --format json` (no project /
+  service / volume name hardcoded) and emits a **generated, out-of-tree**
+  compose override that re-pins every `external:`/fixed-`name:` volume to a
+  non-external, worktree-namespaced volume (`<project>_wt_<name>_<volkey>`) and
+  strips fixed host-port publishing (via compose's `!override []` — a plain
+  `ports: []` merges/appends in Compose v2+; verified on Docker Compose v5.1.1).
+  The override is written under `<summary_dir>/` and wired in via
+  `COMPOSE_FILE=<base>:<override>` appended to the worktree's **copied** `.env`,
+  so **no tracked compose file is ever mutated**. Volumes safe to keep shared
+  (a read-only dep/venv cache) are exempted via `--share-volume`.
+- **`skills.prepare-worktree.shared_volumes` config field** (array of compose
+  volume keys, default `[]`). Lists volumes safe to keep shared across worktrees
+  — read-only dep/venv caches only, never a data/DB volume. Feeds
+  `gen-compose-worktree-override.sh --share-volume`. Added to the config schema
+  and the bootstrap template's `prepare-worktree` block.
+- **`prepare-worktree` Step 4a "Neutralize compose isolation leaks"**, a
+  Verification invariant that boots the worktree's DB service and asserts its
+  resolved data volume name differs from main's (failing provisioning loudly
+  otherwise), a matching Pitfall + Rules entry, and a `state.compose` summary
+  schema extension (per-volume fork decisions, override path, stripped ports)
+  so teardown is mechanical (`docker volume rm` the forked names; `rm` the
+  override — never `down -v`, which would nuke shared volumes).
+
+### Changed
+
+- **`prepare-worktree` foundation skill — rebalanced Step 3b (test database)
+  to be stack-agnostic.** The section previously led with a detailed
+  `pytest-django` recipe (with `vitest`/`jest` and Rails as one-liners),
+  which read as Django-centric. It now opens with the stack-agnostic
+  principle — give the worktree its own test DB name, inject it through
+  whatever channel the runner already reads (env var or per-worktree config
+  override), and never edit tracked test config in place — then lists the
+  runners as equal-weight illustrations grouped by *how they take config*:
+  env-var runners (`vitest`/`jest`, `go test`, `cargo test`), config-file
+  runners (`pytest-django`), convention-based runners (Rails), and
+  compose-based test DBs. No behavior change; the pytest-django mechanics
+  (`conftest_worktree.py`, don't touch the tracked `conftest.py`) are
+  preserved. **Consumers**: re-sync to pick up the reworded skill body.
+
+## [0.2.0] — 2026-07-15
+
+### Added
+
+- **Project-wide model selection for the review sub-agents and mechanical
+  steps, via a new optional `agent_models` section in
+  `.vinta-ai-workflows.yaml`.** Until now only the per-phase *implementer*
+  model was configurable (each plan phase's `**Suggested AI model**:` line);
+  the reviewer, the fixer, and the mechanical steps (worktree prep, opening
+  the PR / integrate) always inherited the runtime default. `agent_models`
+  maps each of `reviewer` / `fixer` / `worktree_prep` / `integrate` to a
+  **tier (1–4)** into the same `plan-feature/resources/ai-models.yaml` table
+  the implementer uses — so no model IDs are hard-coded and the nightly
+  `check-ai-models` job keeps them fresh. Behavior:
+  - `review-phase` spawns the reviewer at `agent_models.reviewer` and the
+    fixer at `agent_models.fixer` **as the project default** — a plan phase
+    can override either for that phase via an optional `**Review models**:`
+    line (per-phase override wins → else `agent_models` → else runtime
+    default). Lets a plan raise the review model on its few critical /
+    high-blast-radius phases without changing the project-wide setting.
+  - `implement-plan` **delegates** the mechanical steps to a cheap subagent
+    when `agent_models.worktree_prep` / `agent_models.integrate` is set —
+    provisioning the worktree and pushing + opening the PR run on the
+    configured model instead of the conductor's (usually pricier) session.
+    The PR-context file + `open-pr.sh` stays the only PR-creation path.
+  - `plan-feature` phases always pick the implementer model
+    (`**Suggested AI model**:`) and MAY add an optional `**Review models**:`
+    line to override the reviewer / fixer tier for that phase; the mechanical
+    models stay config-only.
+  Every key is optional and backward-compatible: an unset key (or the whole
+  section absent) means that spawn keeps using the runtime default.
+  **Consumers**: re-sync to pick up the `agent_models` bootstrap question and
+  the updated plan-execution skills; existing configs are unaffected until
+  they add the section.
+
+<!-- pre-release: 0.2.0-alpha7 on 2026-07-13 -->
 
 ### Changed
 
@@ -30,7 +148,7 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   are unaffected (the e2e regions strip out as before).
 
 
-<!-- pre-release: 0.2.0-alpha7 on 2026-07-13 -->
+<!-- pre-release: 0.2.0-alpha6 on 2026-07-13 -->
 
 ### Changed
 

package/README.md

@@ -2,14 +2,14 @@
 
 Bootstrap AI tooling — AGENTS.md, sub-agents, project skills, multi-vendor wiring — into any project, then get out of the way.
 
-Distributed as a private npm package (`vinta-ai-workflows`) with a CLI that installs / updates / uninstalls a set of one-shot bootstrap skills into the project's vendor-specific skill directories (Claude Code, Codex, Cursor, VS Code + GitHub Copilot).
+Distributed as an npm package (`vinta-ai-workflows`) with a CLI that installs / updates / uninstalls a set of one-shot bootstrap skills into the project's vendor-specific skill directories (Claude Code, Codex, Cursor, VS Code + GitHub Copilot).
 
 ## Quick start
 
 ```bash
 # 1. Add the package to the target project.
 cd ~/code/my-project
-npm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#0.1.0
+npm install -D vinta-ai-workflows
 
 # 2. Install the bootstrap skills for your AI tool.
 npx vinta-ai-workflows install --tool claude-code
@@ -28,7 +28,7 @@ npx vinta-ai-workflows uninstall --tool claude-code
 npm uninstall vinta-ai-workflows
 ```
 
-Prerequisites: Node ≥ 18, SSH access to the private repo (or a registry token if your team mirrors it).
+Pin a version for determinism with `npm install -D vinta-ai-workflows@0.2.0`. Prerequisites: Node ≥ 18.
 
 ## Why this is useful
 
@@ -208,10 +208,22 @@ Standalone re-invocation works at every step — kick `create-spec` again when t
 
 Quick inventory of what `vinta-bootstrap-ai-tools` writes into your repo's `ai-tools/` layout (and exposes via per-vendor wiring at `.claude/skills/`, `.agents/skills/`, etc.). Two disclaimers up front:
 
-> **Optional foundation skills are gated by the bootstrap interview.** `systematic-debugging`, `add-e2e-test`, `add-env-var`, and `add-one-off-script` ship **only** if the user says yes during `vinta-bootstrap-ai-tools` Step 0 (or later opts in via `vinta-sync-ai-tools`). They are not in every bootstrapped project. The opt-in is recorded in `.vinta-ai-workflows.yaml` under `foundation_skills.*.enabled` and is sticky across syncs.
+> **Optional foundation skills are gated by the bootstrap interview.** `systematic-debugging`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, and `handoff-to-client` ship **only** if the user says yes during `vinta-bootstrap-ai-tools` Step 0 (or later opts in via `vinta-sync-ai-tools`). They are not in every bootstrapped project. The opt-in is recorded in `.vinta-ai-workflows.yaml` under `foundation_skills.*.enabled` and is sticky across syncs.
 >
 > **Stack-specific skills and sub-agents are user-supplied.** This package ships **detection signals + category lists** per stack ([resources/stacks/](skills/vinta-bootstrap-ai-tools/resources/stacks/) — Django, Medplum, Next.js App Router, Python package, TypeScript monorepo), not the bodies. When a stack is detected, the orchestrator asks the user for a path / URL to their team's existing template. If no template exists, the category is recorded as a gap in the final summary, not auto-drafted. Bodies are project- and team-specific; one shared template doesn't fit every team's conventions.
 
+### New in the 0.2.0 releases
+
+The 0.2.0 alpha line adds five foundation skills and restructures plan execution. Two ship in every bootstrapped project, three are opt-in:
+
+- **`handoff` (always)** — writes a session-continuation doc to `.vinta-ai-workflows/handoffs/` so a fresh session, a different agent, or a teammate can resume in-flight work without re-deriving context. Write mode gathers the goal, what's verified vs. still assumed, decisions and the alternatives rejected, landmines, and the single concrete next step **from the repo, never from memory**. Resume mode reads a handoff and re-checks its claims against the repo before trusting them.
+- **`deslop-comments` (always)** — rewrites the comments and doc blocks a task touched into Simple English, stripping AI-slop vocabulary and negative framing. Comment-only: no renames, no behavior change. It's wired into the review flow — `review-phase` Layer 2 gained a comment-hygiene check and dispatches a `fixer` to run this skill on any comment-slop finding — and is also invokable standalone ("deslop these comments").
+- **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and decides per ignored path whether to symlink, copy, or fork (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it.
+- **`thermo-nuclear-code-quality-review` (opt-in)** — a deliberately harsh, on-demand structural-maintainability audit of a diff (abstraction quality, giant files, spaghetti-condition growth) that hunts for "code-judo" reframes collapsing whole branches / helpers / modes / layers rather than polishing them. Read-only — it reports findings and hands each fix to a `fixer`. `review-phase` Layer 3 now applies a condensed version of this lens on every phase and escalates to the full audit only when a phase touches core architecture, crosses ~1,000 lines, or surfaces a structural smell too big to fix inline.
+- **`handoff-to-client` (opt-in, API-only repos)** — generates a self-contained markdown document for the client teams consuming the repo's API: every endpoint / operation added, changed, deprecated, or removed on the current branch vs. the default branch, with request/response shapes derived from the code, auth + error changes, breaking-change flags judged from the strictest plausible client, one realistic example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (required `client_platforms`, plus `api_style` / `api_spec_path` / `output_dir`).
+
+Alongside the new skills, **`implement-plan` was decomposed into a modular plan-execution unit** — a thin conductor plus three co-shipped single-purpose sub-skills (`implement-phase`, `review-phase`, `integrate-phase`). `review-phase` is now the one review implementation shared by `implement-plan`, `amend-plan`, and `systematic-debugging`. The behavior is unchanged; the split is for reviewability and determinism. Two more knobs land in `.vinta-ai-workflows.yaml`: **`agent_models`** (set a tier per `reviewer` / `fixer` / `worktree_prep` / `integrate` so the review sub-agents and mechanical steps aren't stuck on the runtime default), and **E2E tests are now opt-in** in both `plan-feature` and `implement-plan` (they make runs materially slower; default off, re-enable per-run or per-project).
+
 ### Foundation skills (project-agnostic)
 
 Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
@@ -227,10 +239,15 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
 | `review-phase` | always (unit) | Plan-execution sub-skill: the three-layer review (mechanical / plan-compliance / independent reviewer) + fix loop. Shared by `implement-plan`, `amend-plan`, and `systematic-debugging`. |
 | `integrate-phase` | always (unit) | Plan-execution sub-skill: push the reviewed phase along the project's commit strategy + open the PR via context file. Under `commit_strategy = ask`, ships as `integrate-phase-stacked` + `integrate-phase-modular`. |
 | `amend-plan` | always (generated) | History-rewriting companion to `implement-plan` — revises in-flight plans, amends prior-phase commits, force-pushes, rebases stacked downstream branches. Reuses `review-phase` + `implement-phase`'s shared prompt loop. |
+| [`handoff`](skills/vinta-derive-skills/resources/foundation-skills/handoff/SKILL.md) | always | Session-continuation handoff doc → `.vinta-ai-workflows/handoffs/`. **Write** captures goal, verified-vs-unverified state, decisions + rejected alternatives, landmines, and the single next step — gathered from the repo, never memory. **Resume** verifies a handoff's claims against the repo before continuing from its next step. |
+| [`deslop-comments`](skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md) | always | Rewrite comments + doc blocks touched during a task into Simple English (strips AI-slop vocabulary + negative framing; comment-only — no renames, no behavior change). `review-phase` Layer 2 depends on it; also invokable standalone. |
 | `systematic-debugging` | **opt-in** | Root-cause-first debugging with project-specific repro commands + MCP evidence-gathering (error tracking, traces, logs, metrics, alerts). Renders from a catalogue of observability MCP servers the user declares. |
 | `add-e2e-test` | **opt-in** | Add an e2e test. Body covers e2e framework, page-object pattern, auth/storage-state, seed helpers, tenant scoping, screenshot conventions. |
 | `add-env-var` | **opt-in** | Propagate a new env var through every layer (`.env.example`, build tool envPrefix, build cache hash, app config, AGENTS.md, CI, deploy injection). |
 | [`add-one-off-script`](skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md) | **opt-in** | Author one-off operational scripts (backfills, cleanups, ad-hoc fixes). Ships a `BaseOneOffScript` class (Python + TS) enforcing dry-run default, idempotency, batched DB ops, segmented CSV backups, signal-safe interruption, multi-sink logging. |
+| [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it. |
+| [`thermo-nuclear-code-quality-review`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | **opt-in** | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to `fixer`. `review-phase` Layer 3 runs a condensed lens every phase and escalates to this full audit on core-architecture / ~1000-line / structurally-smelly phases. |
+| `handoff-to-client` | **opt-in** | (API-only repos) Generate a self-contained API-change handoff doc for the client teams consuming the repo's API — every endpoint / operation added / changed / deprecated / removed vs the default branch, with request/response shapes, auth + error changes, breaking-change flags, one example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (client platforms, API style, spec path). |
 
 ### Foundation sub-agents (project-agnostic)
 
@@ -251,7 +268,7 @@ Bootstrap is a snapshot. `vinta-ai-workflows` keeps shipping — new foundation
 ### The flow at a glance
 
 ```bash
-# 1. Pull the new package version (or update the git+ssh ref).
+# 1. Pull the new package version.
 npm update vinta-ai-workflows
 
 # 2. Run the sync skill from your AI tool.
@@ -314,48 +331,48 @@ To bring a previously-bootstrapped project up to date with a newer package versi
 
 ## Install variants
 
-The package is private. Two install paths.
-
-### A. From git+ssh (no registry needed)
+The package is published to the public npm registry. Three install paths.
 
-Each developer's GitHub SSH key needs read access to the repo. Then:
+### A. From the npm registry (default)
 
 ```bash
 # inside the target project
-npm  install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
-pnpm add  -D   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
-yarn add  -D   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
-bun  add  -d   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
+npm  install -D vinta-ai-workflows
+pnpm add  -D   vinta-ai-workflows
+yarn add  -D   vinta-ai-workflows
+bun  add  -d   vinta-ai-workflows
 ```
 
-Pin a tag/commit when you want determinism:
+Pin a version when you want determinism:
 
 ```bash
-npm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#0.1.0
+npm install -D vinta-ai-workflows@0.2.0
 ```
 
-### B. From GitHub Packages (if/when published)
+### B. From git+ssh (an unreleased ref)
 
-In the project root, add `.npmrc`:
+Use this to install a branch or commit that isn't published yet — each developer's GitHub SSH key needs read access to the repo:
 
-```ini
-@vinta:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```bash
+# inside the target project
+npm  install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
+pnpm add  -D   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
+yarn add  -D   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
+bun  add  -d   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
 ```
 
-Export `GITHUB_TOKEN` (a Personal Access Token with `read:packages` and the `repo` scope for private repos), then:
+Pin a tag/commit when you want determinism:
 
 ```bash
-npm install -D vinta-ai-workflows
+npm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#0.1.0
 ```
 
-### One-shot via npx (no install)
+### C. One-shot via npx (no install)
 
 If you don't want the dep tracked in `package.json`:
 
 ```bash
-npx -y -p git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git \
-  vinta-ai-workflows install --tool all
+npx -y -p vinta-ai-workflows vinta-ai-workflows install --tool all
 ```
 
 ### Picking a tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.2.0-alpha7",
+  "version": "0.3.0",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
   "bin": {

package/schemas/vinta-ai-workflows-config.v1.schema.json

@@ -245,6 +245,37 @@
         "fixer": { "type": "string", "enum": ["enabled", "disabled"] }
       }
     },
+    "agent_models": {
+      "description": "Per-role / per-task model selection for the plan-execution family, expressed as **tiers** (1–4) into the same table `plan-feature` uses — `ai-tools/skills/plan-feature/resources/ai-models.yaml`. Each consuming skill resolves a tier to a concrete model at runtime: take that tier's `models`, filter to the vendors the runtime exposes, pick the cheapest survivor. This keeps the config free of hard-coded model IDs (which go stale) — the nightly `check-ai-models` job keeps the tier table fresh. Every key is optional; an unset key (or the whole section absent) means the spawn uses the runtime's default model, i.e. today's behavior. These are the **project defaults**: the `reviewer` / `fixer` tiers here can be overridden per phase by a plan's optional `**Review models**:` line (a phase override wins over the value here for that phase only — see `plan-feature`). The per-phase implementer model is NOT here — that stays owned by each plan phase's `**Suggested AI model**:` line. The mechanical steps (`worktree_prep`, `integrate`) are never plan-named.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "reviewer": {
+          "description": "Default tier for the independent reviewer subagent spawned by `review-phase` (Layer 3). Reviewing wants a capable model — Tier 3 is the usual default. A plan phase's `**Review models**:` line can override this for that phase. Unset (and no phase override) → runtime default.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4
+        },
+        "fixer": {
+          "description": "Default tier for the fixer subagent spawned by `review-phase`'s fix loop to apply one reviewer finding. Narrow, well-specified edits — Tier 2 is the usual default. A plan phase's `**Review models**:` line can override this for that phase. Unset (and no phase override) → runtime default.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4
+        },
+        "worktree_prep": {
+          "description": "Tier for the mechanical worktree-provisioning step (`prepare-worktree`), which `implement-plan` / `amend-plan` run once at the start of a worktree-enabled run. When set, the conductor delegates the step to a subagent at this tier instead of running it inline in its own (usually pricier) session. Mechanical, precedent-driven work — Tier 1 is the usual default. Unset → conductor runs it inline. Irrelevant when `foundation_skills.prepare-worktree` is `disabled`.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4
+        },
+        "integrate": {
+          "description": "Tier for the mechanical integrate step (`integrate-phase`: push the phase branch + open/update the PR via the bundled `open-pr.sh`) that `implement-plan` runs once per phase. When set, the conductor delegates the step to a subagent at this tier instead of running it inline. Mechanical git + PR-context work — Tier 1 is the usual default. Unset → conductor runs it inline. The PR-context file + `open-pr.sh` remains the only PR-creation path regardless of who runs the step.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4
+        }
+      }
+    },
     "stacks": {
       "description": "Stack templates applied at bootstrap (e.g. `medplum`, `django`, `nextjs-app-router`).",
       "type": "array",
@@ -389,10 +420,16 @@
               "default": "fork-on-schema-change"
             },
             "summary_dir": {
-              "description": "Where per-worktree summary YAMLs land. Default `.vinta-ai-workflows/worktrees` — covered by the umbrella gitignore added in 0.1.3. The skill writes `<summary_dir>/<name>.yaml` per provisioned worktree; teardown reads it.",
+              "description": "Where per-worktree summary YAMLs land. Default `.vinta-ai-workflows/worktrees` — covered by the umbrella gitignore added in 0.1.3. The skill writes `<summary_dir>/<name>.yaml` per provisioned worktree; teardown reads it. The generated compose override (see `shared_volumes`) also lands here as `<summary_dir>/<name>.docker-compose.override.yml`.",
               "type": "string",
               "minLength": 1,
               "default": ".vinta-ai-workflows/worktrees"
+            },
+            "shared_volumes": {
+              "description": "Compose volume KEYS (as they appear under top-level `volumes:` in the project's compose config) that are safe to keep SHARED across worktrees — a read-only dep/venv/asset cache with no write churn. The skill's compose-isolation step (Step 4a) forks EVERY `external:`/fixed-`name:` volume into a worktree-namespaced copy by default (COMPOSE_PROJECT_NAME does not isolate those, and two servers on one DATA volume corrupts the store); volumes listed here are exempted and stay shared. NEVER list a database/data volume here. Passed through to `scripts/gen-compose-worktree-override.sh --share-volume`. Empty/omitted = fork every leaky volume (safest).",
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "default": []
             }
           }
         },

package/skills/vinta-bootstrap-ai-tools/SKILL.md

@@ -81,6 +81,8 @@ These bleed across sub-skills, so capture once now:
 
    Lands in `.vinta-ai-workflows.yaml` `policies.commit_strategy`. Drives the `implement-plan` template's branch / commit / PR-opening flow + the `amend-plan` skill's supported-strategies check.
 
+9. **Agent model tiers (optional).** The plan-execution family picks the **implementer** model per phase from the plan itself, but the **reviewer**, **fixer**, and the mechanical steps (**worktree prep**, **opening the PR / integrate**) have no model input unless the project sets one. Offer to pin each to a **tier** (1–4) into the same table `plan-feature` uses — `ai-tools/skills/plan-feature/resources/ai-models.yaml` — so review runs on a capable model while cheap mechanical work runs on a cheap one. `AskUserQuestion`: `Use recommended defaults (reviewer 3, fixer 2, worktree prep 1, integrate 1)`, `Customize each`, `Leave unset — every spawn uses the runtime default`. On `Customize each`, ask a per-role tier (1–4) for `reviewer` / `fixer` / `worktree_prep` / `integrate`. Land the chosen tiers in `.vinta-ai-workflows.yaml` `agent_models`; omit any role the user leaves unset (unset → runtime default). Recommend the defaults for most teams; recommend `Leave unset` only when the runtime exposes a single model anyway. Note `worktree_prep` is a no-op unless `prepare-worktree` is enabled, and setting `worktree_prep` / `integrate` makes `implement-plan` delegate those steps to a cheap subagent instead of running them inline.
+
 ### D. Optional foundation skills
 
 Seven skills are part of the foundation set but aren't always needed. Ask explicitly:
@@ -270,6 +272,15 @@ foundation_agents:
   reviewer: enabled
   fixer: enabled
 
+# Only emit the roles the user chose in the "Agent model tiers" question (C.9).
+# Omit the whole block on "Leave unset"; omit any individual role left unset.
+# Each value is a tier (1–4) into ai-tools/skills/plan-feature/resources/ai-models.yaml.
+agent_models:
+  reviewer: <C.9 → reviewer tier, default 3>
+  fixer: <C.9 → fixer tier, default 2>
+  worktree_prep: <C.9 → worktree_prep tier, default 1; omit when prepare-worktree disabled>
+  integrate: <C.9 → integrate tier, default 1>
+
 stacks: <Stack detection → matched stacks>
 stack_specialist_agents: <empty unless user supplied templates>
 
@@ -301,6 +312,10 @@ skills:
     compose_network: per-worktree
     test_db_strategy: <prepare-worktree follow-up — fork-on-schema-change | always-fork | share>
     summary_dir: .vinta-ai-workflows/worktrees
+    # Compose volume keys safe to keep shared across worktrees (read-only dep/venv
+    # caches only — NEVER a data/DB volume). Empty = fork every external/named
+    # volume (safest). See prepare-worktree Step 4a.
+    shared_volumes: []
 
   # Only emit this block when foundation_skills.add-one-off-script = enabled.
   add-one-off-script:

package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md

@@ -245,6 +245,8 @@ Tests:
 
 **Suggested AI model**: {tier choice + why}. See "AI model selection".
 
+**Review models** (optional — omit for the project defaults): reviewer Tier {N}, fixer Tier {N} — {why this phase warrants a non-default review model}. See "AI model selection".
+
 **Reusable skills**: {invoke `Skill(name)` — see "Project skills"}.
 
 Acceptance: {one literal statement true after merge + deploy of this phase, only this phase}.
@@ -318,6 +320,15 @@ Common mistake: leave cross-repo producer wiring for last, then discover the ups
 
 For each phase, suggest **cheapest/fastest model likely to one-shot work**. Iterating with cheap model usually beats burning Opus tokens on CRUD scaffold.
 
+**Scope: the plan always picks the *implementer* model, and MAY override the reviewer / fixer models per phase.**
+
+- `**Suggested AI model**:` drives the implementer subagent that writes the phase — **required on every phase**.
+- `**Review models**:` (optional) overrides the reviewer and/or fixer tier **for this phase only**. Use it when a phase is riskier than average — high blast-radius change, subtle concurrency / transaction logic, security-sensitive surface, a migration that's hard to undo — and you want a more capable reviewer or fixer than the project default. Name a tier for reviewer, fixer, or both; omit either to leave that role on the default.
+- **Precedence** (resolved by `implement-plan` / `review-phase`): a phase's `**Review models**:` override wins → else the project-wide `agent_models.reviewer` / `agent_models.fixer` tier in `.vinta-ai-workflows.yaml` → else the runtime default. So the project keeps sane defaults and the plan only speaks up for the phases that need a different review model.
+- The mechanical-step models (worktree prep, opening the PR / integrate) are **not** plan-owned — they stay under `agent_models` in `.vinta-ai-workflows.yaml`. Don't add worktree/PR model hints to a phase; they'd be ignored.
+
+**Most phases carry only the implementer line.** Add `**Review models**:` deliberately, for the few phases that earn it — not by default on every phase.
+
 **Concrete model IDs per tier live in [resources/ai-models.yaml](resources/ai-models.yaml) — read that file when writing each suggestion. Never recall model names from memory; they go stale as vendors ship.** The tiers below define *when* each applies (stable judgement); the IDs drift, and a nightly job keeps the resource current. Note the file's `last_verified` date — if it's far in the past, the IDs may be stale; flag that rather than trusting them blindly.
 
 ### Tier 1 — cheapest/fastest (boilerplate, exact-precedent edits)
@@ -342,6 +353,14 @@ When one tier doesn't fit, name both:
 
 > **Suggested AI model**: Tier 2 for repository + serializer; step up to Tier 3 for the integration test spanning upsert → routing → reprocess. IDs per tier in [resources/ai-models.yaml](resources/ai-models.yaml).
 
+### Overriding the review models on a critical phase (optional)
+
+Add a `**Review models**:` line **only** when the phase justifies a non-default reviewer / fixer. Pick the tier from the same rubric — a higher tier for the *review* of a delicate change, not for its authoring:
+
+> **Review models**: reviewer Tier 4 — this phase rewrites the transactional batch-apply protocol with deferred constraints; a subtle ordering bug here corrupts data, so the independent review runs on the most capable model. Fixer left on the project default.
+
+Name only the role you're changing (`reviewer`, `fixer`, or both). Omitting the line entirely — the common case — leaves both roles on the project's `agent_models` defaults.
+
 **Default to cheapest tier that plausibly works, not safest.** Cheap models failing fast beats expensive succeeding slowly.
 
 ## Project skills to leverage
@@ -406,6 +425,7 @@ When in doubt, model the plan after a recent example in `ai-plans/` — look for
 - [ ] Phase numbering uses numbers + letters consistently.
 - [ ] **Phase granularity matches the Step 0 answer.** Default (one-use-case-per-phase): at least one phase per spec use-case, no phase implements two use-cases. If bundling was chosen: grouped phases stay MR-sized, one concern, independently mergeable. Cross-cutting scaffolding is its own foundation phase either way.
 - [ ] Each phase has Goal / Spec use-case / Feature flag (or explicit waiver) / Changes / Tests / Suggested AI model / Reusable skills / Acceptance.
+- [ ] `**Review models**:` appears **only** on phases that justify a non-default reviewer / fixer (not on every phase); each such line names a tier + why. Phases without it inherit the project's `agent_models` defaults.
 <!-- e2e:start -->
 - [ ] **If e2e coverage was opted into at Step 0:** every phase introducing a new UI flow has an **E2E happy-path test** in its Tests block, with screenshot output to `pr-screenshots/`. If it was not opted into (default), **no phase carries an e2e spec** and there is no `QA_USE_CASES.md` / `pr-screenshots/` reference.
 <!-- e2e:end -->

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md

@@ -109,6 +109,8 @@ Default: **copy** for pnpm + npm + cargo + go; **reinstall** for poetry + venv +
 
 `env_change = true` → `cp <main>/.env <worktree>/.env`. Then mutate per the **Database fork** step (DB URL) + the **Docker / compose isolation** step (compose project name).
 
+**Compose forces a copy.** If the project uses compose, the [4a](#4a--neutralize-compose-isolation-leaks) sub-step appends `COMPOSE_FILE=…` to the worktree's `.env` — a mutation. So a compose project ALWAYS needs a copied `.env` (or a copied `.envrc`) even when `env_change = false`; a symlinked `.env` would leak the `COMPOSE_FILE` line into main. Treat "project uses compose" as an independent reason to copy `.env`.
+
 `.env.example` is **always** symlinked — it's committed; the worktree should keep tracking it.
 
 ### 2c — Skip rules
@@ -129,6 +131,11 @@ Whatever the app reads + writes during local dev. Detect the connection string s
 2. Project config files: `config/database.yml` (Rails), `database.ini`, `prisma/schema.prisma`'s `datasource`, `knexfile.js`, Django `settings.py`'s `DATABASES`.
 3. Docker compose service env: `services.db.environment.POSTGRES_DB`.
 
+**First, determine HOW the DB is delivered — this changes what "share" even means.** Two deliveries:
+
+- **External server** — the DB runs on a server the worktree only *connects* to (a system Postgres, an RDS instance, a compose service the worktree does NOT boot its own copy of). Here "share" = point the worktree's connection string at the one already-running server. Fork = clone into a new DB *on that same server*.
+- **Per-worktree compose stack** — the DB is delivered *through the worktree's own `docker compose up`* (a `db` service the worktree boots). Here the worktree runs its **own server process**. "Share" the way the connection-string sense means is impossible without corruption: booting a second server against the same data volume is two postmasters on one PGDATA. **For compose-delivered DBs the data volumes are ALWAYS forked, independent of `schema_change`** — see the [Neutralize compose isolation leaks](#4a--neutralize-compose-isolation-leaks) sub-step, which does the volume fork mechanically. `schema_change = false` may still let you skip *cloning main's data* into the forked volume (boot empty + migrate), but it never authorizes a shared data volume.
+
 For each detected DB, ask the user (`AskUserQuestion`) once:
 
 - **Fork the DB** — recommended when `schema_change = true` or when the plan's phases run destructive migrations. Strategy depends on the engine:
@@ -137,7 +144,7 @@ For each detected DB, ask the user (`AskUserQuestion`) once:
   - **SQLite (file-based)** — `cp <main>/db.sqlite3 <worktree>/db.sqlite3`. Symlink would defeat the point.
   - **Mongo / Redis / Elasticsearch** — engine-specific clone, OR per-worktree DB name / key prefix (`REDIS_URL=redis://localhost:6379/<index>` with a free index; `MONGODB_URI=mongodb://localhost:27017/<db>_wt_<name>`).
 
-- **Share the DB (don't fork)** — only safe when `schema_change = false` AND there's no risk of conflicting writes. Symlink the SQLite file or point the worktree's env at the same URL. Warn explicitly: "DB shared with main checkout — destructive ops here will be visible in main."
+- **Share the DB (don't fork)** — means share a *connection to a single already-running server*, nothing more. Only safe when the DB is an **external server** (NOT compose-delivered — see the delivery check above) AND `schema_change = false` AND there's no risk of conflicting writes. Symlink the SQLite file or point the worktree's env at the same URL. Warn explicitly: "DB shared with main checkout — destructive ops here will be visible in main." **Never read this bullet as permission to point a second per-worktree compose server at a shared data volume** — that is not sharing a connection, it is running two servers on one data directory, and it corrupts the store regardless of `schema_change`.
 
 - **Stub the DB** — point the worktree at a fresh empty DB (`createdb <main_db>_wt_<name>` + run all migrations + seed if a seed exists). Best when the feature needs schema parity but no production data.
 
@@ -147,10 +154,12 @@ Record the chosen strategy + the forked DB name in the worktree summary (written
 
 A different beast — tests on the same engine but a different DB name (`<main_db>_test`, `test_<repo>`). Parallel worktrees running tests against the same `<main_db>_test` will overwrite each other's fixtures and produce flaky failures.
 
-- **`pytest-django` / `pytest`** — set `--reuse-db` per worktree via a per-worktree `DJANGO_SETTINGS_MODULE` env, OR override `DATABASES['default']['NAME']` to `<main_db>_test_wt_<name>` in `conftest.py` when the env var `WORKTREE_NAME` is set. Drop a `conftest_worktree.py` patch in the worktree (don't edit `conftest.py` in tracked code — too easy to commit by accident).
-- **`vitest` / `jest`** — set `TEST_DATABASE_URL` per worktree; ensure the test setup respects it.
-- **Rails** — `DATABASE_URL` for the `test` env, `<main_db>_test_wt_<name>`.
-- **Docker-compose-based test DB** — see the **Docker / compose isolation** step below; per-worktree compose project name fixes it.
+**The principle (stack-agnostic):** give the worktree its own test DB name (`<main_db>_test_wt_<name>`), inject it through whatever channel the test runner already reads (an env var or a per-worktree config override), and **never edit tracked test config in place** — a worktree-local override or an env var is safe; a change to a committed config file is one `git add -A` away from leaking into main. How each runner exposes that channel:
+
+- **Env-var runners (`vitest` / `jest`, `go test`, `cargo test`, most CI-shaped suites)** — set `TEST_DATABASE_URL` (or the suite's equivalent) per worktree and confirm the test setup reads it. Simplest case; no file edits at all.
+- **Config-file runners (`pytest-django` / `pytest`)** — set `--reuse-db` per worktree via a per-worktree `DJANGO_SETTINGS_MODULE`, OR override `DATABASES['default']['NAME']` to `<main_db>_test_wt_<name>` guarded on a `WORKTREE_NAME` env var. Put the override in a `conftest_worktree.py` in the worktree — don't touch the tracked `conftest.py`.
+- **Convention-based runners (Rails)** — point the `test` env's `DATABASE_URL` at `<main_db>_test_wt_<name>`.
+- **Docker-compose-based test DB (any stack)** — see the **Docker / compose isolation** step below; a per-worktree compose project name fixes it.
 
 If `test_infra_change = true` → fork the test DB unconditionally. If `false` and the user says "share is fine" → still flag the race risk; offer a one-line fix to switch later.
 
@@ -166,10 +175,15 @@ If the project has a `docker-compose.yml` / `compose.yaml` / `docker-compose.ove
 
 1. Set `COMPOSE_PROJECT_NAME=<repo>_<worktree-name>` in the worktree's `.env` (or in a `.envrc` if the project uses direnv). Then `docker compose up` inside the worktree spins a fresh container set.
 
-2. **Shared network** — if the worktree's app needs to reach services running in the *main* checkout's compose stack (a queue, a cache, a search index that's expensive to spin twice), put them on an external network:
+   **`COMPOSE_PROJECT_NAME` is necessary but NOT sufficient.** It namespaces containers and networks, and auto-named volumes — but it does **not** isolate two very common compose patterns: volumes declared `external: true` and/or pinned to a fixed top-level `name:`, and services with fixed host port bindings (`ports: - "5432:5432"`). A shared *database* volume is the dangerous one: two worktree stacks (or a worktree stack + main's stack) mount the same physical volume, so two server processes run against one data directory → corruption. The next sub-step closes both leaks mechanically.
+
+2. **Neutralize compose isolation leaks** — see [4a](#4a--neutralize-compose-isolation-leaks) below. Run this whenever the project has compose, before ever booting the worktree's stack.
+
+3. **Shared network** — if the worktree's app needs to reach services running in the *main* checkout's compose stack (a queue, a cache, a search index that's expensive to spin twice), put them on an external network:
 
    ```yaml
-   # docker-compose.override.yml in the worktree (or in main; pick one place)
+   # Add to the SAME out-of-tree override the 4a sub-step generates — NOT a
+   # tracked docker-compose.override.yml at the worktree root (see 4a for why).
    networks:
      shared:
        external: true
@@ -182,9 +196,44 @@ If the project has a `docker-compose.yml` / `compose.yaml` / `docker-compose.ove
 
    Or use `network_mode: host` if the project uses that pattern. Decide once per project and record in `.vinta-ai-workflows.yaml` → `run_options.prepare-worktree.compose_network: per-worktree | shared-external | host`.
 
-3. **Linters / formatters / test runners that run inside docker** (a Dockerfile-based `pnpm test`, a `lint` target that mounts source into a sidecar container) — these MUST run with the worktree's `COMPOSE_PROJECT_NAME`. Otherwise concurrent runs hit the same container and one wins. The standard fix: ensure the project's lint/test scripts read `COMPOSE_PROJECT_NAME` from env instead of hard-coding it.
+4. **Linters / formatters / test runners that run inside docker** (a Dockerfile-based `pnpm test`, a `lint` target that mounts source into a sidecar container) — these MUST run with the worktree's `COMPOSE_PROJECT_NAME`. Otherwise concurrent runs hit the same container and one wins. The standard fix: ensure the project's lint/test scripts read `COMPOSE_PROJECT_NAME` from env instead of hard-coding it.
+
+5. **Per-worktree volumes** — for a volume the project leaves un-named, compose auto-namespaces it by project name and it's already isolated. But projects routinely pin data volumes with `external: true` or a fixed `name:` (for good reasons of their own — you must NOT edit their committed compose to "fix" that). Those are the leaks the [4a](#4a--neutralize-compose-isolation-leaks) sub-step re-pins in a generated override. Never touch the tracked compose file to change a volume's isolation; the override is the only lever.
+
+### 4a — Neutralize compose isolation leaks
+
+Runs whenever the project has any compose file, before the worktree's stack is ever booted. Fully project-agnostic — every decision is driven by `docker compose config --format json`, no project / service / volume name is hardcoded.
+
+**1. Generate the override.** Run the bundled [scripts/gen-compose-worktree-override.sh](scripts/gen-compose-worktree-override.sh):
+
+```bash
+override=$(scripts/gen-compose-worktree-override.sh \
+  --main     <main-checkout-root> \
+  --worktree <worktree-path> \
+  --name     <worktree-name> \
+  --out      <summary_dir>/<name>.docker-compose.override.yml \
+  --share-volume <volkey>...)   # 0+ volumes safe to keep shared (see below)
+```
+
+The script renders the resolved config from the main checkout and, for the worktree:
+- re-pins every volume that is `external: true` OR carries a fixed top-level `name:` to a **non-external, worktree-namespaced** volume (`<project>_wt_<name>_<volkey>`), so the worktree's server writes to its OWN physical volume;
+- strips host port publishing from every service that publishes a fixed port (via compose's `!override []` — a plain `ports: []` **merges/appends** in Compose v2+ and would NOT strip it; verified on Docker Compose v5.1.1);
+- leaves alone any volume already namespaced by project name (auto-named), and any volume the caller passes via `--share-volume` (a read-only dep/venv cache with no dep churn is safe to keep shared — the config's `shared_volumes` list feeds this arg).
+
+The script exits non-zero with a clear message if `docker compose` is unavailable or the config doesn't parse; surface that and stop (don't boot a stack you couldn't prove is isolated).
+
+**2. Write it OUT OF TREE and wire it in via the copied `.env`.** The override goes to `<summary_dir>/<name>.docker-compose.override.yml` (under the already-ignored `.vinta-ai-workflows/` umbrella) — **NOT** a `docker-compose.override.yml` at the worktree root. Rationale: a root `docker-compose.override.yml` is auto-loaded by compose, but it is frequently a **tracked** file (it was in the project that hit the 2026-07-17 incident); writing the generated override there pollutes the worktree diff and risks `git add -A` leaking it into main. Instead, wire it in by appending to the worktree's **copied** `.env`:
+
+```bash
+# The generator prints exactly this line (base:override) on stderr — use it verbatim.
+echo "COMPOSE_FILE=<base-compose-file>:<ABSOLUTE-override-path>" >> <worktree>/.env
+```
+
+`COMPOSE_FILE` makes compose load base + override for every `docker compose` call in the worktree without touching any tracked file. The **override path must be absolute** — it lives under `<summary_dir>` (outside the worktree), so a bare basename wouldn't resolve from the worktree's compose project dir; the generator prints the absolute path for you (and on stdout, for `$(...)` capture). The base file stays relative — the worktree carries its own tracked copy. **This requires `.env` to be COPIED, not symlinked** — appending to a symlinked `.env` leaks the line into main. If the **Env files** step decided `env_change = false` (symlink), flip `.env` to a copy here (compose isolation is itself an env change) and note it in the summary. Use the exact base compose filename the generator reports (`compose.yaml` vs `docker-compose.yml`).
+
+**3. Record the decision.** Write the per-volume fork decisions and the override path into the summary YAML's `state.compose` (see the **Write the summary file** step). The override's own `volumes:` block is the teardown manifest — each pinned `name:` is a `docker volume rm` target.
 
-4. **Per-worktree volumes** — let compose auto-create volumes namespaced by project name. Don't manually `external: true` data volumes (defeats isolation).
+**Relation to `test_db_strategy`.** The `test_db_strategy: fork-on-schema-change` config governs the **test-DB axis only** (Step 3b — which test DB *name* the runner targets). It says nothing about compose data volumes and must **never** be read as permission to share the compose stack's volumes. Volume forking here is unconditional for compose-delivered DBs, independent of `schema_change` and independent of `test_db_strategy`.
 
 ## Step 5 — Other shared infra to fork
 
@@ -303,6 +352,14 @@ state:
   compose:
     project_name: <repo>_<worktree-name>
     network_strategy: per-worktree | shared-external | host
+    override_path: <summary_dir>/<name>.docker-compose.override.yml   # null when no compose
+    base_compose_file: docker-compose.yml    # the base file COMPOSE_FILE prepends
+    forked_volumes:                          # [] when nothing leaked; teardown removes each name
+      - volume_key: pgdata                   # the compose key
+        reason: external | fixed-name        # why it leaked past COMPOSE_PROJECT_NAME
+        forked_name: <repo>_wt_<name>_pgdata # the worktree-namespaced physical volume
+    shared_volumes: [virtualenv]             # leaky volumes deliberately kept shared (--share-volume)
+    ports_stripped_from: [db, cache]         # services whose fixed host ports the override removed
   other:
     redis_db_index: <int>
     s3_prefix: wt-<name>/
@@ -346,7 +403,12 @@ guard is active; the orchestrator's post-run stray-write check is the backstop.
 When the plan is merged / abandoned:
   git worktree remove <path>
   <drop-db command>          # if fork strategy was `fork`
-  docker compose -p <project_name> down -v   # if compose was forked
+  # Compose (if forked). Do NOT use `down -v` — it can also nuke SHARED volumes
+  # (a fixed-name dep/venv cache). Bring the stack down, then remove only the
+  # worktree-namespaced volumes the override created:
+  docker compose -p <project_name> down
+  docker volume rm <each state.compose.forked_volumes[].forked_name>
+  rm <override_path>         # the generated out-of-tree compose override
 
 The summary file at `.vinta-ai-workflows/worktrees/<name>.yaml` records every
 decision for mechanical teardown.
@@ -371,7 +433,10 @@ A sibling skill / explicit command — not auto-run by this skill. Steps:
 1. Confirm no uncommitted changes in the worktree (`git -C <path> status`).
 2. `git worktree remove <path>` (or `--force` after explicit confirmation if the user is fine losing work).
 3. Drop the forked DB (`dropdb <forked_name>`, `DROP DATABASE`, `rm <sqlite-file>`, …) — read the strategy from the summary YAML.
-4. `docker compose -p <project_name> down -v` for forked compose.
+4. Compose teardown (read `state.compose` from the summary YAML):
+   - `docker compose -p <project_name> down` — **not `down -v`**; a bare `down -v` also removes shared volumes (a fixed-name dep/venv cache in `state.compose.shared_volumes`), which belong to main.
+   - `docker volume rm <forked_name>` for each entry in `state.compose.forked_volumes` — these are the worktree-only volumes the generated override created; removing them is safe and leaves main's / shared volumes untouched.
+   - `rm <state.compose.override_path>` — delete the generated out-of-tree override.
 5. Remove `.vinta-ai-workflows/worktrees/<name>.yaml`.
 
 Every step gated on user confirmation when the worktree has un-pushed branches.
@@ -380,6 +445,7 @@ Every step gated on user confirmation when the worktree has un-pushed branches.
 
 - **Symlink for reads, copy for writes, fork for state.** This is the only mental model that scales. Default to fork when unsure — disk is cheap, corrupted main-checkout DBs are not.
 - **Never share a writable DB across worktrees by default.** The race conditions are subtle and the failure mode is silent data corruption.
+- **`COMPOSE_PROJECT_NAME` does not isolate `external:`/fixed-`name:` volumes or fixed host ports — always run the [4a](#4a--neutralize-compose-isolation-leaks) generator.** For a compose-delivered DB the data volumes are forked *unconditionally* (independent of `schema_change` and `test_db_strategy`): the worktree runs its own server, and two servers on one volume is corruption. "Share the DB" only ever means share a connection to a single already-running server, never a second server on shared storage. The fix is a generated, out-of-tree override + a `COMPOSE_FILE` line in the copied `.env` — never an edit to any tracked compose file. Verify the volume-differs invariant before declaring the worktree runnable.
 - **Every fork decision lands in `.vinta-ai-workflows/worktrees/<name>.yaml`.** Teardown reads it; humans grep it; agents resuming a stalled plan read it. No decision lives only in conversation memory.
 - **Worktree root governed by runtime conventions.** claude-code uses `.claude/worktrees/`; other harnesses use sibling dirs. Don't fight the harness — match it.
 - **Don't mutate the main checkout from this skill.** Every write goes to the worktree or to `.vinta-ai-workflows/`. Forking a Postgres DB is the one exception (the new DB lives in the same server) — document it loudly in the summary.
@@ -395,6 +461,9 @@ Every step gated on user confirmation when the worktree has un-pushed branches.
 - **Symlinking `node_modules` for a `pnpm add` phase.** The new package writes back through the symlink into the main checkout's store. Detect dep churn in the **Plan inspection** step and copy/reinstall instead.
 - **Forking the dev DB but forgetting the test DB.** Tests still hit the shared test DB and stomp on parallel worktrees' fixtures. Both axes need their own decision in the **Database fork** step.
 - **Forgetting `COMPOSE_PROJECT_NAME`.** Containers from worktree-A overwrite worktree-B's containers; volumes get nuked. Set it in `.env` so every `docker compose` call inherits.
+- **Trusting `COMPOSE_PROJECT_NAME` to isolate `external:`/fixed-`name:` volumes and fixed host ports — it does NOT.** These defeat the project-name namespace: every worktree's compose stack mounts the SAME external/named volume and binds the SAME host port. For a DB volume that means two server processes on one data directory — the 2026-07-17 corruption incident (a worktree's `docker compose down` deleted the shared `postmaster.pid` and the main checkout's Postgres self-terminated). The fix is the [4a](#4a--neutralize-compose-isolation-leaks) generated out-of-tree override, never an edit to the tracked compose file. Verify the invariant (Verification step 6), don't assume it.
+- **Confusing "share the DB" (a connection to one running server) with "share the data volume" (a second server on shared storage).** The first can be safe when `schema_change = false`; the second is always corruption. `schema_change = false` and `test_db_strategy` never authorize a shared compose data volume — see [3a](#3a--dev--app-database).
+- **Writing the compose override to the worktree-root `docker-compose.override.yml`.** It's auto-loaded (convenient) but often a *tracked* file — the generated override then shows up in the diff and one `git add -A` leaks it into main. Write it under `<summary_dir>/` and wire it in via `COMPOSE_FILE` in the COPIED `.env` ([4a](#4a--neutralize-compose-isolation-leaks)).
 - **Sharing a Redis DB without per-worktree prefix.** Tests writing `user:123` collide across worktrees. Pick an index OR a key prefix.
 - **Copying `node_modules` for yarn PnP / absolute-path setups.** The copy carries baked-in paths from the main checkout. Reinstall instead — pnpm's relative-symlink store is the safe-to-copy exception.
 - **Forgetting to `--allow` the `.vinta-ai-workflows` dir under sandbox.** It's shared/symlinked but the run *writes* it (summary YAMLs, prs-context). If it's not an `--allow` exception, those writes hit the read-only main subtree and fail mid-run. Pass it alongside the worktree path.
@@ -413,4 +482,7 @@ After the **Write the summary file** step writes the summary:
 3. `git -C <worktree-path> status` is clean (no accidental file additions from the prep step).
 4. The summary YAML parses (`python3 -c "import yaml; yaml.safe_load(open('.vinta-ai-workflows/worktrees/<name>.yaml'))"`).
 5. `WORKTREE.md` exists at the worktree root with accurate fork / share annotations.
-6. Optional smoke test: run a single new-test command in the worktree (e.g. `pytest -x tests/health.py`) — confirms env vars resolved, DB reachable, deps importable.
+6. **Compose volume-isolation invariant (when the DB is compose-delivered).** This is the checked form of the footgun that caused the 2026-07-17 incident — do not skip it when the project boots its DB via compose. From the worktree:
+   - Resolve the worktree's DB data volume: `docker compose config --format json | <read the db service's data volume `source`, then that volume's `.name`>`. Assert it **differs** from the main checkout's resolved DB volume name (run the same read in `<main-checkout-root>`). If they're equal, the override didn't take — **fail provisioning loudly**; do not proceed.
+   - Boot only the DB service in the worktree (`docker compose up -d <db-service>`), then confirm the **main checkout's** DB container is still healthy/running afterward (`docker inspect`/`pg_isready` against main's DB). Bring the worktree DB back down. A main-DB disturbance here means isolation failed — fail provisioning.
+7. Optional smoke test: run a single new-test command in the worktree (e.g. `pytest -x tests/health.py`) — confirms env vars resolved, DB reachable, deps importable.

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-compose-worktree-override.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# gen-compose-worktree-override.sh — generate an out-of-tree docker-compose
+# override that neutralizes the isolation leaks COMPOSE_PROJECT_NAME does NOT
+# cover, so a per-worktree compose stack cannot collide with the main checkout's.
+#
+# Why this exists: COMPOSE_PROJECT_NAME namespaces containers and networks, but
+# NOT two very common compose patterns —
+#
+#   1. Volumes declared `external: true` and/or pinned to a fixed top-level
+#      `name:`. These are addressed by name, so EVERY worktree's compose stack
+#      mounts the SAME physical volume. For a database volume that means two
+#      postmasters on one PGDATA → data corruption (the 2026-07-17 incident).
+#   2. Fixed host port bindings (`ports: - "5432:5432"`). These publish to a
+#      fixed host port that collides across compose projects regardless of name.
+#
+# The fix is a GENERATED, out-of-tree override (never a mutation of the project's
+# committed compose files) that, for the worktree:
+#   - re-pins every leaky volume to a NON-external, worktree-namespaced volume
+#     (`<project>_wt_<name>_<volkey>`), EXCEPT volumes the caller marks shareable
+#     (a read-only dep/venv cache with no dep churn is safe to keep shared);
+#   - strips host port publishing from every service that has it, using compose's
+#     `!override []` tag (a plain `ports: []` MERGES/appends in Compose v2+ and
+#     would NOT strip the port — verified on Docker Compose v5.1.1).
+#
+# Detection is 100% generic — no project / service / volume name is hardcoded.
+# Everything comes from `docker compose config --format json` run in the main
+# checkout. A volume leaks when `.external == true` OR its resolved `.name`
+# differs from the auto-namespaced form `<project>_<volkey>` (i.e. it carries a
+# fixed top-level `name:`). Setting `external: false` in the override is
+# mandatory — without it the base `external: true` merges through and the volume
+# stays externally-pinned (verified).
+#
+# Usage:
+#   gen-compose-worktree-override.sh \
+#     --main     <main-checkout-root> \
+#     --worktree <worktree-path> \
+#     --name     <worktree-name> \
+#     --out      <override-output-path> \
+#     [--share-volume <volkey>]...   # volumes safe to keep shared (repeatable)
+#
+# Output:
+#   stdout — the override path (only, on success) so it is safe to capture with
+#            $(...). stderr carries a human-readable decision report + the
+#            suggested `COMPOSE_FILE=<base>:<override>` wiring line.
+#   The generated override's `volumes:` block lists the forked volumes by their
+#   pinned name — that IS the teardown manifest (`docker volume rm <name>`).
+#
+# Exit: 0 on success; 2 on argument / setup errors (no `docker compose`, config
+#       does not parse, no base compose file found).
+
+set -u
+
+die() { echo "gen-compose-worktree-override: $*" >&2; exit 2; }
+
+MAIN=""; WORKTREE=""; NAME=""; OUT=""
+SHARE=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --main)         shift; [ $# -gt 0 ] || die "--main needs a path"; MAIN="$1"; shift ;;
+    --worktree)     shift; [ $# -gt 0 ] || die "--worktree needs a path"; WORKTREE="$1"; shift ;;
+    --name)         shift; [ $# -gt 0 ] || die "--name needs a value"; NAME="$1"; shift ;;
+    --out)          shift; [ $# -gt 0 ] || die "--out needs a path"; OUT="$1"; shift ;;
+    --share-volume) shift; [ $# -gt 0 ] || die "--share-volume needs a volume key"; SHARE+=("$1"); shift ;;
+    *)              die "unknown arg: $1" ;;
+  esac
+done
+
+[ -n "$MAIN" ]     || die "--main <main-checkout-root> required"
+[ -n "$WORKTREE" ] || die "--worktree <path> required"
+[ -n "$NAME" ]     || die "--name <worktree-name> required"
+[ -n "$OUT" ]      || die "--out <override-path> required"
+
+command -v docker >/dev/null 2>&1 || die "docker not found on PATH — cannot generate compose override"
+docker compose version >/dev/null 2>&1 || die "'docker compose' unavailable — is the Compose v2 plugin installed?"
+
+# Canonicalize the main checkout (must exist).
+[ -d "$MAIN" ] || die "main checkout path is not a directory: $MAIN"
+MAIN=$(cd "$MAIN" && pwd -P)
+
+# Locate the base compose file compose will auto-load (standard search order).
+BASE=""
+for f in compose.yaml compose.yml docker-compose.yaml docker-compose.yml; do
+  if [ -f "$MAIN/$f" ]; then BASE="$f"; break; fi
+done
+[ -n "$BASE" ] || die "no compose file (compose.yaml / docker-compose.yml) found in $MAIN"
+
+# Render the resolved config from the MAIN checkout. Do not force
+# COMPOSE_PROJECT_NAME: let it default exactly as the project normally resolves
+# it, so the auto-namespace comparison below reflects reality.
+CONFIG_JSON=$(cd "$MAIN" && docker compose config --format json 2>/dev/null) \
+  || die "'docker compose config' failed in $MAIN — the compose config does not parse"
+
+mkdir -p "$(dirname "$OUT")" || die "cannot create output dir for $OUT"
+
+CONFIG_JSON="$CONFIG_JSON" OUT="$OUT" NAME="$NAME" BASE="$BASE" \
+python3 - "${SHARE[@]:-}" <<'PY' || die "failed to generate override"
+import json, os, sys
+
+cfg = json.loads(os.environ["CONFIG_JSON"])
+out = os.environ["OUT"]
+wt_name = os.environ["NAME"]
+base = os.environ["BASE"]
+share = {s for s in sys.argv[1:] if s}
+
+# The override lives OUT of the worktree (under <summary_dir>), so the COMPOSE_FILE
+# entry must reference it by ABSOLUTE path — a basename would only resolve if the
+# file sat in the compose project dir. The base file is worktree-local (the
+# worktree carries its own tracked copy), so it stays relative.
+out_abs = os.path.abspath(out)
+
+project = cfg.get("name") or "compose"
+volumes = cfg.get("volumes") or {}
+services = cfg.get("services") or {}
+
+# ---- Detect leaky volumes -------------------------------------------------
+# A volume leaks past COMPOSE_PROJECT_NAME when it is external, or carries a
+# fixed top-level name (resolved name != the auto-namespaced <project>_<key>).
+forked = []          # (volkey, reason, pinned_name)
+shared_leaky = []    # (volkey, reason) — leaky but caller marked shareable
+for key, vol in volumes.items():
+    vol = vol or {}
+    external = bool(vol.get("external"))
+    resolved = vol.get("name", "")
+    auto = f"{project}_{key}"
+    if external:
+        reason = "external:true"
+    elif resolved and resolved != auto:
+        reason = f"fixed name '{resolved}'"
+    else:
+        continue  # already namespaced by project name — safe
+    if key in share:
+        shared_leaky.append((key, reason))
+        continue
+    pinned = f"{project}_wt_{wt_name}_{key}"
+    forked.append((key, reason, pinned))
+
+# ---- Detect services publishing fixed host ports --------------------------
+stripped = []  # service names whose host port publishing we drop
+for svc, spec in services.items():
+    spec = spec or {}
+    ports = spec.get("ports") or []
+    if any((p or {}).get("published") for p in ports):
+        stripped.append(svc)
+
+# ---- Emit the override YAML (hand-rolled; no yaml dependency) --------------
+def y(s):
+    # Quote scalars that YAML could misread; safe for our name/key charset.
+    return json.dumps(s)
+
+lines = []
+lines.append("# GENERATED by gen-compose-worktree-override.sh — do not edit by hand.")
+lines.append("# Out-of-tree compose override that neutralizes the isolation leaks")
+lines.append("# COMPOSE_PROJECT_NAME does not cover (external / fixed-name volumes,")
+lines.append("# fixed host port bindings). Wire in without touching tracked files via:")
+lines.append(f"#   COMPOSE_FILE={base}:{out_abs}   (in the worktree's .env)")
+lines.append(f"# Source project: {project}   Worktree: {wt_name}")
+if shared_leaky:
+    for key, reason in shared_leaky:
+        lines.append(f"# KEPT SHARED (caller --share-volume): {key} ({reason})")
+lines.append("")
+
+if stripped:
+    lines.append("services:")
+    for svc in sorted(stripped):
+        lines.append(f"  {y(svc)}:")
+        # `!override []` REPLACES the base list (plain [] would append/merge).
+        lines.append("    ports: !override []")
+    lines.append("")
+
+if forked:
+    lines.append("volumes:")
+    for key, _reason, pinned in forked:
+        lines.append(f"  {y(key)}:")
+        lines.append(f"    name: {y(pinned)}")
+        lines.append("    external: false")
+    lines.append("")
+
+if not stripped and not forked:
+    lines.append("# No isolation leaks detected: every volume is already namespaced by")
+    lines.append("# COMPOSE_PROJECT_NAME and no service publishes a fixed host port.")
+    lines.append("# This override is a valid no-op; wiring it in is harmless.")
+    lines.append("")
+
+with open(out, "w") as f:
+    f.write("\n".join(lines).rstrip("\n") + "\n")
+
+# ---- Report to stderr (human + agent readable) ----------------------------
+def err(msg):
+    print(msg, file=sys.stderr)
+
+err(f"gen-compose-worktree-override: wrote {out}")
+err(f"  base compose file: {base}   project: {project}")
+if forked:
+    err("  forked volumes (were shared → now worktree-namespaced, non-external):")
+    for key, reason, pinned in forked:
+        err(f"    - {key} ({reason}) -> {pinned}")
+else:
+    err("  forked volumes: none")
+if shared_leaky:
+    err("  KEPT SHARED (caller --share-volume) — verify these are read-only caches:")
+    for key, reason in shared_leaky:
+        err(f"    - {key} ({reason})")
+if stripped:
+    err(f"  stripped host-port publishing from: {', '.join(sorted(stripped))}")
+else:
+    err("  stripped host-port publishing from: none")
+err(f"  wire in: COMPOSE_FILE={base}:{out_abs}  (append to the worktree's copied .env)")
+
+# stdout = override path ONLY (safe for $(...) capture).
+print(out_abs)
+PY

package/skills/vinta-derive-skills/resources/plan-execution/partials/agent-models.md

@@ -0,0 +1,29 @@
+<!-- Partial: agent-models — resolves the `.vinta-ai-workflows.yaml` `agent_models` section (tier per role/task) to a concrete spawn model, and the mechanical-step delegation pattern. Blocks: TIER_RESOLVE (review-phase reviewer/fixer + implement-plan mechanical steps), MECHANICAL_DELEGATION (implement-plan worktree/integrate steps). The implementer model is NOT here — that stays plan-owned via model-pick. -->
+
+<!-- block-begin: TIER_RESOLVE -->
+## Resolve an `agent_models` tier to a spawn model
+
+`.vinta-ai-workflows.yaml` may carry an `agent_models` section mapping a role/task (`reviewer`, `fixer`, `worktree_prep`, `integrate`) to a **tier** (1–4) into the same table the per-phase implementer suggestion uses — [`ai-tools/skills/plan-feature/resources/ai-models.yaml`](../plan-feature/resources/ai-models.yaml). `agent_models` is the **project default** for these roles; for `reviewer` / `fixer`, a plan phase's optional `**Review models**:` line may override the tier for that one phase (the caller resolves that precedence and hands this block the effective tier). The mechanical steps (`worktree_prep`, `integrate`) are never plan-named. To turn a tier into the model a spawn actually uses:
+
+1. Determine the **effective tier** for the role: for `reviewer` / `fixer`, a per-phase override the conductor passed wins over `agent_models.<role>`; for the mechanical steps, it's simply `agent_models.<role>`.
+2. **No effective tier (override absent AND key unset, or the whole `agent_models` section absent) → do not force a model.** Spawn with the runtime's default model (today's behavior). Skip the rest.
+3. Open [`ai-tools/skills/plan-feature/resources/ai-models.yaml`](../plan-feature/resources/ai-models.yaml), take that tier's `models`, **filter to the vendors the runtime actually exposes**, pick the cheapest/fastest survivor, and translate it to the runner's spawn form — the same resolution [implement-phase](../implement-phase/SKILL.md) runs for the implementer, only keyed by a config tier instead of a plan line.
+4. `ai-models.yaml` missing, or the tier has no runtime-available vendor → fall back to the runtime default and surface the fallback once. Never hard-fail a phase over a model-selection miss.
+
+Record the **model actually used** in tracking: for `reviewer` / `fixer`, alongside the review note; for the mechanical steps, in the phase's tracking row next to the branch/PR fields.
+<!-- block-end: TIER_RESOLVE -->
+
+<!-- block-begin: MECHANICAL_DELEGATION -->
+## Delegate a mechanical step to a configured model
+
+Two steps the conductor would otherwise run **inline in its own (usually pricier) session** — provisioning the worktree ([prepare-worktree](../prepare-worktree/SKILL.md)) and integrating a phase ([integrate-phase](../integrate-phase/SKILL.md): push the branch + open/update the PR through the bundled `open-pr.sh`) — are mechanical, precedent-driven work that a cheap model handles fine. The `agent_models.worktree_prep` / `agent_models.integrate` tiers let a project push that work down.
+
+- **Tier set** (`worktree_prep` / `integrate`) → **spawn exactly one subagent** at the [resolved model](#resolve-an-agent_models-tier-to-a-spawn-model), hand it the step's SKILL.md plus the same inputs the conductor would use, and consume its returned report exactly as if the conductor had done the work inline. This subagent is a **labor delegate, not a decision-maker**: the conductor still owns git topology (which branch stacks on which base) and still holds every value the step returns (`WORKROOT` / `BASE_BRANCH` / worktree summary for `worktree_prep`; branch + PR-context path + `status` for `integrate`). The delegate executes and reports those back.
+- **Tier unset** → run the step inline in the conductor's own session — today's behavior, no subagent.
+
+Rules that hold **regardless of who runs the step**:
+
+- The **PR-context file + `open-pr.sh` is still the only PR-creation path.** An `integrate` delegate uses the bundled script; it never calls raw `gh pr create` / `glab mr create`.
+- The delegate is `read-write` (worktree provisioning writes dirs/DBs; integrate pushes + writes the PR-context file) but **makes no plan or code decisions** — a malformed or failed delegate report is surfaced to the user, never worked around.
+- This delegation is **separate from the phase-work sub-agents** (implementer / reviewer / fixer). Those still never branch, push, or open PRs — that prohibition is about code-authoring agents, not the dedicated mechanical delegate the conductor spawns to run the integrate step itself.
+<!-- block-end: MECHANICAL_DELEGATION -->

package/skills/vinta-derive-skills/resources/plan-execution/partials/model-pick.md

@@ -2,7 +2,7 @@
 <!-- block-begin: MODEL_PICK -->
 ## Pick the model from the plan's per-phase suggestion
 
-**The plan owns model selection — this skill does not re-derive tiers and doesn't assume a vendor.** Each phase carries a `**Suggested AI model**:` line listing one model per vendor.
+**The plan owns the *implementer* model — this skill does not re-derive tiers and doesn't assume a vendor.** Each phase carries a `**Suggested AI model**:` line listing one model per vendor. (The reviewer / fixer models default to `.vinta-ai-workflows.yaml`'s `agent_models` section, though a phase's optional `**Review models**:` line can override them for that phase; the mechanical-step models are `agent_models`-only. All of that is handled by `review-phase` / the conductor, not this implementer step.)
 
 Pick:
 

package/skills/vinta-derive-skills/resources/plan-execution/partials/review-layers.md

@@ -30,7 +30,7 @@ Open the phase body alongside the diff and walk:
 
 ## Layer 3 — Independent reviewer subagent
 
-After Layers 1–2 pass, spawn a **separate** subagent (different session, no implementation context) using the project's `reviewer` agent type ([ai-tools/agents/reviewer.md](ai-tools/agents/reviewer.md)). Read-only by design.
+After Layers 1–2 pass, spawn a **separate** subagent (different session, no implementation context) using the project's `reviewer` agent type ([ai-tools/agents/reviewer.md](ai-tools/agents/reviewer.md)) at the model resolved from `agent_models.reviewer` (see the [Resolve the reviewer + fixer model](#resolve-the-reviewer--fixer-model) step; unset → runtime default). Read-only by design.
 
 Reviewer prompt template — see the reviewer agent's body for the standard form. Triage findings:
 - **BLOCKER**: must fix before the phase is pushed (the conductor's integrate step).
@@ -43,7 +43,7 @@ The reviewer finds nothing on a >300-LoC multi-file phase → suspicious. Read o
 
 ## Fix loop
 
-1. Spawn a **new** subagent — the project's `fixer` agent type ([ai-tools/agents/fixer.md](ai-tools/agents/fixer.md)). The fix prompt quotes the finding verbatim. For comment-hygiene findings (Layer 2 item 8), the fix prompt tells the fixer to run the `deslop-comments` skill ([ai-tools/skills/deslop-comments/SKILL.md](ai-tools/skills/deslop-comments/SKILL.md)) scoped to the phase's touched files — comment-only edits, no behavior change.
+1. Spawn a **new** subagent — the project's `fixer` agent type ([ai-tools/agents/fixer.md](ai-tools/agents/fixer.md)) at the model resolved from `agent_models.fixer` (see the [Resolve the reviewer + fixer model](#resolve-the-reviewer--fixer-model) step; unset → runtime default). The fix prompt quotes the finding verbatim. For comment-hygiene findings (Layer 2 item 8), the fix prompt tells the fixer to run the `deslop-comments` skill ([ai-tools/skills/deslop-comments/SKILL.md](ai-tools/skills/deslop-comments/SKILL.md)) scoped to the phase's touched files — comment-only edits, no behavior change.
 2. The `fixer`'s system prompt mandates re-running the inner loop + outer gate (in `<WORKROOT>`).
 3. After the fixer returns, redo Layer 1 in full + the affected portion of Layer 2.
 4. Loop until Layers 1, 2, 3 are all clean.

package/skills/vinta-derive-skills/resources/plan-execution/partials/worktree-seam.md

@@ -13,7 +13,7 @@ Resolve three values **once**, before any phase runs, and record them in trackin
 
 **When `use_worktree = false`:** set `WORKROOT` = main checkout, `BASE_BRANCH = {{DEFAULT_BRANCH}}`, `SANDBOX_TIER = none`. Make `BASE_BRANCH` current + up to date: `git -C <WORKROOT> checkout {{DEFAULT_BRANCH}} && git -C <WORKROOT> pull --ff-only`. Jump to Step 1.
 
-**When `use_worktree = true`:** invoke [prepare-worktree](../prepare-worktree/SKILL.md) **once**:
+**When `use_worktree = true`:** run [prepare-worktree](../prepare-worktree/SKILL.md) **once**. This is a mechanical step: when `agent_models.worktree_prep` is set, **delegate it to a subagent** per the [Delegate a mechanical step to a configured model](#delegate-a-mechanical-step-to-a-configured-model) pattern (hand the subagent prepare-worktree's SKILL.md + the inputs below; consume its returned `worktree_path` / `worktree_branch` / `worktree_summary` / `sandbox_tier` report). When the tier is unset, run it inline — the steps below read the same either way:
 
 1. **Inputs.** Plan path (so prepare-worktree can read it for deps / migrations / env / compose churn — see prepare-worktree's **Plan inspection** step), suggested worktree name = `plan-{plan-id-kebab}`, plan-driven mode.
 2. **Pre-run sanity.** Confirm no existing worktree at the target path (`git worktree list | grep <name>` — refuse if collision). Confirm `git -C <main_checkout> status` of the main checkout (warn if dirty; defer to prepare-worktree's **Sanity checks** step for the call).

package/skills/vinta-derive-skills/resources/plan-execution/shell/amend-plan-template.md

@@ -126,7 +126,7 @@ Always the first write. Plan file is durable; commits get rewritten next.
    - Letter: `1b` between `1` (relabeled `1a`) and `2`. Requires renaming `1` → `1a` inside **Phased Rollout** + updating downstream references.
    Ask the user. Default: decimal — no rename of existing ids.
 
-3. **Appends** — new `## Phase N+1` block at end of **Phased Rollout**. Same shape as siblings: Goal, Suggested AI model, reusable_skills, Changes, Tests, Acceptance.
+3. **Appends** — new `## Phase N+1` block at end of **Phased Rollout**. Same shape as siblings: Goal, Suggested AI model, optional Review models, reusable_skills, Changes, Tests, Acceptance.
 
 4. **Guiding Decisions changes** — rewrite the affected row. Add a one-line note at the top of **Guiding Decisions** ("**Amended YYYY-MM-DD**: replaced storage shape from X to Y; affects phases 2, 3, 4.") so reviewers see what shifted. Reference the changed row by its **Decision** column name, not by a `§N.M` shorthand.
 
@@ -241,7 +241,7 @@ For `change_kind = rebase-only` (downstream phase whose parent moved): skip the
 
 ### 4c. Run the three-layer review
 
-Invoke [review-phase](../review-phase/SKILL.md) against the rewritten branch, passing the **new** phase body to walk against and `WORKROOT`. Layer 2 walks: every "Changes" item in the new body, every "Tests" entry, the new acceptance line.
+Invoke [review-phase](../review-phase/SKILL.md) against the rewritten branch, passing the **new** phase body to walk against, `WORKROOT`, and the `reviewer` / `fixer` agent types with their `agent_models` tiers plus this phase's `reviewer_model_tier` / `fixer_model_tier` overrides (parsed from the rewritten body's `**Review models**:` line, null when absent). Layer 2 walks: every "Changes" item in the new body, every "Tests" entry, the new acceptance line.
 
 Skip this step only when `change_kind = rebase-only` (no body change → no compliance walk). Even then, spot-run review-phase's Layer 1 mechanical checks to verify the rebase didn't lose unrelated work.
 

package/skills/vinta-derive-skills/resources/plan-execution/shell/implement-plan-template.md

@@ -37,7 +37,7 @@ Parse once, reuse for every phase:
    - **Goals + Non-goals** section — verbatim, used in every phase prompt.
    - **Guiding Decisions** section — verbatim. Pay attention to: feature flag (key, scope, default, flip-on criterion), storage shape, tenant scoping, API contract decisions.
    - **Data Model Changes** section — keep full body; later phases reference earlier subsections.
-   - **Phased Rollout** section — parse into phase records: `{ id, title, goal, body, spec_use_case, suggested_model_tier, reusable_skills, has_e2e, acceptance, is_cross_repo, is_flag_removal }`.
+   - **Phased Rollout** section — parse into phase records: `{ id, title, goal, body, spec_use_case, suggested_model_tier, reviewer_model_tier, fixer_model_tier, reusable_skills, has_e2e, acceptance, is_cross_repo, is_flag_removal }`. `reviewer_model_tier` / `fixer_model_tier` come from the phase's optional `**Review models**:` line (null when the phase doesn't override — most phases).
    - **Risk & Rollout Notes**, **Open Questions**, **Touch List** sections — keep available; include in phase prompts only when relevant.
 3. **Classify each phase**: `is_cross_repo`, `is_flag_removal` — the conductor does NOT auto-execute these (see [Cross-repo phases](#cross-repo-phases) + [Flag-removal phase](#flag-removal-phase-always-out-of-scope)).
 4. **Ask the user three opt-in questions** via `AskUserQuestion`. Defaults are project-specific (see below); record every answer in tracking under `run_options`:
@@ -60,6 +60,14 @@ Parse once, reuse for every phase:
 
    Wait for "go". After that, the per-phase pause behavior follows `run_options.pause_between_phases`. Inline-comment drafting follows `run_options.generate_inline_comments`. Worktree isolation follows `run_options.use_worktree`. Outer-gate test scope follows `run_options.full_test_suite`.{{E2E_RUN_OPTION_TRAILER}}{{COMMIT_STRATEGY_STEP0_TRAILER}}
 
+## Agent models — reviewer, fixer, and mechanical steps
+
+The per-phase **implementer** model stays plan-owned (each phase's `**Suggested AI model**:` line — see [implement-phase](../implement-phase/SKILL.md)). Every *other* model this conductor spawns — the review sub-agents and the mechanical steps — is chosen from `.vinta-ai-workflows.yaml`'s `agent_models` section, never from the plan. Read that section once in [Step 0](#step-0--locate--parse-plan) alongside `run_options`.
+
+<!-- include: partials/agent-models.md#TIER_RESOLVE -->
+
+<!-- include: partials/agent-models.md#MECHANICAL_DELEGATION -->
+
 <!-- include: partials/worktree-seam.md#WORKROOT_RESOLUTION -->
 
 <!-- include: partials/worktree-seam.md#WORKROOT_TOPOLOGY_RULE -->
@@ -76,11 +84,11 @@ Invoke [implement-phase](../implement-phase/SKILL.md), passing the phase record,
 
 ### 1b. Review
 
-Invoke [review-phase](../review-phase/SKILL.md) against the phase diff, passing the phase body to walk, `WORKROOT`, `main_checkout`, `run_options.full_test_suite`{{E2E_RUN_OPTION_TRACKING}}, and the `reviewer` / `fixer` agent types. It loops its three layers + fix loop until clean, then returns `PASS` (or the surfaced findings). Do not proceed to integrate while any layer is red.
+Invoke [review-phase](../review-phase/SKILL.md) against the phase diff, passing the phase body to walk, `WORKROOT`, `main_checkout`, `run_options.full_test_suite`{{E2E_RUN_OPTION_TRACKING}}, and the `reviewer` / `fixer` agent types with their `agent_models.reviewer` / `agent_models.fixer` tiers **plus this phase's `reviewer_model_tier` / `fixer_model_tier` overrides (null when the phase didn't set a `**Review models**:` line)**. review-phase prefers a phase override over the `agent_models` default. It loops its three layers + fix loop until clean, then returns `PASS` (or the surfaced findings). Do not proceed to integrate while any layer is red.
 
 ### 1c. Integrate
 
-Invoke {{INTEGRATE_PHASE_DISPATCH}}, passing `WORKROOT` / `BASE_BRANCH`, the `{{PR_POLICY_BLOCK}}` policy, and `run_options.generate_inline_comments`. It pushes the branch and routes the PR through the context file, returning the branch + PR-context path + status.
+Invoke {{INTEGRATE_PHASE_DISPATCH}}, passing `WORKROOT` / `BASE_BRANCH`, the `{{PR_POLICY_BLOCK}}` policy, and `run_options.generate_inline_comments`. It pushes the branch and routes the PR through the context file, returning the branch + PR-context path + status. This is a mechanical step: when `agent_models.integrate` is set, run it as a delegated subagent per the [Delegate a mechanical step to a configured model](#delegate-a-mechanical-step-to-a-configured-model) pattern (the delegate pushes + writes the PR-context file + runs `open-pr.sh`, then reports the branch / path / status back); when unset, run it inline. Either way the PR-context file + `open-pr.sh` is the only PR-creation path.
 
 ### 1d. Update tracking file
 
@@ -151,9 +159,10 @@ After all executable phases complete:
 - **Read AGENTS.md** in every phase prompt.
 - **Stage explicitly.** No `git add -A`.
 - **Subagents work in fresh sessions.** Each phase = a new subagent. Tracking + plan files = the context handoff.
-- **Conductor owns git topology.** Subagents commit but never branch, push, {{PR_RULE_TAIL}}.
+- **Conductor owns git topology.** Phase-work subagents (implementer / reviewer / fixer) commit but never branch, push, {{PR_RULE_TAIL}}. The one exception is a **mechanical `integrate` delegate** spawned per `agent_models.integrate` — it exists precisely to run the conductor's integrate step (push + PR via `open-pr.sh`) on a cheaper model, and the conductor still dictates the branch/base topology it uses.
 {{COAUTHOR_RULE_LINE}}
-- **Trust the plan's per-phase model suggestion.** Model selection lives in [implement-phase](../implement-phase/SKILL.md); the conductor never re-derives tiers.
+- **Trust the plan's per-phase model suggestion.** Implementer model selection lives in [implement-phase](../implement-phase/SKILL.md); the conductor never re-derives tiers.
+- **Reviewer / fixer / mechanical-step models come from `agent_models`, not the plan.** Resolve each configured tier via the [Agent models](#agent-models--reviewer-fixer-and-mechanical-steps) step; an unset key means the spawn uses the runtime default. The plan never names these models.
 - **Don't re-implement what a project skill encodes.**
 {{UI_E2E_RULE_LINE}}
 - **Two-tier verification, in order, every phase.** Inner scoped, then the outer gate — enforced inside [implement-phase](../implement-phase/SKILL.md). The outer gate always runs the repo-wide type/build gate; its test scope follows `run_options.full_test_suite` (scoped suite by default, full repo suite when opted in).

package/skills/vinta-derive-skills/resources/plan-execution/shell/review-phase-template.md

@@ -14,7 +14,20 @@ The single review implementation shared by every plan-execution conductor: [impl
 - `WORKROOT`, `SANDBOX_TIER` — resolved once by the conductor.
 - `main_checkout` — the repo root the run was invoked from (equals `WORKROOT` when no worktree).
 - `run_options.full_test_suite` — resolves which outer gate Layer 1 item 3 verifies ran (false = scoped suite; true = full repo suite).
-- The project's `reviewer` + `fixer` agent types.
+- The project's `reviewer` + `fixer` agent types, plus their `agent_models.reviewer` / `agent_models.fixer` tiers (when set in `.vinta-ai-workflows.yaml`).
+- Optional per-phase `reviewer_model_tier` / `fixer_model_tier` overrides — the tiers parsed from this phase's `**Review models**:` line in the plan (null when the phase didn't set one, which is the common case).
+
+## Resolve the reviewer + fixer model
+
+Each of `reviewer` and `fixer` spawns at an **effective tier**, resolved per role with this precedence:
+
+1. The phase's `reviewer_model_tier` / `fixer_model_tier` override, when the conductor passed one (the plan chose a non-default review model for this critical phase).
+2. Else the project-wide `agent_models.reviewer` / `agent_models.fixer` tier from `.vinta-ai-workflows.yaml`.
+3. Else unset → the runtime default model.
+
+Feed that effective tier into the resolution below (it turns a tier into a concrete spawn model). A phase override applies to that phase only; the next phase falls back to the `agent_models` default unless it too overrides.
+
+<!-- include: partials/agent-models.md#TIER_RESOLVE -->
 
 ## Review