buddy-agent-harness 0.5.0 → 0.7.0

package/skills/init/SKILL.md

@@ -1,21 +1,23 @@
 ---
 name: init
 description: Use this skill when initializing, adopting, or migrating a repository's agent configuration to the open AGENTS.md and Agent Skills standards, so one canonical source works across Claude Code, Codex, Cursor, Copilot CLI, and other agent harnesses.
-argument-hint: '[--root <dir>] [--harness <names>] [--copy] [--force]'
+argument-hint: '[--root <dir>] [--harness <names>] [--copy] [--force <targets>]'
 ---
 
 # Harness Init
 
 Give the repository one canonical agent configuration — a root `AGENTS.md` and an `.agents/` tree — then bridge the harnesses that cannot read it directly.
 
-Most of the field already reads `.agents/skills/` natively: Codex, Cursor, GitHub Copilot CLI, and Devin Desktop need no projection at all. Only Claude Code and Gemini CLI read solely their own directory and need a link. Keep that asymmetry in mind — this is a consolidation job, not a copy-everywhere job.
+Most of the field already reads `.agents/skills/` natively: Codex, Cursor, GitHub Copilot CLI, Gemini CLI, and Devin Desktop need no projection at all. Only Claude Code reads solely its own directory and needs a link. Keep that asymmetry in mind — this is a consolidation job, not a copy-everywhere job.
+
+Skills and instructions are separate questions. Gemini CLI reads the canonical skills directory and still does not read `AGENTS.md`, so it needs an instruction bridge and no skills projection.
 
 `references/standard.md` defines the baseline every repository gets. Read the file below for each harness you are enabling, and only those.
 
 | Harness | Skills projection | Instruction bridge | Read |
 | --- | --- | --- | --- |
 | Claude Code | `.claude/skills` | `CLAUDE.md` with `@AGENTS.md` | `references/harnesses/claude-code.md` |
-| Gemini CLI | `.gemini/skills` | `.gemini/settings.json` edit | `references/harnesses/gemini-cli.md` |
+| Gemini CLI | none | `.gemini/settings.json` edit | `references/harnesses/gemini-cli.md` |
 | Codex | none | none | `references/harnesses/codex.md` |
 | Cursor | none | none written; one gap to report | `references/harnesses/cursor.md` |
 | GitHub Copilot CLI | none | none | `references/harnesses/copilot-cli.md` |
@@ -25,12 +27,12 @@ Most of the field already reads `.agents/skills/` natively: Codex, Cursor, GitHu
 
 ## Arguments
 
-An invocation may carry the command's own flags, most often when `doctor` hands back a repair: `/buddy-agent-harness:init --copy --force`.
+An invocation may carry the command's own flags, most often when `doctor` hands back a repair: `/buddy-agent-harness:init --copy --force .claude/skills`.
 
 Read them from the invocation itself rather than from a placeholder. Claude Code appends what the caller typed as `ARGUMENTS: <value>`, and Codex substitutes nothing at all, so on every harness the flags arrive as text you can read. Writing `$ARGUMENTS` into this body would resolve on Claude Code and stay literal everywhere else.
 
 - `--root`, `--harness`, `--copy`, `--force`, and `--format` pass through to the command in Phase 4.
-- Prose carries the same weight: "links are unavailable here" means `--copy`, and "replace the bridge" means `--force`.
+- Prose carries the same weight: "links are unavailable here" means `--copy`, and "replace the bridge" means `--force` naming that bridge.
 - An argument never skips a phase. `--force` still needs the Phase 3 approval, and the survey still runs first.
 - Say what you did not recognize and carry on. Never guess at a flag.
 
@@ -42,6 +44,8 @@ Locate the Git repository root; the canonical configuration always lives there,
 
 Inventory both the canonical surface (`AGENTS.md`, `.agents/AGENTS.md`, `.agents/skills/`, and any nested `AGENTS.md` below the root) and every pre-existing harness artifact listed in `references/detection.md`. Read what you find. Write nothing yet.
 
+Run `node scripts/doctor.mjs` for the artifacts only one harness can read. It reports each with the canonical form it is a candidate for, and that report is the list — detection lives in the command, so deriving a second one here would drift from it.
+
 ## 2. Classify
 
 Sort each finding into exactly one bucket:
@@ -50,7 +54,8 @@ Sort each finding into exactly one bucket:
 - **already linked** — a symlink resolving into `.agents/`; skip it. This is what makes re-runs idempotent.
 - **consolidatable** — harness instruction files whose content belongs in `AGENTS.md`.
 - **portable** — skill and command directories that move into `.agents/skills/`.
-- **canonical-only** — MCP servers, rules, subagents, hooks, output styles. No safe cross-harness mapping exists, so report them and leave them alone.
+- **convertible with judgment** — a rule only one harness reads. Where its guidance is generally true and the paths it names are incidental, a skill carries it to every harness; where the path scoping is the point, nothing reproduces it and the rule stays. Which of the two it is cannot be read off the file, so it is offered and never assumed.
+- **canonical-only** — subagents, hooks, output styles, MCP servers. Report them and leave them alone. For the first three there is no cross-harness format to convert into. For MCP there is a mapping, but it is not lossless — some servers cannot be expressed for some hosts, and writing one into another host's format means supplying fields the source never carried. Never convert one.
 
 ## 3. Confirm
 
@@ -58,6 +63,10 @@ Present the plan before touching anything the user wrote: what will be created,
 
 Get explicit approval before any step that deletes, replaces, or rewrites a user-authored file. Creating a missing directory, a missing `AGENTS.md`, or a `CLAUDE.md` bridge stub needs no approval, and neither does the non-material region in `references/agents-md.md` — report these rather than asking.
 
+**List every artifact only one harness can read, and ask about each one separately.** Give its path, what reads it today, and the canonical form it is a candidate for. Ask per artifact rather than for the set: they convert for different reasons and a single yes would carry files the owner never looked at. Say plainly which ones have no candidate at all — a subagent has none — so the list is not read as a queue of pending work.
+
+**A conversion that would narrow what reads the content is not offered without the bridge that prevents it.** Cursor reads `AGENTS.md` in Agent mode only, so moving `.cursorrules` there and deleting it takes that guidance out of Chat and Composer. The offer is therefore always *consolidate into `AGENTS.md` and leave a generated copy behind*, never *consolidate and delete* — `references/harnesses/cursor.md` has the detail. Where no such bridge exists, say so and leave the artifact alone.
+
 One case does need asking even though it only creates a file: a nested `AGENTS.md` that reverses a root rule, where bridging it hands Claude Code a contradiction it has no rule for resolving. Raise that file, bridge the others, and keep going.
 
 ## 4. Apply
@@ -65,15 +74,18 @@ One case does need asking even though it only creates a file: a nested `AGENTS.m
 1. Scaffold the baseline in `references/standard.md`: `.agents/`, `.agents/skills/`, and a root `AGENTS.md` if absent. Never clobber an existing one. `references/agents-md.md` decides what belongs in that file — a repository with no instruction content still needs one derived and confirmed, not an empty heading.
 2. Move approved skills and commands to `.agents/skills/<name>/SKILL.md`, preferring `git mv` so history follows. Fix frontmatter per `references/frontmatter.md` — this is where cross-harness portability is won or lost.
 3. Merge approved instruction content into `AGENTS.md`, preserving the author's wording. Append; do not restructure. Replace a harness file with a pointer only where approved. Content only some tasks need belongs in a skill, not in `AGENTS.md`.
-4. Run `node scripts/init.mjs` at the repository root, resolving that path against this skill's own directory. The launcher runs the CLI that shipped beside it, so nothing is downloaded; fall back to `npx -y buddy-agent-harness@^0.5.0 init` when the path cannot be resolved. It links `.agents/skills` into the harnesses that need it and skips those that read it natively. Add harnesses the user names with `--harness codex,gemini-cli`.
-5. If the command reports a conflict, resolve the named target and retry. Use `--force` only to replace that exact projection; use `--copy` only where links are unavailable — a copy is a snapshot, not a live projection, so say so when you fall back.
-6. Apply the instruction bridges `init` does not write. Claude Code reads `CLAUDE.md`, not `AGENTS.md` — create a `CLAUDE.md` containing `@AGENTS.md`. Gemini CLI needs `AGENTS.md` added to `context.fileName` in `.gemini/settings.json`. Both are detailed in the matching `references/harnesses/<harness>.md`; apply only the ones you enabled. Where nested `AGENTS.md` files exist, write the same stub in each directory holding one — `references/agents-md.md` covers the one case that stops for approval first.
-7. If any bridge now exists, write or restore the non-material region in `AGENTS.md` per `references/agents-md.md`, unless the markers are present and empty. Without it, an agent asked to change a skill edits `.claude/skills/<name>/SKILL.md` — which a link resolves back to canonical, but a copy silently forks. Skip this when every enabled harness reads `.agents/skills/` natively; with no bridge there is nothing to warn about.
+4. Apply the conversions that were approved, one at a time, and nothing else from the list. A rule approved as a skill moves to `.agents/skills/<name>/SKILL.md` with frontmatter per `references/frontmatter.md`; instruction content approved for consolidation is appended as in the step above and its harness file left as a generated copy. Everything declined, and everything with no candidate, stays exactly where it is.
+5. Run `node scripts/init.mjs` at the repository root, resolving that path against this skill's own directory. The launcher runs the CLI that shipped beside it, so nothing is downloaded; fall back to `npx -y buddy-agent-harness@^0.7.0 init` when the path cannot be resolved. It links `.agents/skills` into the harnesses that need it and skips those that read it natively. Add harnesses the user names with `--harness codex,gemini-cli`.
+6. If the command reports a conflict, resolve the named target and retry. Pass the target to `--force` — `--force .claude/skills` replaces that projection and reports any other conflict untouched, where a bare `--force` replaces every conflicting target at once. Reach for the bare form only when replacing all of them is what you came for. Use `--copy` only where links are unavailable — a copy is a snapshot, not a live projection, so say so when you fall back.
+7. Apply the instruction bridges `init` does not write. Claude Code reads `CLAUDE.md`, not `AGENTS.md` — create a `CLAUDE.md` containing `@AGENTS.md`. Gemini CLI needs `AGENTS.md` added to `context.fileName` in `.gemini/settings.json`. Both are detailed in the matching `references/harnesses/<harness>.md`; apply only the ones you enabled. Where nested `AGENTS.md` files exist, write the same stub in each directory holding one — `references/agents-md.md` covers the one case that stops for approval first.
+8. If any bridge now exists, write or restore the non-material region in `AGENTS.md` per `references/agents-md.md`, unless the markers are present and empty. Without it, an agent asked to change a skill edits `.claude/skills/<name>/SKILL.md` — which a link resolves back to canonical, but a copy silently forks. Skip this when every enabled harness reads `.agents/skills/` natively; with no bridge there is nothing to warn about.
 
 ## 5. Verify and report
 
 Confirm each projection resolves into `.agents/skills` and that every migrated `SKILL.md` parses and has valid frontmatter. The command reports the enabled set itself; it records nothing on disk, so there is no file to reconcile against. Report what was created, consolidated, linked, and left canonical-only.
 
+Report the artifacts only one harness can read that are still there, split by why: declined, or no canonical form to convert into. Re-running `doctor` gives the same list, and a repository works toward having none of them — that is a direction, not a state anything here blocks on.
+
 `init` is not a formatter. If the repository has one, run it over the written files and say so.
 
 Then offer to continue with the `enhance` skill, which proposes guidance the repository is missing rather than consolidating what it has. Ask once and take the answer; `init` writes no instruction content of its own either way, and `enhance` decides for itself whether anything is worth offering.
@@ -82,6 +94,8 @@ Then offer to continue with the `enhance` skill, which proposes guidance the rep
 
 - Never invent project policy, and never make a material change to a user's `AGENTS.md`. `references/agents-md.md` draws the line: a statement that would stop being true if `init`'s output were removed describes the tool's own artifact and is non-material.
 - Never convert tool settings between formats without a documented mapping. Unmapped settings stay canonical.
+- Never convert an artifact only one harness reads without asking, and never in a way that leaves fewer readers than before. The content is the user's, the conversion is a judgment about what their guidance is *for*, and a consolidation with no bridge behind it silently narrows who sees it.
+- Edit a user-authored settings file in place: change the one key or array element you came for and leave the rest byte-identical, including key order, indentation, and comments. Harnesses disagree about whether a JSON settings file may hold comments, so reading one with `JSON.parse` and writing the object back either deletes what the author wrote or produces a file the harness rejects. The matching `references/harnesses/<harness>.md` says which case a file is.
 - Symlinks belong in version control. Leave them tracked; do not add them to `.gitignore`.
 - Only `.agents/skills/` is an established convention. Do not invent `.agents/rules/`, `.agents/commands/`, or `.agents/agents/` and present them as standard.
 - Never merge a nested `AGENTS.md` into the root. Merging changes which files it governs.

package/skills/init/references/detection.md

@@ -8,11 +8,13 @@ What to look for during the survey, and where each finding belongs.
 | Nested instructions | `**/AGENTS.md` below the root, and any `**/CLAUDE.md` beside one | canonical and scoped — report, never merge upward. Bridging is per directory and per approval; see `agents-md.md` |
 | Skills | `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.github/skills/`, `.windsurf/skills/`, `.gemini/skills/` | move to `.agents/skills/`, fix frontmatter, then link back |
 | Commands | `.claude/commands/*.md`, `.cursor/commands/*.md` | move to `.agents/skills/<name>/SKILL.md`. Claude Code has merged commands into skills, so this follows the harness rather than fighting it |
-| Subagents | `.claude/agents/` | canonical-only — no cross-harness format exists. Report; leave in place |
-| Rules | `.cursor/rules/**.mdc`, `.claude/rules/`, `.windsurf/rules/` | canonical-only — `.mdc` and `.md` are not interchangeable, and path-scoping syntax differs. Report |
-| MCP servers | `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.claude/settings.json` | canonical-only. Report; never convert between formats |
+| Subagents | `.claude/agents/` | canonical-only — no cross-harness format exists. Report as having no candidate at all, so the list is not read as pending work; leave in place |
+| Rules | `.cursor/rules/**.mdc`, `.claude/rules/`, `.windsurf/rules/` | offer a skill where the paths a rule names are incidental to what it says; leave it where the path scoping is the point. `.mdc` and `.md` are not interchangeable and path-scoping has no `AGENTS.md` equivalent, so the choice is the owner's — ask per rule |
+| MCP servers | `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.claude/settings.json` | canonical-only. Report; never convert between formats. A mapping between them exists but is not lossless, and applying it means inventing fields the source did not carry |
 | Hooks, LSP, output styles | hook blocks in settings files, `.claude/output-styles/` | canonical-only. Hook event names differ by case across harnesses, so no safe projection exists. Report |
 
+`doctor` reports every artifact only one harness can read, each with the canonical form it is a candidate for. That report is the list — the table above says what each class *is*, and the command says what this repository actually has. Do not derive a second list by walking these paths yourself.
+
 For every entry, record which of three states it is in:
 
 - a real file or directory the user authored,

package/skills/init/references/harnesses/claude-code.md

@@ -47,6 +47,8 @@ Report these and do not convert them:
 - hook blocks in `.claude/settings.json` — event names differ by case across harnesses
 - MCP server definitions
 
+`.claude/settings.json` is strict JSON, the opposite of Gemini CLI's settings file: a comment is a parse error, and a settings file that fails to parse is rejected whole rather than in part. Never add one, and never offer one as a way to annotate a permission or hook entry.
+
 ## Commands
 
 `.claude/commands/*.md` are **portable** — migrate to `.agents/skills/<name>/SKILL.md`. Claude Code has merged commands into skills, so this follows the harness rather than fighting it.

package/skills/init/references/harnesses/cursor.md

@@ -14,10 +14,17 @@ Tell the user: a repository that consolidates into `AGENTS.md` keeps its instruc
 
 ## Do not
 
-- **Do not generate `.cursor/rules/*.mdc` from `AGENTS.md`.** Rules are canonical-only — `.mdc` and `.md` are not interchangeable and path-scoping has no `AGENTS.md` equivalent.
-- **Do not delete or rewrite `.cursorrules` or `.cursor/rules/**` on the assumption that `AGENTS.md` covers them.** In Chat and Composer it does not.
+- **Do not generate `.cursor/rules/*.mdc` from `AGENTS.md`.** `.mdc` and `.md` are not interchangeable and path-scoping has no `AGENTS.md` equivalent, so a generated rule would be inventing scope the source never carried.
+- **Do not delete or rewrite `.cursorrules` or `.cursor/rules/**` on the assumption that `AGENTS.md` covers them.** In Chat and Composer it does not. This is the reason a migration is *offered* rather than applied: the owner is agreeing to a trade, and they cannot agree to one nobody described.
 - Do not assert whether Cursor's `.agents/skills` discovery recurses into nested subdirectories. It is untested.
 
+## Migrating a rule, when the owner asks for it
+
+Offer, never assume, and offer the whole thing:
+
+- **A rule whose paths are incidental** — guidance that happens to name files but says something generally true — becomes a skill under `.agents/skills/`, which every harness reads. A rule whose scoping *is* the point has no equivalent; say so and leave it.
+- **Consolidating `.cursorrules` into `AGENTS.md` narrows who reads it** unless a copy stays behind for Chat and Composer. Offer the consolidation and the copy together. Never offer the consolidation alone, and never delete the file because `AGENTS.md` now carries the words.
+
 ## Frontmatter
 
 `paths`, `disable-model-invocation`, and legacy `globs` are Cursor-recognized. Other harnesses drop them — keep load-bearing behavior in the body, per `frontmatter.md`.

package/skills/init/references/harnesses/gemini-cli.md

@@ -1,18 +1,14 @@
 # Gemini CLI
 
-Reads `.agents/skills` at **user scope only**. At project scope it reads `.gemini/skills/` and nothing else, so **both bridges are required**.
+Reads `.agents/skills` at both scopes, so **skills need no bridge**. It does not read `AGENTS.md`, so **the instruction bridge is required**.
 
-Do not enable Gemini CLI speculatively — unlike Cursor, enabling it writes a real directory and symlink. Enable it only via `--harness gemini-cli` or a pre-existing `.gemini/` directory.
+## Skills — nothing to write
 
-## Bridge 1 — skills
+`.agents/skills` is read directly at project scope, where the alias takes precedence over `.gemini/skills/`. `init` writes no skills bridge for Gemini CLI.
 
-`buddy-agent-harness init` creates this when `gemini-cli` is enabled:
+An existing `.gemini/skills` symlink still resolves — that path is still scanned. Leave it; removing it is not part of enabling this harness.
 
-```
-.gemini/skills → ../.agents/skills
-```
-
-## Bridge 2 — instructions
+## Instructions — required
 
 `init` does **not** do this, and it cannot be a link. Add `AGENTS.md` to `context.fileName` in `.gemini/settings.json`:
 
@@ -30,4 +26,5 @@ When the file already exists:
 
 - Get approval first — it is user-authored.
 - Add to the array; do not replace it. Preserve surrounding settings.
+- **Comments are legal in this file.** Gemini CLI strips them before parsing, so a user's settings may carry them, and `JSON.parse` on the whole file deletes every one. Make a targeted edit to the `context.fileName` array instead of a parse-and-rewrite, and leave key order and indentation as the author left them. `.claude/settings.json` is the opposite case; see `claude-code.md`.
 - Keep `GEMINI.md` in the list if the repository still has one.

package/skills/init/scripts/doctor.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand.
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+// <package>/skills/<skill>/scripts/doctor.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+const { run } = await import(pathToFileURL(join(packageRoot, 'dist', 'cli.mjs')).href)
+
+// The subcommand is composed into a fresh argv rather than spliced into the global one, so nothing
+// outside this file observes the rewrite. Applied only when non-zero, so a usage code clibuilder
+// recorded itself is not overwritten by the zero `run` returns on that path.
+const code = await run([...process.argv.slice(0, 2), 'doctor', ...process.argv.slice(2)])
+if (code !== 0) process.exitCode = code

package/skills/init/scripts/init.mjs

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 // Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand.
 import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 // <package>/skills/<skill>/scripts/init.mjs: four levels up is the package root.
 const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+const { run } = await import(pathToFileURL(join(packageRoot, 'dist', 'cli.mjs')).href)
 
-process.argv.splice(2, 0, 'init')
-await import(join(packageRoot, 'bin', 'buddy-agent-harness.mjs'))
+// The subcommand is composed into a fresh argv rather than spliced into the global one, so nothing
+// outside this file observes the rewrite. Applied only when non-zero, so a usage code clibuilder
+// recorded itself is not overwritten by the zero `run` returns on that path.
+const code = await run([...process.argv.slice(0, 2), 'init', ...process.argv.slice(2)])
+if (code !== 0) process.exitCode = code

package/skills/repair/README.md

@@ -0,0 +1,21 @@
+# Harness Repair
+
+Correct agent configuration a repository already has that is wrong or outdated.
+
+## What it does
+
+`init` consolidates what a repository has, `enhance` offers what it is missing, and `doctor` reports what is wrong. Configuration that is present but **wrong** falls between all three, and that is what this skill takes: a harness name the registry retired, a git-ignored bridge, an `AGENTS.local.md` nothing reads, a skill whose frontmatter makes a harness skip it.
+
+Each correction is offered with the file as it stands and as it would read, and written only on approval.
+
+## Why a fourth skill rather than a `--fix` flag
+
+`doctor` stays read-only. Its whole safety property is that it never writes, which is what makes it safe to run from a session-start hook — a repair flag would forfeit that for every caller. Its **bridge** findings are all repairable with existing `init` flags, so a flag there would duplicate `init` rather than add anything; its **configuration** findings need judgment about files you wrote, which is a skill's job and not a flag's.
+
+That split also defines this skill's remit. `repair` owns what `init` deliberately refuses. Every bridge finding — including an instruction bridge that was never completed — is reported and handed to `init`, which is what writes bridges in the first place.
+
+## The line it does not cross
+
+`repair` corrects what the **tooling** decides is wrong, never what the project means. The discriminator is the one `init` already applies: content that would stop being true if this tool's output were removed is non-material, and non-material content is all this skill may correct. A statement about how the repository is worked in stays the user's, even when it is out of date — `repair` reports it and offers no write.
+
+`references/classes.md` carries the detection, the correction, and the stopping point for each class.

package/skills/repair/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: repair
+description: Use this skill when a repository's agent configuration is present but wrong or outdated — a retired harness name, a git-ignored bridge, an AGENTS.local.md nothing reads, or a skill a harness refuses to load. Runs doctor to find them, then offers each correction with its before and after and writes only what is approved.
+---
+
+# Harness Repair
+
+`init` consolidates what a repository has. `enhance` proposes what it does not. `doctor` reports what is wrong. `repair` corrects it.
+
+Each of the other three refuses this work deliberately. `init` has to run anywhere and invent nothing, so it never clobbers a file the user wrote. `enhance` only offers what is **missing**. `doctor` never writes, which is what makes it safe in a session-start hook. Configuration that is present but wrong falls between them.
+
+**`doctor` detects; this skill repairs.** Detection has one home, so the two cannot drift and the finding set can grow without touching this file. Do not detect anything yourself — run the command and repair what it reports.
+
+## 1. Diagnose
+
+```sh
+node scripts/doctor.mjs
+```
+
+That path is relative to this skill's own directory. The launcher runs the CLI that shipped beside it against the current working directory, so nothing is downloaded. Fall back to `npx -y buddy-agent-harness@^0.5.0 doctor` when the launcher cannot be resolved or run.
+
+The default output is TOON, which is what you parse. Each entry in `findings` carries three fields: `problem` (the finding's name), `path` (what it is about), and `detail` (what is wrong, in prose). The repairs are not on the row — they are lifted into `help`, which follows `findings` in order and collapses two entries only where the repair is word-for-word identical. Read a finding's repair off the matching position and confirm it by the `path` it names; where two findings sit at one path, what each repair says to do is what tells them apart.
+
+**Route on `problem`, never on `detail`.** The prose exists to be read by a person, and rewording it must not change what you do.
+
+If `findings` reports zero problems, say so and stop. There is nothing to repair.
+
+## 2. Sort what it found
+
+**Route on `problem`.** `references/classes.md` carries one section per fault this skill corrects, keyed by the `problem` name. A `problem` with a section there is yours; a `problem` without one is not. Nothing else decides it.
+
+That rule holds for every finding `doctor` reports today and for the ones it reports next year. A fault this skill has no correction for is not one it can repair, so what `classes.md` covers and what this skill owns are the same fact — and a finding added tomorrow gets reported rather than improvised on.
+
+**Do not read ownership off a skill name in `help`.** Most repairs name no skill — some are a shell invocation, some a `git` command, some a reconciliation by hand — and only the instruction and configuration families name one at all. An owner is not something the report can always be asked for.
+
+- **Findings that are yours.** Look the `problem` up in `references/classes.md`, which carries the correction and the stopping point for each.
+- **Findings that are not yours.** Report each one and pass on the repair `doctor` states for it, unchanged. **Who to hand it to is read off that repair, and the question is whether it names `init`.** Some name the `/buddy-agent-harness:init` skill and some name a `buddy-agent-harness init` command line; both mean the same thing — the finding is `init`'s, because `init` writes both kinds of bridge in the first place, and it writes the `CLAUDE.md` stub *without* asking, where everything here needs approval, and one write cannot have two homes and two contradictory approval rules. Hand it to the **skill** and never run the command yourself: rebuilding a projection can relocate skills a user wrote, and on the Windows case the naive repair is to recreate the link, the operation that already failed on that machine. A repair naming `init` in **neither** form — a `git` invocation, a reconciliation by hand, every MCP finding — is work for a person; say that rather than inferring an owner, and never rebuild over a two-sided divergence, which discards whichever side holds the newer edit.
+
+## 3. Draw the line at material content
+
+You correct what the **tooling** decides is wrong, never what the repository means.
+
+`../init/references/agents-md.md` draws the line: content that would stop being true if this tool's output were removed is **non-material**, and non-material content is all you may correct. A statement about how the repository is worked in is the user's, even when it is out of date — report it and offer no write.
+
+The clearest case is `unloadable-skill`. A `description` broken by an unquoted colon is a quoting fault — correct it. A `description` that is **missing** cannot be written without asserting what a skill you did not author does, and that claim holds whether or not this tool ever ran. Report it and ask.
+
+## 4. Offer
+
+Show the file **as it stands and as it would read**. Not a summary — the actual before and after, so the user is reading the change rather than your description of it.
+
+Where more than one correction is valid, present the options and ask which. Never pick for the user. `unread-local-override` is always this case, and its options come from `references/classes.md` — `doctor` names one repair per finding and has not read the file's contents.
+
+Do not argue past one sentence. The diff is the argument.
+
+## 5. Apply and re-run
+
+Write only what was approved, preserving the rest of the file exactly.
+
+Then **run `doctor` again**. A correction can fail to hold — a second `.gitignore` rule matching the same path, a frontmatter fix that leaves another fault behind. Re-running is how you know, and it costs nothing. When a finding survives, say it is still open rather than reporting it landed.
+
+## 6. Report
+
+Report every run, whichever way it went. One row per finding, naming its **path**, what was wrong, and its **outcome** — corrected, declined, handed to `init`, reported as material, or still open.
+
+A run that finds nothing still reports. "Nothing found" without saying `doctor` ran clean is indistinguishable from not having looked.
+
+## Rules
+
+- **Never write without approval.** There is no flag that skips it and none should be added.
+- **Never detect.** `doctor` owns detection. A check written here is a second home for it, and two homes drift.
+- **Never rebuild a bridge.** That is `doctor`'s diagnosis and `init`'s repair.
+- **Never consolidate.** Moving content into `AGENTS.md` is `init`'s and has one home.
+- **Correct only non-material content.** Project policy is the user's, even when it is wrong.
+- Local agent configuration only. Do not change workflows, GitHub Actions, repository settings, security scanning, branch rules, or unrelated project files — a retired harness name in a workflow file is not yours to rename.

package/skills/repair/references/classes.md

@@ -0,0 +1,49 @@
+# Correction classes
+
+One row per fault `doctor` reports here, with the correction and where it stops.
+
+**This file carries no detection.** `doctor` decides what is wrong; you decide how to correct it. If you find yourself checking whether a fault is present, you are doing the command's job — run it instead.
+
+Every correction below is non-material: it would stop being true if this tool's output were removed. That is what makes it correctable at all. Where a finding's correction would change what the repository *means*, report it and stop; `../../init/references/agents-md.md` draws the line.
+
+## `deprecated-harness`
+
+**Correct.** The replacement harness reads `.agents/skills/` natively and needs no projection at all, so the correction is to **delete** the reported projection — not to rename it, and not to create a new one under the new name. This is the one correction that removes a path rather than editing a file, so show what will be deleted and what will remain.
+
+**Stops at.** Everything under that harness's directory that is not the skills projection. `.windsurfrules` and any settings file are instruction artifacts; consolidating them is `init`'s. A harness name in a workflow, a README, or a comment is prose, not configuration — leave it.
+
+## `ignored-bridge`
+
+**Correct.** Narrow or remove the reported `.gitignore` rule so the bridge is tracked. Where the rule exists for something else under that directory, the correction is a negation (`!.claude/skills`) rather than a deletion — that keeps the rest of the rule doing its job.
+
+**Stops at.** Every rule that does not match a bridge path. `.gitignore` is a project file, and only the part swallowing a bridge is this tool's business.
+
+## `unread-local-override`
+
+**More than one correction is valid, so this fault always presents options and never picks.** The options come from this file, not from the report: `doctor` names one repair per finding, and choosing among these is a judgment about content it has not read.
+
+Read the file to describe the options, then offer all three:
+
+- move it to `CLAUDE.local.md` and add that to `.gitignore`, where the content is personal and Claude Code is the reader that matters;
+- hand it to `init` to consolidate into `AGENTS.md`, where the content is project guidance — that move is material, and `init`'s;
+- delete it, where it is dead.
+
+**Stops at.** The content. Read it to describe the options; never rewrite it.
+
+## `unloadable-skill`
+
+Two faults arrive under this name, and only one of them is correctable.
+
+**An unquoted colon in `description`.** Correctable: quote the value. The YAML then parses and the skill loads.
+
+**A missing or empty `description`.** **Not correctable — report it and ask.** Writing one would mean inventing a claim about what a skill you did not author does, and that claim is material: it stays true whether or not this tool ever ran. Name the skill, say why it will not load, and stop.
+
+**Stops at.** Everything below the frontmatter. The skill body is the author's. A `name` that mismatches its directory is not reported by `doctor` at all — it is a warning and the skill still loads.
+
+## Not yours: every `problem` with no section above
+
+`doctor` reports far more than this file covers: skills bridges that no longer resolve, instruction bridges that were never completed, and drift between the golden MCP server set and a harness's copy of it. None of them has a section here, and that is what says they are not yours.
+
+**Who to hand one to is read off the repair `doctor` gave it, and the question is whether it names `init`.** It names it one of two ways — the `/buddy-agent-harness:init` skill, or a `buddy-agent-harness init` command line — and both mean the finding is `init`'s, which writes both kinds of bridge in the first place and writes a `CLAUDE.md` stub *without* asking, where every correction here needs approval. Hand it to the skill; never run the command. A repair naming `init` in **neither** form is work for a person: `doctor` states it in full, and passing it on is the whole of what you do with it. Every MCP finding is that second case, as is every bridge finding a rebuild would not fix.
+
+Never infer an owner for a finding that names none. The wrong guess is always `init`, and on a two-sided divergence rebuilding is precisely what discards whichever side holds the newer edit.

package/skills/repair/scripts/doctor.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand.
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+// <package>/skills/<skill>/scripts/doctor.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+const { run } = await import(pathToFileURL(join(packageRoot, 'dist', 'cli.mjs')).href)
+
+// The subcommand is composed into a fresh argv rather than spliced into the global one, so nothing
+// outside this file observes the rewrite. Applied only when non-zero, so a usage code clibuilder
+// recorded itself is not overwritten by the zero `run` returns on that path.
+const code = await run([...process.argv.slice(0, 2), 'doctor', ...process.argv.slice(2)])
+if (code !== 0) process.exitCode = code

package/src/cli.ts

@@ -1,17 +1,50 @@
-import { cli } from 'clibuilder'
+import { readFileSync } from 'node:fs'
+import { cli, exitCodes } from 'clibuilder'
 import { doctorCommand } from './diagnose-bridges/doctor.command.ts'
 import { initCommand } from './initialize-harnesses/init.command.ts'
 
-export async function main(): Promise<void> {
-	const app = cli({
+/**
+ * Read from the manifest rather than restated here: a version written into this call is a second
+ * home for a number that already has one, and it stayed at `0.1.0` for five minor releases.
+ *
+ * `../package.json` resolves from `src/cli.ts` and from the bundled `dist/cli.mjs` alike — both sit
+ * one directory under the package root.
+ */
+const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version as string
+
+/**
+ * A factory rather than a module-level constant: `cli()` builds state, and state built at import
+ * time is shared by every later call in the process.
+ */
+function app() {
+	return cli({
 		name: 'buddy-agent-harness',
-		version: '0.1.0',
+		version,
 		description: 'Initialize agent harness skill compatibility in consumer repositories.',
 	})
+		.command(initCommand)
+		.command(doctorCommand)
+}
+
+/**
+ * The application boundary: argv in, exit code out, nothing read from or written to the process.
+ *
+ * The exit code is returned rather than written so that a caller which is not the process — a skill
+ * launcher, a test — can run a command and learn how it went. `bin/buddy-agent-harness.mjs` is the
+ * only place that turns the returned code back into a process outcome.
+ *
+ * One exit path this return cannot carry: `clibuilder` answers an unknown option or an unknown
+ * command by printing help and writing `process.exitCode` itself, returning nothing. `run` reports
+ * `0` there, which is why `bin` and the launchers apply the returned code only when it is non-zero.
+ */
+export async function run(argv: string[]): Promise<number> {
 	try {
-		await app.command(initCommand).command(doctorCommand).parse(process.argv)
+		const code = await app().parse<number | undefined>(argv)
+		return typeof code === 'number' ? code : exitCodes.success
 	} catch (error) {
-		process.stdout.write(`error: ${error instanceof Error ? error.message : 'Invalid command.'}\n`)
-		process.exitCode = 2
+		// stderr, not stdout: `doctor`'s default output is TOON that an agent parses, and an error
+		// line on that stream lands in the middle of what it is parsing.
+		process.stderr.write(`error: ${error instanceof Error ? error.message : 'Invalid command.'}\n`)
+		return exitCodes.usage
 	}
 }

package/src/command-output/command-output.ts

@@ -1,5 +1,6 @@
 import { sep } from 'node:path'
 import { encode } from '@toon-format/toon'
+import { isRecord } from '../is-record/is-record.ts'
 
 export type OutputFormat = 'json' | 'toon' | 'text'
 
@@ -21,10 +22,6 @@ function encodeResult(value: object, format: OutputFormat): string {
 	return format === 'text' ? renderText(value) : encode(value)
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
 function cell(value: unknown): string {
 	return value === undefined ? '' : String(value)
 }

package/src/diagnose-bridges/agents-files.ts

@@ -0,0 +1,34 @@
+import { type Dirent, existsSync, readdirSync } from 'node:fs'
+import { join, posix } from 'node:path'
+
+/** Directories that never hold instructions this repository is responsible for bridging. */
+const pruned = new Set(['node_modules'])
+
+/**
+ * Every directory below `root` holding an `AGENTS.md`, repository-relative and POSIX-separated,
+ * with the root itself as `''`. Sorted, root first.
+ *
+ * Dot-directories are pruned along with `node_modules`. That is not only a speed measure:
+ * `.agents/AGENTS.md` is canonical shared instructions rather than a subtree-scoped file, and
+ * bridging it would claim a scope it does not have.
+ */
+export function agentsFileDirectories(root: string): string[] {
+	const found: string[] = []
+
+	const walk = (relative: string): void => {
+		if (existsSync(join(root, relative, 'AGENTS.md'))) found.push(relative)
+		let entries: Dirent[]
+		try {
+			entries = readdirSync(join(root, relative), { withFileTypes: true })
+		} catch {
+			return
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name.startsWith('.') || pruned.has(entry.name)) continue
+			walk(relative ? posix.join(relative, entry.name) : entry.name)
+		}
+	}
+
+	walk('')
+	return found.sort()
+}