vinta-ai-workflows 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,173 @@ 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.4.0] — 2026-07-31
+
+### Added
+
+- **`write-unit-test` foundation skill (template-rendered, default-on when a
+  unit-test framework is detected).** A new foundation skill that ships into
+  target projects' `ai-tools/skills/write-unit-test/` to write durable unit
+  tests. The body enforces six universal rules regardless of framework — mock
+  only genuine externals (never the unit under test / DB / local collaborators),
+  assert the **full** expected output (not counts or truthiness), clean up
+  created data or run inside a rolled-back transaction, never hit an external
+  service that can't run in dev/test, keep test logic literal (no loops /
+  conditionals recomputing the expectation), and decouple from implementation
+  internals — plus a self-review checklist and a "run it green, then break it to
+  see it go red" step.
+  - Rendered from
+    [`skills/vinta-derive-skills/resources/write-unit-test-template.md`](skills/vinta-derive-skills/resources/write-unit-test-template.md)
+    (bucket B). New placeholders: `{{FRAMEWORK_PACKS_LIST}}`,
+    `{{FRAMEWORK_PACK_LOADER_BLOCK}}`, `{{PROJECT_TEST_PREFERENCES_BLOCK}}`,
+    `{{ADDITIONAL_CONVENTIONS_BLOCK}}` (reuses the existing `{{TEST_CMD}}` /
+    `{{NEW_TEST_CMD_PATTERN}}` / `{{SCOPED_TEST_NOTE}}` / `{{PROJECT_NAME}}` /
+    `{{STACK_SUMMARY}}` set). All four new placeholders are documented in the
+    `vinta-derive-skills` placeholder table.
+  - **Best-practice packs on two independent axes** (the framework-specific
+    "sub-skills"), verbatim references under
+    [`skills/vinta-derive-skills/resources/write-unit-test-packs/`](skills/vinta-derive-skills/resources/write-unit-test-packs/).
+    `derive-skills` copies only what the project matches into
+    `ai-tools/skills/write-unit-test/resources/packs/` so framework-specific
+    advice never ships to a project that doesn't use that framework (a FastAPI
+    repo never receives Django guidance; a pure library gets no web-framework
+    pack):
+    - **Runner packs** (`packs/runners/`, stack-agnostic — structure /
+      assertions / mocking): `pytest.md`, `vitest.md`, `jest.md`. One selected
+      by `inventory.tests.unit_framework`.
+    - **Stack packs** (`packs/stacks/`, DB isolation / framework client / domain
+      mocks): `django.md`, `fastapi.md`, `flask.md`, `medplum.md`, `react.md`,
+      `nextjs.md`, `tanstack-start.md`, `react-router.md`, `prisma.md`,
+      `python-package.md`, `typescript-package.md`. Every pack whose stack the inventory matched
+      ships (a project can match several — e.g. Next.js + React, or TanStack
+      Start + React); a repo with no web framework (a standalone TS/Python package like
+      an open-source lib) gets its `*-package.md` and no more; when nothing
+      matches, the runner pack ships alone. Missing packs for a present
+      framework are recorded as a gap (candidate for a new pack via
+      `add-foundation-skill`).
+    - **Stack packs may carry a one-time project-setup step**, applied at derive
+      time (not per test). Medplum ships the two Vitest setup files
+      `medplum-test.globalSetup.ts` + `medplum-test.setup.ts` (FHIR search-parameter
+      indexing shared across workers via `provide`/`inject`, so `MockClient`
+      search filtering works) — the derive flow installs them and registers both
+      `test.globalSetup` + `test.setupFiles` in the Vitest config; the `medplum.md`
+      pack only references it. Bundled verbatim (dated headers) from the team's
+      `medplum-snippet-catalog` (`TestSetup/`) so bootstrap stays offline-safe.
+  - **Schema:** new `foundation_skills.write-unit-test` enum
+    (`enabled` / `disabled`) and a new `skills.write-unit-test` config block —
+    `test_style` (functions / classes / framework-default), `data_setup`
+    (factories / fixtures / inline / framework-default), `assertion_style`
+    (plain-assert / framework-methods / framework-default), `db_isolation`
+    (transaction-rollback / truncate / recreate / framework-default), and a
+    free-form `additional_conventions[]`. All optional; every field defaults to
+    `framework-default`.
+  - **Bootstrap:** `write-unit-test` is **default-on, not an opt-in** — the
+    interview sets `foundation_skills.write-unit-test: enabled` whenever a
+    unit-test framework was detected, `disabled` otherwise. New Project-conventions
+    interview item **C.9 (Test conventions for `write-unit-test`)** captures the
+    four preferences + extras, pre-filled from inference on existing projects.
+    (The former C.9 "Agent model tiers" is now **C.10**; its Step 0.5 references
+    were updated.) Step 0.5 emits the `skills.write-unit-test` block; the outputs
+    tree, the three-buckets paragraph, and the `Replace with Vinta foundation
+    version` foundation-shape list all now list `write-unit-test`.
+  - **Inference:** `vinta-analyze-codebase` §6 (Tests) now reads a sample of the
+    existing unit tests and reports a `tests.conventions` block
+    (`test_style` / `data_setup` / `assertion_style` / `db_isolation` / `extras`,
+    each `framework-default` when mixed / greenfield) that seeds the C.9 defaults.
+  - **Review-driven refinements** (PR #21): two universal rules added — **kill
+    nondeterminism** (clock / randomness / timezone / ordering / concurrency → no
+    flaky tests) and **cover the branches** (aim 95%+ branch coverage); the
+    full-value assertion rule now carves out **brittle human-facing text** (assert
+    a stable anchor — error code, role, i18n key — for error/UI strings, not exact
+    prose). Runner packs gained a **record/replay cassette** note for complex APIs
+    like LLM endpoints (PollyJS / `nock.back` for JS, `vcrpy` / `betamax` for
+    Python). The Medplum pack gained a **`MockClient` limitations** section
+    (pre-seeded example resources skew unfiltered searches, partial search-param
+    support, server-only behavior not enforced — defer those to integration/e2e).
+
+## [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

package/README.md

@@ -241,6 +241,7 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
 | `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. |
+| `write-unit-test` | default-on (generated) | Write durable unit tests for a unit of behavior, enforcing six framework-agnostic rules + this project's captured test conventions, with runner- and stack-specific best-practice packs. Ships automatically whenever a unit-test framework is detected (set `disabled` to opt out). Generated from a template; config under `skills.write-unit-test.*`. See below. |
 | `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). |
@@ -249,6 +250,28 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
 | [`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). |
 
+#### `write-unit-test` in depth
+
+Agents write tests that pass but assert too little, mock everything, leave data behind, or couple to internals — this skill exists so you don't have to babysit that. It bakes in **six framework-agnostic rules** that hold for every test in every stack:
+
+1. **Mock only genuine externals** — never the unit under test, its local collaborators, or the DB.
+2. **Assert the full expected value**, not counts or truthiness (`assert result`, `len(x) == 3` are too weak).
+3. **Leave no trace** — transaction-rollback where available, else clean up in teardown (runs on failure too).
+4. **No external service** that can't run in dev/test — stub at the boundary.
+5. **Test logic stays literal** — no loops/conditionals recomputing the expected value.
+6. **Decouple from internals** — assert observable state/output; survive a behavior-preserving rewrite.
+7. **Kill nondeterminism** — control every entropy source (clock, randomness, timezone/locale, iteration/DB order, concurrency); a flaky test is worse than none. Don't over-fit brittle text either — assert a stable anchor (error code, role, i18n key) for error messages and UI copy, not the exact churning prose.
+8. **Cover the branches** — aim high (95%+ branch coverage): every error path, guard, and edge gets a case. Coverage is the floor; correct assertions are the point.
+
+Plus a "run it green, then break the code to watch it go red" step and a name-for-the-behavior / one-reason-to-fail convention.
+
+**Framework guidance ships as best-practice packs on two independent axes**, so a project only ever receives advice for frameworks it actually uses (a FastAPI repo never gets Django guidance; a pure library gets no web-framework pack):
+
+- **Runner pack** (`resources/packs/runners/`) — how to structure, assert, and mock. One, picked by the detected test runner: `pytest`, `vitest`, or `jest`.
+- **Stack pack(s)** (`resources/packs/stacks/`) — DB isolation, framework client, domain mocks. Every matched stack's pack ships (a project can match several — e.g. Next.js + React, or TanStack Start + React): `django`, `fastapi`, `flask`, `medplum`, `react`, `nextjs`, `tanstack-start`, `react-router`, `prisma`, plus pure-library packs `python-package` / `typescript-package` for framework-less packages.
+
+**Project preferences are captured at bootstrap** (and inferred from an existing suite, then confirmed) under `skills.write-unit-test.*`: `test_style` (classes vs functions), `data_setup` (factories / fixtures / inline), `assertion_style`, `db_isolation`, plus free-form `additional_conventions`. Each defaults to `framework-default`, deferring to the pack. New frameworks slot in by adding a pack under [`write-unit-test-packs/`](skills/vinta-derive-skills/resources/write-unit-test-packs/) and a detection signal — no schema change.
+
 ### Foundation sub-agents (project-agnostic)
 
 Land at `ai-tools/agents/<name>.yaml` (canonical YAML; `setup-ai-tools.mjs` emits per-vendor copies into `.claude/agents/`, `.cursor/`, `.codex/`, `.github/`). Always-on trio.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.2.0",
+  "version": "0.4.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

@@ -232,6 +232,11 @@
           "description": "Generate a markdown API-change handoff document for client teams consuming an API-only repo — endpoints added/changed/deprecated/removed on the current branch vs the default branch, with request/response shapes, breaking-change flags, and per-platform migration notes. Template-rendered (bucket B) from `vinta-derive-skills/resources/handoff-to-client-template.md` and opt-in (bucket C) — only ships when the bootstrap interview confirms an API-only repo with separate client codebases. When `enabled`, project-level configuration lives under `skills.handoff-to-client` (client platforms, API style, spec path, output dir).",
           "type": "string",
           "enum": ["enabled", "disabled"]
+        },
+        "write-unit-test": {
+          "description": "Write durable unit tests for a unit of behavior — mock only genuine externals, assert the full expected output (not counts/truthiness), clean up created data or run inside a rolled-back transaction, never hit an external service that can't run in dev/test, keep test logic literal, and decouple from implementation internals. Template-rendered (bucket B) from `vinta-derive-skills/resources/write-unit-test-template.md`, with best-practice packs copied verbatim into the skill's `resources/packs/` on two independent axes — one runner pack (`runners/`: pytest / vitest / jest) selected by the detected test framework, plus a stack pack per matched stack (`stacks/`: django / fastapi / flask / medplum / react / nextjs / tanstack-start / react-router / prisma / python-package / typescript-package) so framework-specific advice ships only when that framework is present. Default-on: bootstrap sets `enabled` whenever `vinta-analyze-codebase` detects a unit-test framework, `disabled` when none is found (there's nothing to render against). When `enabled`, project-level test conventions live under `skills.write-unit-test` (test style, data setup, assertion style, DB isolation, inferred extra conventions).",
+          "type": "string",
+          "enum": ["enabled", "disabled"]
         }
       }
     },
@@ -420,10 +425,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": []
             }
           }
         },
@@ -473,6 +484,44 @@
               "default": "one-off-runs/"
             }
           }
+        },
+        "write-unit-test": {
+          "description": "Configuration for the `write-unit-test` foundation skill. Optional when `foundation_skills.write-unit-test` is `enabled` — every field defaults to `framework-default`, deferring to the shipped framework pack. At bootstrap, values are inferred from the existing test suite (see `vinta-analyze-codebase` inventory `tests.conventions`) and confirmed by the user; on a greenfield project they're asked directly. Rendered into the skill body at derive time.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "test_style": {
+              "description": "Whether new tests are written as standalone functions or grouped in test classes. `functions` (pytest-style `def test_x()`), `classes` (TestCase / describe-block grouping), or `framework-default` (defer to the framework pack — functions for pytest/vitest/jest, classes for Django TestCase). Inferred from the dominant shape in the existing suite.",
+              "type": "string",
+              "enum": ["functions", "classes", "framework-default"],
+              "default": "framework-default"
+            },
+            "data_setup": {
+              "description": "How test data is constructed. `factories` (factory classes like factory_boy / FactoryBot / builder helpers — preferred when the project has them), `fixtures` (framework fixtures / fixture files), `inline` (built in the test body), or `framework-default`. Inferred from `tests.test_data_helpers` and the dominant pattern in the suite.",
+              "type": "string",
+              "enum": ["factories", "fixtures", "inline", "framework-default"],
+              "default": "framework-default"
+            },
+            "assertion_style": {
+              "description": "Which assertion form new tests use. `plain-assert` (Python plain `assert` / pytest introspection, or JS `expect`), `framework-methods` (`unittest` `self.assertEqual` family), or `framework-default`. Inferred from the existing suite — a pytest suite that already uses plain `assert` sets `plain-assert`; a `TestCase`-heavy suite sets `framework-methods`.",
+              "type": "string",
+              "enum": ["plain-assert", "framework-methods", "framework-default"],
+              "default": "framework-default"
+            },
+            "db_isolation": {
+              "description": "How data created by a test is undone between tests. `transaction-rollback` (each test runs in a transaction rolled back at teardown — preferred where supported), `truncate` (tables truncated between tests, e.g. Django TransactionTestCase), `recreate` (schema/DB rebuilt), or `framework-default`. Inferred from the test base classes / fixtures in use.",
+              "type": "string",
+              "enum": ["transaction-rollback", "truncate", "recreate", "framework-default"],
+              "default": "framework-default"
+            },
+            "additional_conventions": {
+              "description": "Free-form project-specific test conventions the four structured fields can't capture — inferred from the existing suite at bootstrap (e.g. `co-locate tests next to source as *.test.ts`, `one assertion per test`, `name tests should_<behavior>_when_<condition>`, `mock the network with our recorded-cassette helper`) or supplied by the user. Rendered verbatim into the skill body's project-conventions section. Empty array is fine — the universal rules + framework pack already cover the essentials.",
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "uniqueItems": true,
+              "default": []
+            }
+          }
         }
       }
     }

package/skills/vinta-analyze-codebase/SKILL.md

@@ -62,6 +62,8 @@ Match top-level deps against this table:
 | `flask` | Flask |
 | `pytest` | pytest |
 | `mypy`, `ruff`, `black` | Python lint/type tools |
+| `@tanstack/react-start`, `@tanstack/start` | TanStack Start (check `@tanstack/react-router`) |
+| `react-router`, `react-router-dom`, `@react-router/*` | React Router |
 | `tRPC`, `@trpc/*` | tRPC |
 | `prisma`, `@prisma/client` | Prisma |
 | `drizzle-orm` | Drizzle |
@@ -94,6 +96,12 @@ For each app/package: name + path + framework (cross-ref the [Frameworks (from d
 - Unit / integration: where are they? `apps/*/src/**/*.test.ts`, `tests/`, `__tests__/`, `<pkg>/tests/unit`, `<pkg>/tests/integration`. Glob.
 - E2E: `e2e/`, `playwright/`, `cypress/`. Read fixtures + setup files for: auth strategy, seed helpers, tenant scoping in seeds.
 - Test data: factories, fixtures, mocks. Note conventions (`@medplum/mock`, `factory_boy`, MSW, etc).
+- **Unit-test conventions (feeds `write-unit-test`).** Read a representative sample of existing unit tests (not e2e) and infer the **dominant** pattern for each axis below. These pre-fill `skills.write-unit-test.*` in the bootstrap interview (group C.9), so the shipped skill matches the suite instead of imposing a house style. Report `framework-default` for any axis where the suite is mixed or there's no signal (greenfield):
+  - **test_style** — `functions` (standalone `def test_x` / bare `it(...)`) vs `classes` (`TestCase` subclasses, `describe` grouping). Which dominates?
+  - **data_setup** — `factories` (factory_boy / FactoryBot / builder helpers — cross-ref `test_data_helpers`), `fixtures` (pytest fixtures / fixture files / `setUpTestData`), or `inline` (objects built in the test body).
+  - **assertion_style** — `plain-assert` (Python `assert` / JS `expect`) vs `framework-methods` (`self.assertEqual`-family).
+  - **db_isolation** — `transaction-rollback` (Django `TestCase`, pytest-django `db`, SQLAlchemy savepoint fixtures), `truncate` (`TransactionTestCase`), or `recreate`. Read the test base classes / DB fixtures to tell.
+  - **extras** — any other recurring convention worth carrying (test file co-location + naming pattern, one-assertion-per-test, a house HTTP-mock helper / recorded-cassette pattern, custom assertion helpers). List them; they seed `additional_conventions`.
 
 ### 7. Deploy / release model
 
@@ -155,7 +163,7 @@ This is a load-bearing input for the rest of the bootstrap flow — surface ever
 For each skill, also classify:
 
 - `vinta-managed` — directory name starts with `vinta-` (installed by `vinta-ai-workflows`; can be left alone or refreshed via that CLI).
-- `foundation-shape` — name matches the Vinta foundation set (`plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `implement-phase`, `review-phase`, `integrate-phase`, `amend-plan`, `add-e2e-test`, `add-env-var`). `implement-phase` / `review-phase` / `integrate-phase` are the plan-execution sub-skills co-shipped with `implement-plan`.
+- `foundation-shape` — name matches the Vinta foundation set (`plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `implement-phase`, `review-phase`, `integrate-phase`, `amend-plan`, `add-e2e-test`, `add-env-var`, `write-unit-test`). `implement-phase` / `review-phase` / `integrate-phase` are the plan-execution sub-skills co-shipped with `implement-plan`.
 - `project-custom` — anything else; written by the team.
 
 **Sub-agents** — list every agent file with its name + description:
@@ -273,6 +281,12 @@ tests:
   e2e_framework: playwright | cypress | none
   e2e_paths: [<path>]
   test_data_helpers: [<file>]   # factories, mock clients, seed scripts
+  conventions:                  # inferred dominant patterns → skills.write-unit-test.* (framework-default when mixed / no signal)
+    test_style: functions | classes | framework-default
+    data_setup: factories | fixtures | inline | framework-default
+    assertion_style: plain-assert | framework-methods | framework-default
+    db_isolation: transaction-rollback | truncate | recreate | framework-default
+    extras: [<free-form recurring convention>]   # seeds additional_conventions; [] when none
 
 deploy:
   targets: [vercel, aws-ecs, heroku, k8s, medplum-bots, npm-publish, ...]

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

@@ -81,7 +81,19 @@ 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.
+9. **Test conventions for `write-unit-test`.** The `write-unit-test` foundation skill ships **by default whenever a unit-test framework is detected** (item 2 above) — it's not an opt-in in group D. Capture the project's test conventions so the rendered skill matches the suite instead of imposing a house style. Land them under `skills.write-unit-test.*` in `.vinta-ai-workflows.yaml`.
+
+   **On an existing project, infer first, then confirm.** [vinta-analyze-codebase](../vinta-analyze-codebase/SKILL.md#6-tests)'s `tests.conventions` block reports the dominant patterns it read from the suite (test style, data setup, assertion style, DB isolation, plus any recurring extras). Present those inferred values as the defaults and ask only "these match? anything to change?". On a greenfield project with no tests yet, ask directly (recommend `framework-default` for all four — the shipped framework pack already encodes the idiomatic choice). Skip this item entirely when no test framework was detected (`foundation_skills.write-unit-test: disabled`).
+
+   Four structured `AskUserQuestion` fields (each offers a `Framework default` option — pick it to defer to the pack):
+   - **Test style** — `Standalone functions`, `Test classes`, `Framework default`. → `test_style`.
+   - **Test-data setup** — `Factory classes / builders`, `Fixtures`, `Inline in the test`, `Framework default`. → `data_setup`.
+   - **Assertion style** — `Plain assert / expect`, `Framework assertion methods (self.assertEqual …)`, `Framework default`. → `assertion_style`.
+   - **DB isolation** — `Transaction rollback`, `Truncate between tests`, `Recreate schema/DB`, `Framework default`. → `db_isolation`.
+
+   **Additional conventions (optional).** Open prose: *"Any recurring test conventions the four fields above don't capture? (e.g. 'co-locate tests as `*.test.ts` next to source', 'name tests `should_<behavior>_when_<condition>`', 'mock HTTP with our recorded-cassette helper'.)"* On an existing project, seed this from the extras `vinta-analyze-codebase` surfaced and let the user trim. Each entry lands in `skills.write-unit-test.additional_conventions[]`. Leave empty when there's nothing project-specific — the universal rules + framework pack already cover the essentials.
+
+10. **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
 
@@ -144,7 +156,7 @@ For each artifact, read it (frontmatter + body), then ask the user via `AskUserQ
   - `Keep in current vendor path, don't touch` — leaves it where it is. AGENTS.md may reference it; downstream skill setup won't manage it.
   - `Drop` — delete (rare; usually the user wants to migrate).
 
-  Foundation-shape skills (name matches `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `implement-phase`, `review-phase`, `integrate-phase`, `amend-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `deslop-comments`, `handoff`, `handoff-to-client`) get an extra option: `Replace with Vinta foundation version` — overwrites with the canonical foundation content, preserving the user's name. Useful when the existing version is stale. (`implement-phase` / `review-phase` / `integrate-phase` are the plan-execution sub-skills co-shipped with `implement-plan`; replace them as a unit.)
+  Foundation-shape skills (name matches `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `implement-phase`, `review-phase`, `integrate-phase`, `amend-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `deslop-comments`, `handoff`, `handoff-to-client`, `write-unit-test`) get an extra option: `Replace with Vinta foundation version` — overwrites with the canonical foundation content, preserving the user's name. Useful when the existing version is stale. (`implement-phase` / `review-phase` / `integrate-phase` are the plan-execution sub-skills co-shipped with `implement-plan`; replace them as a unit.)
 
 - **Sub-agents** (each under any vendor `agents/` dir):
   - `Migrate to ai-tools/agents/<name>.yaml` — converts vendor-specific format → canonical YAML; `setup-ai-tools.mjs` re-emits per-vendor copies.
@@ -266,20 +278,21 @@ foundation_skills:
   deslop-comments: enabled  # always ships — review-phase Layer 2 comment-hygiene + fix loop depend on it
   handoff: enabled  # always ships — project-agnostic session-continuation handoff docs
   handoff-to-client: <Optional foundation skills → handoff-to-client answer → enabled | disabled; only asked for API-only repos>
+  write-unit-test: <enabled when a unit-test framework was detected (Project conventions → Test framework(s)); disabled when none found — default-on, not an opt-in>
 
 foundation_agents:
   implementer: enabled
   reviewer: enabled
   fixer: enabled
 
-# Only emit the roles the user chose in the "Agent model tiers" question (C.9).
+# Only emit the roles the user chose in the "Agent model tiers" question (C.10).
 # 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>
+  reviewer: <C.10 → reviewer tier, default 3>
+  fixer: <C.10 → fixer tier, default 2>
+  worktree_prep: <C.10 → worktree_prep tier, default 1; omit when prepare-worktree disabled>
+  integrate: <C.10 → integrate tier, default 1>
 
 stacks: <Stack detection → matched stacks>
 stack_specialist_agents: <empty unless user supplied templates>
@@ -305,6 +318,17 @@ skills:
     api_spec_path: <handoff-to-client follow-up — repo-relative spec path + regen command; omit when none>
     output_dir: .vinta-ai-workflows/client-handoffs
 
+  # Only emit this block when foundation_skills.write-unit-test = enabled.
+  # Values come from Project conventions → C.9 (Test conventions), inferred from the
+  # existing suite (analyze-codebase tests.conventions) and confirmed. Omit any field
+  # left at framework-default and the whole block when there's nothing but defaults.
+  write-unit-test:
+    test_style: <C.9 → functions | classes | framework-default>
+    data_setup: <C.9 → factories | fixtures | inline | framework-default>
+    assertion_style: <C.9 → plain-assert | framework-methods | framework-default>
+    db_isolation: <C.9 → transaction-rollback | truncate | recreate | framework-default>
+    additional_conventions: <C.9 → free-form array of extra conventions inferred/supplied; [] when none>
+
   # Only emit this block when foundation_skills.prepare-worktree = enabled.
   prepare-worktree:
     worktree_root: <prepare-worktree follow-up — `.claude/worktrees` | `../<repo>-wt-`>
@@ -312,6 +336,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:
@@ -384,6 +412,11 @@ ai-tools/
 │   ├── add-env-var/SKILL.md             ← optional — only if user opts in
 │   ├── systematic-debugging/SKILL.md    ← optional — only if user opts in (template-rendered)
 │   ├── handoff-to-client/SKILL.md       ← optional — only for API-only repos, if user opts in (template-rendered; config under skills.handoff-to-client.*)
+│   ├── write-unit-test/                 ← default-on when a unit-test framework was detected (template-rendered; config under skills.write-unit-test.*)
+│   │   ├── SKILL.md
+│   │   └── resources/packs/             ← verbatim packs for the detected runner + matched stacks only
+│   │       ├── runners/<runner>.md      ← one: pytest.md / vitest.md / jest.md
+│   │       └── stacks/<stack>.md        ← only matched: django / fastapi / flask / medplum / react / nextjs / tanstack-start / react-router / prisma / python-package / typescript-package
 │   ├── add-one-off-script/              ← optional — only if user opts in (verbatim copy + bundled BaseOneOffScript + LocalRuntime templates)
 │   │   ├── SKILL.md
 │   │   └── resources/
@@ -420,7 +453,7 @@ Plus the symlinks + per-vendor generated files, set up by the install step.
 Foundation skills break into three buckets — see [vinta-derive-skills](../vinta-derive-skills/SKILL.md) for the full mechanics:
 
 - **Always copy verbatim**: `plan-feature`, `create-spec`, `create-qa-use-cases`, `deslop-comments`, `handoff`. Bundled with the bootstrap skill set; project-agnostic enough to ship as-is (with light path scrubs). `deslop-comments` always ships because `review-phase`'s Layer 2 comment-hygiene check + fix loop dispatch it. `handoff` always ships because its session-continuation body is fully project-agnostic.
-- **Always generate**: the plan-execution unit — `implement-plan` (conductor) + its co-shipped sub-skills `implement-phase` / `review-phase` / `integrate-phase`, plus `amend-plan` (conductor). Bodies have too much project-specific content (test commands, branch convention, PR + co-author policy, agent dispatch) — generated from parameterized templates + shared partials using interview answers + inventory. The sub-skills are not independently opt-in; they always ship with the conductors.
+- **Always generate**: the plan-execution unit — `implement-plan` (conductor) + its co-shipped sub-skills `implement-phase` / `review-phase` / `integrate-phase`, plus `amend-plan` (conductor). Bodies have too much project-specific content (test commands, branch convention, PR + co-author policy, agent dispatch) — generated from parameterized templates + shared partials using interview answers + inventory. The sub-skills are not independently opt-in; they always ship with the conductors. `write-unit-test` is also template-rendered but **conditionally generated** — it ships whenever a unit-test framework was detected (not an opt-in question, not ask-first): the rendered body bakes in the project's test command + captured `skills.write-unit-test.*` conventions, and the verbatim packs land in its `resources/packs/` — one runner pack for the detected test framework plus a stack pack per matched stack (Django / FastAPI / Flask / Medplum / React / Next.js / TanStack Start / React Router / Prisma / pure-package), so framework-specific advice only ships when that framework is present. A few stack packs also apply a one-time project-setup step at derive time (e.g. Medplum wires the two FHIR-indexing Vitest setup files — `test.globalSetup.ts` + `test.setup.ts` — into the Vitest config so `MockClient` search filtering works) — a project mutation done once, not per test.
 - **Optional, ask first**: `add-e2e-test`, `add-env-var`, `systematic-debugging`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `handoff-to-client`. Skipped by default; orchestrator asks via `AskUserQuestion` whether the project has the relevant flow at all. `add-e2e-test` / `add-env-var`: if yes + user has a template → copy + adapt; if yes + no template → draft from scratch via interview; if no → don't ship. `systematic-debugging`: if yes → render the bundled template plus the per-tool MCP catalogue blocks for the observability tools selected in its follow-up; if no → don't ship. `add-one-off-script`: if yes → copy the bundled SKILL.md verbatim plus the language-specific `BaseOneOffScript` template (`one_off_script_base.py` / `one_off_script_base.ts`) chosen via its follow-up; if no → don't ship. `prepare-worktree`: if yes → copy the bundled SKILL.md verbatim, populate `skills.prepare-worktree.*` defaults from its follow-ups, and (when the user opted in via the worktree-default follow-up) flip `run_options.implement-plan.use_worktree` to `true` so `implement-plan`'s Step 0 question (c) defaults to yes; if no → don't ship. `thermo-nuclear-code-quality-review`: if yes → copy the bundled SKILL.md verbatim (no follow-up config); if no → don't ship. `handoff-to-client`: asked only for API-only repos; if yes → render the bundled template using `skills.handoff-to-client.*` (client platforms, API style, spec path, output dir) from its follow-ups; if no → don't ship.
 
 Stack-specific skills + agents land in the target only when the user provides templates for them. If they don't have templates yet, the orchestrator records the detected stacks + skill categories as a TODO list the user can address later via [vinta-derive-skills](../vinta-derive-skills/SKILL.md) / [vinta-derive-subagents](../vinta-derive-subagents/SKILL.md) standalone runs.

package/skills/vinta-derive-skills/SKILL.md

@@ -26,7 +26,7 @@ Before drafting any new SKILL.md, walk through every entry in `existing_ai_artif
 - **Migrate to `ai-tools/skills/<name>/`** — `git mv` the existing skill folder (with all its resources) into the canonical layout. After move, scan the body for hard-coded vendor paths that no longer apply (`.cursor/skills/...` self-references, etc.) and rewrite to the new path. `setup-ai-tools.mjs` will re-link to the chosen vendors.
 - **Keep in current vendor path, don't touch** — leave it where it is; AGENTS.md may reference it; downstream skill setup won't manage it. **Don't ship a foundation duplicate that would shadow it.**
 - **Drop** — log removal; don't emit anything.
-- **Replace with Vinta foundation version** (foundation-shape only — `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `deslop-comments`, `handoff`, `handoff-to-client`) — proceed with the bucket A / B / C flow below for that name. The user has explicitly opted into overwriting their version.
+- **Replace with Vinta foundation version** (foundation-shape only — `plan-feature`, `create-spec`, `create-qa-use-cases`, `implement-plan`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `deslop-comments`, `handoff`, `handoff-to-client`, `write-unit-test`) — proceed with the bucket A / B / C flow below for that name. The user has explicitly opted into overwriting their version.
 - **`vinta-managed`** (any skill whose dir starts with `vinta-`) — leave alone. These come from the `vinta-ai-workflows` CLI; `vinta-derive-skills` doesn't manage them.
 
 For each name in the foundation set: only emit it (verbatim copy / generate from template / interview-draft) when no existing skill of that name is being migrated or kept. If the user said `Migrate` or `Keep` for an existing `plan-feature/SKILL.md`, **do not overwrite**.
@@ -67,7 +67,7 @@ The **always-on unit** is `plan-feature` + `create-spec` + `open-pr-from-context
 
 After copying, scan each for project-specific path references that no longer match the target (the bundled copies may still carry source-repo paths such as `<source-repo>/ai-plans/` or `apps/<service>/`). Replace with the target's paths from the inventory.
 
-### B. Generate — the **plan-execution unit** + `systematic-debugging` from templates
+### B. Generate — the **plan-execution unit** + `systematic-debugging` + `write-unit-test` from templates
 
 Project-specific skills, generated from templates because their bodies cite real test commands, branch conventions, agent dispatch table, PR / co-author policy, or selected MCP tools.
 
@@ -85,6 +85,41 @@ The five are a **co-shipped unit**: `implement-plan` is always generated, so `im
 
 - **`handoff-to-client`** — generate a markdown API-change handoff document for the client teams consuming an API-only repo: endpoints/operations added / changed / deprecated / removed on the current branch vs the default branch, with request/response shapes, breaking-change flags, and per-platform migration notes. From [resources/handoff-to-client-template.md](resources/handoff-to-client-template.md). **Opt-in** — only generated when `foundation_skills.handoff-to-client` is `enabled` in `.vinta-ai-workflows.yaml` (the bootstrap interview asks only when the repo looks API-only with separate client codebases). The rendered body bakes in `skills.handoff-to-client.*` config: client platforms, API style, optional API spec path, output dir. Standalone — no cross-links into the plan-execution unit.
 
+- **`write-unit-test`** — write durable unit tests for a unit of behavior, enforcing the universal rules (mock only genuine externals, assert the full expected output not counts/truthiness, clean up created data or roll back the transaction, never hit an external service unavailable in dev/test, keep test logic literal, decouple from internals) plus this project's captured test conventions. From [resources/write-unit-test-template.md](resources/write-unit-test-template.md). **Default-on, not ask-first** — generated whenever `foundation_skills.write-unit-test` is `enabled`, which bootstrap sets automatically when `vinta-analyze-codebase` detected a unit-test framework (`disabled` → skip; nothing to render against). The rendered body bakes in `skills.write-unit-test.*` config: test style, data setup, assertion style, DB isolation, plus any inferred `additional_conventions`. Standalone — no cross-links into the plan-execution unit.
+
+  **Ship the packs too — two axes, matched independently.** Alongside the rendered `SKILL.md`, copy the **verbatim** packs the project needs from [resources/write-unit-test-packs/](resources/write-unit-test-packs/) into `ai-tools/skills/write-unit-test/resources/packs/`. There are two kinds, selected on **different** signals so framework-specific advice only ships when its framework is actually present:
+
+  - **Runner pack** (`resources/packs/runners/<runner>.md` → shipped to `.../packs/runners/`) — the test-runner idioms (structure, assertions, mocking). Select **one (or, in a polyglot repo, one per language)** by `inventory.tests.unit_framework`: `pytest` → `pytest.md`; `vitest` → `vitest.md`; `jest` → `jest.md`. Runner packs are **stack-agnostic** — they contain no Django/FastAPI/Medplum specifics.
+  - **Stack pack(s)** (`resources/packs/stacks/<stack>.md` → shipped to `.../packs/stacks/`) — DB isolation, framework client/test-client, domain mocks. Ship **every** pack whose stack the inventory matched (a project can match several — e.g. `nextjs` + `react`, or `tanstack-start` + `react`). Match on `inventory.frameworks` / `inventory.stacks`:
+
+    | Detected signal | Stack pack |
+    |---|---|
+    | Django | `django.md` |
+    | FastAPI | `fastapi.md` |
+    | Flask | `flask.md` |
+    | Medplum (`@medplum/*`) | `medplum.md` |
+    | React (renders UI) | `react.md` |
+    | Next.js | `nextjs.md` |
+    | TanStack Start (`@tanstack/react-start`) | `tanstack-start.md` |
+    | React Router (`react-router` / `@react-router/*`) | `react-router.md` |
+    | Prisma (`@prisma/client`) | `prisma.md` |
+    | Standalone Python package (no web framework) | `python-package.md` |
+    | Standalone TS package / lib (no framework) | `typescript-package.md` |
+
+  **Only ship what matched — never dump the whole directory.** A FastAPI project must not receive `django.md`; a pure-library project gets its `*-package.md` and **no** web-framework pack. When no stack pack matches (e.g. a plain script repo), ship the runner pack alone — the rendered body already falls back to the universal rules + the nearest existing tests. When the runner or a clearly-present stack has no pack here, ship nothing for it and record the gap in the orchestrator's final summary (a candidate for a new pack via the source repo's `add-foundation-skill` flow). The `{{FRAMEWORK_PACK_LOADER_BLOCK}}` + `{{FRAMEWORK_PACKS_LIST}}` placeholders are rendered from exactly the set of packs you shipped.
+
+  **Some stack packs need a one-time project-setup step, done here — not per test.** A pack may require a project-level test-setup fixture that must exist before any test runs; wire it once at derive time so no individual test has to. Currently:
+
+  - **Medplum** (Vitest) — `MockClient` search filtering (`searchResources` / `searchOne` with filters) silently returns nothing unless the FHIR structure definitions + search parameters are indexed in the test process. When you ship `medplum.md`, also install the **two** bundled Vitest setup files and wire both hooks:
+    - Copy [resources/write-unit-test-packs/stacks/medplum-test.globalSetup.ts](resources/write-unit-test-packs/stacks/medplum-test.globalSetup.ts) → the project's setup dir (commonly `src/test.globalSetup.ts`) and register it in `vitest.config.*` under `test.globalSetup`. It indexes the bundles once in the main process and shares `globalSchema.types` to every worker via `project.provide`.
+    - Copy [resources/write-unit-test-packs/stacks/medplum-test.setup.ts](resources/write-unit-test-packs/stacks/medplum-test.setup.ts) → `src/test.setup.ts` and register it under `test.setupFiles`. It `inject`s the shared index and assigns it at **module scope** (not `beforeAll` — timing matters).
+    - **Deps:** `@medplum/definitions` as a devDependency; Vitest **3+** (the `provide`/`inject` API); Node **≥ 22.4** or add `ws` for the WebSocket polyfill (@medplum/core v5). Flag any of these that are missing.
+    - **Version alignment:** `@medplum/core`, `@medplum/definitions`, `@medplum/mock`, `@medplum/fhirtypes` must be on matching versions.
+    - **Idempotent + merge, don't clobber:** if the project already has `test.setup.ts` / `test.globalSetup.ts`, merge the indexing + inject/provide logic in rather than overwriting; if it already does this, do nothing. Create the files + point the runner config at them only when absent.
+    - **Jest-based Medplum project** (rare — the catalog is Vitest-first): there's no bundled Jest variant; index the FHIR bundles in a single `setupFilesAfterEnv` file instead and record it as a follow-up to add a Jest snippet to the catalogue.
+
+    This is a project mutation — do it once at bootstrap. Canonical source is the team's snippet catalogue (`vintasoftware/medplum-snippet-catalog`, `TestSetup/`); the bundled copies (dated in their headers) keep bootstrap offline-safe — prefer the live catalogue if it has advanced. The rendered `medplum.md` only *mentions* the override so tests don't re-index.
+
 Every plan-execution shell + `systematic-debugging` consumes the placeholder set below — render each by substituting from the inventory + Step 0 interview answers. `systematic-debugging` reuses the same set plus two extra placeholders (`{{OBSERVABILITY_MCP_BLOCK}}`, `{{OBSERVABILITY_MCP_LIST}}`) rendered from the catalogue.
 
 #### Rendering the plan-execution unit
@@ -150,6 +185,10 @@ The remaining per-shell placeholders:
 | `{{CLIENT_PLATFORMS_LIST}}` | `skills.handoff-to-client.client_platforms` (handoff-to-client only) | comma-separated, e.g. `iOS (Swift), Android (Kotlin), web SPA (React)` |
 | `{{CLIENT_HANDOFF_DIR}}` | `skills.handoff-to-client.output_dir` (handoff-to-client only) | `.vinta-ai-workflows/client-handoffs` (default) |
 | `{{API_SPEC_BLOCK}}` | derived from `skills.handoff-to-client.api_spec_path` (handoff-to-client only) | when set: a paragraph instructing the agent to regenerate/read the spec at that path on both base and branch and diff the two as the primary change-enumeration source (cross-checking against the code diff). When absent: a one-line note that no machine-readable spec exists, so shapes come from route/serializer code alone. |
+| `{{FRAMEWORK_PACKS_LIST}}` | derived from the packs shipped (write-unit-test only) | comma-separated names of the runner + stack packs that landed under `resources/packs/`, e.g. `pytest + Django` or `vitest, React, TanStack Start`. Renders `the project's test framework` when only the runner shipped with no stack pack. |
+| `{{FRAMEWORK_PACK_LOADER_BLOCK}}` | derived from the packs shipped (write-unit-test only) | bullets pointing at each shipped pack, runner first then stacks: `- Runner: **pytest** → read [resources/packs/runners/pytest.md](resources/packs/runners/pytest.md).` then `- Stack: **Django** → read [resources/packs/stacks/django.md](resources/packs/stacks/django.md).` (one bullet per matched stack). When only the runner shipped, emit just its bullet plus `- No stack pack matched — apply the universal rules and mirror the nearest existing tests.` When no pack shipped at all, render that single fallback line alone. |
+| `{{PROJECT_TEST_PREFERENCES_BLOCK}}` | derived from `skills.write-unit-test.{test_style,data_setup,assertion_style,db_isolation}` (write-unit-test only) | one bullet per field whose value is **not** `framework-default`, phrased as an instruction: `test_style: classes` → `- Group tests in test classes (not standalone functions).`; `data_setup: factories` → `- Build test data with factory classes / builders, not inline literals or fixture files.`; `assertion_style: plain-assert` → `- Use plain \`assert\` (not \`self.assertEqual\`-family methods).`; `db_isolation: transaction-rollback` → `- Isolate DB state with transaction rollback (each test in a rolled-back transaction).`. Emit `- No project-specific overrides — follow the framework pack's defaults.` when all four are `framework-default`. |
+| `{{ADDITIONAL_CONVENTIONS_BLOCK}}` | derived from `skills.write-unit-test.additional_conventions[]` (write-unit-test only) | when non-empty: a `### Additional project conventions` sub-block listing each entry as a bullet, verbatim. Empty string (whole block omitted) when the array is empty. Starts with a leading blank line so it slots cleanly under the preferences block. |
 | `{{DEPENDENCY_LICENSE_BLOCK}}` | derived from `policies.dependency_licenses` | Top-level `## Adding new third-party dependencies` section. Empty string when `enforcement: off` or the block is absent. When `block` / `warn`: short paragraph naming the enforcement mode + the forbidden SPDX list + the pre-install check (`npm view <pkg> license`, PyPI metadata, etc.) + a one-line pointer to the **Dependency licenses** section in [AGENTS.md](AGENTS.md) for the full table including `allowed_overrides` and `notes`. See [resources/dependency-license-block.md](resources/dependency-license-block.md) for the canonical body. |
 | `{{DEPENDENCY_LICENSE_LAYER1_CHECK}}` | derived from `policies.dependency_licenses` | Layer 1 review checklist item. Empty string when `enforcement: off`. When `block` / `warn`: `6. **Dependency license scan**: \`git diff package.json pyproject.toml ...\` (project-relevant manifests) — for every added dep look up its SPDX license (\`npm view <pkg> license\`, PyPI metadata, repo \`LICENSE\`). A license in \`policies.dependency_licenses.forbidden_spdx\` and not in \`allowed_overrides\` is a BLOCKER (when \`block\`) or a SHOULD-FIX (when \`warn\`). A missing / \`UNKNOWN\` / undeclared license is **always a BLOCKER** regardless of enforcement mode — there is no override to silently bless undisclosed terms.` |
 | `{{DEPENDENCY_LICENSE_RULE_LINE}}` | derived from `policies.dependency_licenses` | Important-rules bullet. Empty string when `enforcement: off`. When `block`: `- **License check before any new dep.** Refuse \`npm add\` / \`pnpm add\` / \`pip install\` / \`poetry add\` / \`uv add\` / \`cargo add\` / \`go get\` when the package's SPDX license is in the forbidden list — see AGENTS.md **Dependency licenses**. User can grant a one-off override after acknowledging the violation; record the override in \`policies.dependency_licenses.allowed_overrides\` before re-running.` When `warn`: same line but `Proceed but record the violation in the phase report` instead of `Refuse`. |
@@ -221,6 +260,7 @@ Render each template (expand includes → substitute placeholders → write), pr
 - `ai-tools/skills/amend-plan/SKILL.md` (from `plan-execution/shell/amend-plan-template.md`)
 - `ai-tools/skills/systematic-debugging/SKILL.md` (from `systematic-debugging-template.md`) — only when `foundation_skills.systematic-debugging: enabled`
 - `ai-tools/skills/handoff-to-client/SKILL.md` (from `handoff-to-client-template.md`) — only when `foundation_skills.handoff-to-client: enabled`
+- `ai-tools/skills/write-unit-test/SKILL.md` (from `write-unit-test-template.md`) **plus** `ai-tools/skills/write-unit-test/resources/packs/runners/<runner>.md` + `.../packs/stacks/<stack>.md` (verbatim from `write-unit-test-packs/`, only the detected runner + matched stacks) — only when `foundation_skills.write-unit-test: enabled` (default-on when a test framework was detected)
 
 The first five are the **plan-execution unit** — render them together (they share partials + placeholders + cross-links); a change to one partial ripples to every shell that includes it.
 
@@ -321,4 +361,5 @@ After all skills written:
 4. Foundation skills (plan-feature, create-spec, open-pr-from-context — plus create-qa-use-cases when e2e is enabled) reference each other correctly via `[name](../<name>/SKILL.md)` links. When e2e is disabled, confirm `plan-feature` has **no** surviving `<!-- e2e:start/end -->` markers and no dangling link to `create-qa-use-cases` / `add-e2e-test`.
 5. **Plan-execution unit intact.** All five files exist; no surviving `<!-- include -->` markers; the conductor's `[implement-phase]` / `[review-phase]` / integrate-phase links resolve, and `amend-plan` + `systematic-debugging` (when shipped) → `[review-phase]` resolve. Under `ask`: both `integrate-phase-stacked` + `integrate-phase-modular` exist and the conductor's dispatch line names both.
 6. `implement-plan` (+ the plan-execution sub-skills) cite real commands + the project's actual code host + branch / PR / co-author policy.
-7. Setup script ([vinta-install-ai-tools-setup](../vinta-install-ai-tools-setup/SKILL.md)) runs cleanly with the new skills in place.
+7. **`write-unit-test` (when shipped)** renders with no surviving `{{PLACEHOLDER}}`, cites the project's real test command, and every pack path in its `{{FRAMEWORK_PACK_LOADER_BLOCK}}` resolves to a file that actually landed under `ai-tools/skills/write-unit-test/resources/packs/`. One runner pack; stack packs only for frameworks the project actually uses (no `django.md` in a FastAPI repo, no web-framework pack in a pure-library repo). **Medplum projects**: confirm both FHIR-indexing setup files exist and are registered in `vitest.config.*` (`test.globalSetup` + `test.setupFiles`), `@medplum/definitions` is a devDependency, and no test re-indexes.
+8. Setup script ([vinta-install-ai-tools-setup](../vinta-install-ai-tools-setup/SKILL.md)) runs cleanly with the new skills in place.