vinta-ai-workflows 0.1.7

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

@@ -0,0 +1,184 @@
+---
+name: vinta-sync-ai-tools
+description: Bring a project up to date with the latest `vinta-ai-workflows` package version. Reads the project's `.vinta-ai-workflows.yaml` (the single source of truth for which surface area is enabled), reads the cloned package's `CHANGELOG.md` to enumerate releases since the project's recorded version, classifies each change against the project's opt-in surface (affects-project / opt-in-offer / config-schema-change / not-applicable), shows per-change diffs, asks the user one `AskUserQuestion` per change (`Apply` / `Skip` / `Show diff`), applies approved changes (re-render templates, add new foundation skills, patch setup script, migrate config schema), and bumps `vinta_ai_workflows_version` + `last_synced_at` at the end. Layers on top of [vinta-update-project-skills](../vinta-update-project-skills/SKILL.md), which it invokes for foundation-skill body diffs. Use after `npm update vinta-ai-workflows` or pulling a newer git+ssh ref.
+---
+
+# vinta-sync-ai-tools
+
+The version-upgrade path. Companion to the rest of the builder skills:
+
+- [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md) — writes the project for the first time.
+- **vinta-sync-ai-tools** — this skill. Updates the project against a newer package version.
+- [vinta-update-project-skills](../vinta-update-project-skills/SKILL.md) — narrow tool for refreshing only the foundation-skill bodies. This skill calls it as a sub-step.
+
+## Source of truth
+
+`.vinta-ai-workflows.yaml` at the repo root. Defined by [`schemas/vinta-ai-workflows-config.v1.schema.json`](../../schemas/vinta-ai-workflows-config.v1.schema.json). Every consumer (this skill, every other builder skill, every template render) reads from this file. Modifying values there is the only supported way to change project-wide settings — never hand-edit values inlined into rendered SKILL.md bodies, those will be overwritten on the next sync.
+
+If `.vinta-ai-workflows.yaml` is missing (older bootstrap or hand-built project), the sync skill's first step builds one by reverse-extracting state from the project's existing artifacts and interview-filling gaps. See "Bootstrapping the config file" below.
+
+## Inputs
+
+1. The project root (default: cwd).
+2. The cloned `vinta-ai-workflows` source. Auto-detected via the same paths as [vinta-update-project-skills](../vinta-update-project-skills/SKILL.md) — symlink realpath, copy-mode marker, or asked.
+3. The project's `.vinta-ai-workflows.yaml` (read; rewritten at the end).
+
+## Steps
+
+### 1. Locate + load the config
+
+`<project>/.vinta-ai-workflows.yaml` is required. If absent, run "Bootstrapping the config file" below to seed it before continuing.
+
+Validate the config against the schema matching its `schema_version`. Any validation error → stop, surface the error path. Don't proceed against a malformed config.
+
+Read:
+
+- `vinta_ai_workflows_version` (call it `OLD_VERSION`).
+- The current `version` field of the cloned package's `package.json` (call it `NEW_VERSION`).
+- `foundation_skills`, `foundation_agents`, `vendors`, `stacks`, `policies` — used to decide what's `affects-project` vs `not-applicable` per change.
+
+`OLD_VERSION === NEW_VERSION` → nothing to sync. Print "already up to date" and exit.
+
+### 2. Enumerate releases
+
+Read the cloned package's `CHANGELOG.md`. Parse each `## [X.Y.Z]` heading. Build the ordered list of releases between `OLD_VERSION` (exclusive) and `NEW_VERSION` (inclusive).
+
+For each release, parse the `### Added`, `### Changed`, `### Removed`, `### Deprecated`, `### Notes` sub-sections into a list of change records: `{ release, kind, summary, body }`.
+
+If the changelog is missing entries that file diffs reveal exist (orphan diffs), surface them at the end as "undocumented changes — please cross-check with maintainers". Don't try to apply orphans automatically.
+
+### 3. Classify each change
+
+For each change record, decide its bucket:
+
+| Bucket | Trigger |
+|---|---|
+| `affects-project` | Touches surface area enabled in the config. Examples: foundation-skill body changed and the skill is `enabled`; template gained a section and the project has the rendered skill. |
+| `opt-in-offer` | New optional surface area. Project doesn't have it enabled. Show the description; offer to enable. |
+| `config-schema-change` | Adds a field to the config schema or bumps its major. Migrate the config; ask user to fill new required fields. |
+| `not-applicable` | Project opted out (`disabled` in config) or never applicable (e.g. stack-specific change for a stack the project doesn't use). |
+| `tooling` | Setup-script / gitignore / packaging changes that propagate transparently — no per-change question; apply if approved as a batch. |
+
+Cross-check via file diff: every `affects-project` change should correspond to a real file delta between `OLD_VERSION`'s source (reachable via git tag in the clone) and `NEW_VERSION`'s source. Diffs without changelog entries → flag as orphan (see step 2).
+
+### 4. Build the proposal
+
+Group by bucket. Print as a structured report. Example:
+
+```
+vinta-ai-workflows sync: 0.1.0 → 0.1.2 (2 releases)
+====================================================
+
+AFFECTS PROJECT — your enabled surface gained changes
+  [0.1.1] implement-plan template: "Open PR via context file" PR-context flow added
+    file: ai-tools/skills/implement-plan/SKILL.md (will re-render)
+    diff: +88 lines, -6 lines
+
+  [0.1.2] amend-plan template: blast-radius gate added
+    file: ai-tools/skills/amend-plan/SKILL.md (will re-render)
+    diff: +52 lines, -0 lines
+
+OPT-IN OFFER — new optional surface area
+  [0.1.2] foundation skill: open-pr-from-context
+    your config has: foundation_skills.open-pr-from-context: <missing>
+    enabling will: copy SKILL.md + scripts/open-pr.sh into ai-tools/skills/
+
+CONFIG SCHEMA CHANGE
+  [0.1.2] new field: run_options.amend-plan.blast_radius_signal_threshold (int, default 2)
+
+TOOLING (batch-apply if approved)
+  [0.1.2] setup-ai-tools.mjs: appends `.vinta-ai-workflows/prs-context/` to .gitignore on first run
+
+NOT APPLICABLE (skipped — opted out / unused stack)
+  [0.1.1] add-env-var optional skill update — your config has add-env-var: disabled
+  [0.1.1] medplum stack notes update — project doesn't use medplum stack
+```
+
+For each `affects-project` and `opt-in-offer` entry, expand a unified diff inline on user request.
+
+### 5. Per-change confirmation
+
+**Critical: never apply silently.**
+
+For each `affects-project` and `opt-in-offer` and `config-schema-change` entry, ask the user via `AskUserQuestion`:
+
+- `Apply`
+- `Skip` (records as opted-out for this version; next sync won't re-propose; user can later flip the foundation skill back to `enabled` to re-offer)
+- `Show diff` (re-displays in full, then re-asks)
+
+`tooling` changes batch under one prompt: `Apply all tooling changes?` — they're typically idempotent and small.
+
+`opt-in-offer` `Skip` writes the corresponding entry to `foundation_skills` (or wherever it lives) as `disabled` so the next sync respects the choice.
+
+Don't batch `affects-project` decisions. Each is a separate decision so the user can keep their hand-tuned wording for one skill while accepting another.
+
+### 6. Apply approved changes
+
+In order:
+
+1. **`config-schema-change`** first. Migrate `.vinta-ai-workflows.yaml`:
+   - Add new optional fields with defaults from the schema.
+   - For new required fields: prompt the user for a value with `AskUserQuestion`.
+   - On schema major bump: apply the documented migration from the bumped schema's release notes.
+   - Bump `schema_version` if the major changed.
+
+2. **`opt-in-offer` accepts** — flip the corresponding entry to `enabled` in the config; copy / render the artifact (foundation skill, agent, etc.).
+
+3. **`affects-project` accepts** — re-render the relevant template (for `implement-plan` / `amend-plan`) or re-copy the foundation skill body (for verbatim ones — delegated to [vinta-update-project-skills](../vinta-update-project-skills/SKILL.md)). Use the values in `.vinta-ai-workflows.yaml` as the substitution source. Validate every `{{PLACEHOLDER}}` is resolved.
+
+4. **`tooling` accepts** — run setup-ai-tools.mjs from the new package version in idempotent mode. The script handles gitignore append, vendor symlinks, vendor agent file regeneration.
+
+5. Re-validate every YAML file under the project against its schema (`.vinta-ai-workflows.yaml`, `ai-tools/agents/*.yaml`, any `.vinta-ai-workflows/prs-context/**/*.md` frontmatter blocks). Surface validation failures; don't silently proceed.
+
+### 7. Bump version + final report
+
+After all approved changes apply:
+
+1. Update `.vinta-ai-workflows.yaml`:
+   - `vinta_ai_workflows_version: <NEW_VERSION>`.
+   - `last_synced_at: <ISO timestamp>`.
+2. Print the final summary:
+   - Applied (per-change list).
+   - Skipped — and where the user can re-evaluate later (config file path).
+   - New `foundation_skills` / `foundation_agents` entries set to `disabled`.
+   - Orphan diffs (undocumented changes from step 2) for the user's review.
+   - If the package version was a major bump (e.g. `0.x.y` → `1.0.0`): warn the user to read the full changelog, especially the `### Removed` / `### Deprecated` sections.
+
+## Bootstrapping the config file
+
+Run on first sync against a project without `.vinta-ai-workflows.yaml`:
+
+1. Detect the installed package version: read `node_modules/vinta-ai-workflows/package.json` (or the clone's). Use as `vinta_ai_workflows_version`.
+2. Detect project facts:
+   - `project.name` → `package.json#name` or `Cargo.toml#package.name` or repo dir name; confirm.
+   - `project.default_branch` → `git remote show origin | grep 'HEAD branch'` or `git rev-parse --abbrev-ref origin/HEAD`.
+   - `project.code_host` → parse `git remote get-url origin`.
+   - `project.stack_summary` → run [vinta-analyze-codebase](../vinta-analyze-codebase/SKILL.md) inventory, take the one-liner.
+   - `project.ai_plans_dir` → look for `ai-plans/`, `apps/<service>/ai-plans/`, etc.
+3. Detect commands by scanning `package.json#scripts`, `Makefile`, etc. Confirm each via `AskUserQuestion`.
+4. Detect policies by reading the existing `ai-tools/skills/implement-plan/SKILL.md` (if present) — reverse-extract `pr_creation`, `ai_coauthor`, `commit_style` from the rendered body. Interview-fill gaps.
+5. Detect vendor coverage from existing vendor symlinks/dirs (`.claude/`, `.cursor/`, `.codex/`, `.github/agents/`).
+6. Detect foundation-skill opt-ins by scanning `ai-tools/skills/`.
+7. Detect stacks via `vinta-analyze-codebase` matched-stacks list.
+8. Write `.vinta-ai-workflows.yaml` with the inferred state. Add the schema-language-server directive at the top.
+9. Print the final config to the user; ask `AskUserQuestion`: `Looks right — proceed with sync` / `Edit values first` / `Stop`.
+
+Then re-enter step 1 of the main flow.
+
+## Pitfalls
+
+- **Hand-edited rendered skill bodies.** `vinta-sync-ai-tools` re-renders templates from the config — any inline edits the user made to the rendered `ai-tools/skills/<name>/SKILL.md` will be overwritten on `Apply`. Surface a warning when re-rendering would clobber a body the user touched (heuristic: file modified after the bootstrap commit). Default action: ask before overwriting.
+- **`OLD_VERSION` lower than the oldest changelog entry.** Some projects predate the changelog. Treat anything before the earliest documented version as "best-effort sync" and rely on file diff entirely.
+- **Multiple package versions in the clone.** If the user has both `node_modules/vinta-ai-workflows/` and a separate `git clone`, they may diverge. Pick one source and pin to it for the run; surface the choice up front.
+- **Orphan diffs.** Surfaced, never auto-applied. Ask the maintainer to add a changelog entry; don't try to interpret an undocumented change.
+- **Breaking schema bump (`schema_version: N → N+1`).** Migration code must come from the package's release notes. If migration data is missing, stop — don't guess.
+- **Sticky opt-outs.** A user who accepted `add-env-var: disabled` once stays disabled across sync runs. To re-offer, manually flip to `enabled` in `.vinta-ai-workflows.yaml` and re-run sync.
+
+## Verification
+
+1. **Up-to-date project**: `OLD_VERSION === NEW_VERSION` → "already up to date", no changes.
+2. **Single template change accepted**: re-renders one skill body, all `{{PLACEHOLDER}}` resolved, `vinta_ai_workflows_version` bumped, no other files touched.
+3. **Opt-in declined**: `foundation_skills.<name>: disabled` written to config; nothing else added.
+4. **Schema bump**: new field added with default; `schema_version` bumped if major changed; payload still validates.
+5. **Bootstrap from missing config**: `.vinta-ai-workflows.yaml` written with reverse-extracted values; user confirms before main flow runs.
+6. **Orphan diff**: changelog has no entry for a real file change; sync surfaces it at the end without applying.

package/skills/vinta-update-project-skills/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: vinta-update-project-skills
+description: Refresh the user's project skills under `ai-tools/skills/` against the latest versions in this `vinta-ai-workflows` repo. Detects which project skills came from the bundled foundation set or stack templates, computes a per-file diff against the current source, presents the proposed changes, and only applies them after the user explicitly accepts each one. Skills the user authored themselves (no matching upstream source) are detected and left alone. Use after pulling a new version of `vinta-ai-workflows` to bring an existing project up to date without re-running the full bootstrap. Read-only by default — every write is gated on explicit user approval.
+---
+
+# Update project skills
+
+[vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md) (specifically [vinta-derive-skills](../vinta-derive-skills/SKILL.md)) seeds a project's `ai-tools/skills/` directory from sources that live in this repo:
+
+- **Verbatim foundation skills** — copied as-is from `vinta-derive-skills/resources/foundation-skills/<name>/SKILL.md`.
+- **Templated skills** — `implement-plan/SKILL.md` is rendered from `vinta-derive-skills/resources/implement-plan-template.md` with project-specific values interpolated.
+- **Stack-derived skills** — drafted from prompts under `vinta-bootstrap-ai-tools/resources/stacks/<stack>/notes.md`.
+- **User-authored skills** — anything else the team added later. **Never overwritten.**
+
+When this repo gains an updated foundation skill (new section, fixed wording, bumped checklist), existing projects sit on the old copy until someone refreshes them. This skill is the safe path to that refresh.
+
+## Inputs
+
+- Path to the project being updated (default: cwd).
+- Path to the `vinta-ai-workflows` clone (auto-detected from this skill's installed location — see "Locating the source").
+- The project's `ai-tools/skills/` directory.
+
+## Output
+
+- A diff report listing each project skill with status: `up-to-date`, `outdated`, `templated (regenerate)`, or `user-authored (skip)`.
+- For each `outdated` skill the user accepts: the project file is overwritten with the source content. Nothing else changes.
+- A summary of what was updated, what was left alone, and any follow-ups (e.g. "re-run [vinta-derive-skills](../vinta-derive-skills/SKILL.md) to refresh `implement-plan`").
+
+## Locating the source
+
+The skill must know where this `vinta-ai-workflows` repo lives. Resolution order:
+
+1. **Symlink installs** (default): the project's installed copy of this skill is a symlink. Use `realpath` of `<project>/.claude/skills/vinta-update-project-skills/SKILL.md` (or whichever vendor path) to walk back to `<clone>/ai-tools-builder/skills/vinta-update-project-skills/SKILL.md`. From there, `<clone>` is three directories up.
+2. **Copy installs**: the installed copy contains `.installed-by-vinta-ai-workflows` whose body records the original `source:` path. Read that path and walk up.
+3. **Both fail** (e.g. the clone moved): ask the user for the path with `AskUserQuestion`. Don't proceed without it.
+
+Once located:
+
+- Foundation source root: `<clone>/ai-tools-builder/skills/vinta-derive-skills/resources/foundation-skills/`.
+- Template source root: `<clone>/ai-tools-builder/skills/vinta-derive-skills/resources/`.
+- Stack source root: `<clone>/ai-tools-builder/skills/vinta-bootstrap-ai-tools/resources/stacks/`.
+
+## Steps
+
+### 1. Prerequisite check
+
+`<project>/ai-tools/skills/` exists and is non-empty. If not → stop and tell the user to run [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md) first.
+
+The clone is locatable (per "Locating the source"). If not → ask, then continue.
+
+### 2. Inventory the project skills
+
+For each subdirectory under `<project>/ai-tools/skills/`, record:
+
+- Skill name (= directory name).
+- The file paths inside (`SKILL.md` always; sometimes `resources/`, `scripts/`, etc.).
+- The current contents of `SKILL.md`.
+
+### 3. Classify each skill
+
+For each project skill, decide its bucket:
+
+| Bucket | Detection | Action |
+|---|---|---|
+| `verbatim` | The skill name matches a directory under `vinta-derive-skills/resources/foundation-skills/` (e.g. `plan-feature`, `create-spec`, `create-qa-use-cases`). | Diff against source. |
+| `templated` | The skill name is `implement-plan` (or any other future templated skill listed under `vinta-derive-skills/resources/*-template.md`). | **Don't diff.** Surface as "regenerate via [vinta-derive-skills](../vinta-derive-skills/SKILL.md)". |
+| `stack-derived` | The skill maps to a stack-template prompt under `vinta-bootstrap-ai-tools/resources/stacks/<stack>/notes.md`. | Same as `templated` — surface, don't diff. |
+| `user-authored` | None of the above. | Skip silently. |
+
+For `templated` and `stack-derived`, in-place diffing is misleading because the project version contains interpolated values (commands, branch names, etc.) that won't appear in the template. The right refresh path for those is to re-run [vinta-derive-skills](../vinta-derive-skills/SKILL.md) so the user can re-supply the inputs.
+
+### 4. Diff verbatim skills
+
+For each `verbatim` skill:
+
+- Read the source `SKILL.md` from the clone.
+- Read the project's `SKILL.md`.
+- If byte-identical → mark `up-to-date`.
+- Else → mark `outdated`, compute a unified diff (use `git diff --no-index` if available, otherwise produce a text diff yourself).
+
+Also compare the rest of the directory tree (`resources/`, `scripts/`, etc.). Any source files not present in the project version → mark as "new files to add". Any project files not present in source → leave alone (could be local additions).
+
+### 5. Build the proposal
+
+Produce a human-readable report grouped by status. Example:
+
+```
+Project skills under ai-tools/skills/ — refresh proposal
+========================================================
+
+UP-TO-DATE (no action needed)
+  - plan-feature
+
+OUTDATED (proposed: overwrite SKILL.md from source)
+  - create-spec        (12 lines added, 3 removed)
+  - create-qa-use-cases (2 lines changed)
+
+REGENERATE NEEDED (proposed: re-run vinta-derive-skills)
+  - implement-plan     (templated — values would be lost on overwrite)
+
+USER-AUTHORED (no action — left alone)
+  - my-team-thing
+  - update-tenant-fields
+```
+
+For each `outdated` entry, include the diff inline (collapsed if long). Don't truncate — the user needs to see what's changing.
+
+### 6. Per-skill confirmation
+
+**Critical: never apply changes silently.**
+
+For each `outdated` skill, ask the user explicitly. Use `AskUserQuestion` (or the equivalent for the vendor) with options:
+
+- `Apply` — overwrite the project file with source.
+- `Skip` — leave the project version alone for now.
+- `Diff again` — re-display the diff in full.
+
+Do NOT batch these under a single "apply all?" prompt. Each skill is a separate decision so the user can keep their hand-tuned wording where it matters.
+
+For `templated` / `stack-derived` skills, the question is different — they can't be applied directly:
+
+- `Re-run vinta-derive-skills now` (orchestrator decides if that's in-scope for this session) — exits this skill, hands off.
+- `Skip` — leave alone, surface as a TODO at the end.
+
+### 7. Apply approved changes
+
+For each `outdated` skill where the user said `Apply`:
+
+- Overwrite `<project>/ai-tools/skills/<name>/SKILL.md` with source content.
+- For any "new files to add" inside that skill's source tree, copy them into the project (preserving subdir structure).
+- Do not touch project-only files inside that skill's directory.
+
+After each write, log: `[updated] ai-tools/skills/<name>/SKILL.md`.
+
+### 8. Re-run the per-vendor setup script
+
+The project's `ai-tools/scripts/setup-ai-tools.mjs` (installed by [vinta-install-ai-tools-setup](../vinta-install-ai-tools-setup/SKILL.md)) materializes vendor-specific copies. After updating canonical skills, run it so each vendor's `<vendor>/skills/` symlink/copy resolves to the new content:
+
+```bash
+pnpm setup:ai-tools
+# or: node ai-tools/scripts/setup-ai-tools.mjs
+```
+
+If the project's setup script is symlinked-style, this is a no-op; for copy-style it refreshes the per-vendor copies.
+
+### 9. Final report
+
+Echo back, in this order:
+
+1. **Updated** — skills that got overwritten (with file paths).
+2. **Skipped by user** — skills the user kept their version of (with reason if given).
+3. **Needs regeneration** — `templated` / `stack-derived` skills the user should refresh by re-running [vinta-derive-skills](../vinta-derive-skills/SKILL.md).
+4. **User-authored (untouched)** — for transparency.
+
+If anything was updated, suggest the next steps the user should take: review the changes (`git diff ai-tools/`), commit, optionally re-run vendor setup.
+
+## Read-only mode
+
+If the user asks for a "preview" / "what would change" / "dry-run" — perform steps 1–5 only. Stop before step 6. Print the proposal and exit. The user can re-invoke without `--dry-run` semantics when ready.
+
+When invoked without an explicit dry-run intent, still default to **showing all diffs first, then asking**. Never start with destructive actions.
+
+## Pitfalls
+
+- **Overwriting hand-edited foundation skills.** Some teams tweak the foundation `SKILL.md` after bootstrap (project-specific examples). The byte-diff will flag those as `outdated` even though the upstream hasn't moved. The per-skill confirmation gate is what protects them — but make sure the diff is *visible* before asking, so the user notices their edit is about to be lost.
+- **Skipping the explicit confirmation.** Bulk "apply all" prompts feel efficient but defeat the safety property. One question per outdated skill.
+- **Trying to diff templated skills.** `implement-plan` and stack-derived skills contain interpolated values. A byte-diff vs the template will be huge and useless. Classify them first; never diff.
+- **Forgetting the per-vendor refresh.** The user runs this skill, sees "updated 3 files", opens Cursor, and Cursor still shows the old content because its `.cursor/skills/` is a copy that wasn't refreshed. Step 8 fixes this — don't skip it.
+- **Hard-coded clone path.** Don't assume `~/code/vinta-ai-workflows`. Resolve the clone via the symlink / marker / explicit ask path described in "Locating the source".
+- **Touching skills not under `ai-tools/skills/`.** This skill operates only on the canonical skill source directory. The vendor-specific copies under `.claude/skills/`, `.cursor/skills/`, etc. are derived — they get refreshed by step 8, not by direct writes here.
+
+## Verification
+
+1. **Up-to-date project**: run the skill; expected outcome — every project skill in `up-to-date` bucket, no questions asked, exit cleanly.
+2. **Drift case**: edit one foundation skill in this repo, run the skill on a project that has the old version; expected — that skill flagged `outdated`, diff displayed, user prompted, accept → file updated, decline → file unchanged.
+3. **User-authored skill present**: project has `ai-tools/skills/my-thing/SKILL.md` with no upstream source; expected — bucket = `user-authored`, no prompt, no write.
+4. **Templated skill drift**: `implement-plan` differs from template; expected — bucket = `templated`, prompt offers re-run hand-off, never auto-overwrites.
+5. **No `ai-tools/skills/`**: expected — stop early, route to [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md).

package/skills/vinta-write-agents-md/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: vinta-write-agents-md
+description: Synthesize `ai-tools/AGENTS.md` from the inventory produced by [vinta-analyze-codebase](../vinta-analyze-codebase/SKILL.md) plus a focused interview for what the analysis can't see. Used by [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md) as step 2; also runnable standalone to refresh AGENTS.md after a major refactor. Project-agnostic — sections are the same shape across stacks, content adapts. Symlinked into root `AGENTS.md` so Claude Code, Cursor, Codex, VS Code Copilot all read it natively.
+---
+
+# Write AGENTS.md
+
+The canonical project-conventions document. Read by every AI tool. Single source of truth — every other agent / skill defers to it for "how this project does X".
+
+## Output
+
+`ai-tools/AGENTS.md`. The setup script symlinks `AGENTS.md` at root and `.github/copilot-instructions.md` to it.
+
+## Inputs
+
+1. The structured inventory from [vinta-analyze-codebase](../vinta-analyze-codebase/SKILL.md). Pay attention to `existing_ai_artifacts.instructions` — every found instruction doc must be folded in, replaced, or referenced per the [Existing AI artifacts (per-artifact disposition)](../vinta-bootstrap-ai-tools/SKILL.md#e-existing-ai-artifacts-per-artifact-disposition) decision captured in the bootstrap interview.
+2. Any existing `AGENTS.md` / `CLAUDE.md` / `CONTRIBUTING.md` / `README.md` / `.cursorrules` / `.github/copilot-instructions.md` content — read in full. Behavior depends on the user's disposition:
+   - **Merge into new AGENTS.md** — extract every still-accurate fact (commands, paths, naming rules, multi-tenancy notes, env vars, deploy steps) and weave into the canonical sections below. Don't lose content silently — if a paragraph doesn't fit any section, surface it for the user to place or drop.
+   - **Keep as-is, link from AGENTS.md** — leave the file untouched; add a `## See also` reference to it from the new AGENTS.md and copy only the high-level pointer (one sentence + link).
+   - **Replace from scratch** — discard the old content; draft fresh from inventory + interview. Note the discarded files in the run summary so the user can verify nothing important was lost.
+3. Interview answers (Step 0 below).
+
+## Step 0 — Interview before drafting
+
+The analysis tells you the *shape* of the repo. The interview tells you *intent* — conventions humans hold but don't surface in code. Use `AskUserQuestion` for finite-choice; iterate plain prose for narrative.
+
+### A. Project framing
+
+1. **What does this project do?** One paragraph. Inferred from README is OK; confirm with user.
+2. **Primary user(s)?** Internal team, external customers, both, integration partners.
+3. **Maturity stage?** Greenfield, MVP, post-launch, mature.
+
+### B. Conventions the analysis can't see
+
+1. **Code-style nuances Biome / ruff / etc don't enforce** — naming, file layout, import order conventions. Free-form list.
+2. **"Always do X" / "never do Y" rules** the team holds. e.g. "always inject deps with defaults", "never use `let` unless reassignment", "all FHIR resources stamp `meta.account`".
+3. **Architecture patterns** — separation of concerns, where business logic lives, error-handling style.
+4. **Testing philosophy** — unit vs integration ratio, mock vs real backends, test data conventions.
+5. **Multi-tenancy details** if applicable — how is tenant scope enforced at every layer (DB / API / UI / background jobs).
+
+### C. Deploy + env model
+
+1. **Environments named.** `staging`, `production`, `preview-*`, `dev-<handle>`, etc. Confirm what `vinta-analyze-codebase` extracted.
+2. **Deploy gates** — manual approval, soak window, automated promotion?
+3. **Manual deploy steps** that aren't in CI — `npx medplum post`, `pnpm bots:deploy`, `kubectl apply`, etc.
+4. **Per-env value mechanism** — `.env` files, secret managers, deploy-time injection, project-wide secrets vs per-env.
+
+### D. PR + commit conventions
+
+1. **Branch naming** — `feature/*`, `feat/*`, `<ticket>-<slug>`, free-form.
+2. **PR who-creates-it** — agents create PRs, or only branches and humans open PRs?
+3. **Commit message style** — Conventional Commits, short imperative, free-form.
+4. **AI co-author trailers in commits** — allowed, forbidden, undefined. Most repos: forbidden.
+
+### E. Out of scope (non-goals)
+
+1. **Things AGENTS.md should explicitly NOT cover** — internal API tokens, customer data, security secrets that don't belong in a public-ish doc.
+2. **Topics handled elsewhere** — if there's a `docs/ARCHITECTURE.md` or `docs/RBAC.md` already, reference it instead of duplicating.
+
+After interview: read back load-bearing decisions in one paragraph; final `AskUserQuestion` `Looks good` / `Some corrections` / `More to clarify` / `Stop, rethink`. Loop until `Looks good`.
+
+## Structure
+
+The skeleton is fixed. Sections that don't apply: skip with a one-line "n/a — single-tenant" note rather than omitting silently.
+
+```markdown
+# {Project Name}
+
+{One-paragraph what + why, from the **Project framing** interview group.}
+
+## Project Overview
+
+{Apps, libs, services list — one bullet per. Pulled from analyze-codebase monorepo.apps + .packages.}
+
+{Key data backend / framework callout — e.g. "All data is stored as FHIR resources in Medplum — there is no traditional database." Or "Postgres 17 with psqlextra LIST partitioning by tenant_id". Or "stateless API; no persistent storage."}
+
+## Tech Stack
+
+- **{Framework}** {version} — {one-line role}
+- **{Build tool}** ({purpose}), **{Test runner}** ({purpose}), **{Package manager}** ({version})
+- **{Lint+format}** — {note any deviation from defaults}
+- **{Deploy target}** — {note manual steps}
+- ... etc
+
+## Common Commands
+
+```bash
+{install}
+{dev}
+{build}
+{test_unit}
+{test_e2e}     # if applicable
+{lint}
+{format}
+{typecheck}    # if separate from build
+{deploy_*}     # if commands surface in package.json / Makefile
+```
+
+## Code Style
+
+{Pulled from analysis + the **Conventions the analysis can't see** interview group. Bullet list of enforced + cultural rules.}
+
+## Architecture
+
+### {Subsystem 1, e.g. "FHIR Workflow Engine" / "Data Pipeline" / "Auth"}
+{Describe at the level a new contributor needs. Reference files / dirs.}
+
+### {Subsystem 2, e.g. "Access Control" / "Multi-tenancy"}
+{...}
+
+### Routing / Page structure / Service shape (whichever applies)
+{...}
+
+### Testing
+{What runner, where tests live, mocking conventions, fixture patterns.}
+
+## {Multi-tenancy / Tenant Model — only if applicable}
+
+{How tenants are scoped at every layer. Pull from the **Conventions the analysis can't see → Multi-tenancy details** interview answer + analyze-codebase env_model.multi_tenancy.}
+
+## Environment Variables
+
+{Per-app or per-service code fence with var names — no values. Pull from analyze-codebase env_model.example_files.}
+
+**{App 1}** (`.env`):
+```
+VAR_ONE
+VAR_TWO
+...
+```
+
+**{App 2}** (`.env`):
+```
+...
+```
+
+## Error / Exception Tracking
+
+{If Sentry / Bugsnag / Datadog detected: one section with init pattern + tracing examples. Else: omit.}
+
+## Deployment
+
+| Environment | URL / target | Trigger |
+|---|---|---|
+| Staging | ... | ... |
+| Production | ... | ... |
+
+{Manual deploy steps if any: bullet list.}
+
+## Key Documentation
+
+{Bullets pointing at docs/<file>.md for deep dives the AGENTS.md doesn't replicate.}
+```
+
+## Rules
+
+- **Don't replicate doc content already in `docs/`.** Reference it. AGENTS.md is the orientation map, not the encyclopedia.
+- **Be specific.** "Use bulk_create" not "use efficient ORM patterns". "Stamp meta.account on every FHIR resource" not "respect tenancy".
+- **Cite paths.** Every "X lives in Y" claim names the file or dir. Future readers grep for the filename.
+- **Plain English.** Read by humans + agents + new hires. Acronyms expanded on first use.
+- **No code beyond what's necessary.** If a 5-line snippet captures the convention, use it. Don't paste 50 lines of context.
+- **No marketing language.** "Robust", "seamless", "delightful" — strike. State what it does.
+- **No `§N` shorthand for cross-references.** When AGENTS.md points at other docs, name the section (`See the **Multi-tenancy** section in docs/ARCHITECTURE.md`). `§4.2` is unreadable for humans and breaks when section numbering shifts.
+
+## What NOT to put in AGENTS.md
+
+- Customer-specific business rules ("this clinic gets X discount") — too volatile.
+- Secrets, tokens, real env values.
+- Detailed RBAC matrices — link to `docs/RBAC.md` if it exists; if not, derive-skills creates `manage-access-policy/SKILL.md` to handle it.
+- Architecture deep-dives — those live in `docs/ARCHITECTURE.md` or per-subsystem docs.
+- Incident postmortems / change history — git log + a CHANGELOG handle that.
+
+## Examples to study before writing
+
+If the source repo (the one defining `vinta-bootstrap-ai-tools`) has a real `AGENTS.md`, read it first as a worked example. Vinta's lives at `ai-tools/AGENTS.md` in the bootstrap-defining repo. Note its sectioning + density before writing the target's.
+
+## Verification
+
+After writing:
+
+1. Re-read the document end-to-end — does it answer "what is this codebase, how do I work in it, what conventions matter"?
+2. Every claim cites a file or convention source.
+3. Section headings match the skeleton above (or skipped sections are explicit).
+4. Length: 200–400 lines for a typical project. Shorter = probably under-specified. Longer = probably duplicating docs/ content.
+5. `pnpm setup:ai-tools` (or whichever vendors selected) re-runs cleanly after the file is in place — confirms the symlinks point at it.
+
+## Pitfalls
+
+- **Letting analyze-codebase output dictate the prose.** The inventory is structured data; AGENTS.md is human-readable narrative. Translate, don't paste.
+- **Writing the convention "Use X library" when the project actually uses Y.** Re-read direct deps in `package.json` / `pyproject.toml` before each section.
+- **Forgetting commit / PR conventions.** The **PR + commit conventions** interview group is short and easy to skip; don't. The implement-plan / fixer agents need this.
+- **Assuming multi-tenant when single-tenant.** Re-read evidence from the **Conventions the analysis can't see → Multi-tenancy details** answer + analyze-codebase env_model.multi_tenancy. If absent, mark the section "n/a — single-tenant".