From bf619d94ff44f7fa9323bc0e6277e719b05d6f27 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 17:36:44 -0500
Subject: [PATCH 1/9] docs: trim the root AGENTS.md to rules with no other home

Cut the sections that duplicated a nested AGENTS.md, a playbook or an eslint rule: the DNP
package list, the code-philosophy section, the route-tree rule, and the lint-enforced halves
of the formatting, tests, coverage and translation rules. The scoped-run tips move to
testing-strategy.md, which had no copy. Set agentGuidance: false in turbo.json and drop the
managed Turborepo block it maintained.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .agents/docs/architecture/testing-strategy.md |   8 ++
 .agents/skills/odc-agent-docs/SKILL.md        |   2 +-
 AGENTS.md                                     | 133 +++++-------------
 turbo.json                                    |   1 +
 4 files changed, 46 insertions(+), 98 deletions(-)

diff --git a/.agents/docs/architecture/testing-strategy.md b/.agents/docs/architecture/testing-strategy.md
index 9df238645..ef4378d98 100644
--- a/.agents/docs/architecture/testing-strategy.md
+++ b/.agents/docs/architecture/testing-strategy.md
@@ -16,6 +16,14 @@ What is tested where, and what CI blocks a merge on. Writing an e2e test is
 is the only code path that touches a real database: a permissions or row-scoping change is untested
 until an e2e spec covers it.
 
+## Scoping a run
+
+Scope a package script with `pnpm --filter @opendatacapture/<pkg> <script>` or turbo's
+`--filter=<pkg>`. Scope vitest to one project with `pnpm exec vitest --project <name>` (names come
+from the `name` field in each package's `vitest.config.ts`, e.g. `api`, `web`, `schemas`), or run a
+single file with `pnpm exec vitest path/to/file.test.ts`. A scoped run with `--coverage` measures
+only what it ran against the whole coverage scope, so add `--coverage.thresholds.100=false` to it.
+
 ## A test nothing collects passes silently
 
 Root `vitest.config.ts` collects only `apps/*/vitest.config.ts`, `packages/*/vitest.config.ts` and
diff --git a/.agents/skills/odc-agent-docs/SKILL.md b/.agents/skills/odc-agent-docs/SKILL.md
index 6cdf457a9..15f32cae9 100644
--- a/.agents/skills/odc-agent-docs/SKILL.md
+++ b/.agents/skills/odc-agent-docs/SKILL.md
@@ -62,7 +62,7 @@ always loaded.
 | a vitest project added or removed       | `testing-strategy.md` Vitest projects table, its count and its "no unit tests" list; `workspace-map.md` `Vitest project` column; `## Tests`       |
 | a new playbook                          | root `AGENTS.md` "Step-by-step playbooks"                                                                                                         |
 | a new architecture doc                  | root `AGENTS.md` "Deeper reference, read on demand"                                                                                               |
-| a new `.agents/docs/packages/<name>.md` | `.agents/docs/packages/index.md` (`Docs` link, fidelity table) and root `AGENTS.md` "Internal DNP packages"                                       |
+| a new `.agents/docs/packages/<name>.md` | `.agents/docs/packages/index.md` (`Docs` link, fidelity table)                                                                                    |
 
 **Done when** a grep for each fact you wrote finds one statement and any number of pointers, every path you
 cited resolves, every table in the row you triggered is updated, and any `AGENTS.md` your change contradicts
diff --git a/AGENTS.md b/AGENTS.md
index 2b0ef04a7..d87612c41 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,16 +25,10 @@ pnpm test:coverage          # vitest with coverage — fails below 100%, the gat
 pnpm test:e2e               # playwright, in testing/
 ```
 
-Scope a run to one package with `pnpm --filter @opendatacapture/<pkg> <script>` or turbo's
-`--filter=<pkg>`. Scope vitest to one project with `pnpm exec vitest --project <name>` (names come
-from the `name` field in each package's `vitest.config.ts`, e.g. `api`, `web`, `schemas`). Run a
-single file with `pnpm exec vitest path/to/file.test.ts`. A scoped run with `--coverage` measures
-only what it ran against the whole coverage scope, so add `--coverage.thresholds.100=false` to it.
-
-`pnpm lint`, `pnpm test` and `pnpm test:coverage` all need `.env` to exist. `pnpm lint` also needs a
-generated Prisma client, so a cold run is not fast. A fresh clone needs more than `pnpm install`
-before `pnpm dev` serves anything — `.agents/docs/playbooks/run-locally.md` is the order of
-operations.
+Everything after `pnpm generate:env` needs `.env` to exist, and a fresh clone needs more than
+`pnpm install` before `pnpm dev` serves anything: `.agents/docs/playbooks/run-locally.md` is the
+order of operations. Scoping a run to one package, project or file is in
+`.agents/docs/architecture/testing-strategy.md`.
 
 ## Hard rules
 
@@ -43,17 +37,18 @@ not every tool loads nested files.
 
 - **Ask before writing code if the task is ambiguous** or its stated scope cannot accomplish the
   goal.
-- **No new dependencies without asking in-conversation.** Versions are pinned in the `catalog:`
-  block of `pnpm-workspace.yaml` — reference `"catalog:"` in a `package.json`, never a literal
-  version. `minimumReleaseAge` is 7 days, so a freshly published package will be rejected.
+- **No new dependencies without asking in-conversation.** Check `.agents/docs/packages/index.md`
+  first: one of the `@douglasneuroinformatics/*` packages this repo already consumes probably solves
+  it. Versions are pinned in the `catalog:` block of `pnpm-workspace.yaml` — reference `"catalog:"`
+  in a `package.json`, never a literal version. `minimumReleaseAge` is 7 days, so a freshly published
+  package will be rejected.
 - **Every change needs a unit test _and_ an end-to-end test in `testing/`.** See
   `.agents/docs/playbooks/add-e2e-test.md`. Utility scripts under `scripts/` and the standalone
   `cli/odc-cli` script, which has no test harness, are the exceptions and need no tests.
 - **Unit test coverage stays at 100%.** `pnpm test:coverage` fails below 100% statements, branches,
   functions or lines, and CI runs it. Code no test can reach is dead code: prove it dead (the types,
-  the callers, the library contract) and delete it. Never add a coverage-ignore comment (eslint
-  rejects one) or widen `coverage.exclude` to get past the gate; that list is for non-code —
-  fixtures, generated files and bare entrypoints.
+  the callers, the library contract) and delete it. Never widen `coverage.exclude` to get past the
+  gate; that list is for non-code — fixtures, generated files and bare entrypoints.
 - **Commit messages follow Conventional Commits.** `type(scope): subject`, where `type` is one of the
   11 `@commitlint/config-conventional` types and `scope`, if present, is an `@opendatacapture/*`
   workspace name without the prefix. A `commit-msg` hook and the `Commitlint` CI job enforce it, and
@@ -62,12 +57,9 @@ not every tool loads nested files.
 - **Pull requests and issues go to `DouglasNeuroInformatics/OpenDataCapture`, base `main`.**
   `origin` is your fork (`CONTRIBUTING.md`), so pass `--repo DouglasNeuroInformatics/OpenDataCapture`
   to `gh`.
-- **All frontend user-facing strings go through `useTranslation`.** Every language the frontend
-  exposes gets an entry. In web, gateway and react-core, prefer inline
-  `t({ en: '...', es: '...', fr: '...' })` unless the string is used more than once; each workspace
-  enables `requireCompleteTranslations`, so omitting a language is a type error caught by `pnpm lint`.
-- **Never run the `apps/web` route-tree generator.** `src/route-tree.ts` is generated and
-  git-tracked, but the user regenerates it manually after route changes. Never hand-edit it either.
+- **All frontend user-facing strings go through `useTranslation`**, with an entry for every language
+  the frontend exposes. Prefer inline `t({ en: '...', es: '...', fr: '...' })` unless the string is
+  used more than once.
 - **If code needs a comment to be understood, the code is wrong** — rewrite it. Comments are for
   the non-obvious: a vendor bug, a protocol quirk, a deliberate version pin. Never restate the code.
 - **Make small, incremental, easily reviewable changes.** No sweeping refactors unless asked.
@@ -86,9 +78,8 @@ cover.
 
 ## Where to look
 
-Read the `AGENTS.md` in the directory you are editing. Each one covers only that workspace. New
-here? Bring the stack up (`.agents/docs/playbooks/run-locally.md`), then read
-`.agents/docs/workspace-map.md` and `.agents/docs/architecture/testing-strategy.md`.
+Read the `AGENTS.md` in the directory you are editing; each covers only that workspace. New here?
+`.agents/docs/playbooks/run-locally.md`, then `.agents/docs/workspace-map.md`.
 
 | Working on                                      | Read first                              |
 | ----------------------------------------------- | --------------------------------------- |
@@ -110,11 +101,10 @@ here? Bring the stack up (`.agents/docs/playbooks/run-locally.md`), then read
 Every other workspace has its own `AGENTS.md` too — check the directory before assuming there
 isn't one.
 
-> **`packages/instrument-guidelines/AGENTS.md` is the one exception.** It is not this repo's
-> conventions: it is a published npm artifact (`@opendatacapture/instrument-guidelines`) whose bin
-> installs it into _external_ instrument repositories as their `AGENTS.md`. Read it as the
-> specification for authoring an instrument. Editing it changes a published package, so treat any
-> change there as a release, and do not add Open Data Capture repo rules to it.
+> **`packages/instrument-guidelines/AGENTS.md` is not this repo's conventions.** Its bin installs it
+> into _external_ instrument repositories as their `AGENTS.md`, so it is the specification for
+> authoring an instrument and a published npm package: treat a change there as a release, and keep
+> Open Data Capture repo rules out of it.
 
 ### Deeper reference, read on demand
 
@@ -147,35 +137,12 @@ runtime**.
 | Add a vitest project to a package      | `.agents/docs/playbooks/add-vitest-project.md`    |
 | Promote a component to react-core      | `.agents/docs/playbooks/promote-to-react-core.md` |
 
-## Internal DNP packages
-
-This repo depends on 11 `@douglasneuroinformatics/*` packages, maintained in separate repos and
-consumed from npm: `eslint-config`, `prettier-config`, `tsconfig`, `esbuild-plugin-prisma`, `libjs`,
-`libcrypto`, `libnest`, `libpasswd`, `libstats`, `libui-form-types`, `libui`.
-
-**Check `.agents/docs/packages/index.md` before writing utility, crypto, stats, form-typing or UI
-code from scratch, or before adding a third-party dependency** — one of these probably already
-solves it. Most publish their original TypeScript under `src/` in `node_modules`; read that instead
-of guessing at a signature.
-
-## What good code looks like here
-
-Each principle applies where its problem exists. Machinery without its justifying problem is
-ceremony, and ceremony is worse than plain code.
+## Conventions
 
-- **Correctness is structural, not vigilant.** A correct system is one where the invalid state
-  cannot be written, not one where a careful person catches it. Anything a human must remember, the
-  compiler should remember instead.
-- **One source of truth; everything derived.** A contract exists once; types, variants and fixtures
-  flow from it. Two artifacts that must agree is a bug waiting for its trigger.
 - **Strict validation at the boundary, trust inside.** Data is distrusted exactly once — at the
   perimeter — then the interior runs clean, with no defensive re-checking cluttering the logic.
-- **Shape is never repeated.** Shared structure gets abstracted, with types before runtime
-  indirection, so change propagates instead of being replicated.
-- **Names and types carry all meaning.** Guards first, success path flat, reading top to bottom.
-- Prefer descriptive variable names over terse or cryptic ones.
-
-## Conventions
+- **One source of truth; everything derived.** A contract exists once; types, variants and fixtures
+  flow from it. Two artifacts that must agree is a bug waiting for its trigger.
 
 Define Zod schemas for data validation; derive types via `z.infer`. Convention: `$`-prefixed schema,
 same-named inferred type, type declared first:
@@ -189,44 +156,16 @@ Variants are composed from a base shape, never written from scratch. Schemas exi
 actually parsed at a perimeter; everything else is a plain type. See `packages/schemas/AGENTS.md`.
 
 **Types.** Strict mode; no casting at call sites. No loose records where a closed key set is known;
-if only a subset of keys is known, type those and add an index signature. Type safety takes
-precedence over convenience.
-
-Use conditional types, template literal types, inference extraction and mapped types as routine
-tools to keep call sites short and fully inferred. Concentrate the cost: complex type machinery
-belongs in a small number of utilities, never spread across ordinary code.
-
-Name generics with a `T` prefix and a PascalCase noun describing the parameter's role — `TValue`,
-`TError`. The prefix distinguishes a type parameter from a concrete type at a glance; the noun
-explains it.
-
-**Formatting is not your problem.** `eslint --fix` and prettier run as part of `pnpm lint` and
-`pnpm format`. In particular `perfectionist/sort-objects` alphabetizes every object literal and
-`import/exports-last` moves exports to the bottom — write code in a sensible order and let the
-tooling rearrange it. Where ordering is load-bearing, the existing code carries an explicit
-`eslint-disable` comment; follow that pattern rather than fighting the rule. Every `eslint-disable`
-states why after `--`, as in `// eslint-disable-next-line <rule> -- <reason>`; eslint rejects one
-that does not.
-
-**Tests.** A unit test is `<file>.test.ts(x)` in a `__tests__/` folder beside the file it tests:
-`src/index.ts` is tested by `src/__tests__/index.test.ts`. A suite that drives a whole package, like
-`apps/api/test/`, lives in that package's `test/` folder instead. A unit test imports the file it
-tests and titles each top-level `describe` after a name it imports from it, or after the file's name
-when it imports the module itself (a side-effect import, `import * as`, or `await import()`) to test
-what loading it does. Three eslint rules
-enforce the layout: two in `eslint.config.js`, and `odc/unit-test-subject` in `.eslint/rules/`,
-where the repo's other custom rules live too. `packages/instrument-library` is the one exception, for
-the reason its `AGENTS.md` gives. Keep test bodies short; each verifies one behavior. Descriptions are concise, grammatical
-sentences stating the behavioral reason, e.g. `'should key the cache on every parameter, so paging
-does not serve a stale page'`.
-
-<!-- BEGIN:turborepo-agent-rules -->
-
-# This is NOT the Turborepo you know
-
-Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`.
-
-Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.
-
-This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
-<!-- END:turborepo-agent-rules -->
+if only a subset of keys is known, type those and add an index signature.
+
+**Formatting is not your problem.** `pnpm lint` runs `eslint --fix` and prettier, so write code in a
+sensible order and let the tooling sort objects and move exports. Where ordering is load-bearing,
+the existing code carries an `eslint-disable` comment with its reason after `--`; follow that pattern
+rather than fighting the rule.
+
+**Tests.** A unit test is `<file>.test.ts(x)` in a `__tests__/` folder beside the file it tests, or
+in a package's `test/` folder when it drives the whole package; eslint enforces the layout
+(`odc/unit-test-subject` in `.eslint/rules/`, beside the repo's other custom rules). Keep test
+bodies short; each verifies one behavior. Descriptions are concise, grammatical sentences stating
+the behavioral reason, e.g. `'should key the cache on every parameter, so paging does not serve a
+stale page'`.
diff --git a/turbo.json b/turbo.json
index e3c706033..163162385 100644
--- a/turbo.json
+++ b/turbo.json
@@ -1,5 +1,6 @@
 {
   "$schema": "https://turbo.build/schema.json",
+  "agentGuidance": false,
   "globalDependencies": [".env", "eslint.config.js", "tsconfig.json", "prettier.config.js"],
   "globalEnv": ["NODE_ENV", "NODE_OPTIONS", "RELEASE_VERSION"],
   "tasks": {

From cd071805fb7093315919659be8494ed47f62e42e Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 17:44:13 -0500
Subject: [PATCH 2/9] chore: update interview skill

---
 .agents/skills/interview/SKILL.md | 13 +------------
 skills-lock.json                  |  2 +-
 2 files changed, 2 insertions(+), 13 deletions(-)

diff --git a/.agents/skills/interview/SKILL.md b/.agents/skills/interview/SKILL.md
index 34f87588a..d21e80f78 100644
--- a/.agents/skills/interview/SKILL.md
+++ b/.agents/skills/interview/SKILL.md
@@ -6,18 +6,7 @@ disable-model-invocation: true
 
 Interview me about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
-Before the first question, explore the environment, then calibrate the session in one brief message:
-
-- Open with one or two sentences restating the task, to show you understand it.
-- Then a numbered list of calibration questions, each with your recommended answer, covering only the items my opening prompt leaves open:
-  1. Ambiguities in the request
-  2. The criteria for judging options.
-  3. How deep to grill me.
-  4. What the deliverable is when we're done.
-- Keep each item concise and focused
-- If my opening prompt settles all four, skip the list and follow the restatement with the first question.
-
-After calibration, ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
 
 A question stays open until I make a decision or tell you to move on. If I reply with anything else, such as a question of my own, answer it, then close by asking whether there is more to discuss or I'm ready to decide.
 
diff --git a/skills-lock.json b/skills-lock.json
index a6f0934d1..1fa526caf 100644
--- a/skills-lock.json
+++ b/skills-lock.json
@@ -17,7 +17,7 @@
       "source": "joshunrau/skills",
       "sourceType": "github",
       "skillPath": "skills/interview/SKILL.md",
-      "computedHash": "8c4282946c760be30b49f1fbf5645bb0aedac285e6cac5c8f9e8c8b68f35a422"
+      "computedHash": "6cf86ca51424350f10880c3a2fd3dd018c6682c90dfb81baf66e91615df4a0fa"
     }
   }
 }

From 3ab058169af06f6c9b24f54fd23ffbe8114ab625 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 17:44:53 -0500
Subject: [PATCH 3/9] chore: add writing-skills-for-agents skill

---
 .../skills/writing-skills-for-agents/SKILL.md | 145 ++++++++++++++++++
 .claude/skills/writing-skills-for-agents      |   1 +
 skills-lock.json                              |   6 +
 3 files changed, 152 insertions(+)
 create mode 100644 .agents/skills/writing-skills-for-agents/SKILL.md
 create mode 120000 .claude/skills/writing-skills-for-agents

diff --git a/.agents/skills/writing-skills-for-agents/SKILL.md b/.agents/skills/writing-skills-for-agents/SKILL.md
new file mode 100644
index 000000000..fc5031b5a
--- /dev/null
+++ b/.agents/skills/writing-skills-for-agents/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: writing-skills-for-agents
+description: Draft or edit skills for Claude or other agents. Use for drafting, editing, reviewing, or editing any skills.
+---
+
+# Writing Skills for Agents
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required)
+├── references/        # Detailed docs (if needed)
+└── scripts/           # Utility scripts (if needed)
+    └── helper.js
+```
+
+## When to Add References
+
+Add reference documents when:
+
+- SKILL.md exceeds 200 lines
+
+## When to Add Scripts
+
+Add utility scripts when:
+
+- Operation is deterministic (validation, formatting)
+- Same code would be generated repeatedly
+- Errors need explicit handling
+
+Scripts save tokens and improve reliability vs generated code
+
+## Anti-Pattern: Overfitting to the Case That Just Happened
+
+### The Golden Rule
+
+Write for an agent that has no memory of the session that produced the skill, holds only the files committed in the repo, and is working on an input maximally dissimilar to the one you just handled while still within the skill's scope. Every line must be understandable to that agent and useful to it.
+
+You usually write or edit a skill right after working one specific case: a bug, a document, a script, a workflow. Call it the _source case_. The reader will never see the source case, so every line has to hold across the skill's whole scope.
+
+The description sets the scope. Before testing a line, read the description and find the input furthest from the source case that it still covers. A skill for "debugging Node.js applications" can name JavaScript debugging techniques; a skill for "systematic debugging" cannot.
+
+### Three Ways a Line Fails
+
+Check each line against all three, in this order. A line can fail more than one.
+
+#### 1. Dangling references
+
+The reader cannot resolve a name. Every path, name, and term in the skill must resolve to one of three places: a file committed in the repo, a definition in the skill itself, or general knowledge of the domain.
+
+Tells:
+
+- Paths under a temp, scratch, home, or download directory.
+- Files the session wrote but never committed, such as a notes file in the working directory.
+- "As discussed", "as agreed", "the earlier approach", or any phrase pointing at a conversation.
+- Roles, nicknames, or labels coined during the session and used without definition.
+- Ids, keys, or row numbers from a local database or spreadsheet.
+- Skill-local conventions, such as a priority scale, that the skill never defines.
+
+Fix: commit the file, define the term in the skill, or delete the reference.
+
+#### 2. Run reports
+
+The line records what happened instead of telling the reader what to do. Dates, counts, "results", which inputs were processed and what broke: these are log entries. Past tense on its own is fine; a past observation can back an instruction (see evidence, below).
+
+Fix: extract the instruction the report implies and write it as an instruction. Delete the rest.
+
+#### 3. Details from the source case
+
+The line names something from the source case that the dissimilar input does not contain. Run the **noun test**: for each noun in the line, check that it refers to something in the dissimilar input. Then sort each noun that fails:
+
+- **Data** the reader would act on directly (a URL, selector, id, email pattern, page count, or flag value): delete it, or move it to the store the skill's data already lives in, such as a database, a data file, or a tracker.
+- **Evidence** that supports a rule: keep it, and say that it is one observation and what produced it, so the reader can weigh it.
+- **The subject of the instruction**: write the role it played in the source case instead. "`checkout.spec.ts` flakes under parallel runs" becomes "a test that flakes under parallel runs".
+
+### Examples
+
+All excerpts come from a fictional skill, `triage-ci-failures`: "Triage failing CI jobs in a repo, separate flaky failures from real ones, and file or fix each."
+
+#### Dangling references
+
+Before:
+
+```markdown
+Mark timeouts P2, as agreed. Notes from the last triage are in `ci-notes.md`.
+```
+
+"As agreed" points at a conversation, `ci-notes.md` was never committed, and P2 means something different on every team, so the skill has to define it.
+
+After:
+
+```markdown
+Priority: P1 blocks merges, P2 fails on rerun, P3 fails once and passes on rerun. Mark timeouts P2.
+```
+
+#### Run reports
+
+Before:
+
+```markdown
+**Triage run (Sep 2026)**
+
+14 failures: 9 flaky, 3 real, 2 unresolved. `payments-e2e` timed out on both reruns, so it was left open.
+```
+
+The section records one run. Its only instruction is what to do with a job that times out twice, and `payments-e2e` becomes the role it played.
+
+After:
+
+```markdown
+A job that times out on every rerun is not flaky. Leave it open and assign it.
+```
+
+#### Details from the source case: data
+
+Before:
+
+```markdown
+Known flaky: `checkout.spec.ts:88`, `auth-refresh.spec.ts`. The `db-migrate` job needs `RETRY=3`.
+```
+
+Each test name, job name, and flag value fails the noun test, and the reader would act on each directly, so all of it is data.
+
+After: deleted. The flaky list belongs in a quarantine file or the issue tracker, where it is maintained.
+
+#### Details from the source case: evidence
+
+Before:
+
+```markdown
+Rerun once before triaging. Retrying cut false failures from 31 to 12.
+```
+
+The numbers support the rule and are not something the reader acts on, so they are evidence. What is missing is their source.
+
+After:
+
+```markdown
+Rerun once before triaging. In one week of runs, a single rerun cut false failures from 31 to 12.
+```
+
+## Verifying
+
+Have a subagent verify the skill. Give it the skill under review and this skill, tell it to assume only the committed files, and have it apply the three tests to every line. It reports each failing line with the tests it failed. Done when it reports none.
diff --git a/.claude/skills/writing-skills-for-agents b/.claude/skills/writing-skills-for-agents
new file mode 120000
index 000000000..c55d63cac
--- /dev/null
+++ b/.claude/skills/writing-skills-for-agents
@@ -0,0 +1 @@
+../../.agents/skills/writing-skills-for-agents
\ No newline at end of file
diff --git a/skills-lock.json b/skills-lock.json
index 1fa526caf..eda48bc43 100644
--- a/skills-lock.json
+++ b/skills-lock.json
@@ -18,6 +18,12 @@
       "sourceType": "github",
       "skillPath": "skills/interview/SKILL.md",
       "computedHash": "6cf86ca51424350f10880c3a2fd3dd018c6682c90dfb81baf66e91615df4a0fa"
+    },
+    "writing-skills-for-agents": {
+      "source": "joshunrau/skills",
+      "sourceType": "github",
+      "skillPath": "skills/writing-skills-for-agents/SKILL.md",
+      "computedHash": "692102f9ab7e6dc148240a3f6255aa9856b7bea177133d4241ca0906e67d7be6"
     }
   }
 }

From 0f76c51ccaaeac3db550d413d2330ffb296841b7 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 18:00:44 -0500
Subject: [PATCH 4/9] chore: revise agents.md

---
 .agents/docs/index.md                         |  60 +++++++
 .agents/docs/playbooks/cut-a-release.md       |   7 +-
 .agents/skills/adding-dependencies/SKILL.md   |  31 ++++
 .../adding-dependencies/agents/openai.yaml    |   3 +
 .../{odc-done => finishing-changes}/SKILL.md  |  38 +++--
 .../agents/openai.yaml                        |   2 +-
 .agents/skills/odc-agent-docs/SKILL.md        |  14 +-
 .agents/skills/opening-issues/SKILL.md        |   2 +-
 .claude/skills/adding-dependencies            |   1 +
 .claude/skills/finishing-changes              |   1 +
 .claude/skills/odc-done                       |   1 -
 AGENTS.md                                     | 159 ++++++------------
 package.json                                  |   1 +
 13 files changed, 183 insertions(+), 137 deletions(-)
 create mode 100644 .agents/docs/index.md
 create mode 100644 .agents/skills/adding-dependencies/SKILL.md
 create mode 100644 .agents/skills/adding-dependencies/agents/openai.yaml
 rename .agents/skills/{odc-done => finishing-changes}/SKILL.md (51%)
 rename .agents/skills/{odc-done => finishing-changes}/agents/openai.yaml (70%)
 create mode 120000 .claude/skills/adding-dependencies
 create mode 120000 .claude/skills/finishing-changes
 delete mode 120000 .claude/skills/odc-done

diff --git a/.agents/docs/index.md b/.agents/docs/index.md
new file mode 100644
index 000000000..d6c2a0d58
--- /dev/null
+++ b/.agents/docs/index.md
@@ -0,0 +1,60 @@
+# Where to look
+
+Read the `AGENTS.md` in the directory you are editing; each covers only that workspace. New here?
+`.agents/docs/playbooks/run-locally.md`, then `.agents/docs/workspace-map.md`.
+
+| Working on                                      | Read first                              |
+| ----------------------------------------------- | --------------------------------------- |
+| Clinician-facing React SPA                      | `apps/web/AGENTS.md`                    |
+| NestJS backend                                  | `apps/api/AGENTS.md`                    |
+| Patient-facing SSR app for remote assignments   | `apps/gateway/AGENTS.md`                |
+| In-browser instrument editor                    | `apps/playground/AGENTS.md`             |
+| Marketing site and user docs                    | `apps/outreach/AGENTS.md`               |
+| Shared Zod schemas / cross-tier contracts       | `packages/schemas/AGENTS.md`            |
+| Compiling instrument source into bundles        | `packages/instrument-bundler/AGENTS.md` |
+| Building the library catalog instruments import | `packages/runtime-bundler/AGENTS.md`    |
+| The `defineInstrument` public API               | `packages/runtime-core/AGENTS.md`       |
+| Adding or editing a built-in instrument         | `packages/instrument-library/AGENTS.md` |
+| Pinned library wrappers instruments import      | `vendor/AGENTS.md`                      |
+| The published runtime artifact                  | `runtime/v1/AGENTS.md`                  |
+| End-to-end tests                                | `testing/AGENTS.md`                     |
+| User documentation                              | `docs/AGENTS.md`                        |
+
+Every other workspace has its own `AGENTS.md` too — check the directory before assuming there
+isn't one.
+
+> **`packages/instrument-guidelines/AGENTS.md` is not this repo's conventions.** Its bin installs it
+> into _external_ instrument repositories as their `AGENTS.md`, so it is the specification for
+> authoring an instrument and a published npm package: treat a change there as a release, and keep
+> Open Data Capture repo rules out of it.
+
+## Deeper reference, read on demand
+
+| Topic                                                           | Path                                                |
+| --------------------------------------------------------------- | --------------------------------------------------- |
+| Which workspace depends on which, what is built, what publishes | `.agents/docs/workspace-map.md`                     |
+| The 11 `@douglasneuroinformatics/*` packages this repo consumes | `.agents/docs/packages/index.md`                    |
+| Instrument source → bundle → store → interpret → render         | `.agents/docs/architecture/instrument-pipeline.md`  |
+| The six similarly-named `runtime-*` things, and `vendor/`       | `.agents/docs/architecture/runtime-and-vendor.md`   |
+| CASL, `@RouteAccess`, and group scoping                         | `.agents/docs/architecture/auth-and-permissions.md` |
+| What is tested where, and what CI gates                         | `.agents/docs/architecture/testing-strategy.md`     |
+
+## Step-by-step playbooks
+
+Follow these in full. Each covers a task where **skipping a step compiles cleanly and fails at
+runtime**.
+
+| Task                                   | Playbook                                          |
+| -------------------------------------- | ------------------------------------------------- |
+| Add an API endpoint                    | `.agents/docs/playbooks/add-api-endpoint.md`      |
+| Add a route to `apps/web`              | `.agents/docs/playbooks/add-web-route.md`         |
+| Add a data-fetching hook to `apps/web` | `.agents/docs/playbooks/add-web-data-hook.md`     |
+| Add an end-to-end test                 | `.agents/docs/playbooks/add-e2e-test.md`          |
+| Add a built-in instrument              | `.agents/docs/playbooks/add-instrument.md`        |
+| Add a vendored library for instruments | `.agents/docs/playbooks/add-vendor-package.md`    |
+| Add an environment variable            | `.agents/docs/playbooks/add-env-var.md`           |
+| Add a blog post                        | `.agents/docs/playbooks/add-blog-post.md`         |
+| Run the stack on a fresh clone         | `.agents/docs/playbooks/run-locally.md`           |
+| Cut a release                          | `.agents/docs/playbooks/cut-a-release.md`         |
+| Add a vitest project to a package      | `.agents/docs/playbooks/add-vitest-project.md`    |
+| Promote a component to react-core      | `.agents/docs/playbooks/promote-to-react-core.md` |
diff --git a/.agents/docs/playbooks/cut-a-release.md b/.agents/docs/playbooks/cut-a-release.md
index 95837585a..7b6ed6e99 100644
--- a/.agents/docs/playbooks/cut-a-release.md
+++ b/.agents/docs/playbooks/cut-a-release.md
@@ -15,9 +15,10 @@ them. Never hand-edit a version field.
 ## Steps
 
 1. **Get the branch green before you bump.** Nothing after the PR runs a test against this code: the
-   release's `validate` job runs `pnpm lint` only. Run the root `AGENTS.md` "Before you are done"
-   checks; root `pnpm test` has no turbo `^build` behind it, so run `pnpm build` once first. `pnpm lint`
-   rewrites files, so commit any churn on its own before the bump. Also confirm
+   release's `validate` job runs `pnpm lint` only. Run `pnpm check`
+   (`.agents/skills/finishing-changes/SKILL.md`); root `pnpm test` has no turbo `^build` behind it, so
+   run `pnpm build` once first. `pnpm lint` rewrites files, so commit any churn on its own before the
+   bump. Also confirm
    `gh run list --workflow=Release --limit 1` is green on `main`: nothing local builds the Docker
    images, and `build` gates both publishes.
 
diff --git a/.agents/skills/adding-dependencies/SKILL.md b/.agents/skills/adding-dependencies/SKILL.md
new file mode 100644
index 000000000..27b58c605
--- /dev/null
+++ b/.agents/skills/adding-dependencies/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: adding-dependencies
+description: Add, upgrade or replace a third-party npm package in Open Data Capture. Use before touching a dependencies block in any package.json or the catalog in pnpm-workspace.yaml, including when a task seems to need a library the repo does not have.
+---
+
+**Ask in-conversation before adding anything**: name the package, what it is for, and what you checked first.
+Do not install while waiting. A literal version in a `package.json` installs cleanly and is caught only by the
+grep under Verify; a version too new for the release-age gate is rejected at `pnpm install`.
+
+1. **A library that instruments import is not a dependency of this repo.** It goes through `vendor/`, where
+   each wrapper pins a literal version on purpose: `.agents/docs/playbooks/add-vendor-package.md`, and none
+   of the steps below.
+2. **Check what the repo already has.** `.agents/docs/packages/index.md` lists the `@douglasneuroinformatics/*`
+   packages this repo consumes; one of them usually covers a utility, crypto, stats, form-typing or UI need.
+   Then grep the `catalog:` block of `pnpm-workspace.yaml`: a package already there is added to a workspace
+   with `"catalog:"` and needs no question.
+3. **Pin the version in the catalog, not the package.** Every version lives once, in the `catalog:` block of
+   `pnpm-workspace.yaml`; a `package.json` references `"catalog:"`, never a literal version, so two workspaces
+   cannot drift apart.
+4. **Pick a version older than `minimumReleaseAge`.** It is 7 days (`pnpm-workspace.yaml`), so a release newer
+   than that is rejected at install time. Take the previous release rather than extending
+   `minimumReleaseAgeExclude`; that list is for the repo's own `@douglasneuroinformatics/*` packages and
+   pins the user has explicitly approved.
+5. **Run `pnpm install`** so the lockfile change lands in the same commit as the `package.json` change.
+
+## Verify
+
+```sh
+pnpm install --frozen-lockfile      # ERR_PNPM_OUTDATED_LOCKFILE means step 5 was skipped
+grep -n '<package>' pnpm-workspace.yaml   # no line means the version was pinned in a package.json, not the catalog
+```
diff --git a/.agents/skills/adding-dependencies/agents/openai.yaml b/.agents/skills/adding-dependencies/agents/openai.yaml
new file mode 100644
index 000000000..41082f7ab
--- /dev/null
+++ b/.agents/skills/adding-dependencies/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: 'Adding Dependencies'
+  short_description: 'Add an npm package through the catalog, after asking'
diff --git a/.agents/skills/odc-done/SKILL.md b/.agents/skills/finishing-changes/SKILL.md
similarity index 51%
rename from .agents/skills/odc-done/SKILL.md
rename to .agents/skills/finishing-changes/SKILL.md
index e89d85915..ced6114ea 100644
--- a/.agents/skills/odc-done/SKILL.md
+++ b/.agents/skills/finishing-changes/SKILL.md
@@ -1,21 +1,29 @@
 ---
-name: odc-done
-description: Close out a change to Open Data Capture before committing, opening a PR, or reporting it done — the checks beyond root AGENTS.md "Before you are done". Use also when asked whether the current uncommitted change is ready to merge; an already-opened PR is review-pr's job.
+name: finishing-changes
+description: Close out a change to Open Data Capture before committing, opening a PR, or reporting it done — run `pnpm check`, then the checks a green run does not prove. Use also when asked whether the current uncommitted change is ready to merge; an already-opened PR is review-pr's job.
 ---
 
-Run root `AGENTS.md` "Before you are done" first; this adds what a green run does not prove. Nothing
-downstream catches a skipped check: `.husky/pre-commit` only formats staged files, and CI runs only on a pull
-request. A check you cannot meet is an **exception**: one line in your reply naming it and why.
+Nothing downstream catches a skipped check: `.husky/pre-commit` only formats staged files, and CI runs only on a
+pull request. A PR with a failing check is never acceptable. A check you cannot meet is an **exception**: one
+line in your reply naming it and why. A failure unrelated to your change is not yours to patch over: file it
+with `.agents/skills/opening-issues/SKILL.md` and name the issue in your reply.
 
-1. **After `pnpm lint`, read `git status`.** `eslint --fix` rewrites as it checks; the rewrites are your own
-   code being sorted, so keep them. TS2345 on a route literal you added is an exception until the user
-   regenerates `route-tree.ts` (`.agents/docs/playbooks/add-web-route.md`); revert any `route-tree.ts` diff.
-2. **Prove vitest collected your tests.** `pnpm exec vitest list --filesOnly` must name every test file the
+1. **Run `pnpm check` from the repo root** and fix every failure, a coverage shortfall included. It runs
+   `pnpm lint`, `pnpm test:coverage` and `pnpm test:e2e` in sequence, so a lint failure hides the rest until it
+   is fixed. `pnpm test:e2e` needs its browsers installed once per machine
+   (`.agents/docs/playbooks/add-e2e-test.md`).
+2. **After it, read `git status`.** `eslint --fix` rewrites as it checks; the rewrites are your own code being
+   sorted, so keep them. TS2345 on a route literal you added is an exception until the user regenerates
+   `route-tree.ts` (`.agents/docs/playbooks/add-web-route.md`); revert any `route-tree.ts` diff. Because that
+   failure stops `pnpm check` at lint, run `pnpm test:coverage` directly and leave `pnpm test:e2e` for after
+   the regeneration.
+3. **Prove vitest collected your tests.** `pnpm exec vitest list --filesOnly` must name every test file the
    change added. A workspace with no `vitest.config.ts` collects nothing and still passes
    (`.agents/docs/playbooks/add-vitest-project.md`).
-3. **Name both tests** — the unit test file and the `testing/src/specs/` file — or the exception for each.
-   `pnpm test:e2e` needs its browsers installed once per machine (`.agents/docs/playbooks/add-e2e-test.md`).
-4. **Finish the second file.** Each row is a pair that must agree, where the second is easy to forget:
+4. **Say what covers the change end to end.** Name the `testing/src/specs/` file that exercises it, or state
+   that it is not important user-facing functionality and needs none. Add a spec only for functionality no
+   existing spec reaches: the suite is kept small on purpose.
+5. **Finish the second file.** Each row is a pair that must agree, where the second is easy to forget:
 
    | You touched                               | What must follow                                                         | Owner                                          |
    | ----------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------- |
@@ -28,10 +36,12 @@ request. A check you cannot meet is an **exception**: one line in your reply nam
    | a request or response shape in `apps/api` | `cli/odc-cli`, which nothing links to the API                            | `cli/AGENTS.md`                                |
    | a new workspace or vitest project         | the tables in `workspace-map.md` and `testing-strategy.md`               | `.agents/skills/odc-agent-docs/SKILL.md`       |
 
-5. **If the diff touches `apps/api`, account for every Prisma query, not a sample**: each `where` names
+6. **If the diff touches `apps/api`, account for every Prisma query, not a sample**: each `where` names
    `accessibleQuery` or your reply says why it is unscoped, and every handler calling a scoped service
    forwards `@CurrentUser('ability')` (`apps/api/AGENTS.md`).
-6. **Fixing a contradicted `AGENTS.md`?** `.agents/skills/odc-agent-docs/SKILL.md` has the house format.
+7. **Re-read the `AGENTS.md` of every package or app you modified** and confirm your change does not
+   contradict it. If it does, revise the change, or propose the smallest `AGENTS.md` edit and wait for the
+   user's approval (root `AGENTS.md` hard rule); `.agents/skills/odc-agent-docs/SKILL.md` has the house format.
 
 **Done when** your reply lists every exception, including any row above you took on trust, or states that
 every check ran green.
diff --git a/.agents/skills/odc-done/agents/openai.yaml b/.agents/skills/finishing-changes/agents/openai.yaml
similarity index 70%
rename from .agents/skills/odc-done/agents/openai.yaml
rename to .agents/skills/finishing-changes/agents/openai.yaml
index 77f89bb06..c29b7eb2d 100644
--- a/.agents/skills/odc-done/agents/openai.yaml
+++ b/.agents/skills/finishing-changes/agents/openai.yaml
@@ -1,3 +1,3 @@
 interface:
-  display_name: 'ODC Done'
+  display_name: 'Finishing Changes'
   short_description: 'Close out a change before committing or opening a PR'
diff --git a/.agents/skills/odc-agent-docs/SKILL.md b/.agents/skills/odc-agent-docs/SKILL.md
index 15f32cae9..167a7f463 100644
--- a/.agents/skills/odc-agent-docs/SKILL.md
+++ b/.agents/skills/odc-agent-docs/SKILL.md
@@ -56,13 +56,13 @@ always loaded.
 
 ## Tables that move together
 
-| You changed                             | These move with it                                                                                                                                |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| a workspace added, renamed or moved     | `workspace-map.md` (section table, Built vs source-only, Published to npm), root `AGENTS.md` "Where to look", the new `AGENTS.md` and its symlink |
-| a vitest project added or removed       | `testing-strategy.md` Vitest projects table, its count and its "no unit tests" list; `workspace-map.md` `Vitest project` column; `## Tests`       |
-| a new playbook                          | root `AGENTS.md` "Step-by-step playbooks"                                                                                                         |
-| a new architecture doc                  | root `AGENTS.md` "Deeper reference, read on demand"                                                                                               |
-| a new `.agents/docs/packages/<name>.md` | `.agents/docs/packages/index.md` (`Docs` link, fidelity table)                                                                                    |
+| You changed                             | These move with it                                                                                                                                       |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| a workspace added, renamed or moved     | `workspace-map.md` (section table, Built vs source-only, Published to npm), `.agents/docs/index.md` "Where to look", the new `AGENTS.md` and its symlink |
+| a vitest project added or removed       | `testing-strategy.md` Vitest projects table, its count and its "no unit tests" list; `workspace-map.md` `Vitest project` column; `## Tests`              |
+| a new playbook                          | `.agents/docs/index.md` "Step-by-step playbooks"                                                                                                         |
+| a new architecture doc                  | `.agents/docs/index.md` "Deeper reference, read on demand"                                                                                               |
+| a new `.agents/docs/packages/<name>.md` | `.agents/docs/packages/index.md` (`Docs` link, fidelity table)                                                                                           |
 
 **Done when** a grep for each fact you wrote finds one statement and any number of pointers, every path you
 cited resolves, every table in the row you triggered is updated, and any `AGENTS.md` your change contradicts
diff --git a/.agents/skills/opening-issues/SKILL.md b/.agents/skills/opening-issues/SKILL.md
index 6759f0b2e..26b146047 100644
--- a/.agents/skills/opening-issues/SKILL.md
+++ b/.agents/skills/opening-issues/SKILL.md
@@ -19,7 +19,7 @@ only labels that already exist.
 | Area       | one or more — where the fix lands            | `Area: API`, `Area: Web`, `Area: Gateway`, `Area: Playground`, `Area: Instruments`, `Area: Shared`, `Area: Outreach`, `Area: Infrastructure` |
 | Flags      | every one that is true                       | `Performance`, `Security`, `Good First Issue`, `Needs Info`, `Needs Decision`, `Upstream`                                                    |
 
-Estimate difficulty against the current code, counting the unit and e2e test every change needs.
+Estimate difficulty against the current code, counting the unit tests that keep coverage at 100%.
 
 ## Create
 
diff --git a/.claude/skills/adding-dependencies b/.claude/skills/adding-dependencies
new file mode 120000
index 000000000..b73255782
--- /dev/null
+++ b/.claude/skills/adding-dependencies
@@ -0,0 +1 @@
+../../.agents/skills/adding-dependencies
\ No newline at end of file
diff --git a/.claude/skills/finishing-changes b/.claude/skills/finishing-changes
new file mode 120000
index 000000000..a17bcd63b
--- /dev/null
+++ b/.claude/skills/finishing-changes
@@ -0,0 +1 @@
+../../.agents/skills/finishing-changes
\ No newline at end of file
diff --git a/.claude/skills/odc-done b/.claude/skills/odc-done
deleted file mode 120000
index 7549974c7..000000000
--- a/.claude/skills/odc-done
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/odc-done
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index d87612c41..5555fee45 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,9 +5,9 @@ It is a pnpm/Turborepo monorepo written in TypeScript: 27 first-party workspaces
 `packages/`, `runtime/`, `storybook/` and `testing/`, plus 38 thin version-pinned wrappers under
 `vendor/` that are also workspaces.
 
-**This file is a router, not a manual.** It holds the rules that apply everywhere plus a map of
-where everything else is documented. Read the `AGENTS.md` for the area you are working in before
-you write code there.
+**This file is a router, not a manual.** It holds the rules that apply everywhere; the map of where
+everything else is documented is @.agents/docs/index.md. Read the `AGENTS.md` for the area you are
+working in before you write code there.
 
 ## Commands
 
@@ -21,8 +21,9 @@ pnpm build                  # turbo build (all packages/apps)
 pnpm lint                   # turbo lint — `tsc && eslint --fix src` per package, plus lint:root for root-level scripts and configs
 pnpm format                 # turbo format (prettier per package)
 pnpm test                   # vitest across the workspace
-pnpm test:coverage          # vitest with coverage — fails below 100%, the gate CI and "Before you are done" run
+pnpm test:coverage          # vitest with coverage — fails below 100%, the gate CI runs
 pnpm test:e2e               # playwright, in testing/
+pnpm check                  # lint, test:coverage and test:e2e in sequence — what "done" means
 ```
 
 Everything after `pnpm generate:env` needs `.env` to exist, and a fresh clone needs more than
@@ -37,112 +38,50 @@ not every tool loads nested files.
 
 - **Ask before writing code if the task is ambiguous** or its stated scope cannot accomplish the
   goal.
-- **No new dependencies without asking in-conversation.** Check `.agents/docs/packages/index.md`
-  first: one of the `@douglasneuroinformatics/*` packages this repo already consumes probably solves
-  it. Versions are pinned in the `catalog:` block of `pnpm-workspace.yaml` — reference `"catalog:"`
-  in a `package.json`, never a literal version. `minimumReleaseAge` is 7 days, so a freshly published
-  package will be rejected.
-- **Every change needs a unit test _and_ an end-to-end test in `testing/`.** See
-  `.agents/docs/playbooks/add-e2e-test.md`. Utility scripts under `scripts/` and the standalone
-  `cli/odc-cli` script, which has no test harness, are the exceptions and need no tests.
+- **A change is not done until `.agents/skills/finishing-changes/SKILL.md` has run green.** It runs
+  `pnpm check` and the checks a green run does not prove.
+- **Adding a dependency follows `.agents/skills/adding-dependencies/SKILL.md`**, which starts with
+  asking in-conversation.
 - **Unit test coverage stays at 100%.** `pnpm test:coverage` fails below 100% statements, branches,
   functions or lines, and CI runs it. Code no test can reach is dead code: prove it dead (the types,
   the callers, the library contract) and delete it. Never widen `coverage.exclude` to get past the
   gate; that list is for non-code — fixtures, generated files and bare entrypoints.
-- **Commit messages follow Conventional Commits.** `type(scope): subject`, where `type` is one of the
-  11 `@commitlint/config-conventional` types and `scope`, if present, is an `@opendatacapture/*`
-  workspace name without the prefix. A `commit-msg` hook and the `Commitlint` CI job enforce it, and
-  `CHANGELOG.md` is generated from the `feat`, `fix`, `perf` and breaking commits: one commit is one
-  entry.
-- **Pull requests and issues go to `DouglasNeuroInformatics/OpenDataCapture`, base `main`.**
-  `origin` is your fork (`CONTRIBUTING.md`), so pass `--repo DouglasNeuroInformatics/OpenDataCapture`
-  to `gh`.
-- **All frontend user-facing strings go through `useTranslation`**, with an entry for every language
-  the frontend exposes. Prefer inline `t({ en: '...', es: '...', fr: '...' })` unless the string is
-  used more than once.
-- **If code needs a comment to be understood, the code is wrong** — rewrite it. Comments are for
-  the non-obvious: a vendor bug, a protocol quirk, a deliberate version pin. Never restate the code.
-- **Make small, incremental, easily reviewable changes.** No sweeping refactors unless asked.
-- **Never silently fail on errors.** Fail loudly on an undeclared policy.
-
-### Before you are done
-
-1. Run `pnpm lint`, `pnpm test:coverage`, and `pnpm test:e2e` from the repo root and fix every
-   failure, a coverage shortfall included.
-2. **Re-read the `AGENTS.md` of every package or app you modified and confirm your change does not
-   contradict it.** If it does, either revise the change or update that `AGENTS.md` in the same
-   commit — never leave the two disagreeing.
-
-`.agents/skills/odc-done/SKILL.md` runs these two plus the checks a green `pnpm lint` does not
-cover.
-
-## Where to look
-
-Read the `AGENTS.md` in the directory you are editing; each covers only that workspace. New here?
-`.agents/docs/playbooks/run-locally.md`, then `.agents/docs/workspace-map.md`.
-
-| Working on                                      | Read first                              |
-| ----------------------------------------------- | --------------------------------------- |
-| Clinician-facing React SPA                      | `apps/web/AGENTS.md`                    |
-| NestJS backend                                  | `apps/api/AGENTS.md`                    |
-| Patient-facing SSR app for remote assignments   | `apps/gateway/AGENTS.md`                |
-| In-browser instrument editor                    | `apps/playground/AGENTS.md`             |
-| Marketing site and user docs                    | `apps/outreach/AGENTS.md`               |
-| Shared Zod schemas / cross-tier contracts       | `packages/schemas/AGENTS.md`            |
-| Compiling instrument source into bundles        | `packages/instrument-bundler/AGENTS.md` |
-| Building the library catalog instruments import | `packages/runtime-bundler/AGENTS.md`    |
-| The `defineInstrument` public API               | `packages/runtime-core/AGENTS.md`       |
-| Adding or editing a built-in instrument         | `packages/instrument-library/AGENTS.md` |
-| Pinned library wrappers instruments import      | `vendor/AGENTS.md`                      |
-| The published runtime artifact                  | `runtime/v1/AGENTS.md`                  |
-| End-to-end tests                                | `testing/AGENTS.md`                     |
-| User documentation                              | `docs/AGENTS.md`                        |
-
-Every other workspace has its own `AGENTS.md` too — check the directory before assuming there
-isn't one.
-
-> **`packages/instrument-guidelines/AGENTS.md` is not this repo's conventions.** Its bin installs it
-> into _external_ instrument repositories as their `AGENTS.md`, so it is the specification for
-> authoring an instrument and a published npm package: treat a change there as a release, and keep
-> Open Data Capture repo rules out of it.
-
-### Deeper reference, read on demand
-
-| Topic                                                           | Path                                                |
-| --------------------------------------------------------------- | --------------------------------------------------- |
-| Which workspace depends on which, what is built, what publishes | `.agents/docs/workspace-map.md`                     |
-| The 11 `@douglasneuroinformatics/*` packages this repo consumes | `.agents/docs/packages/index.md`                    |
-| Instrument source → bundle → store → interpret → render         | `.agents/docs/architecture/instrument-pipeline.md`  |
-| The six similarly-named `runtime-*` things, and `vendor/`       | `.agents/docs/architecture/runtime-and-vendor.md`   |
-| CASL, `@RouteAccess`, and group scoping                         | `.agents/docs/architecture/auth-and-permissions.md` |
-| What is tested where, and what CI gates                         | `.agents/docs/architecture/testing-strategy.md`     |
-
-### Step-by-step playbooks
-
-Follow these in full. Each covers a task where **skipping a step compiles cleanly and fails at
-runtime**.
-
-| Task                                   | Playbook                                          |
-| -------------------------------------- | ------------------------------------------------- |
-| Add an API endpoint                    | `.agents/docs/playbooks/add-api-endpoint.md`      |
-| Add a route to `apps/web`              | `.agents/docs/playbooks/add-web-route.md`         |
-| Add a data-fetching hook to `apps/web` | `.agents/docs/playbooks/add-web-data-hook.md`     |
-| Add an end-to-end test                 | `.agents/docs/playbooks/add-e2e-test.md`          |
-| Add a built-in instrument              | `.agents/docs/playbooks/add-instrument.md`        |
-| Add a vendored library for instruments | `.agents/docs/playbooks/add-vendor-package.md`    |
-| Add an environment variable            | `.agents/docs/playbooks/add-env-var.md`           |
-| Add a blog post                        | `.agents/docs/playbooks/add-blog-post.md`         |
-| Run the stack on a fresh clone         | `.agents/docs/playbooks/run-locally.md`           |
-| Cut a release                          | `.agents/docs/playbooks/cut-a-release.md`         |
-| Add a vitest project to a package      | `.agents/docs/playbooks/add-vitest-project.md`    |
-| Promote a component to react-core      | `.agents/docs/playbooks/promote-to-react-core.md` |
+- **All frontend user-facing strings go through `useTranslation`.** Prefer inline
+  `t({ en: '...', es: '...', fr: '...' })` unless the string is used more than once.
+- **Never edit an `AGENTS.md` without the user's express approval**, and keep any proposed edit as
+  minimal as possible.
 
-## Conventions
+## Commits and pull requests
+
+Commit messages follow Conventional Commits: `type(scope): subject`, where `type` is one of the 11
+`@commitlint/config-conventional` types and `scope`, if present, is an `@opendatacapture/*`
+workspace name without the prefix. A `commit-msg` hook and the `Commitlint` CI job enforce it, and
+`CHANGELOG.md` is generated from the `feat`, `fix`, `perf` and breaking commits: one commit is one
+entry.
+
+Pull requests and issues go to `DouglasNeuroInformatics/OpenDataCapture`, base `main`.
+
+## Coding Guidelines
+
+**Principles**
+
+- Correctness is structural, not vigilant. A correct system is one where the invalid state cannot be written, not one where a careful person catches it. Anything a human must remember, the compiler should remember instead.
+- One source of truth; everything derived. Two artifacts that must agree is a bug waiting for its trigger.
+- Strict data validation at the boundary, trusting inside. Data is distrusted exactly once, at the perimeter, then the interior runs clean, with no defensive re-checking cluttering the logic. The perimeter is where data arrives from outside the system's control: a request, the environment, a third-party response. What the system wrote, such as a JSON column, is inside.
+- A declaration's name and type carry its meaning. When you reach for a doc comment to say what something is, returns or contains, use a more descriptive name instead. A comment explaining what code does usually means the code should be clearer. Save comments for what code can't say: facts about the outside world (a vendor bug, a protocol quirk) and navigation aids (e.g., section banners in long declaration files).
+- Complexity concentrated, periphery boring. Sophistication lives in a small framework core so that ordinary code stays trivial, short, and fully inferred. Clever call sites mean the cleverness is in the wrong place.
+- Never silently fail on errors. Fail loudly on an undeclared policy.
 
-- **Strict validation at the boundary, trust inside.** Data is distrusted exactly once — at the
-  perimeter — then the interior runs clean, with no defensive re-checking cluttering the logic.
-- **One source of truth; everything derived.** A contract exists once; types, variants and fixtures
-  flow from it. Two artifacts that must agree is a bug waiting for its trigger.
+**Style**
+
+- A name says what the thing is. A request's parameters are not its result, a container is not its content, and raw input is not parsed data. When a name is another name plus a word, that word says how the two differ.
+- Name a database model or entity type as a domain noun: a thing a user would recognize, not a process.
+- Prefer one general function or component to several near-duplicates. Delete code that exists only to keep variants alike.
+- Match existing code of the same role. New code takes the naming, parameters and shape of the code that already does the same kind of job.
+
+_Break any of these guidelines sooner than write anything outright barbarous._
+
+## Conventions
 
 Define Zod schemas for data validation; derive types via `z.infer`. Convention: `$`-prefixed schema,
 same-named inferred type, type declared first:
@@ -155,13 +94,13 @@ export const $Entity = z.object({ ... });
 Variants are composed from a base shape, never written from scratch. Schemas exist only for data
 actually parsed at a perimeter; everything else is a plain type. See `packages/schemas/AGENTS.md`.
 
-**Types.** Strict mode; no casting at call sites. No loose records where a closed key set is known;
-if only a subset of keys is known, type those and add an index signature.
+**Types.**
+
+Strict mode; no casting at call sites. No loose records where a closed key set is known. If only a subset of keys is known, type those keys and add an index signature. Type safety takes precedence over convenience.
+
+Outside call sites, an assertion the lint flags (`as`, `!`) is allowed only when the fact holds for every input the exported signature admits, so no test could reach a guard for it; when the proof is code in the same function, a documented contract of the language, platform or a library, or a brand on the value's type applied where the fact is checked; and when no rewrite of similar size would remove it (e.g., having the function that produces the value return a discriminated union). Name the proof in the lint-disable reason. When the proof is a brand, a spec beside the assertion checks that the code applying it rejects the case the assertion excludes.
 
-**Formatting is not your problem.** `pnpm lint` runs `eslint --fix` and prettier, so write code in a
-sensible order and let the tooling sort objects and move exports. Where ordering is load-bearing,
-the existing code carries an `eslint-disable` comment with its reason after `--`; follow that pattern
-rather than fighting the rule.
+Advanced type-level constructs (e.g., conditional types, template literal types, inference extraction, mapped types) are a routine tool.
 
 **Tests.** A unit test is `<file>.test.ts(x)` in a `__tests__/` folder beside the file it tests, or
 in a package's `test/` folder when it drives the whole package; eslint enforces the layout
diff --git a/package.json b/package.json
index a6e93e3b1..3bf6e5206 100644
--- a/package.json
+++ b/package.json
@@ -10,6 +10,7 @@
   },
   "scripts": {
     "build": "env-cmd turbo run build",
+    "check": "pnpm lint && pnpm test:coverage && pnpm test:e2e",
     "clean": "find . -type d '(' -name '.turbo' -o -name 'dist' -o -name 'node_modules' ')' -prune -exec rm -rf {} \\;",
     "clean:workflows": "./scripts/clean-workflows.sh",
     "db:generate": "turbo run db:generate",

From 0eb6932c128348dd294bfc66d86511afeb04bcc2 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 18:05:42 -0500
Subject: [PATCH 5/9] chore: rename the odc-agent-docs and odc-debugging skills

writing-agent-docs and troubleshooting follow the gerund names of the other skills, with the
directories, .claude/skills symlinks, display names and cross-references updated to match.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .agents/skills/finishing-changes/SKILL.md                     | 4 ++--
 .agents/skills/{odc-debugging => troubleshooting}/SKILL.md    | 4 ++--
 .../{odc-debugging => troubleshooting}/agents/openai.yaml     | 2 +-
 .../skills/{odc-agent-docs => writing-agent-docs}/SKILL.md    | 2 +-
 .../{odc-agent-docs => writing-agent-docs}/agents/openai.yaml | 2 +-
 .claude/skills/odc-agent-docs                                 | 1 -
 .claude/skills/odc-debugging                                  | 1 -
 .claude/skills/troubleshooting                                | 1 +
 .claude/skills/writing-agent-docs                             | 1 +
 9 files changed, 9 insertions(+), 9 deletions(-)
 rename .agents/skills/{odc-debugging => troubleshooting}/SKILL.md (98%)
 rename .agents/skills/{odc-debugging => troubleshooting}/agents/openai.yaml (73%)
 rename .agents/skills/{odc-agent-docs => writing-agent-docs}/SKILL.md (99%)
 rename .agents/skills/{odc-agent-docs => writing-agent-docs}/agents/openai.yaml (69%)
 delete mode 120000 .claude/skills/odc-agent-docs
 delete mode 120000 .claude/skills/odc-debugging
 create mode 120000 .claude/skills/troubleshooting
 create mode 120000 .claude/skills/writing-agent-docs

diff --git a/.agents/skills/finishing-changes/SKILL.md b/.agents/skills/finishing-changes/SKILL.md
index ced6114ea..99db40226 100644
--- a/.agents/skills/finishing-changes/SKILL.md
+++ b/.agents/skills/finishing-changes/SKILL.md
@@ -34,14 +34,14 @@ with `.agents/skills/opening-issues/SKILL.md` and name the issue in your reply.
    | an environment variable                   | the rest of the chain, in the playbook's order                           | `.agents/docs/playbooks/add-env-var.md`        |
    | a `packages/react-core` component         | `src/index.ts` — the barrel is the public API, there are no deep imports | `packages/react-core/AGENTS.md`                |
    | a request or response shape in `apps/api` | `cli/odc-cli`, which nothing links to the API                            | `cli/AGENTS.md`                                |
-   | a new workspace or vitest project         | the tables in `workspace-map.md` and `testing-strategy.md`               | `.agents/skills/odc-agent-docs/SKILL.md`       |
+   | a new workspace or vitest project         | the tables in `workspace-map.md` and `testing-strategy.md`               | `.agents/skills/writing-agent-docs/SKILL.md`   |
 
 6. **If the diff touches `apps/api`, account for every Prisma query, not a sample**: each `where` names
    `accessibleQuery` or your reply says why it is unscoped, and every handler calling a scoped service
    forwards `@CurrentUser('ability')` (`apps/api/AGENTS.md`).
 7. **Re-read the `AGENTS.md` of every package or app you modified** and confirm your change does not
    contradict it. If it does, revise the change, or propose the smallest `AGENTS.md` edit and wait for the
-   user's approval (root `AGENTS.md` hard rule); `.agents/skills/odc-agent-docs/SKILL.md` has the house format.
+   user's approval (root `AGENTS.md` hard rule); `.agents/skills/writing-agent-docs/SKILL.md` has the house format.
 
 **Done when** your reply lists every exception, including any row above you took on trust, or states that
 every check ran green.
diff --git a/.agents/skills/odc-debugging/SKILL.md b/.agents/skills/troubleshooting/SKILL.md
similarity index 98%
rename from .agents/skills/odc-debugging/SKILL.md
rename to .agents/skills/troubleshooting/SKILL.md
index c32101bdb..3e25f5d25 100644
--- a/.agents/skills/odc-debugging/SKILL.md
+++ b/.agents/skills/troubleshooting/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: odc-debugging
+name: troubleshooting
 description: Symptom index for what actually breaks in Open Data Capture — a failing build, lint, unit test or e2e run; a change with no visible effect; a suite that stays green after you broke the code on purpose; an error naming runtime/v1, btoa, turbo or .env. Each row names the doc that owns the fix.
 ---
 
@@ -48,5 +48,5 @@ The last row is usually the database: `NODE_ENV=test` gives the API an in-memory
 `testing/src/global/setup.spec.ts`, while development uses a real Mongo that nothing resets, and JWT expiry is
 ignored in development.
 
-When no row matches and you find the cause, land the missing fact where `.agents/skills/odc-agent-docs/SKILL.md`
+When no row matches and you find the cause, land the missing fact where `.agents/skills/writing-agent-docs/SKILL.md`
 says it belongs — this table is a candidate.
diff --git a/.agents/skills/odc-debugging/agents/openai.yaml b/.agents/skills/troubleshooting/agents/openai.yaml
similarity index 73%
rename from .agents/skills/odc-debugging/agents/openai.yaml
rename to .agents/skills/troubleshooting/agents/openai.yaml
index 540584978..1c20d43b7 100644
--- a/.agents/skills/odc-debugging/agents/openai.yaml
+++ b/.agents/skills/troubleshooting/agents/openai.yaml
@@ -1,3 +1,3 @@
 interface:
-  display_name: 'ODC Debugging'
+  display_name: 'Troubleshooting'
   short_description: 'What actually breaks in Open Data Capture, keyed by symptom'
diff --git a/.agents/skills/odc-agent-docs/SKILL.md b/.agents/skills/writing-agent-docs/SKILL.md
similarity index 99%
rename from .agents/skills/odc-agent-docs/SKILL.md
rename to .agents/skills/writing-agent-docs/SKILL.md
index 167a7f463..33287eba9 100644
--- a/.agents/skills/odc-agent-docs/SKILL.md
+++ b/.agents/skills/writing-agent-docs/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: odc-agent-docs
+name: writing-agent-docs
 description: Write or correct this repo's agent documentation — a workspace AGENTS.md (or its CLAUDE.md symlink), a playbook under .agents/docs/playbooks, an architecture doc, the workspace map, or a skill. Use when a documented rule is wrong or missing, when a change contradicts an AGENTS.md, or when another skill needs the house format for these files. Architectural decisions land in .agents/docs/architecture; there is no ADR flow.
 ---
 
diff --git a/.agents/skills/odc-agent-docs/agents/openai.yaml b/.agents/skills/writing-agent-docs/agents/openai.yaml
similarity index 69%
rename from .agents/skills/odc-agent-docs/agents/openai.yaml
rename to .agents/skills/writing-agent-docs/agents/openai.yaml
index ab2468aa0..40887d469 100644
--- a/.agents/skills/odc-agent-docs/agents/openai.yaml
+++ b/.agents/skills/writing-agent-docs/agents/openai.yaml
@@ -1,3 +1,3 @@
 interface:
-  display_name: 'ODC Agent Docs'
+  display_name: 'Writing Agent Docs'
   short_description: 'Where a repo fact belongs, and the house doc format'
diff --git a/.claude/skills/odc-agent-docs b/.claude/skills/odc-agent-docs
deleted file mode 120000
index 73e679a1a..000000000
--- a/.claude/skills/odc-agent-docs
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/odc-agent-docs
\ No newline at end of file
diff --git a/.claude/skills/odc-debugging b/.claude/skills/odc-debugging
deleted file mode 120000
index b24bd45ac..000000000
--- a/.claude/skills/odc-debugging
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/odc-debugging
\ No newline at end of file
diff --git a/.claude/skills/troubleshooting b/.claude/skills/troubleshooting
new file mode 120000
index 000000000..96a5a0175
--- /dev/null
+++ b/.claude/skills/troubleshooting
@@ -0,0 +1 @@
+../../.agents/skills/troubleshooting
\ No newline at end of file
diff --git a/.claude/skills/writing-agent-docs b/.claude/skills/writing-agent-docs
new file mode 120000
index 000000000..a0770d0a9
--- /dev/null
+++ b/.claude/skills/writing-agent-docs
@@ -0,0 +1 @@
+../../.agents/skills/writing-agent-docs
\ No newline at end of file

From 2fcd691f640a207741eff011954c6e6de3f7425b Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 18:16:03 -0500
Subject: [PATCH 6/9] chore: split coding guidelines

---
 .agents/docs/coding-guidelines.md | 17 +++++++++++++++++
 AGENTS.md                         | 20 ++------------------
 2 files changed, 19 insertions(+), 18 deletions(-)
 create mode 100644 .agents/docs/coding-guidelines.md

diff --git a/.agents/docs/coding-guidelines.md b/.agents/docs/coding-guidelines.md
new file mode 100644
index 000000000..6438bc9c3
--- /dev/null
+++ b/.agents/docs/coding-guidelines.md
@@ -0,0 +1,17 @@
+**Principles**
+
+- Correctness is structural, not vigilant. A correct system is one where the invalid state cannot be written, not one where a careful person catches it. Anything a human must remember, the compiler should remember instead.
+- One source of truth; everything derived. Two artifacts that must agree is a bug waiting for its trigger.
+- Strict data validation at the boundary, trusting inside. Data is distrusted exactly once, at the perimeter, then the interior runs clean, with no defensive re-checking cluttering the logic. The perimeter is where data arrives from outside the system's control: a request, the environment, a third-party response. What the system wrote, such as a JSON column, is inside.
+- A declaration's name and type carry its meaning. When you reach for a doc comment to say what something is, returns or contains, use a more descriptive name instead. A comment explaining what code does usually means the code should be clearer. Save comments for what code can't say: facts about the outside world (a vendor bug, a protocol quirk) and navigation aids (e.g., section banners in long declaration files).
+- Complexity concentrated, periphery boring. Sophistication lives in a small framework core so that ordinary code stays trivial, short, and fully inferred. Clever call sites mean the cleverness is in the wrong place.
+- Never silently fail on errors. Fail loudly on an undeclared policy.
+
+**Style**
+
+- A name says what the thing is. A request's parameters are not its result, a container is not its content, and raw input is not parsed data. When a name is another name plus a word, that word says how the two differ.
+- Name a database model or entity type as a domain noun: a thing a user would recognize, not a process.
+- Prefer one general function or component to several near-duplicates. Delete code that exists only to keep variants alike.
+- Match existing code of the same role. New code takes the naming, parameters and shape of the code that already does the same kind of job.
+
+_Break any of these guidelines sooner than write anything outright barbarous._
diff --git a/AGENTS.md b/AGENTS.md
index 5555fee45..6b25dfd65 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,7 @@ It is a pnpm/Turborepo monorepo written in TypeScript: 27 first-party workspaces
 `vendor/` that are also workspaces.
 
 **This file is a router, not a manual.** It holds the rules that apply everywhere; the map of where
-everything else is documented is @.agents/docs/index.md. Read the `AGENTS.md` for the area you are
+everything else is documented is .agents/docs/index.md. Read the `AGENTS.md` for the area you are
 working in before you write code there.
 
 ## Commands
@@ -63,23 +63,7 @@ Pull requests and issues go to `DouglasNeuroInformatics/OpenDataCapture`, base `
 
 ## Coding Guidelines
 
-**Principles**
-
-- Correctness is structural, not vigilant. A correct system is one where the invalid state cannot be written, not one where a careful person catches it. Anything a human must remember, the compiler should remember instead.
-- One source of truth; everything derived. Two artifacts that must agree is a bug waiting for its trigger.
-- Strict data validation at the boundary, trusting inside. Data is distrusted exactly once, at the perimeter, then the interior runs clean, with no defensive re-checking cluttering the logic. The perimeter is where data arrives from outside the system's control: a request, the environment, a third-party response. What the system wrote, such as a JSON column, is inside.
-- A declaration's name and type carry its meaning. When you reach for a doc comment to say what something is, returns or contains, use a more descriptive name instead. A comment explaining what code does usually means the code should be clearer. Save comments for what code can't say: facts about the outside world (a vendor bug, a protocol quirk) and navigation aids (e.g., section banners in long declaration files).
-- Complexity concentrated, periphery boring. Sophistication lives in a small framework core so that ordinary code stays trivial, short, and fully inferred. Clever call sites mean the cleverness is in the wrong place.
-- Never silently fail on errors. Fail loudly on an undeclared policy.
-
-**Style**
-
-- A name says what the thing is. A request's parameters are not its result, a container is not its content, and raw input is not parsed data. When a name is another name plus a word, that word says how the two differ.
-- Name a database model or entity type as a domain noun: a thing a user would recognize, not a process.
-- Prefer one general function or component to several near-duplicates. Delete code that exists only to keep variants alike.
-- Match existing code of the same role. New code takes the naming, parameters and shape of the code that already does the same kind of job.
-
-_Break any of these guidelines sooner than write anything outright barbarous._
+@.agents/docs/coding-guidelines.md
 
 ## Conventions
 

From a1935c7d8e611d91daf47e6d38b9a96aa481bc65 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 18:19:34 -0500
Subject: [PATCH 7/9] chore: set disable-model-invocation true for review-pr

---
 .agents/skills/review-pr/SKILL.md           | 1 +
 .agents/skills/review-pr/agents/openai.yaml | 3 ---
 .claude/skills/adversarial-review           | 1 +
 3 files changed, 2 insertions(+), 3 deletions(-)
 delete mode 100644 .agents/skills/review-pr/agents/openai.yaml
 create mode 120000 .claude/skills/adversarial-review

diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.md
index 657ad6cc2..ebeae0b90 100644
--- a/.agents/skills/review-pr/SKILL.md
+++ b/.agents/skills/review-pr/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: review-pr
 description: Triage pull requests against upstream main — one verdict, action items, and whether it needs the user's eyes. Use when the user asks to review a PR by number, review all the open PRs, or asks whether a PR is worth their time.
+disable-model-invocation: true
 ---
 
 Triage PRs so the user opens only the ones that need them. The run completes unattended: everything for
diff --git a/.agents/skills/review-pr/agents/openai.yaml b/.agents/skills/review-pr/agents/openai.yaml
deleted file mode 100644
index 578386034..000000000
--- a/.agents/skills/review-pr/agents/openai.yaml
+++ /dev/null
@@ -1,3 +0,0 @@
-interface:
-  display_name: 'Review PR'
-  short_description: 'Triage open pull requests and say which need you'
diff --git a/.claude/skills/adversarial-review b/.claude/skills/adversarial-review
new file mode 120000
index 000000000..c714f2c3e
--- /dev/null
+++ b/.claude/skills/adversarial-review
@@ -0,0 +1 @@
+../../.agents/skills/adversarial-review
\ No newline at end of file

From 0546bbc7e9241aa0f67cadeaeac8d39bac5bb5b4 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 18:23:23 -0500
Subject: [PATCH 8/9] chore: add adversarial-review

---
 .agents/skills/adversarial-review/SKILL.md    | 46 +++++++++++++++++++
 .../adversarial-review/agents/openai.yaml     |  3 ++
 .../adversarial-review/references/defence.md  | 13 ++++++
 .../references/prosecutor.md                  | 30 ++++++++++++
 4 files changed, 92 insertions(+)
 create mode 100644 .agents/skills/adversarial-review/SKILL.md
 create mode 100644 .agents/skills/adversarial-review/agents/openai.yaml
 create mode 100644 .agents/skills/adversarial-review/references/defence.md
 create mode 100644 .agents/skills/adversarial-review/references/prosecutor.md

diff --git a/.agents/skills/adversarial-review/SKILL.md b/.agents/skills/adversarial-review/SKILL.md
new file mode 100644
index 000000000..0a85af7b7
--- /dev/null
+++ b/.agents/skills/adversarial-review/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: adversarial-review
+description: Review the current branch against upstream main before a pull request is opened, or before a follow-up that adds code is pushed to one — a prosecutor sub-agent finds defects, a defence sub-agent tries to refute each, and only confirmed findings come back to the caller. Runs only after `pnpm check` is green; changes no code.
+---
+
+Two `general-purpose` sub-agents in sequence: the prosecutor finds, the defence refutes, and the caller sees
+only what survives, because the caller acts on every line it is given and has no human to filter for it.
+`pnpm check` has already passed when this runs, so neither agent runs lint, tsc or a test, and anything those
+would report is not a finding.
+
+## 1. Select the diff
+
+```sh
+git fetch upstream main
+BASE=$(git merge-base upstream/main HEAD)
+git diff --name-only --diff-filter=d "$BASE"
+git ls-files --others --exclude-standard
+```
+
+`origin` is the fork (`CONTRIBUTING.md`), so a base taken from it reviews against a stale main and misses
+what upstream has changed underneath. A clone without the `upstream` remote adds it first:
+`git remote add upstream https://github.com/DouglasNeuroInformatics/OpenDataCapture.git`.
+Keep only `.ts`, `.tsx`, `.js`, `.jsx`, `.css` and `.prisma` files, and drop `apps/web/src/route-tree.ts`,
+`testing/src/generated/` and `*.stories.*`. An empty list ends the review: reply `CLEAN`.
+
+## 2. Prosecute
+
+Spawn one sub-agent:
+
+> Follow `.agents/skills/adversarial-review/references/prosecutor.md`. Base: `<BASE>`. Files: `<the list>`.
+
+## 3. Defend
+
+When the prosecutor returned anything but `NONE`, spawn one sub-agent with its output verbatim:
+
+> Follow `.agents/skills/adversarial-review/references/defence.md`. Base: `<BASE>`. Findings: `<the output>`.
+
+## 4. Report
+
+Reply with the `CONFIRMED` findings only, worst first, one line each, and nothing else:
+
+```
+<path>:<line> — <claim> — <fix>
+```
+
+`CLEAN` when nothing survived. A refuted finding is not mentioned.
diff --git a/.agents/skills/adversarial-review/agents/openai.yaml b/.agents/skills/adversarial-review/agents/openai.yaml
new file mode 100644
index 000000000..b3ba73e17
--- /dev/null
+++ b/.agents/skills/adversarial-review/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: 'Adversarial Review'
+  short_description: 'Prosecute and defend a branch against upstream main before a PR'
diff --git a/.agents/skills/adversarial-review/references/defence.md b/.agents/skills/adversarial-review/references/defence.md
new file mode 100644
index 000000000..538281dfb
--- /dev/null
+++ b/.agents/skills/adversarial-review/references/defence.md
@@ -0,0 +1,13 @@
+# Defence
+
+You try to refute each finding. Read root `AGENTS.md` and `.agents/docs/coding-guidelines.md`. For each
+finding, read the cited location in full, trace the callers or data flow its evidence names, and look for
+what the prosecutor missed: a guard upstream, a type that excludes the case, a test that would fail if the defect were real,
+a rule quoted out of context. Run nothing that writes, and not lint, tsc or any test.
+
+A finding is `REFUTED` only by evidence you cite; one you merely doubt is `CONFIRMED`. Return one line per
+finding, keeping its number, and nothing else:
+
+```
+<n>. CONFIRMED | REFUTED — <one sentence: what you traced and what it showed>
+```
diff --git a/.agents/skills/adversarial-review/references/prosecutor.md b/.agents/skills/adversarial-review/references/prosecutor.md
new file mode 100644
index 000000000..19918916c
--- /dev/null
+++ b/.agents/skills/adversarial-review/references/prosecutor.md
@@ -0,0 +1,30 @@
+# Prosecutor
+
+You review the change on the current branch. Read root `AGENTS.md`, `.agents/docs/coding-guidelines.md`, the
+`AGENTS.md` of every workspace a listed file sits in, and `.agents/docs/architecture/auth-and-permissions.md`
+when a listed file is under `apps/api/`. Read every listed file in full, then `git diff <base> -- <files>`;
+an untracked file is new in full. Read callers and the rest of a module when a claim depends on them. Run
+nothing that writes, and not lint, tsc or any test: the caller has already run `pnpm check` green.
+
+Findings concern changed code and code the change makes wrong, wherever that code is. Look for, worst
+first:
+
+- Data crossing a group boundary: a Prisma `where` without `accessibleQuery`, or a handler that forwards
+  neither `@CurrentUser('ability')` nor, to a service taking `RequestUser`, `@CurrentUser()`.
+- Access wrongly granted, or no check for the action taken.
+- Data lost, corrupted or silently dropped: a logic error, an unhandled state, a race, a swallowed error.
+- Data from outside the system — a request, the environment, a third-party response — used before a Zod
+  schema parses it.
+- A test that would still pass if the code under it were wrong.
+- A breach of a rule in the files you read, with the rule quoted.
+- Complexity its purpose does not justify: a helper with one caller, an abstraction with one user, pure
+  indirection, a near-duplicate, a defensive check on data the system wrote, a step that changes nothing.
+
+Before returning, re-read each location and check every quote word for word; drop what does not hold. Return
+`NONE`, or one finding per paragraph:
+
+```
+<n>. <path>:<line> — <claim in one sentence>
+Evidence: <what the code does and the callers or data flow the claim rests on; the quoted rule when one applies>
+Fix: <the change to make>
+```

From 3697377df526339e5be965d48077c5873d183fe9 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Mon, 9 Nov 2026 18:45:30 -0500
Subject: [PATCH 9/9] ci: gate pull requests on an adversarial review and a
 fixed body

Three skills carry the process: adversarial-review runs a prosecutor and a defence sub-agent
over the branch against upstream main and returns only confirmed findings; opening-pr writes
the body a reviewer can read in seconds, with the review block and what was fixed or declined;
finishing-changes links them in order. The pr-body workflow checks every body and closes a PR
whose block is missing, stale, or drops a finding, or that carries a Verification or Notes
section.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .agents/skills/adversarial-review/SKILL.md   |   5 +-
 .agents/skills/finishing-changes/SKILL.md    |   5 +
 .agents/skills/opening-pr/SKILL.md           |  96 ++++++++++++
 .agents/skills/opening-pr/agents/openai.yaml |   3 +
 .claude/skills/opening-pr                    |   1 +
 .github/workflows/pr-body.yaml               |  32 ++++
 scripts/check-pr-body.ts                     | 157 +++++++++++++++++++
 7 files changed, 297 insertions(+), 2 deletions(-)
 create mode 100644 .agents/skills/opening-pr/SKILL.md
 create mode 100644 .agents/skills/opening-pr/agents/openai.yaml
 create mode 120000 .claude/skills/opening-pr
 create mode 100644 .github/workflows/pr-body.yaml
 create mode 100644 scripts/check-pr-body.ts

diff --git a/.agents/skills/adversarial-review/SKILL.md b/.agents/skills/adversarial-review/SKILL.md
index 0a85af7b7..4f21a1c85 100644
--- a/.agents/skills/adversarial-review/SKILL.md
+++ b/.agents/skills/adversarial-review/SKILL.md
@@ -37,10 +37,11 @@ When the prosecutor returned anything but `NONE`, spawn one sub-agent with its o
 
 ## 4. Report
 
-Reply with the `CONFIRMED` findings only, worst first, one line each, and nothing else:
+Reply with the `CONFIRMED` findings only, worst first, one line each under the prosecutor's number, and
+nothing else:
 
 ```
-<path>:<line> — <claim> — <fix>
+<n>. <path>:<line> — <claim> — <fix>
 ```
 
 `CLEAN` when nothing survived. A refuted finding is not mentioned.
diff --git a/.agents/skills/finishing-changes/SKILL.md b/.agents/skills/finishing-changes/SKILL.md
index 99db40226..922d023cf 100644
--- a/.agents/skills/finishing-changes/SKILL.md
+++ b/.agents/skills/finishing-changes/SKILL.md
@@ -42,6 +42,11 @@ with `.agents/skills/opening-issues/SKILL.md` and name the issue in your reply.
 7. **Re-read the `AGENTS.md` of every package or app you modified** and confirm your change does not
    contradict it. If it does, revise the change, or propose the smallest `AGENTS.md` edit and wait for the
    user's approval (root `AGENTS.md` hard rule); `.agents/skills/writing-agent-docs/SKILL.md` has the house format.
+8. **Before opening a PR, or pushing a follow-up that adds code to one, run
+   `.agents/skills/adversarial-review/SKILL.md`** on the green branch. Fix, or decline with a reason, every confirmed finding,
+   then repeat from step 1; review again only when the fixes added code beyond what the findings named.
+   Then open or update the PR with `.agents/skills/opening-pr/SKILL.md`, which carries the review's
+   result.
 
 **Done when** your reply lists every exception, including any row above you took on trust, or states that
 every check ran green.
diff --git a/.agents/skills/opening-pr/SKILL.md b/.agents/skills/opening-pr/SKILL.md
new file mode 100644
index 000000000..29dbfba22
--- /dev/null
+++ b/.agents/skills/opening-pr/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: opening-pr
+description: Open a pull request against DouglasNeuroInformatics/OpenDataCapture, or push a follow-up to one — the body a reviewer reads in seconds, and the adversarial-review block without which `.github/workflows/pr-body.yaml` closes the PR. Use whenever a change is ready for a PR; it refuses a branch whose `pnpm check` is not green or whose review has not run on the current head.
+---
+
+The reviewer reads dozens of these a week. The body says what changed in effect terms and what they might
+disagree with, and nothing a green CI run already proves. `.github/workflows/pr-body.yaml` reads the body on
+every open, edit and push, and closes the PR when the review block is missing, names a commit other than the
+head, drops a finding, or when a forbidden section is present.
+
+## Preconditions
+
+`pnpm check` is green on the branch, and `.agents/skills/adversarial-review/SKILL.md` has run on the
+branch's content, or on content that differs from it only by fixes to the review's own findings, with every
+confirmed finding fixed or declined (`.agents/skills/finishing-changes/SKILL.md` is the order). The stamp
+names the head you push, since the review reads the working tree and the commit comes after. Either missing: stop, open nothing, and say which. There is no exception path; a check that cannot
+pass is reported to the user, never written into a body.
+
+## Body
+
+Write the body to a file and pass it with `--body-file`:
+
+```markdown
+<What a user or operator gets that they did not have before. Closes #N when it closes an issue.>
+
+## Changes
+
+- <one behaviour, in effect terms>
+
+## Decisions
+
+- <a choice a reviewer could reasonably disagree with: the choice, the alternative, and why>
+
+## Risks
+
+- <what could go wrong for an existing deployment, and how it is mitigated or that it is accepted>
+
+Filed: #N, #M
+
+## Adversarial review
+
+Reviewed at commit <full head sha>. pnpm check: green.
+
+### Findings
+
+<the review's reply verbatim: CLEAN, or its numbered lines>
+
+### Fixed
+
+- <n>. <how, in a phrase>
+
+### Declined
+
+- <n>. <what the prosecutor missed, in code terms: a guard upstream, a type that excludes the case, a rule
+  quoted out of context>
+```
+
+- **The opening paragraph is a ceiling, not a floor.** A one-line change gets one or two sentences; one
+  sentence of context is the minimum for anything.
+- **Changes lists every behaviour a reviewer must know, however many.** A migration, an environment variable
+  or a config change is always one. Effect terms: what now happens, not which file or function changed; the
+  diff shows files. Length scales with the diff, and nothing is there for length.
+- **Decisions, Risks and `Filed:` are omitted when empty.** With `CLEAN`, so are Fixed and Declined.
+- **No Verification, Validation, Notes or Implementation notes section**; the workflow refuses them.
+  `pnpm check: green` is the only verification statement. Test names, pass counts and what was not run belong
+  nowhere. An observation that is not a Change, a Decision or a Risk is an issue
+  (`.agents/skills/opening-issues/SKILL.md`), linked under `Filed:`, or deleted.
+- **Every number under Findings appears under exactly one of Fixed or Declined.** A decline reading "out of
+  scope" or "pre-existing" carries the issue number it was filed under.
+
+## Open
+
+```sh
+git push -u origin HEAD
+gh pr create --repo DouglasNeuroInformatics/OpenDataCapture --base main --title "<type(scope): subject>" --body-file <path>
+```
+
+The title follows the commit convention in root `AGENTS.md`; `origin` is the fork, so `gh` infers the head.
+
+## Follow-up pushes
+
+A push moves the head, so the stamp goes stale and the workflow closes the PR on the push unless the body
+already names the new head. Commit, read `git rev-parse HEAD`, edit the body, and only then push. When the
+follow-up adds code, re-run the review and rewrite the block for the new head. When it only addresses
+findings, add this as its own line directly after the `Reviewed at commit` line:
+
+```
+Follow-up <full new head sha>: addresses findings <n, m>; no new code.
+```
+
+```sh
+gh pr edit <number> --repo DouglasNeuroInformatics/OpenDataCapture --body-file <path>
+git push
+```
+
+A PR the workflow closed is reopened with `gh pr reopen <number>` once the body is fixed.
diff --git a/.agents/skills/opening-pr/agents/openai.yaml b/.agents/skills/opening-pr/agents/openai.yaml
new file mode 100644
index 000000000..c70aa2a39
--- /dev/null
+++ b/.agents/skills/opening-pr/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: 'Opening PR'
+  short_description: 'Open or update a pull request with the body the reviewer needs'
diff --git a/.claude/skills/opening-pr b/.claude/skills/opening-pr
new file mode 120000
index 000000000..dce8aac92
--- /dev/null
+++ b/.claude/skills/opening-pr
@@ -0,0 +1 @@
+../../.agents/skills/opening-pr
\ No newline at end of file
diff --git a/.github/workflows/pr-body.yaml b/.github/workflows/pr-body.yaml
new file mode 100644
index 000000000..06553547e
--- /dev/null
+++ b/.github/workflows/pr-body.yaml
@@ -0,0 +1,32 @@
+name: PR Body
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      # pull_request_target runs with a write token, so this job checks out main and reads only the
+      # event payload; it never checks out or runs the pull request's code.
+      - name: Checkout Code
+        uses: actions/checkout@v7
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: '.nvmrc'
+      - name: Check the Body
+        id: check
+        # the explicit shell adds pipefail, so tee cannot hide the script's exit code
+        shell: bash
+        run: node scripts/check-pr-body.ts "$GITHUB_EVENT_PATH" | tee "$RUNNER_TEMP/pr-body-report.md"
+      - name: Close the Pull Request
+        if: failure() && steps.check.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          gh pr comment "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --body-file "$RUNNER_TEMP/pr-body-report.md"
+          gh pr close "$PR_NUMBER" --repo "$GITHUB_REPOSITORY"
diff --git a/scripts/check-pr-body.ts b/scripts/check-pr-body.ts
new file mode 100644
index 000000000..ef516856d
--- /dev/null
+++ b/scripts/check-pr-body.ts
@@ -0,0 +1,157 @@
+import fs from 'node:fs';
+
+type PullRequestEvent = {
+  action: string;
+  pull_request: {
+    body: null | string;
+    head: { sha: string };
+  };
+};
+
+const SKILL_PATH = '.agents/skills/opening-pr/SKILL.md';
+
+const FORBIDDEN_HEADING = /^#{1,6} +(verification|validation|notes|implementation notes)\b/i;
+
+const FENCE = /^(```|~~~)/;
+
+const STAMP = /^(?:Reviewed at commit|Follow-up) ([0-9a-f]{40})\b/gm;
+
+function isRecord(value: unknown): value is { [key: string]: unknown } {
+  return typeof value === 'object' && value !== null;
+}
+
+function parseEvent(contents: unknown): PullRequestEvent {
+  if (!isRecord(contents) || typeof contents.action !== 'string' || !isRecord(contents.pull_request)) {
+    throw new Error('Expected a pull_request event payload with an action and a pull_request');
+  }
+  const { body, head } = contents.pull_request;
+  if ((body !== null && typeof body !== 'string') || !isRecord(head) || typeof head.sha !== 'string') {
+    throw new Error('Expected pull_request.body to be a string or null and pull_request.head.sha a string');
+  }
+  return { action: contents.action, pull_request: { body, head: { sha: head.sha } } };
+}
+
+function readEvent(): PullRequestEvent {
+  const [eventPath] = process.argv.slice(2);
+  if (!eventPath) {
+    throw new Error('Usage: node scripts/check-pr-body.ts <event.json>');
+  }
+  return parseEvent(JSON.parse(fs.readFileSync(eventPath, 'utf8')));
+}
+
+function outsideFences(lines: string[]): string[] {
+  let fenced = false;
+  return lines.filter((line) => {
+    if (FENCE.test(line)) {
+      fenced = !fenced;
+      return false;
+    }
+    return !fenced;
+  });
+}
+
+function findSection(text: string, heading: string, level: number): null | string {
+  const lines = text.split(/\r?\n/);
+  const title = `${'#'.repeat(level)} ${heading}`.toLowerCase();
+  const start = lines.findIndex((line) => line.trim().toLowerCase() === title);
+  if (start === -1) {
+    return null;
+  }
+  const boundary = new RegExp(`^#{1,${level}}\\s`);
+  const end = lines.findIndex((line, index) => index > start && boundary.test(line));
+  return lines.slice(start + 1, end === -1 ? undefined : end).join('\n');
+}
+
+function listNumbers(text: null | string): Set<number> {
+  return new Set(Array.from((text ?? '').matchAll(/^\s*(?:-\s*)?(\d+)\./gm), (match) => Number(match[1])));
+}
+
+function checkReview(review: string, event: PullRequestEvent): string[] {
+  const failures: string[] = [];
+  const stamps = Array.from(review.matchAll(STAMP), (match) => match[1]);
+  const headSha = event.pull_request.head.sha;
+  if (stamps.length === 0) {
+    failures.push('The review block names no reviewed commit.');
+  } else if (event.action !== 'edited' && !stamps.includes(headSha)) {
+    // The body is edited for a new head before that head is pushed, so an edit is checked against
+    // the head only once the push that follows it arrives.
+    failures.push(`The review block names no commit matching the head \`${headSha}\`.`);
+  }
+  if (!/\bpnpm check: green\b/.test(review)) {
+    failures.push('The review block does not state `pnpm check: green`.');
+  }
+  const findings = findSection(review, 'findings', 3);
+  if (findings === null) {
+    failures.push('The review block has no `### Findings` section.');
+    return failures;
+  }
+  const fixed = listNumbers(findSection(review, 'fixed', 3));
+  const declined = listNumbers(findSection(review, 'declined', 3));
+  if (findings.trim() === 'CLEAN') {
+    if (fixed.size + declined.size > 0) {
+      failures.push('A `CLEAN` review lists nothing under Fixed or Declined.');
+    }
+    return failures;
+  }
+  const found = listNumbers(findings);
+  if (found.size === 0) {
+    failures.push('`### Findings` is neither `CLEAN` nor numbered findings.');
+  }
+  for (const number of found) {
+    if (fixed.has(number) && declined.has(number)) {
+      failures.push(`Finding ${number} is listed as both fixed and declined.`);
+    } else if (!fixed.has(number) && !declined.has(number)) {
+      failures.push(`Finding ${number} is neither fixed nor declined.`);
+    }
+  }
+  for (const number of new Set([...fixed, ...declined])) {
+    if (!found.has(number)) {
+      failures.push(`Finding ${number} is fixed or declined but not listed under Findings.`);
+    }
+  }
+  return failures;
+}
+
+function checkBody(event: PullRequestEvent): string[] {
+  const { body } = event.pull_request;
+  if (!body?.trim()) {
+    return ['The body is empty.'];
+  }
+  const failures = outsideFences(body.split(/\r?\n/))
+    .filter((line) => FORBIDDEN_HEADING.test(line))
+    .map((line) => `Remove the \`${line.trim()}\` section; the body carries effects, decisions and risks only.`);
+  const review = findSection(body, 'adversarial review', 2);
+  if (review === null) {
+    failures.push('The body has no `## Adversarial review` section.');
+  } else {
+    failures.push(...checkReview(review, event));
+  }
+  return failures;
+}
+
+function report(failures: string[]): never {
+  const lines = [
+    `This pull request was closed because its body does not meet \`${SKILL_PATH}\`:`,
+    '',
+    ...failures.map((failure) => `- ${failure}`),
+    '',
+    'Fix the body with `gh pr edit <number> --body-file <path>`, then `gh pr reopen <number>`.'
+  ];
+  process.stdout.write(`${lines.join('\n')}\n`);
+  process.exit(1);
+}
+
+function main(): void {
+  let failures: string[];
+  try {
+    failures = checkBody(readEvent());
+  } catch (error) {
+    report([`The check itself failed: ${error instanceof Error ? error.message : String(error)}`]);
+  }
+  if (failures.length > 0) {
+    report(failures);
+  }
+  process.stdout.write('The pull request body meets the template.\n');
+}
+
+main();