buddy-agent-harness 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/.claude-plugin/plugin.json +2 -2
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +1 -1
  4. package/README.md +1 -1
  5. package/dist/cli.mjs +14193 -24818
  6. package/dist/index.d.mts +11 -9
  7. package/dist/index.d.mts.map +1 -1
  8. package/dist/index.mjs +183 -772
  9. package/dist/index.mjs.map +1 -1
  10. package/dist/skill-scripts/doctor.mjs +122 -180
  11. package/dist/skill-scripts/init.mjs +122 -180
  12. package/dist/skill-scripts/mcp.mjs +122 -180
  13. package/llms.txt +11 -8
  14. package/package.json +4 -4
  15. package/plugin.json +2 -2
  16. package/skills/doctor-buddy-agent-harness/README.md +1 -1
  17. package/skills/doctor-buddy-agent-harness/SKILL.md +3 -3
  18. package/skills/doctor-buddy-agent-harness/references/bridges.md +2 -2
  19. package/skills/doctor-buddy-agent-harness/references/configuration.md +4 -4
  20. package/skills/doctor-buddy-agent-harness/references/instructions.md +6 -6
  21. package/skills/doctor-buddy-agent-harness/references/judgment/claude-code.md +64 -0
  22. package/skills/doctor-buddy-agent-harness/references/judgment/codex.md +19 -0
  23. package/skills/doctor-buddy-agent-harness/references/judgment/copilot-cli.md +16 -0
  24. package/skills/doctor-buddy-agent-harness/references/judgment/cursor.md +36 -0
  25. package/skills/doctor-buddy-agent-harness/references/judgment/devin-desktop.md +19 -0
  26. package/skills/doctor-buddy-agent-harness/references/judgment/gemini-cli.md +30 -0
  27. package/skills/doctor-buddy-agent-harness/references/mcp.md +4 -4
  28. package/skills/doctor-buddy-agent-harness/references/nonstandard.md +4 -4
  29. package/skills/doctor-buddy-agent-harness/scripts/doctor.mjs +122 -180
  30. package/skills/enhance/SKILL.md +5 -5
  31. package/skills/enhance/references/agents-md.md +150 -0
  32. package/skills/enhance/references/detection.md +36 -0
  33. package/skills/enhance/references/global-instructions.md +33 -0
  34. package/skills/enhance/scripts/doctor.mjs +122 -180
  35. package/skills/init-buddy-agent-harness/SKILL.md +1 -1
  36. package/skills/init-buddy-agent-harness/scripts/doctor.mjs +122 -180
  37. package/skills/init-buddy-agent-harness/scripts/init.mjs +122 -180
  38. package/skills/repair/SKILL.md +3 -3
  39. package/skills/repair/references/agents-md.md +150 -0
  40. package/skills/repair/references/classes.md +2 -2
  41. package/skills/repair/scripts/doctor.mjs +122 -180
  42. package/skills/repair/scripts/mcp.mjs +122 -180
  43. package/src/cli.ts +22 -4
  44. package/src/command-output/command-output.ts +15 -55
  45. package/src/dep-plugins/dep-plugins.command.ts +8 -14
  46. package/src/dep-plugins/dep-plugins.ts +1 -1
  47. package/src/dep-plugins/resolve.ts +1 -1
  48. package/src/diagnose-bridges/doctor-guidance.ts +64 -54
  49. package/src/diagnose-bridges/doctor.command.ts +12 -22
  50. package/src/governance-overrides/governance-overrides.ts +18 -8
  51. package/src/governance-overrides/governance.command.ts +19 -37
  52. package/src/harness-registry/harness-registry.ts +3 -4
  53. package/src/index.ts +5 -8
  54. package/src/initialize-harnesses/init.command.ts +9 -19
  55. package/src/initialize-harnesses/initialize-harnesses.ts +2 -2
  56. package/src/project-mcp/mcp.command.ts +14 -25
  57. package/src/reconcile-mcp/reconcile.command.ts +15 -26
  58. package/src/references/references.ts +6 -6
  59. package/dist/dist-ktNZ1sJo.mjs +0 -2966
  60. package/dist/esm-BMqwcD7W.mjs +0 -87
  61. package/dist/esm-CVacKtt6.mjs +0 -64
package/llms.txt CHANGED
@@ -21,13 +21,16 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
21
21
  - [`buddy-agent-harness mcp project`](https://repobuddy.github.io/buddy-agent-harness/cli/mcp/): Project the golden MCP server set into each enabled harness. A dry run unless --write; never overwrites a change made on the harness side.
22
22
  - [`buddy-agent-harness mcp reconcile`](https://repobuddy.github.io/buddy-agent-harness/cli/mcp/): Import a harness-side MCP change into the golden set, one approved field at a time. A dry run unless --accept names a field.
23
23
  - [`buddy-agent-harness dep-plugins`](https://repobuddy.github.io/buddy-agent-harness/cli/dep-plugins/): Derive the marketplace catalog for plugins shipped by this repository’s dependencies, so a harness can install them. Writes the catalog; installing is the harness’s own job.
24
- - [`buddy-agent-harness reference`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Read on-demand reference documents by name, layered across the managed, project, user, and plugin tiers, and start or delete one in the project or user tier.
25
- - [`buddy-agent-harness reference show`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Print one or more references, each resolved through the tiers and combined as its layers ask.
26
- - [`buddy-agent-harness reference list`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): List every layer, and every reference at every layer that holds it, marked used or shadowed.
24
+ - [`buddy-agent-harness reference`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Read reference documents by name, composed from the managed, project, user, plugin, and default tiers, and write, select, or delete a contribution.
25
+ - [`buddy-agent-harness reference show`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Print one or more references, each composed from its contributions as their extends and merge declare.
26
+ - [`buddy-agent-harness reference list`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): List every reference name, one row each, with its description, and its status when not found. A pattern keeps only the names it matches exactly.
27
27
  - [`buddy-agent-harness reference search`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Find references by name, description, tags, headings, or body, best match first.
28
- - [`buddy-agent-harness reference where`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): List the project and user files an override of a reference can be written to, highest precedence first, with the copy each overrides and who it applies to.
29
- - [`buddy-agent-harness reference create`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Start a new reference in the project or user tier from a template, marked merge-sections when it overrides a copy below. Never overwrites.
30
- - [`buddy-agent-harness reference delete`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Delete the project or user copy of a reference, and report which copy answers the name afterwards. Never deletes a plugin-shipped or managed copy.
28
+ - [`buddy-agent-harness reference where`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Give the project and user files a customization or a selection of a reference is written to, who each reaches, and the heading paths of the document below each.
29
+ - [`buddy-agent-harness reference create`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Start a contribution in the project or user tier, or in a plugin's or a skill's source folder, from a template or an interface. Never overwrites a file with a body.
30
+ - [`buddy-agent-harness reference select`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Choose what a name builds on: write an `extends` listing the options, bottom first, in the project or user file. Its body and other keys are kept.
31
+ - [`buddy-agent-harness reference delete`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Delete a project or user contribution, or one in a plugin's or a skill's source folder, and report what answers the name afterwards. Never deletes an installed or managed one.
32
+ - [`buddy-agent-harness reference implementations`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): List the implementations of an interface a consumer can load, each with its pin, description, and unsupported sections.
33
+ - [`buddy-agent-harness reference check`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Check interface documents and their implementations, each composed as `show` composes it. With no names, checks every one found. Exits 1 on any failure.
31
34
  - [`buddy-agent-harness governance`](https://repobuddy.github.io/buddy-agent-harness/cli/governance/): Deprecated: use `reference`. Read the governance documents the project, user, and machine-wide override layers hold. Read-only.
32
35
  - [`buddy-agent-harness governance list`](https://repobuddy.github.io/buddy-agent-harness/cli/governance/): List every governance the override layers hold, each at the layer that would win.
33
36
  - [`buddy-agent-harness governance show`](https://repobuddy.github.io/buddy-agent-harness/cli/governance/): Print one governance document, resolved through the layers in order.
@@ -76,8 +79,8 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
76
79
 
77
80
  ## Optional
78
81
 
79
- - [Library: `@cyberuni/agent-harness`](https://repobuddy.github.io/buddy-agent-harness/library/references/): exports `listReferences`, `managedReferencesDir`, `parseReferenceName`, `resolveReference`, `searchReferences`, type `MatchKind`, type `MergeMode`, type `ReferenceLayer`, type `ReferenceListing`, type `ReferenceName`, type `ReferenceRow`, type `ReferenceStatus`, type `ReferenceTier`, type `ResolvedReference`, type `ResolveOptions`, type `SearchMatch`, type `TraceEntry`, type `UsedLayer`.
80
- - [Library: `@cyberuni/agent-harness/commands`](https://repobuddy.github.io/buddy-agent-harness/library/references/): exports type `ReferenceListReport`, type `ReferenceSearchReport`, type `ReferenceShowEntry`.
82
+ - [Library: `cyber-agentkit`](https://repobuddy.github.io/buddy-agent-harness/library/references/): exports `listReferences`, `parseReferenceName`, `resolveReference`, `searchReferences`, type `MatchKind`, type `ReferenceLayer`, type `ReferenceListing`, type `ReferenceListLayerRow`, type `ReferenceListRow`, type `ReferenceName`, type `ReferenceStatus`, type `ReferenceTier`, type `ResolvedReference`, type `ResolveOptions`, type `SearchMatch`.
83
+ - [Library: `cyber-agentkit/commands`](https://repobuddy.github.io/buddy-agent-harness/library/references/): exports type `ReferenceListReport`, type `ReferenceSearchReport`, type `ReferenceShowEntry`.
81
84
  - [Library: `cli.ts`](https://repobuddy.github.io/buddy-agent-harness/library/init/): exports `run`.
82
85
  - [Library: `diagnose-bridges/diagnose-bridges.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `diagnoseBridges`, type `BridgeFinding`, type `BridgeKind`, type `BridgeReport`, type `BridgeStatus`, type `DiagnoseOptions`, type `DiagnoseResult`, type `DivergenceReport`.
83
86
  - [Library: `diagnose-bridges/diagnose-global-instructions.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `diagnoseGlobalInstructions`, type `GlobalInstructionKind`, type `GlobalInstructionReport`, type `GlobalInstructionStatus`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "buddy-agent-harness",
3
- "version": "0.20.0",
3
+ "version": "0.22.0",
4
4
  "description": "Initialize standards-based agent configuration across agent harnesses",
5
5
  "keywords": [
6
6
  "repobuddy",
@@ -35,6 +35,7 @@
35
35
  "dist",
36
36
  "src",
37
37
  "!**/*.{test,spec}.ts",
38
+ "!**/*.test-helper.ts",
38
39
  "skills",
39
40
  "plugin.json",
40
41
  "llms.txt",
@@ -46,15 +47,14 @@
46
47
  "node": ">=22"
47
48
  },
48
49
  "dependencies": {
49
- "@cyberuni/agent-harness": "^0.5.0",
50
- "clibuilder": "^11.3.0",
50
+ "clibuilder": "^12.0.0",
51
+ "cyber-agentkit": "^1.0.0",
51
52
  "jsonc-parser": "^3.3.1",
52
53
  "smol-toml": "^1.8.0",
53
54
  "toml-eslint-parser": "^1.0.3",
54
55
  "yaml": "^2.9.0"
55
56
  },
56
57
  "devDependencies": {
57
- "@toon-format/toon": "^4.1.1",
58
58
  "@types/node": "^24.12.4",
59
59
  "@vitest/coverage-v8": "^5.0.0",
60
60
  "tsdown": "^0.23.0",
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "buddy-agent-harness",
4
- "version": "0.20.0",
4
+ "version": "0.22.0",
5
5
  "description": "Initialize standards-based agent configuration across agent harnesses",
6
6
  "author": {
7
7
  "name": "repobuddy"
@@ -13,7 +13,7 @@
13
13
  "extensions": {
14
14
  "org.cyberuni.universal-plugin": {
15
15
  "skills": "./skills/",
16
- "dependencies": ["cyber-agent-harness"],
16
+ "dependencies": ["cyber-agentkit"],
17
17
  "harnesses": {
18
18
  "claude-code": {},
19
19
  "cursor": {
@@ -7,7 +7,7 @@ Report whether the harness skill bridges in a repository still resolve into `.ag
7
7
  `init` points every harness that cannot read `.agents/skills` at that directory, normally with a directory-level symlink. `doctor` re-checks each of those bridges after the fact and names the repair for whatever it finds. The command names an `init` invocation for a person at a shell; the skill hands the same repair to the `init-buddy-agent-harness` skill, because rebuilding a bridge can move skills a user wrote.
8
8
 
9
9
  ```sh
10
- npx -y buddy-agent-harness doctor
10
+ npx -y buddy-agent-harness@0.22.0 doctor
11
11
  ```
12
12
 
13
13
  ## Why it exists
@@ -17,7 +17,7 @@ Diagnose it:
17
17
  node scripts/doctor.mjs
18
18
  ```
19
19
 
20
- That path is relative to this skill's own directory: `scripts/doctor.mjs` is a self-contained bundle built from this package's source and shipped inside the skill folder through the npm package, so it runs against the current working directory with nothing downloaded and no `node_modules` needed. Fall back to `npx -y buddy-agent-harness@^0.20.0 doctor` when `scripts/doctor.mjs` is missing or cannot be run — the case for a skill installed from git rather than from the npm package, which does not carry the bundle.
20
+ That path is relative to this skill's own directory: `scripts/doctor.mjs` is a self-contained bundle built from this package's source and shipped inside the skill folder through the npm package, so it runs against the current working directory with nothing downloaded and no `node_modules` needed. Fall back to `npx -y buddy-agent-harness@0.22.0 doctor` when `scripts/doctor.mjs` is missing or cannot be run — the case for a skill installed from git rather than from the npm package, which does not carry the bundle.
21
21
 
22
22
  The command is read-only. It never repairs anything, so it is safe to run at any point, including from a session-start hook.
23
23
 
@@ -36,9 +36,9 @@ The command is read-only. It never repairs anything, so it is safe to run at any
36
36
 
37
37
  `command` is empty whenever no single invocation does the job, and that emptiness is the signal: act on `instruction` and do not assemble a command out of it. A runnable invocation quoted *inside* an `instruction` is not the repair either — `diverged-both` names `git diff --no-index` because the diff shows you what differs, not because running it reconciles anything. Apply the repair, then re-run `doctor`.
38
38
 
39
- Nothing in `help` is wrapped. An earlier version prefixed every repair with `Run`, which read as an instruction to paste prose into a shell.
39
+ Nothing in `help` is wrapped.
40
40
 
41
- Do not run an `init` command yourself. Rebuilding a skills bridge can move skills a user wrote, and rewriting an instruction file touches prose a person authored — both are the `init-buddy-agent-harness` skill's judgment, so hand the repair to `/buddy-agent-harness:init-buddy-agent-harness` instead. Every such repair carries an empty `command`: a skill invocation has no shell equivalent at all.
41
+ Do not run an `init` command yourself. Rebuilding a skills bridge can move skills a user wrote, and rewriting an instruction file touches prose a person authored — both are the `init-buddy-agent-harness` skill's judgment, so hand the repair to `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`) instead. Every such repair carries an empty `command`: a skill invocation has no shell equivalent at all.
42
42
 
43
43
  When every bridge resolves, `findings` says so outright rather than being empty.
44
44
 
@@ -4,8 +4,8 @@
4
4
 
5
5
  | Finding | What it means | Repair |
6
6
  | --- | --- | --- |
7
- | `no-canonical` | the canonical skill directory does not exist, so no bridge can resolve | run `/buddy-agent-harness:init-buddy-agent-harness`, which creates `.agents/skills` and the bridges |
8
- | `missing` | no bridge at this path — the harness sees zero project skills | run `/buddy-agent-harness:init-buddy-agent-harness` |
7
+ | `no-canonical` | the canonical skill directory does not exist, so no bridge can resolve | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`), which creates `.agents/skills` and the bridges |
8
+ | `missing` | no bridge at this path — the harness sees zero project skills | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`) |
9
9
  | `degraded` | expected a directory but found a regular file — checkout without core.symlinks | run `/buddy-agent-harness:init-buddy-agent-harness --copy --force <path>` |
10
10
  | `stale` | symlink does not resolve to .agents/skills | run `/buddy-agent-harness:init-buddy-agent-harness --force <path>` |
11
11
  | `diverged-bridge` | only the bridge changed since the two last agreed — an agent wrote through the copy | replace .agents/skills with <path> to keep the newer edit, then run `/buddy-agent-harness:init-buddy-agent-harness --force <path>` |
@@ -6,7 +6,7 @@ The bridges resolve, and the configuration around them is still wrong: a superse
6
6
 
7
7
  | Finding | What it means | Repair |
8
8
  | --- | --- | --- |
9
- | `deprecated-harness` | a projection under a harness name that has been superseded — the replacement reads .agents/skills natively and needs no projection at all | run `/buddy-agent-harness:repair` |
10
- | `ignored-bridge` | a .gitignore rule matches this bridge — an untracked bridge swallows a real edit silently | run `/buddy-agent-harness:repair` |
11
- | `unread-local-override` | no harness reads this filename, so everything in it is invisible to every agent | run `/buddy-agent-harness:repair` |
12
- | `unloadable-skill` | frontmatter that does not parse, or no description — either one makes a harness skip the skill outright | run `/buddy-agent-harness:repair` |
9
+ | `deprecated-harness` | a projection under a harness name that has been superseded — the replacement reads .agents/skills natively and needs no projection at all | run `/buddy-agent-harness:repair` (pnpm install: `pnpm-buddy-agent-harness-repair`) |
10
+ | `ignored-bridge` | a .gitignore rule matches this bridge — an untracked bridge swallows a real edit silently | run `/buddy-agent-harness:repair` (pnpm install: `pnpm-buddy-agent-harness-repair`) |
11
+ | `unread-local-override` | no harness reads this filename, so everything in it is invisible to every agent | run `/buddy-agent-harness:repair` (pnpm install: `pnpm-buddy-agent-harness-repair`) |
12
+ | `unloadable-skill` | frontmatter that does not parse, or no description — either one makes a harness skip the skill outright | run `/buddy-agent-harness:repair` (pnpm install: `pnpm-buddy-agent-harness-repair`) |
@@ -6,12 +6,12 @@ Two shapes, one section. A **bridge** is what a harness needs before it can read
6
6
 
7
7
  | Finding | What it means | Repair |
8
8
  | --- | --- | --- |
9
- | `no-instructions` | no AGENTS.md at the repository root, so the instructions this repository has reach one harness at most | run `/buddy-agent-harness:init-buddy-agent-harness`, which consolidates or derives AGENTS.md |
10
- | `instructions-missing` | no instruction bridge at this path — the harness reads none of AGENTS.md | run `/buddy-agent-harness:init-buddy-agent-harness` |
11
- | `instructions-unbridged` | the file is present but names AGENTS.md nowhere — the harness reads none of it | run `/buddy-agent-harness:init-buddy-agent-harness`, which adds the bridge without discarding what the file already says |
12
- | `instructions-shadowing` | this file suppresses the AGENTS.md beside it — the harness reads this instead, and none of AGENTS.md | run `/buddy-agent-harness:init-buddy-agent-harness`, which consolidates the file into AGENTS.md or imports AGENTS.md from it |
13
- | `instructions-superseded` | a bridge from before the harness read AGENTS.md itself — it still works, and nothing needs it | run `/buddy-agent-harness:init-buddy-agent-harness`, which offers to remove it |
14
- | `instructions-unreadable` | the settings file does not parse, so the harness reads none of it | fix the JSON by hand, then run `/buddy-agent-harness:init-buddy-agent-harness` |
9
+ | `no-instructions` | no AGENTS.md at the repository root, so the instructions this repository has reach one harness at most | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`), which consolidates or derives AGENTS.md |
10
+ | `instructions-missing` | no instruction bridge at this path — the harness reads none of AGENTS.md | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`) |
11
+ | `instructions-unbridged` | the file is present but names AGENTS.md nowhere — the harness reads none of it | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`), which adds the bridge without discarding what the file already says |
12
+ | `instructions-shadowing` | this file suppresses the AGENTS.md beside it — the harness reads this instead, and none of AGENTS.md | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`), which consolidates the file into AGENTS.md or imports AGENTS.md from it |
13
+ | `instructions-superseded` | a bridge from before the harness read AGENTS.md itself — it still works, and nothing needs it | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`), which offers to remove it |
14
+ | `instructions-unreadable` | the settings file does not parse, so the harness reads none of it | fix the JSON by hand, then run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`) |
15
15
 
16
16
  `unbridged` is the one to read carefully. The file is there and looks fine, and it names `AGENTS.md` nowhere — a `.gemini/settings.json` another tool rewrote without `AGENTS.md` in `context.fileName`. Never fix it by replacing the file: the content that displaced the bridge may be the only copy of something.
17
17
 
@@ -0,0 +1,64 @@
1
+ # Claude Code
2
+
3
+ Reads `AGENTS.md`, and does not read `.agents/skills/`. **One bridge is required, and one file has to be got out of the way.**
4
+
5
+ ## Bridge — skills
6
+
7
+ `buddy-agent-harness init` creates this:
8
+
9
+ ```
10
+ .claude/skills → ../.agents/skills
11
+ ```
12
+
13
+ If the directory-level link ever fails, fall back to documented per-skill symlinks (`.claude/skills/<name>` → the canonical skill directory).
14
+
15
+ ## Instructions — no bridge, one file to clear
16
+
17
+ From v2.1.277 Claude Code reads `AGENTS.md` as its project instructions, with no import, no symlink, and no setting. **Never write a `CLAUDE.md`.**
18
+
19
+ It reads it *conditionally*, and the condition is the whole of what this skill has to act on. Claude Code reads `AGENTS.md` only where it finds none of these in the working directory or any directory above it:
20
+
21
+ | File | What it does to `AGENTS.md` |
22
+ | --- | --- |
23
+ | `CLAUDE.md` | read instead of it |
24
+ | `.claude/CLAUDE.md` | read instead of it |
25
+ | `CLAUDE.local.md` | read instead of it |
26
+ | `~/.claude/CLAUDE.md`, a managed `CLAUDE.md`, `.claude/rules/` | nothing — these load alongside |
27
+
28
+ A file carrying an `@AGENTS.md` import is the exception that costs nothing: the canonical file arrives through the import, and Claude Code never reads it twice. So the three dispositions are:
29
+
30
+ - **a body of its own** — consolidate it into `AGENTS.md` and remove it, or leave it holding an import above whatever is genuinely Claude-only.
31
+ - **only `@AGENTS.md`, or a symlink to it** — the bridge this tool used to write. Offer to remove it; it is not wrong to keep.
32
+ - **`CLAUDE.local.md`** — personal and not yours to move. Offer an `@AGENTS.md` import at the top of it, and nothing else.
33
+
34
+ **Sessions that still need the import.** Reading `AGENTS.md` directly is unavailable on a Claude Code before v2.1.277, on a third-party provider such as Amazon Bedrock, with telemetry disabled, in the first session after an install or upgrade, and where hooks or the built-in `agents-md` plugin are disabled. There the import is the only way in — which is why a superseded file is offered for removal rather than removed.
35
+
36
+ The **Project instructions** setting changes which of the two files load, and Claude Code reads it only from the user's own `~/.claude/settings.json` or from managed settings — never from a project settings file. A repository cannot set it for its contributors: never write it, and never offer it as the fix.
37
+
38
+ ## Nested instruction files
39
+
40
+ Nested `AGENTS.md` files need nothing written beside them. Claude Code reads every `AGENTS.md` from the working directory upward at session start, and a subdirectory's `AGENTS.md` when it opens a file there — the same lazy-on-read rule `CLAUDE.md` gets — provided that subdirectory holds none of the three files above.
41
+
42
+ Conflict semantics still differ from the standard's. Claude Code concatenates what it discovers from the filesystem root down; the nearest file is read last but does not win, and the docs say Claude may pick one arbitrarily where two rules contradict. The `AGENTS.md` standard says the nearest file wins. A nested file that *reverses* a root rule is therefore an override for Codex and an ambiguity here — worth saying out loud, and not something writing anything would fix.
43
+
44
+ ## Frontmatter
45
+
46
+ Claude Code recognizes the most fields (`context: fork`, `agent:`, `disable-model-invocation`, `once`, `${CLAUDE_SKILL_DIR}`). Other harnesses drop them silently.
47
+
48
+ - Restate anything load-bearing in the Markdown body.
49
+ - `argument-hint` and `arguments` are Claude Code's argument fields, and the only ones that fail loudly elsewhere: claude.ai uploads and the Skills API reject them outright. Claude Code appends what the caller typed as `ARGUMENTS: <value>` when the body has no `$ARGUMENTS`, so a skill reads its arguments without either field. See `frontmatter.md`.
50
+ - **Enforce `name` equal to the directory name.** Claude Code treats `name` as a display label only and resolves the command from the directory name; matching them removes the discrepancy.
51
+
52
+ ## Leave alone — canonical-only
53
+
54
+ Report these and do not convert them:
55
+
56
+ - `.claude/agents/` (subagents), `.claude/rules/`, `.claude/output-styles/`
57
+ - hook blocks in `.claude/settings.json` — event names differ by case across harnesses
58
+ - MCP server definitions
59
+
60
+ `.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.
61
+
62
+ ## Commands
63
+
64
+ `.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.
@@ -0,0 +1,19 @@
1
+ # Codex
2
+
3
+ **Write nothing.** Codex reads `.agents/skills/` and `AGENTS.md` natively, and walks up to the repository root on its own.
4
+
5
+ - Do not create `.codex/skills` — it is redundant.
6
+ - Detection directory is `.codex`. Its presence enables Codex in the config record and changes nothing on disk.
7
+ - Apply `frontmatter.md` as normal. Codex requires `name` and `description`, and rejects unquoted colons like every other harness.
8
+
9
+ ## Arguments
10
+
11
+ Codex skills have none. No placeholder syntax is documented for `SKILL.md`, and the sidecar below has no argument field. The `$1`–`$9` and `$ARGUMENTS` placeholders belong to custom prompts (`~/.codex/prompts/`), which OpenAI has deprecated in favor of skills.
12
+
13
+ A skill that must take arguments states in its body how to read them from the invocation. That is the one mechanism every harness shares.
14
+
15
+ ## Optional sidecar
16
+
17
+ Codex alone reads `agents/openai.yaml` inside a skill directory (display name, icons, brand color, `allow_implicit_invocation`, MCP dependencies).
18
+
19
+ Never add one unprompted. If the user asks for it, restate anything load-bearing in the `SKILL.md` body — no other harness reads the sidecar.
@@ -0,0 +1,16 @@
1
+ # GitHub Copilot CLI
2
+
3
+ **Write nothing.** Copilot CLI reads `.agents/skills/` and `AGENTS.md` natively.
4
+
5
+ - Detection directory is `.github/skills` — **not** `.github`. A repository with `.github/` but no `.github/skills/` does not enable Copilot CLI by detection.
6
+ - Copilot also reads `.claude/skills`, `.github/skills`, `CLAUDE.md`, and `GEMINI.md`. Do not create any of them for Copilot's benefit.
7
+
8
+ ## Instruction consolidation
9
+
10
+ `.github/copilot-instructions.md` and `.github/instructions/**` are **consolidatable** — move their content into `AGENTS.md` and leave a pointer, with approval.
11
+
12
+ This is safe here because Copilot has no mode that reads only the harness file. Do not assume the same for Cursor.
13
+
14
+ ## Frontmatter
15
+
16
+ `model` is Copilot-only; `license` and `allowed-tools` are accepted. Keep anything load-bearing in the body — see `frontmatter.md`.
@@ -0,0 +1,36 @@
1
+ # Cursor
2
+
3
+ **Write no skills projection.** Cursor reads `.agents/skills/` natively, plus `.cursor/skills/` and compat reads of `.claude/skills/` and `.codex/skills/`.
4
+
5
+ Cursor is enabled unconditionally alongside Claude Code, so it appears in the config record whether or not `.cursor/` exists. That record changes nothing on disk.
6
+
7
+ ## Instructions — no bridge needed
8
+
9
+ Cursor reads `AGENTS.md` in the project root and in subdirectories, and picks it up automatically. It applies in every mode — Agent, Ask, Plan, and Debug.
10
+
11
+ Write no instruction bridge. Consolidating into `AGENTS.md` costs no mode coverage.
12
+
13
+ Two things to tell the user instead:
14
+
15
+ - **`AGENTS.md` has no conditional attachment** — no globs, no description-gating, no `@`-mention-only. It loads on every conversation. Where content needs to apply to one subtree, a nested `AGENTS.md` is the documented way to scope it; where it needs real conditions, that is what `.cursor/rules/*.mdc` is for.
16
+ - **Cursor reads `CLAUDE.md` the same way it reads `AGENTS.md`**, and always applies it regardless of any `alwaysApply` setting. So a `CLAUDE.md` is loaded unconditionally by Cursor *in addition to* `AGENTS.md`, while Claude Code reads it *instead of* `AGENTS.md`. This is a second reason never to write one.
17
+
18
+ ## Do not
19
+
20
+ - **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. A plain `.md` in `.cursor/rules/` is ignored outright — it has no frontmatter.
21
+ - **Do not delete or rewrite `.cursorrules` or `.cursor/rules/**` on the assumption that `AGENTS.md` covers them.** Mode coverage is not the reason. A `.mdc` rule can carry `globs` or a `description` that `AGENTS.md` cannot express, so the trade is conditional activation, and the owner has to agree to it.
22
+ - Do not assert whether Cursor's `.agents/skills` discovery recurses into nested subdirectories. It is untested.
23
+ - Do not claim `AGENTS.md` beats `.cursor/rules/*.mdc` or loses to it. The documented precedence covers Team → Project → User rules and does not place `AGENTS.md` in that order. The two coexist; Cursor loads both.
24
+
25
+ ## Migrating a rule, when the owner asks for it
26
+
27
+ Offer, never assume:
28
+
29
+ - **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.
30
+ - **A rule with `globs` or a `description`** loads conditionally, and `AGENTS.md` has no equivalent. Consolidating it makes it always-on. Say that, and let the owner decide whether the content is worth the context on every turn.
31
+ - An `alwaysApply: true` rule with no `globs` moves to `AGENTS.md` with nothing lost.
32
+
33
+
34
+ ## Frontmatter
35
+
36
+ `paths`, `disable-model-invocation`, and legacy `globs` are Cursor-recognized. Other harnesses drop them — keep load-bearing behavior in the body, per `frontmatter.md`.
@@ -0,0 +1,19 @@
1
+ # Devin Desktop (formerly Windsurf)
2
+
3
+ **Write nothing.** Devin Desktop reads `.agents/skills/` natively — it is the recommended path of the nine it scans.
4
+
5
+ Windsurf was rebranded to Devin Desktop on 2026-06-02. Use `devin-desktop`; `windsurf` still works as a deprecated alias.
6
+
7
+ ## The alias
8
+
9
+ `--harness windsurf` enables a legacy entry that still creates `.windsurf/skills → ../.agents/skills`. Devin also scans `.windsurf/skills/`, so the projection works — it is redundant, not broken.
10
+
11
+ - For a new repository, use `--harness devin-desktop` and write nothing.
12
+ - If a repository already has a `.windsurf/skills` link, leave it. Report it as legacy compatibility, and mention the rename.
13
+ - `init` reports any enabled deprecated name in its `deprecated` result field. Surface that to the user.
14
+
15
+ ## Instructions
16
+
17
+ Whether Devin Desktop reads `AGENTS.md` is **not established**. Do not assert it either way, and do not write an instruction bridge for it.
18
+
19
+ `.windsurfrules` and `.windsurf/rules/` are **canonical-only**. Report them and leave them in place.
@@ -0,0 +1,30 @@
1
+ # Gemini CLI
2
+
3
+ Reads `.agents/skills` at both scopes, so **skills need no bridge**. It does not read `AGENTS.md`, so **the instruction bridge is required**.
4
+
5
+ ## Skills — nothing to write
6
+
7
+ `.agents/skills` is read directly at project scope, where the alias takes precedence over `.gemini/skills/`. `init` writes no skills bridge for Gemini CLI.
8
+
9
+ An existing `.gemini/skills` symlink still resolves — that path is still scanned. Leave it; removing it is not part of enabling this harness.
10
+
11
+ ## Instructions — required
12
+
13
+ `init` does **not** do this, and it cannot be a link. Add `AGENTS.md` to `context.fileName` in `.gemini/settings.json`:
14
+
15
+ ```json
16
+ {
17
+ "context": {
18
+ "fileName": ["AGENTS.md", "GEMINI.md"]
19
+ }
20
+ }
21
+ ```
22
+
23
+ `AGENTS.md` is not in the default list. **Without this edit Gemini CLI gets no instructions at all** from a repository that consolidated into `AGENTS.md`.
24
+
25
+ When the file already exists:
26
+
27
+ - Get approval first — it is user-authored.
28
+ - Add to the array; do not replace it. Preserve surrounding settings.
29
+ - **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`.
30
+ - Keep `GEMINI.md` in the list if the repository still has one.
@@ -12,10 +12,10 @@ Each finding names a **locator**, not a file: `.cursor/mcp.json#servers.linear.c
12
12
  | --- | --- | --- |
13
13
  | `mcp-golden-unreadable` | the golden MCP set does not parse — the locator gives the line and column, and nothing else can be said about it | fix the TOML at <path> by hand — the reported line and column are all that can be quoted, because the parser's own message repeats the offending line and that line is the one holding the credential |
14
14
  | `mcp-target-unreadable` | this harness config does not parse, so the harness starts none of its servers and nothing in it can be compared | fix the syntax of <path> by hand |
15
- | `mcp-unprojected` | the golden set declares this server and the harness config does not carry it | hand <path> to `/buddy-agent-harness:repair`, which projects it from its golden entry with `mcp project` — or drop it from the golden set |
16
- | `mcp-undeclared` | the harness config carries this server and the golden set does not declare it | hand <path> to `/buddy-agent-harness:repair`, which imports it field by field with `mcp reconcile`, refusing any literal credential — or drop it from <path> |
17
- | `mcp-diverged-target` | only the harness config changed since the two last agreed — the edit was made through the copy | hand <path> to `/buddy-agent-harness:repair`, which imports the field into .agents/buddy-agent-harness/mcp.toml with `mcp reconcile` once approved |
18
- | `mcp-diverged-golden` | only the golden set changed since the two last agreed — the harness copy is stale | hand <path> to `/buddy-agent-harness:repair`, which updates it from the golden entry with `mcp project` |
15
+ | `mcp-unprojected` | the golden set declares this server and the harness config does not carry it | hand <path> to `/buddy-agent-harness:repair` (pnpm install: `pnpm-buddy-agent-harness-repair`), which projects it from its golden entry with `mcp project` — or drop it from the golden set |
16
+ | `mcp-undeclared` | the harness config carries this server and the golden set does not declare it | hand <path> to `/buddy-agent-harness:repair` (pnpm install: `pnpm-buddy-agent-harness-repair`), which imports it field by field with `mcp reconcile`, refusing any literal credential — or drop it from <path> |
17
+ | `mcp-diverged-target` | only the harness config changed since the two last agreed — the edit was made through the copy | hand <path> to `/buddy-agent-harness:repair` (pnpm install: `pnpm-buddy-agent-harness-repair`), which imports the field into .agents/buddy-agent-harness/mcp.toml with `mcp reconcile` once approved |
18
+ | `mcp-diverged-golden` | only the golden set changed since the two last agreed — the harness copy is stale | hand <path> to `/buddy-agent-harness:repair` (pnpm install: `pnpm-buddy-agent-harness-repair`), which updates it from the golden entry with `mcp project` |
19
19
  | `mcp-diverged-both` | both sides changed since they last agreed — merging either way would discard the other | reconcile <path> against .agents/buddy-agent-harness/mcp.toml by hand — never merge a three-way conflict automatically |
20
20
  | `mcp-diverged-unknown` | the two disagree and no baseline says which side moved — neither history nor a last-projected record covers this server | compare <path> against .agents/buddy-agent-harness/mcp.toml by hand |
21
21
  | `mcp-literal-secret` | a credential-bearing field holds a literal rather than a reference to an environment variable | move the value at <path> into an environment variable and reference it — read the value from the file, never from this report, and never repeat it back |
@@ -8,10 +8,10 @@ Each finding names the canonical form it converts to. The direction is always th
8
8
 
9
9
  | Finding | What it means | Repair |
10
10
  | --- | --- | --- |
11
- | `nonstandard-instructions` | instruction content only one harness reads — AGENTS.md carries the same prose to all of them | hand <path> to `/buddy-agent-harness:init-buddy-agent-harness`, which consolidates it into AGENTS.md |
12
- | `nonstandard-rule` | a path-scoped rule only one harness reads — a skill reaches every harness where the scoping is incidental | hand <path> to `/buddy-agent-harness:init-buddy-agent-harness` to convert into a skill, unless the path scoping is load-bearing |
13
- | `nonstandard-command` | a harness command file — a skill is the portable form, and this harness reads skills too | hand <path> to `/buddy-agent-harness:init-buddy-agent-harness`, which moves it to .agents/skills |
14
- | `nonstandard-skill` | a skill under a harness directory rather than the canonical one, where only that harness finds it | hand <path> to `/buddy-agent-harness:init-buddy-agent-harness`, which moves it to .agents/skills |
11
+ | `nonstandard-instructions` | instruction content only one harness reads — AGENTS.md carries the same prose to all of them | hand <path> to `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`), which consolidates it into AGENTS.md |
12
+ | `nonstandard-rule` | a path-scoped rule only one harness reads — a skill reaches every harness where the scoping is incidental | hand <path> to `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`) to convert into a skill, unless the path scoping is load-bearing |
13
+ | `nonstandard-command` | a harness command file — a skill is the portable form, and this harness reads skills too | hand <path> to `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`), which moves it to .agents/skills |
14
+ | `nonstandard-skill` | a skill under a harness directory rather than the canonical one, where only that harness finds it | hand <path> to `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`), which moves it to .agents/skills |
15
15
  | `nonstandard-subagent` | a subagent definition with no cross-harness form — nothing outside this harness can read it, and no canonical form exists yet | leave <path> in place — no portable form exists yet, so this is work for a person rather than a skill |
16
16
 
17
17
  ## Two of them need judgment, not a move