vinta-ai-workflows 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,88 @@ All notable changes to `vinta-ai-workflows` are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] — 2026-08-17
+
+### Changed
+
+- **`write-unit-test` now covers the bug-fix case.** The shipped skill body
+  gains a **Regression tests** section. A bug fix ships a test that fails
+  without the fix; when the test came second, revert the fix to check. Name the
+  test for what must not happen. Assert the cause too, when the visible symptom
+  can look right while the bug is still there. Record a state that settles
+  instead of only its final value. This adds one narrow exception to universal
+  rule 6, which otherwise keeps tests decoupled from internals. When no test can
+  cover the regression, the PR says so and a comment gives the reason.
+- **`stacks/react.md`** shows how to record a value on every render, so a bug in
+  a state that settles cannot hide behind the final UI. It also notes that
+  `waitFor` hides the same bug.
+- **`systematic-debugging`** Phase 3 accepts the case where the fix came before
+  the test: revert the fix to prove the test fails. Phase 4 covers the
+  regression no test can reach, and the verification checklist asks for the
+  revert check.
+- **`deslop-comments`** rule 2 no longer accepts a bug fix as a reason to keep
+  "not X, it's Y" framing. The regression test is the record.
+- **`AGENTS.md` now lands at the repo root as a regular file, not at
+  `ai-tools/AGENTS.md` behind a root symlink.** The doc was always *read* from
+  the root through that symlink, so its links were written as repo-root paths —
+  which broke the moment anyone opened the real file at `ai-tools/AGENTS.md`, on
+  GitHub or in an editor that follows the real path. One location means one set
+  of links that resolves for every reader. `ai-tools/` still owns skills,
+  sub-agent definitions, and the setup script; only the conventions doc moved
+  out. Mirrors the change [vintasoftware/building-blocks#403](https://github.com/vintasoftware/building-blocks/pull/403)
+  made by hand, so the next sync into that repo no longer reverts it.
+
+  Wiring that changed in
+  [`setup-ai-tools.mjs`](skills/vinta-install-ai-tools-setup/resources/setup-ai-tools.mjs):
+
+  - The script no longer creates a root `AGENTS.md` symlink. It creates the
+    per-vendor aliases instead — `CLAUDE.md → AGENTS.md` when `claude` is a
+    selected vendor, `.github/copilot-instructions.md → ../AGENTS.md` when
+    `copilot` is. Both are gated on `--only`, matching the script's own rule
+    that unlisted vendors are left untouched.
+  - `ensureSymlink` now resolves a link's target relative to the link's own
+    directory and throws when it does not exist. Before, a link to a missing
+    file was created anyway: the script printed "Symlinks ensured" and exited 0
+    while leaving a dangling link that reads as an empty instruction file to an
+    agent.
+
+  Skills link the doc as `../../../AGENTS.md` — the depth from
+  `ai-tools/skills/<name>/SKILL.md`, and the same depth through every vendor
+  symlink (`.claude/skills/<name>/SKILL.md`, `.agents/…`, `.cursor/…`,
+  `.github/…`). The `implement-plan` / `amend-plan` templates and the
+  dependency-license block previously emitted a bare `[AGENTS.md](AGENTS.md)`,
+  which resolved to a non-existent file inside the skill's own folder; the
+  `systematic-debugging` template was one level short at `../../AGENTS.md`. All
+  four are fixed.
+
+- **`vinta-write-agents-md` writes to the repo root.** Its output section now
+  states the doc's links must be repo-root-relative, and its verification adds a
+  link-resolution check run from the root.
+
+- **`vinta-install-ai-tools-setup` requires a root `AGENTS.md` up front.** The
+  prerequisite check asks for a regular file at the root and routes projects on
+  the old layout to the sync migration below.
+
+### Added
+
+- **`vinta-sync-ai-tools` migrates projects off the old layout.** New
+  `layout-migration` classification bucket — never batched with `tooling`, one
+  question of its own — plus a step-by-step migration for
+  `ai-tools/AGENTS.md` → root `AGENTS.md`: `git mv` so history follows the file,
+  link checks in both directions, a prose sweep over `ai-tools/**` for the old
+  path, and the setup-script re-run ordered *after* the move. Projects
+  bootstrapped on 0.6.0 or later skip it.
+
+  A skipped layout migration is **not** sticky the way a declined foundation
+  skill is — the next sync re-offers it. Nothing errors in the meantime: the new
+  script runs fine against the old layout, because `.github/copilot-instructions.md`
+  → `../AGENTS.md` still resolves through the surviving root symlink. That is
+  what makes the half-migrated state easy to miss, so the final report names it.
+
+- **`vinta-analyze-codebase` recognizes the legacy layout.** A root `AGENTS.md`
+  that is a symlink into `ai-tools/AGENTS.md` is recorded as a finding for the
+  sync skill to act on.
+
 ## [0.5.0] — 2026-08-05
 
 ### Changed

package/README.md

@@ -20,7 +20,7 @@ npx vinta-ai-workflows install --tool claude-code
 #   Claude Code → /vinta-bootstrap-ai-tools
 
 # 4. Review and commit the generated layout.
-git add ai-tools/ AGENTS.md .claude/ .codex/ .cursor/ .github/ .agents/
+git add ai-tools/ AGENTS.md CLAUDE.md .claude/ .codex/ .cursor/ .github/ .agents/
 git commit -m "Bootstrap ai-tools layout"
 
 # 5. Remove the builder skills — one-shot done.
@@ -53,7 +53,7 @@ After bootstrap, the project ships with **three foundation skills** that take a
    └─────────────────┘      pushed to GitHub / GitLab / etc.
 ```
 
-You also get: an `AGENTS.md` tuned to the codebase, project-specific sub-agents and skills derived from the actual stack, and per-vendor wiring so Claude Code / Codex / Cursor / Copilot all see the same artifacts.
+You also get: an `AGENTS.md` tuned to the codebase — a regular file at the repo root, with per-vendor aliases (`CLAUDE.md`, `.github/copilot-instructions.md`) symlinked to it — project-specific sub-agents and skills derived from the actual stack, and per-vendor wiring so Claude Code / Codex / Cursor / Copilot all see the same artifacts.
 
 **The project keeps getting better without re-bootstrapping.** `vinta-ai-workflows` ships new foundation skills, sharper templates, schema additions, and best-practice updates lifted from real projects. A bootstrapped repo pulls those in via [`vinta-sync-ai-tools`](#staying-in-sync-with-upstream) — one command from the AI tool, per-change `Apply` / `Skip` / `Show diff` gating, opt-outs sticky across runs, schema migrations automatic. No manual re-scaffolding, no clobbered hand-tuning, no drift between projects on the same package version. This is treated as a first-class capability of the package, not an afterthought.
 
@@ -206,7 +206,7 @@ Standalone re-invocation works at every step — kick `create-spec` again when t
 
 ## Cheat sheet — what lands in your project
 
-Quick inventory of what `vinta-bootstrap-ai-tools` writes into your repo's `ai-tools/` layout (and exposes via per-vendor wiring at `.claude/skills/`, `.agents/skills/`, etc.). Two disclaimers up front:
+Quick inventory of what `vinta-bootstrap-ai-tools` writes into your repo's `ai-tools/` layout — plus `AGENTS.md` at the repo root, the one artifact that lives outside it — and exposes via per-vendor wiring at `.claude/skills/`, `.agents/skills/`, etc. Two disclaimers up front:
 
 > **Optional foundation skills are gated by the bootstrap interview.** `systematic-debugging`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, and `handoff-to-client` ship **only** if the user says yes during `vinta-bootstrap-ai-tools` Step 0 (or later opts in via `vinta-sync-ai-tools`). They are not in every bootstrapped project. The opt-in is recorded in `.vinta-ai-workflows.yaml` under `foundation_skills.*.enabled` and is sticky across syncs.
 >
@@ -265,6 +265,8 @@ Agents write tests that pass but assert too little, mock everything, leave data
 
 Plus a "run it green, then break the code to watch it go red" step and a name-for-the-behavior / one-reason-to-fail convention.
 
+The skill also covers the bug-fix case, in a **Regression tests** section. The test has to fail without the fix, so revert the fix to check when the test came second. Name it for what must not happen. Assert the cause too, when the visible symptom can look right while the bug is still there. Record a state that settles instead of only its final value. When no test can cover the regression, the PR says so.
+
 **Framework guidance ships as best-practice packs on two independent axes**, so a project only ever receives advice for frameworks it actually uses (a FastAPI repo never gets Django guidance; a pure library gets no web-framework pack):
 
 - **Runner pack** (`resources/packs/runners/`) — how to structure, assert, and mock. One, picked by the detected test runner: `pytest`, `vitest`, or `jest`.

package/package.json

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

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

@@ -120,7 +120,7 @@
           "type": "string"
         },
         "dependency_licenses": {
-          "description": "Third-party dependency license policy. Captured at bootstrap; rendered into `ai-tools/AGENTS.md` (`## Dependency licenses` section) and the `implement-plan` / `amend-plan` skill bodies so the implementer / reviewer agents check a new dep's SPDX license against `forbidden_spdx` before running any install command (`npm add`, `pnpm add`, `pip install`, `poetry add`, `uv add`, `cargo add`, `go get`, etc.). When `enforcement: block`, the agent must refuse the install and surface the violation to the user; `warn` records the violation in the phase report but proceeds; `off` skips the check entirely.",
+          "description": "Third-party dependency license policy. Captured at bootstrap; rendered into the repo-root `AGENTS.md` (`## Dependency licenses` section) and the `implement-plan` / `amend-plan` skill bodies so the implementer / reviewer agents check a new dep's SPDX license against `forbidden_spdx` before running any install command (`npm add`, `pnpm add`, `pip install`, `poetry add`, `uv add`, `cargo add`, `go get`, etc.). When `enforcement: block`, the agent must refuse the install and surface the violation to the user; `warn` records the violation in the phase report but proceeds; `off` skips the check entirely.",
           "type": "object",
           "required": ["enforcement", "forbidden_spdx"],
           "additionalProperties": false,

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

@@ -144,7 +144,7 @@ This is a load-bearing input for the rest of the bootstrap flow — surface ever
 
 **Instruction documents** — search for any of these and capture their content:
 
-- `AGENTS.md` (root + per-app in monorepos).
+- `AGENTS.md` (root + per-app in monorepos; also the legacy `ai-tools/AGENTS.md` path).
 - `CLAUDE.md`, `.cursorrules`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`.
 - Codex / Cursor / Copilot instructions inside vendor dirs (`.codex/AGENTS.md`, etc.).
 - Anything tagged "AI conventions" / "Coding agent guide" / "LLM rules" in CONTRIBUTING / docs.
@@ -186,7 +186,8 @@ For each agent, also classify:
 
 - `ai-tools/scripts/setup-ai-tools.mjs` (Vinta canonical multi-vendor setup).
 - `package.json#scripts.setup:ai-tools` or similar alias.
-- Symlinks: `AGENTS.md → ai-tools/AGENTS.md`, `.claude/skills → ../ai-tools/skills`, etc.
+- Symlinks: `CLAUDE.md → AGENTS.md`, `.github/copilot-instructions.md → ../AGENTS.md`, `.claude/skills → ../ai-tools/skills`, etc.
+- **Legacy layout**: a root `AGENTS.md` that is a *symlink* into `ai-tools/AGENTS.md` predates the move of the doc to the repo root. Record it — [vinta-sync-ai-tools](../vinta-sync-ai-tools/SKILL.md) migrates it.
 
 **Plan/spec docs** — flag presence (full inventory comes later from [vinta-migrate-plans-specs](../vinta-migrate-plans-specs/SKILL.md)):
 

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

@@ -1,13 +1,13 @@
 ---
 name: vinta-bootstrap-ai-tools
-description: Bootstrap a project's AI-tooling layout (`ai-tools/AGENTS.md`, `ai-tools/skills/`, `ai-tools/agents/*.yaml`) plus the multi-vendor setup script that wires the canonical sources into Claude Code, Cursor, Codex, and VS Code Copilot. Project-agnostic — adapts to whatever stack it finds. Detects langs, frameworks, build tools, deploy paths, multi-tenancy patterns, and CI conventions, interviews the user for the gaps, then drafts AGENTS.md, the foundation sub-agents (implementer / reviewer / fixer), and a starter set of project-specific skills. Stack-specific skill + agent templates (Medplum, Django, …) live as resources and get copied when the detected stack matches. Use when invoked in a fresh repo that doesn't yet have an `ai-tools/` directory, or to refresh an existing one. Orchestrates several sub-skills — see "Sub-skill flow" below.
+description: Bootstrap a project's AI-tooling layout (root `AGENTS.md`, `ai-tools/skills/`, `ai-tools/agents/*.yaml`) plus the multi-vendor setup script that wires the canonical sources into Claude Code, Cursor, Codex, and VS Code Copilot. Project-agnostic — adapts to whatever stack it finds. Detects langs, frameworks, build tools, deploy paths, multi-tenancy patterns, and CI conventions, interviews the user for the gaps, then drafts AGENTS.md, the foundation sub-agents (implementer / reviewer / fixer), and a starter set of project-specific skills. Stack-specific skill + agent templates (Medplum, Django, …) live as resources and get copied when the detected stack matches. Use when invoked in a fresh repo that doesn't yet have an `ai-tools/` directory, or to refresh an existing one. Orchestrates several sub-skills — see "Sub-skill flow" below.
 ---
 
 # Bootstrap AI tools
 
 This skill produces, in the target repo:
 
-- `ai-tools/AGENTS.md` — universal project conventions read by Claude Code, Cursor, Codex, Copilot.
+- `AGENTS.md` at the **repo root** — universal project conventions read by Claude Code, Cursor, Codex, Copilot. The one AI-tooling doc that lives outside `ai-tools/`: the tools expect it at the root, and its relative links only resolve for every reader from there.
 - `ai-tools/skills/<name>/SKILL.md` — domain-specific skills (always: foundation set + stack-matched copies).
 - `ai-tools/agents/<name>.yaml` — vendor-agnostic sub-agent definitions; the setup script materializes per-vendor copies.
 - `ai-tools/scripts/setup-ai-tools.mjs` + a `pnpm setup:ai-tools` (or equivalent) script alias.
@@ -20,7 +20,7 @@ Project-agnostic. Adapts to whatever the analysis finds. Stack-specific skill +
 This orchestrator runs six sub-skills in order. Each is its own SKILL.md so it can be invoked standalone (e.g. to refresh just AGENTS.md without redoing analysis from scratch).
 
 1. [vinta-analyze-codebase](../vinta-analyze-codebase/SKILL.md) — walk the repo, build a structured inventory: languages, frameworks, build tools, test frameworks, deploy targets, monorepo shape, env model, multi-tenancy patterns, CI providers. Outputs an in-memory inventory the rest of the flow consumes.
-2. [vinta-write-agents-md](../vinta-write-agents-md/SKILL.md) — synthesize `ai-tools/AGENTS.md` from the inventory + a focused interview for what the analysis can't see.
+2. [vinta-write-agents-md](../vinta-write-agents-md/SKILL.md) — synthesize the root `AGENTS.md` from the inventory + a focused interview for what the analysis can't see.
 3. [vinta-derive-subagents](../vinta-derive-subagents/SKILL.md) — author `ai-tools/agents/*.yaml`. Always emits the foundation trio (`implementer`, `reviewer`, `fixer`); adds stack-specific specialists when the user supplies a template for a matched stack.
 4. [vinta-derive-skills](../vinta-derive-skills/SKILL.md) — author `ai-tools/skills/*/SKILL.md`. Always copies the project-agnostic foundation set (`plan-feature`, `create-spec`, `create-qa-use-cases`) verbatim from its bundled resources. Generates `implement-plan` from a parameterized template using project specifics. Asks the user whether the optional `add-e2e-test` and `add-env-var` skills are needed. Asks for stack-specific templates per matched stack.
 5. [vinta-install-ai-tools-setup](../vinta-install-ai-tools-setup/SKILL.md) — copy the canonical `setup-ai-tools.mjs` into `ai-tools/scripts/`, wire the package script alias, run setup, verify all vendor paths resolve.
@@ -43,7 +43,7 @@ The bootstrap orchestrator doesn't need to invoke it directly. It just needs to
 - Repo has a partial setup and the user wants to refresh / extend it. (This orchestrator is idempotent in spirit — sub-skills read what's there before writing.)
 - Forking the Vinta conventions into a new project.
 
-If the repo already has `ai-tools/AGENTS.md`, **do not overwrite** without explicit confirmation. The orchestrator's first interview question covers this.
+If the repo already has an `AGENTS.md` (at the root, or at the legacy `ai-tools/AGENTS.md` path), **do not overwrite** without explicit confirmation. The orchestrator's first interview question covers this.
 
 ## Interview (Step 0 — before any sub-skill runs)
 
@@ -147,8 +147,8 @@ If the user answers "No" to any of the seven, that skill won't ship. If the user
 For each artifact, read it (frontmatter + body), then ask the user via `AskUserQuestion`:
 
 - **Instruction docs** (`AGENTS.md`, `CLAUDE.md`, etc.):
-  - `Merge into new ai-tools/AGENTS.md` — `vinta-write-agents-md` folds existing content into the canonical sections, preserving anything still accurate.
-  - `Keep as-is, link from ai-tools/AGENTS.md` — leave the file in place, reference it.
+  - `Merge into new AGENTS.md` — `vinta-write-agents-md` folds existing content into the canonical sections at the repo root, preserving anything still accurate.
+  - `Keep as-is, link from AGENTS.md` — leave the file in place, reference it.
   - `Replace from scratch` — discard existing, draft fresh from inventory + interview.
 
 - **Skills** (each under any vendor `skills/` dir):
@@ -173,7 +173,7 @@ Scan the repo root for `DESIGN.md` (case-insensitive). Per [Design.md with Curso
 
 If present, ask via `AskUserQuestion`:
 
-- `Keep and wire into AI tooling` (recommended) — leave file untouched at repo root; reference it from `ai-tools/AGENTS.md`; when `cursor` is in **Scope → Vendor coverage**, write `.cursor/rules/design.mdc` (Cursor Project Rules, Option A from the linked blog post) so Cursor auto-loads it before generating UI files.
+- `Keep and wire into AI tooling` (recommended) — leave file untouched at repo root; reference it from `AGENTS.md`; when `cursor` is in **Scope → Vendor coverage**, write `.cursor/rules/design.mdc` (Cursor Project Rules, Option A from the linked blog post) so Cursor auto-loads it before generating UI files.
 - `Keep as-is, don't reference` — leave the file alone; no AGENTS.md mention, no Cursor rule.
 - `Drop` — delete (rare; confirm twice before removing).
 
@@ -391,12 +391,14 @@ No skill / agent content lives in `resources/stacks/<stack>/`. That's by design
 After Step 0.5 + all six sub-skills run, the target repo has:
 
 ```
+AGENTS.md                                   ← project conventions, at the repo root as a regular
+                                              file (not under ai-tools/, not a symlink) so its
+                                              relative links resolve for every reader
 .vinta-ai-workflows.yaml                    ← single source of truth (Step 0.5)
                                               schema: schemas/vinta-ai-workflows-config.v1.schema.json
 .vinta-ai-workflows/                        ← gitignored local state (only when systematic-debugging enabled)
 └── cache.yaml                              ← MCP preflight cache, schema: mcp-preflight-cache.v1.schema.json
 ai-tools/
-├── AGENTS.md
 ├── skills/
 │   ├── plan-feature/SKILL.md            ← always (copied verbatim from derive-skills resources)
 │   ├── create-spec/SKILL.md             ← always (copied verbatim)
@@ -448,7 +450,7 @@ ai-plans/                                 ← created by migrate-plans-specs (st
                                             write to this layout)
 ```
 
-Plus the symlinks + per-vendor generated files, set up by the install step.
+Plus the symlinks + per-vendor generated files, set up by the install step. The doc aliases among them (`CLAUDE.md`, `.github/copilot-instructions.md`) point at the root `AGENTS.md` and are created only for selected vendors.
 
 Foundation skills break into three buckets — see [vinta-derive-skills](../vinta-derive-skills/SKILL.md) for the full mechanics:
 
@@ -481,7 +483,7 @@ Stack-specific skills + agents land in the target only when the user provides te
 
 After all sub-skills finish:
 
-1. `ls -la ai-tools/` — confirm AGENTS.md, skills/, agents/, scripts/ all exist.
+1. `ls -la AGENTS.md ai-tools/` — confirm root `AGENTS.md` is a regular file and `ai-tools/` has skills/, agents/, scripts/.
 2. `node ai-tools/scripts/setup-ai-tools.mjs` — runs cleanly, no errors.
 3. Each selected vendor's directory has the expected files: `.claude/agents/*.md`, `.cursor/agents/*.md`, `.github/agents/*.agent.md`, `.codex/agents/*.toml`.
 4. Spot-check one skill, one agent: open SKILL.md / `<agent>.yaml` and confirm content describes THIS project (not a copy-pasted template with `<placeholder>` strings).

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

@@ -189,7 +189,7 @@ The remaining per-shell placeholders:
 | `{{FRAMEWORK_PACK_LOADER_BLOCK}}` | derived from the packs shipped (write-unit-test only) | bullets pointing at each shipped pack, runner first then stacks: `- Runner: **pytest** → read [resources/packs/runners/pytest.md](resources/packs/runners/pytest.md).` then `- Stack: **Django** → read [resources/packs/stacks/django.md](resources/packs/stacks/django.md).` (one bullet per matched stack). When only the runner shipped, emit just its bullet plus `- No stack pack matched — apply the universal rules and mirror the nearest existing tests.` When no pack shipped at all, render that single fallback line alone. |
 | `{{PROJECT_TEST_PREFERENCES_BLOCK}}` | derived from `skills.write-unit-test.{test_style,data_setup,assertion_style,db_isolation}` (write-unit-test only) | one bullet per field whose value is **not** `framework-default`, phrased as an instruction: `test_style: classes` → `- Group tests in test classes (not standalone functions).`; `data_setup: factories` → `- Build test data with factory classes / builders, not inline literals or fixture files.`; `assertion_style: plain-assert` → `- Use plain \`assert\` (not \`self.assertEqual\`-family methods).`; `db_isolation: transaction-rollback` → `- Isolate DB state with transaction rollback (each test in a rolled-back transaction).`. Emit `- No project-specific overrides — follow the framework pack's defaults.` when all four are `framework-default`. |
 | `{{ADDITIONAL_CONVENTIONS_BLOCK}}` | derived from `skills.write-unit-test.additional_conventions[]` (write-unit-test only) | when non-empty: a `### Additional project conventions` sub-block listing each entry as a bullet, verbatim. Empty string (whole block omitted) when the array is empty. Starts with a leading blank line so it slots cleanly under the preferences block. |
-| `{{DEPENDENCY_LICENSE_BLOCK}}` | derived from `policies.dependency_licenses` | Top-level `## Adding new third-party dependencies` section. Empty string when `enforcement: off` or the block is absent. When `block` / `warn`: short paragraph naming the enforcement mode + the forbidden SPDX list + the pre-install check (`npm view <pkg> license`, PyPI metadata, etc.) + a one-line pointer to the **Dependency licenses** section in [AGENTS.md](AGENTS.md) for the full table including `allowed_overrides` and `notes`. See [resources/dependency-license-block.md](resources/dependency-license-block.md) for the canonical body. |
+| `{{DEPENDENCY_LICENSE_BLOCK}}` | derived from `policies.dependency_licenses` | Top-level `## Adding new third-party dependencies` section. Empty string when `enforcement: off` or the block is absent. When `block` / `warn`: short paragraph naming the enforcement mode + the forbidden SPDX list + the pre-install check (`npm view <pkg> license`, PyPI metadata, etc.) + a one-line pointer to the **Dependency licenses** section in the root `AGENTS.md` — linked as `../../../AGENTS.md`, the depth from `ai-tools/skills/<name>/SKILL.md` — for the full table including `allowed_overrides` and `notes`. See [resources/dependency-license-block.md](resources/dependency-license-block.md) for the canonical body. |
 | `{{DEPENDENCY_LICENSE_LAYER1_CHECK}}` | derived from `policies.dependency_licenses` | Layer 1 review checklist item. Empty string when `enforcement: off`. When `block` / `warn`: `6. **Dependency license scan**: \`git diff package.json pyproject.toml ...\` (project-relevant manifests) — for every added dep look up its SPDX license (\`npm view <pkg> license\`, PyPI metadata, repo \`LICENSE\`). A license in \`policies.dependency_licenses.forbidden_spdx\` and not in \`allowed_overrides\` is a BLOCKER (when \`block\`) or a SHOULD-FIX (when \`warn\`). A missing / \`UNKNOWN\` / undeclared license is **always a BLOCKER** regardless of enforcement mode — there is no override to silently bless undisclosed terms.` |
 | `{{DEPENDENCY_LICENSE_RULE_LINE}}` | derived from `policies.dependency_licenses` | Important-rules bullet. Empty string when `enforcement: off`. When `block`: `- **License check before any new dep.** Refuse \`npm add\` / \`pnpm add\` / \`pip install\` / \`poetry add\` / \`uv add\` / \`cargo add\` / \`go get\` when the package's SPDX license is in the forbidden list — see AGENTS.md **Dependency licenses**. User can grant a one-off override after acknowledging the violation; record the override in \`policies.dependency_licenses.allowed_overrides\` before re-running.` When `warn`: same line but `Proceed but record the violation in the phase report` instead of `Refuse`. |
 | `{{COMMIT_STRATEGY_*}}` family (`{{COMMIT_STRATEGY_STEP0_QUESTION}}`, `{{COMMIT_STRATEGY_STEP0_TRAILER}}`, `{{COMMIT_STRATEGY_CONFIRM_NOTE}}`, `{{BRANCH_NAMING_PATTERN_SUMMARY}}`, `{{BRANCH_NAMING_BLOCK}}`, `{{PER_PHASE_COMMIT_BLOCK}}`, `{{PR_OPEN_TIMING_BLOCK}}`, `{{PRS_CONTEXT_FILE_PATH}}`, `{{TRACKING_BRANCH_FIELD}}`, `{{TRACKING_PHASE_BRANCH_FIELD}}`, `{{FINAL_REPORT_BRANCH_SUMMARY}}`, `{{BRANCH_CHECKLIST_LINE}}`, `{{COMMIT_STRATEGY_CHECKLIST_BLOCK}}`, `{{BRANCH_PUSH_HEADING}}`) | Step 0 (`policies.commit_strategy`) | Render based on the project's commit strategy (`stacked-branches` / `modular-commits` / `ask`). Multi-line blocks now come from the commit-strategy partials; see the substitution table immediately after this row. |

package/skills/vinta-derive-skills/resources/dependency-license-block.md

@@ -11,7 +11,7 @@ The rendered section sits **directly before** `## Working instructions` so subag
 ```markdown
 ## Adding new third-party dependencies
 
-Before running any install command (`npm add`, `pnpm add`, `yarn add`, `pip install`, `poetry add`, `uv add`, `cargo add`, `go get`, `gem install`, equivalents), check the package's SPDX license against the project's forbidden list — see the **Dependency licenses** section in [AGENTS.md](AGENTS.md) for the full list, the per-package overrides, and any project-specific notes.
+Before running any install command (`npm add`, `pnpm add`, `yarn add`, `pip install`, `poetry add`, `uv add`, `cargo add`, `go get`, `gem install`, equivalents), check the package's SPDX license against the project's forbidden list — see the **Dependency licenses** section in [AGENTS.md](../../../AGENTS.md) for the full list, the per-package overrides, and any project-specific notes.
 
 Quick lookup:
 

package/skills/vinta-derive-skills/resources/foundation-skills/deslop-comments/SKILL.md

@@ -22,7 +22,7 @@ Do not expand scope to a file just because the agent `Read` it or reviewed it in
 Rules 1-5 are usually reworded. Rules 6-12 are usually deleted.
 
 1. **Dense, multi-clause sentences** that try to explain everything at once instead of one idea per sentence. Split a sentence that adds a second thought.
-2. **Negative / before-state framing** - describing removed code, or leading with "not X" when X was never the point. Keep "not X, it's Y" only for a genuine edge case or a non-obvious gotcha.
+2. **Negative / before-state framing** - describing removed code, or leading with "not X" when X was never the point. Keep "not X, it's Y" only for a genuine edge case or a non-obvious gotcha. A regression test records a bug fix; a comment does not. Keep a comment about a bug fix only when no test can cover the regression, and then say why.
 3. **AI buzzwords** in place of plain software engineering vocabulary. Common offenders and their replacements:
    - `gate` / `gates` / `gating` → "check", "decides whether to show...", "authentication check", "feature check"
    - `guard` → "check" / "prevent"

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

@@ -11,7 +11,7 @@ The flow is destructive (force-push). Every modification is gated on user confir
 
 ## Working assumptions
 
-- Repo: {{PROJECT_NAME}} ({{STACK_SUMMARY}}). Conventions: [AGENTS.md](AGENTS.md).
+- Repo: {{PROJECT_NAME}} ({{STACK_SUMMARY}}). Conventions: [AGENTS.md](../../../AGENTS.md).
 - Plan files: [`{{PLAN_DIR}}/YYYY-MM-DD-FEATURE_NAME_PLAN.md`]({{PLAN_DIR}}/).
 - Lint: `{{LINT_CMD}}`. Format: `{{FORMAT_CMD}}`.
 - Type / build gate: `{{BUILD_CMD}}`{{TYPECHECK_NOTE}}.

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

@@ -17,7 +17,7 @@ Execution counterpart to [plan-feature](../plan-feature/SKILL.md). Plan = contra
 
 ## Working assumptions
 
-- Repo: {{PROJECT_NAME}} ({{STACK_SUMMARY}}). Conventions: [AGENTS.md](AGENTS.md).
+- Repo: {{PROJECT_NAME}} ({{STACK_SUMMARY}}). Conventions: [AGENTS.md](../../../AGENTS.md).
 - Plan files: [`{{PLAN_DIR}}/YYYY-MM-DD-FEATURE_NAME_IMPLEMENTATION_PLAN.md`]({{PLAN_DIR}}/).
 - Lint: `{{LINT_CMD}}`. Format: `{{FORMAT_CMD}}`.
 - Type / build gate: `{{BUILD_CMD}}`{{TYPECHECK_NOTE}}.

package/skills/vinta-derive-skills/resources/systematic-debugging-template.md

@@ -108,6 +108,7 @@ Goal: a single hypothesis, a single failing test, no speculative changes.
    - New test file: `{{NEW_TEST_CMD_PATTERN}}`
    - Scoped suite: `{{SCOPED_TEST_PATTERN}}`
    - The test must fail today for the same reason production fails. A test that fails for a different reason is a different bug.
+   - If the fix came before the test, because you found the cause while patching, prove it the other way round: revert the fix, run the test, confirm it fails, then restore the fix. Write the test first when you can — a test that has never failed proves nothing.
 3. Make the smallest possible change. One variable. No drive-by refactors. No "while I'm here".
 4. Re-run the failing test. Did it go green? Re-run the scoped suite — did anything else go red?
 5. If the test stays red, do **not** stack a second change on top. Return to Phase 1 with the new evidence (the test plus what it shows) and re-state the cause.
@@ -128,6 +129,7 @@ Goal: ship the fix at the right level of abstraction with the right safety net.
 4. **Route the fix diff through the shared review gate.** Invoke [review-phase](../review-phase/SKILL.md) — the same three-layer review (mechanical checks, plan/intent-compliance walkthrough, independent reviewer subagent) + fix loop that [implement-plan](../implement-plan/SKILL.md) and [amend-plan](../amend-plan/SKILL.md) use — passing the fix diff, the one-sentence root cause + the new failing-then-passing test as the "body" to walk against, and `WORKROOT` = the current checkout. A bug fix is not done until review-phase returns clean. (When this skill runs *inside* implement-plan's inner/outer loop, the enclosing phase's review-phase already covers this — don't double-review; the standalone invocation is for bugs debugged outside a plan.)
 5. **Verify on the observability side after deploy.** The error fingerprint from Phase 0 should stop firing. If the platform supports it, mark the issue resolved in the source MCP tool so a regression re-opens it instead of creating a duplicate.
 6. **Document if the fix is non-obvious.** A comment is justified only when the *why* would surprise the next reader — a hidden invariant, a workaround for a known upstream bug, a constraint not visible from the call site. Don't narrate the change.
+7. **When no test can cover the regression**, say so in the PR and leave a comment with the reason. This is the exception to item 6.
 
 ## Stop conditions — count your attempts
 
@@ -159,13 +161,13 @@ When this skill runs inside [implement-plan](../implement-plan/SKILL.md) (the in
 
 For the review gate in Phase 4, this skill shares [review-phase](../review-phase/SKILL.md) with implement-plan and amend-plan — one review implementation across all three, so a bug fix meets the same three-layer bar as any planned phase.
 
-For new test scaffolding, defer to the project's test conventions captured in [AGENTS.md](../../AGENTS.md). For env / config issues uncovered in Phase 0, route to the project's `add-env-var` skill if shipped (`{{PROJECT_SKILLS_LIST}}`).
+For new test scaffolding, defer to the project's test conventions captured in [AGENTS.md](../../../AGENTS.md). For env / config issues uncovered in Phase 0, route to the project's `add-env-var` skill if shipped (`{{PROJECT_SKILLS_LIST}}`).
 
 ## Verification checklist (apply before claiming a bug fixed)
 
 1. Phase 0 evidence stored or linked in the PR description (trace id / issue link / dashboard URL).
 2. Root cause stated in one sentence in the PR description.
-3. New failing-then-passing test cited by file:line.
+3. New failing-then-passing test cited by file:line. It fails before the fix, and reverting the fix makes it fail again.
 4. Full local gate green: `{{LINT_CMD}}` + `{{BUILD_CMD}}` + `{{TEST_CMD}}`{{E2E_OUTER_GATE_CHECKLIST}}.
 5. [review-phase](../review-phase/SKILL.md) run on the fix diff and returned clean (unless the fix landed inside an implement-plan phase already covered by its review-phase).
 6. Observability source updated post-deploy (issue resolved / alert acknowledged) so a recurrence pages instead of silently re-opening.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/react.md

@@ -18,6 +18,11 @@ Component-testing idioms with React Testing Library. Loaded **only when the proj
 - Mock HTTP at the network layer with **MSW** (see the runner pack), so components run their real fetch path. For a component that loads data, `await screen.findBy...` the settled UI rather than mocking the fetching hook.
 - Pure logic (reducers, formatters, custom hooks without UI) — test directly, no render. Hooks: `renderHook` + `act`.
 
+## Regression tests on state that settles
+
+- When the bug is a wrong intermediate state that ends up correct, asserting the final UI passes even with the bug present. Record the value on every render instead: push it to an array inside the `renderHook` callback, or from a test-only child in a rendered tree. Then assert the whole sequence — `expect(states).toEqual(["loading", "ready"])` catches the extra skeleton that `findByText` never sees.
+- `await waitFor` hides the same bug. It retries until the assertion passes, so it cannot see a state that was wrong and then corrected.
+
 ## Isolation
 
 - Clean up is automatic per test with the Testing Library auto-cleanup; don't share rendered state between tests. Reset mocks in `afterEach` (see runner pack).

package/skills/vinta-derive-skills/resources/write-unit-test-template.md

@@ -1,6 +1,6 @@
 ---
 name: write-unit-test
-description: Write a unit test for a function, method, class, or module in {{PROJECT_NAME}} ({{STACK_SUMMARY}}) — mock only genuine externals, assert the full output (not counts/truthiness), clean up created data or roll back the transaction, never hit a service unavailable in dev/test, keep test logic literal, stay decoupled from internals. Applies this project's test preferences and the runner + stack packs for {{FRAMEWORK_PACKS_LIST}}. Use on "add a test", "write a unit test", "cover this with tests", or when new behavior lands uncovered.
+description: Write a unit test for a function, method, class, or module in {{PROJECT_NAME}} ({{STACK_SUMMARY}}) — mock only genuine externals, assert the full output (not counts/truthiness), clean up created data or roll back the transaction, never hit a service unavailable in dev/test, keep test logic literal, stay decoupled from internals. Applies this project's test preferences and the runner + stack packs for {{FRAMEWORK_PACKS_LIST}}. A bug fix gets a regression test that fails without the fix. Use on "add a test", "write a unit test", "cover this with tests", "add a regression test", or when new behavior lands uncovered.
 ---
 
 # Write a unit test
@@ -29,6 +29,16 @@ A test should fail when the behavior breaks and pass when it's correct — nothi
 8. **Kill nondeterminism** — control every entropy source (clock, randomness, timezone/locale, iteration/DB order, concurrency). Freeze/inject them; a test that passes only sometimes is worse than none.
 9. **Cover the branches, not just the happy path** — aim high (95%+ branch coverage): each error path, guard, and edge (empty, boundary, null) gets a case. Coverage is the floor, correct assertions are the point.
 
+## Regression tests
+
+A test that exists because of a bug has a second job: fail again if the bug comes back. A comment does not fail when the code changes; a test does.
+
+- **Check that it fails without the fix.** Write the test first and watch it fail. If the fix came first, revert the fix, run the test, confirm it fails, then restore the fix. A test that passes with and without the fix protects nothing. This goes wrong most often with timing and cache-key bugs, where the assertion can run too early to see the broken state.
+- **Name it for what must not happen**, in behavior terms, so the failure line reads as a description of the bug: `keeps the rows on screen across a sort flip instead of falling back to the skeleton`, not `sorts the ids`.
+- **Assert the cause too, when the visible symptom can look right while the bug is still there.** For a cache-key bug, assert that the query ran once, not only that the screen showed the right rows. Keep the assertion on what the user sees and add the one about the cause next to it. This is the only exception to rule 6.
+- **Watch states that settle.** When the bug is a wrong intermediate state that ends up correct, asserting the final state passes even with the bug present. Record the value on every update and assert the whole sequence instead. The stack pack shows how to do this for this project's framework.
+- **When no test can cover the regression**, or the test would cost far more than it protects, say so in the PR and leave a comment with the reason. This is the only case where a comment stands in for a test.
+
 ## Project preferences
 
 Apply these; `framework-default` defers to the pack. If the existing suite contradicts a preference, follow the preference for new tests and flag it — don't rewrite old tests.

package/skills/vinta-install-ai-tools-setup/SKILL.md

@@ -5,7 +5,7 @@ description: Install the multi-vendor `setup-ai-tools.mjs` script in the target
 
 # Install ai-tools setup
 
-The setup script reads `ai-tools/AGENTS.md`, `ai-tools/skills/`, and `ai-tools/agents/*.yaml` (canonical sources) and emits per-vendor copies + symlinks. This skill installs the script + its package wiring + runs it for the first time.
+The setup script reads root `AGENTS.md`, `ai-tools/skills/`, and `ai-tools/agents/*.yaml` (canonical sources) and emits per-vendor copies + symlinks. This skill installs the script + its package wiring + runs it for the first time.
 
 ## Output
 
@@ -16,7 +16,7 @@ The setup script reads `ai-tools/AGENTS.md`, `ai-tools/skills/`, and `ai-tools/a
 
 ## Inputs
 
-- `ai-tools/AGENTS.md` (from [vinta-write-agents-md](../vinta-write-agents-md/SKILL.md))
+- `AGENTS.md` at the repo root (from [vinta-write-agents-md](../vinta-write-agents-md/SKILL.md))
 - `ai-tools/agents/*.yaml` (from [vinta-derive-subagents](../vinta-derive-subagents/SKILL.md))
 - `ai-tools/skills/<name>/SKILL.md` (from [vinta-derive-skills](../vinta-derive-skills/SKILL.md))
 - Step 0 vendor selection from the [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md#a-scope) **Scope → Vendor coverage** answer.
@@ -25,7 +25,9 @@ The setup script reads `ai-tools/AGENTS.md`, `ai-tools/skills/`, and `ai-tools/a
 
 ### 1. Prerequisite check
 
-`ai-tools/AGENTS.md` exists. `ai-tools/agents/*.yaml` has at least the foundation trio (`implementer`, `reviewer`, `fixer`). `ai-tools/skills/` is non-empty.
+`AGENTS.md` exists at the repo root — as a **regular file**, not a symlink. `ai-tools/agents/*.yaml` has at least the foundation trio (`implementer`, `reviewer`, `fixer`). `ai-tools/skills/` is non-empty.
+
+If the project predates the move to the root (a root `AGENTS.md` symlink pointing at `ai-tools/AGENTS.md`), migrate before running the script — `git mv ai-tools/AGENTS.md AGENTS.md` after deleting the symlink, then fix the relative links inside the doc and the links pointing at it from `ai-tools/**`. [vinta-sync-ai-tools](../vinta-sync-ai-tools/SKILL.md) does this as a guided migration.
 
 If any are missing → stop. Route the user back to the relevant sub-skill ([vinta-write-agents-md](../vinta-write-agents-md/SKILL.md), [vinta-derive-subagents](../vinta-derive-subagents/SKILL.md), [vinta-derive-skills](../vinta-derive-skills/SKILL.md)).
 
@@ -92,7 +94,7 @@ Expected output: list of symlinks ensured, list of generated per-vendor files, l
 
 For each vendor in the user's selection:
 
-- **Claude Code**: `ls .claude/agents/` lists every agent's `.md`. `ls .claude/skills/` (or `ls -L`) lists every skill dir. `cat AGENTS.md` resolves to the canonical content.
+- **Claude Code**: `ls .claude/agents/` lists every agent's `.md`. `ls .claude/skills/` (or `ls -L`) lists every skill dir. `cat CLAUDE.md` resolves to the root `AGENTS.md` content.
 - **Cursor**: `ls .cursor/agents/` + `ls .cursor/skills/`. Open Cursor and check that the agent + skill panels surface them.
 - **VS Code Copilot**: `ls .github/agents/` lists `*.agent.md`. `ls .github/skills/` lists skill dirs. `cat .github/copilot-instructions.md` resolves to the canonical AGENTS.md.
 - **Codex**: `ls .codex/agents/` lists `*.toml`. Each TOML opens cleanly + has `name` / `description` / `sandbox_mode` / `developer_instructions` fields.
@@ -105,8 +107,8 @@ Stage:
 - `ai-tools/` (canonical sources + script)
 - `package.json` (script alias + yaml dep)
 - `pnpm-lock.yaml` / `package-lock.json` / `yarn.lock` (after install)
-- `AGENTS.md` (root symlink)
-- `.claude/`, `.cursor/`, `.github/agents/`, `.github/skills/`, `.github/copilot-instructions.md`, `.codex/agents/`, `.agents/skills/` — whichever vendors selected
+- `AGENTS.md` (regular file at the repo root)
+- `CLAUDE.md`, `.claude/`, `.cursor/`, `.github/agents/`, `.github/skills/`, `.github/copilot-instructions.md`, `.codex/agents/`, `.agents/skills/` — whichever vendors selected
 
 Commit message style matches the project's convention captured during the bootstrap interview's **Project conventions** group. Default: `Bootstrap ai-tools layout (AGENTS.md, skills, sub-agents, vendor wiring)`.
 
@@ -117,7 +119,7 @@ The setup script is **selective by vendor** but **destructive within a vendor**:
 - For vendors in `--only` (or all four by default): the script `rm -rf` the target dir and regenerates. Hand-edits to per-vendor files are lost.
 - For vendors NOT in `--only`: the script leaves their files untouched.
 
-**Always edit the canonical sources** (`ai-tools/agents/*.yaml`, `ai-tools/skills/`, `ai-tools/AGENTS.md`). Generated vendor files are derived; they get overwritten on the next run.
+**Always edit the canonical sources** (`ai-tools/agents/*.yaml`, `ai-tools/skills/`, root `AGENTS.md`). Generated vendor files are derived; they get overwritten on the next run.
 
 ## Pitfalls
 
@@ -134,5 +136,5 @@ Final smoke test:
 1. `pnpm setup:ai-tools` runs cleanly, no errors.
 2. Spot-check one agent file in each selected vendor — content matches the canonical YAML.
 3. Spot-check one skill — the skill description shows up in the vendor's UI (Claude `/help`, Cursor agent panel, Copilot chat slash menu, Codex slash menu).
-4. Edit `ai-tools/AGENTS.md` (add a comment line). Confirm the change appears in `cat AGENTS.md` (root symlink) + each selected vendor's instruction-file path.
+4. Edit `AGENTS.md` (add a comment line). Confirm the change appears at each selected vendor's instruction-file path (`CLAUDE.md`, `.github/copilot-instructions.md`).
 5. Edit `ai-tools/agents/implementer.yaml` (e.g. tweak description). Re-run setup. Confirm changes propagate to all selected vendor agent files.

package/skills/vinta-install-ai-tools-setup/resources/setup-ai-tools.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-// Setup script: wire ai-tools/{AGENTS.md,skills,agents/*.yaml} into every supported vendor.
+// Setup script: wire AGENTS.md + ai-tools/{skills,agents/*.yaml} into every supported vendor.
 //
 // Source of truth:
-//   - ai-tools/AGENTS.md           — universal project conventions (markdown).
+//   - AGENTS.md                    — universal project conventions (markdown). Lives at the
+//                                    repo root so its relative links resolve for every reader.
 //   - ai-tools/skills/<name>/      — universal skills (SKILL.md format converges across
 //                                    Claude Code, Cursor, Codex, VS Code Copilot — symlinked).
 //   - ai-tools/agents/<name>.yaml  — vendor-agnostic sub-agent definitions. This script
@@ -10,7 +11,7 @@
 //                                    format each tool expects (markdown, .agent.md, .toml).
 //
 // What this script does:
-//   1. Symlinks ai-tools/AGENTS.md + ai-tools/skills/ into each vendor's expected paths.
+//   1. Symlinks AGENTS.md + ai-tools/skills/ into each vendor's expected paths.
 //   2. Reads each ai-tools/agents/<name>.yaml.
 //   3. For every supported vendor, generates a target file with vendor-specific frontmatter
 //      / format. Vendor-specific overrides come from the YAML's `overrides:<vendor>:` block;
@@ -122,6 +123,12 @@ const DEFAULTS = {
 // ── Helpers ──────────────────────────────────────────────────────────────
 
 function ensureSymlink(target, linkPath) {
+  // `target` is relative to the link's own directory, so resolve it from there.
+  // A missing target would produce a broken link that reads as empty to an agent.
+  const resolved = join(dirname(linkPath), target);
+  if (!existsSync(resolved)) {
+    throw new Error(`[setup-ai-tools] cannot link ${linkPath} → ${target}: ${resolved} does not exist`);
+  }
   mkdirSync(dirname(linkPath), { recursive: true });
   let existing;
   try {
@@ -285,21 +292,27 @@ function emitCodex(name, doc, body) {
 
 const gitignoreAdded = ensureGitignoreEntries(['.vinta-ai-workflows/']);
 
-// ── Stage 1: stable symlinks (skills + AGENTS.md) ────────────────────────
+// ── Stage 1: stable symlinks (skills + vendor doc aliases) ───────────────
 
-// Universal anchors — always set up regardless of --only selection.
-ensureSymlink('ai-tools/AGENTS.md', 'AGENTS.md');
+// AGENTS.md is a real file at the repo root. Each vendor that reads it under a
+// different filename gets a symlink below.
+//
+// Skills are symlinked into .agents/, .claude/, .cursor/, and .github/, so a
+// SKILL.md always sits at <top-level-dir>/skills/<name>/SKILL.md — three levels
+// below the root through every path. That is why SKILL.md files link the doc as
+// `../../../AGENTS.md`. Keep new skills dirs at <top-level-dir>/skills.
 ensureSymlink('../ai-tools/skills', '.agents/skills');
 
 // Vendor-specific symlinks — gated on SELECTED.
 if (SELECTED.has('claude')) {
+  ensureSymlink('AGENTS.md', 'CLAUDE.md');
   ensureSymlink('../ai-tools/skills', '.claude/skills');
 }
 if (SELECTED.has('cursor')) {
   ensureSymlink('../ai-tools/skills', '.cursor/skills');
 }
 if (SELECTED.has('copilot')) {
-  ensureSymlink('../ai-tools/AGENTS.md', '.github/copilot-instructions.md');
+  ensureSymlink('../AGENTS.md', '.github/copilot-instructions.md');
   ensureSymlink('../ai-tools/skills', '.github/skills');
 }
 // Codex shares `.agents/skills` (already linked above) — no extra symlink needed.
@@ -367,9 +380,9 @@ if (gitignoreAdded.length) {
 }
 
 console.log('Symlinks ensured:');
-console.log('  AGENTS.md                          → ai-tools/AGENTS.md');
 console.log('  .agents/skills                     → ../ai-tools/skills');
 if (SELECTED.has('claude')) {
+  console.log('  CLAUDE.md                          → AGENTS.md');
   console.log('  .claude/skills                     → ../ai-tools/skills');
 }
 if (SELECTED.has('cursor')) {
@@ -377,7 +390,7 @@ if (SELECTED.has('cursor')) {
 }
 if (SELECTED.has('copilot')) {
   console.log('  .github/skills                     → ../ai-tools/skills');
-  console.log('  .github/copilot-instructions.md    → ../ai-tools/AGENTS.md');
+  console.log('  .github/copilot-instructions.md    → ../AGENTS.md');
 }
 console.log('');
 

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

@@ -58,6 +58,7 @@ For each change record, decide its bucket:
 | `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. |
+| `layout-migration` | The project's on-disk layout has to move before the new surface works. Never batched — one question, with the file moves listed. See "One-time migrations" below. |
 
 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).
 
@@ -126,9 +127,11 @@ In order:
 
 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.
+4. **`layout-migration` accepts** — run the migration from "One-time migrations" below **before** the setup script, so the script wires the vendors against the final layout.
 
-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.
+5. **`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.
+
+6. 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
 
@@ -165,6 +168,40 @@ Run on first sync against a project without `.vinta-ai-workflows.yaml`:
 
 Then re-enter step 1 of the main flow.
 
+## One-time migrations
+
+### `ai-tools/AGENTS.md` → root `AGENTS.md` (0.6.0)
+
+**Detect**: root `AGENTS.md` is a symlink (`test -L AGENTS.md`) and `ai-tools/AGENTS.md` exists. A project bootstrapped on 0.6.0 or later already has the doc at the root as a regular file — skip.
+
+**Why**: the doc was read from the root through the symlink, so its links were written as repo-root paths. That broke them whenever the real file was opened at `ai-tools/AGENTS.md` — on GitHub, in a file tree, in any editor that follows the real path. Moving the file to the root makes one set of links correct everywhere.
+
+**Steps** — ask once via `AskUserQuestion` (`Apply` / `Skip` / `Show the file list`), then:
+
+1. `rm AGENTS.md` (the symlink), `git mv ai-tools/AGENTS.md AGENTS.md`. Use `git mv` so the file's history follows it.
+2. Fix links **inside** the doc. They were already repo-root-relative, so most need no change — but verify every one from the root:
+
+   ```bash
+   grep -noE '\]\(([^)]+)\)' AGENTS.md | sed -E 's/\]\(//; s/\)$//' | while IFS=: read -r line target; do
+     path="${target%%#*}"
+     case "$path" in http*|"") continue ;; esac
+     [ -e "$path" ] || echo "BROKEN line $line: $target"
+   done
+   ```
+
+3. Fix links **pointing at** the doc from inside `ai-tools/`. Every `ai-tools/skills/<name>/SKILL.md` sits three levels below the root, so the link is `../../../AGENTS.md`. Files at other depths (e.g. `ai-tools/rules/*.md`, two levels down) need `../../AGENTS.md`. Bare `[AGENTS.md](AGENTS.md)` links inside a skill folder were always broken — they resolved to a non-existent sibling — and get the same fix.
+4. Rewrite prose references to the old path in the canonical sources: `ai-tools/agents/*.yaml`, `ai-tools/skills/**/SKILL.md`, any `ai-tools/rules/*.md`. `ai-tools/AGENTS.md` → `AGENTS.md`.
+5. Re-run the setup script so the vendor aliases repoint: `CLAUDE.md → AGENTS.md` (claude), `.github/copilot-instructions.md → ../AGENTS.md` (copilot). The generated vendor agent files under `.claude/agents/`, `.cursor/agents/`, `.github/agents/`, `.codex/agents/` are regenerated from the YAMLs in step 4 — don't hand-edit them.
+6. Confirm nothing live still points at the old path:
+
+   ```bash
+   grep -rn "ai-tools/AGENTS.md" --exclude-dir=node_modules --exclude-dir=.git .
+   ```
+
+   Historical records (`ai-plans/*.md`, changelogs, past plan docs) are dated snapshots — leave them. Surface the list to the user and let them decide.
+
+**Order matters**: run this migration *before* `setup-ai-tools.mjs`. Running the new script against the old layout leaves `.github/copilot-instructions.md` pointing at `../AGENTS.md`, which resolves through the surviving root symlink — it works, but hides the fact that the migration hasn't happened.
+
 ## 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.
@@ -173,6 +210,7 @@ Then re-enter step 1 of the main flow.
 - **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.
+- **A `layout-migration` skipped but the tooling batch applied.** The setup script runs fine against the pre-migration layout, so nothing errors — the project just sits half-migrated, with skill links still written for the old depth. Record the skip in the final report and re-offer the migration on the next sync (unlike a skipped foundation skill, a layout migration is not sticky).
 
 ## Verification
 
@@ -182,3 +220,4 @@ Then re-enter step 1 of the main flow.
 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.
+7. **Layout migration applied**: `AGENTS.md` is a regular file at the root, `ai-tools/AGENTS.md` is gone, `grep -rn "ai-tools/AGENTS.md"` returns only historical records, and both link checks in "One-time migrations" print nothing.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Synthesize the repo-root `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. Lives at the repo root so Claude Code, Cursor, Codex, VS Code Copilot all read it natively and its relative links resolve for every reader.
 ---
 
 # Write AGENTS.md
@@ -9,7 +9,11 @@ The canonical project-conventions document. Read by every AI tool. Single source
 
 ## Output
 
-`ai-tools/AGENTS.md`. The setup script symlinks `AGENTS.md` at root and `.github/copilot-instructions.md` to it.
+`AGENTS.md` at the **repo root**, as a regular file — not inside `ai-tools/`, not a symlink. Every other AI-tooling artifact lives under `ai-tools/`; this one doc is the exception, because the tools that read it expect it at the root and because its relative links must resolve the same way whether an agent reads it from the root or a human opens it on GitHub.
+
+The setup script symlinks the per-vendor aliases to it: `CLAUDE.md` (when `claude` is a selected vendor) and `.github/copilot-instructions.md` (when `copilot` is).
+
+Write the doc's internal links as **repo-root-relative paths** (`ai-tools/rules/testing.md`, `docs/ARCHITECTURE.md`) — that is what resolves from the root. Skills that link *back* to it from `ai-tools/skills/<name>/SKILL.md` use `../../../AGENTS.md`.
 
 ## Inputs
 
@@ -197,7 +201,7 @@ VAR_TWO
 
 ## 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.
+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 the root of the bootstrap-defining repo. Note its sectioning + density before writing the target's.
 
 ## Verification
 
@@ -207,7 +211,17 @@ After writing:
 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.
+5. Every relative link in the doc resolves **from the repo root** — the script that checks it, run from the root, prints nothing:
+
+   ```bash
+   grep -noE '\]\(([^)]+)\)' AGENTS.md | sed -E 's/\]\(//; s/\)$//' | while IFS=: read -r line target; do
+     path="${target%%#*}"
+     case "$path" in http*|"") continue ;; esac
+     [ -e "$path" ] || echo "BROKEN line $line: $target"
+   done
+   ```
+
+6. `pnpm setup:ai-tools` (or whichever vendors selected) re-runs cleanly after the file is in place — confirms the vendor aliases point at it. The script throws if `AGENTS.md` is missing from the root.
 
 ## Pitfalls