repobuddy/buddy-agent-harness

v1.0.0MIT

Initialize standards-based agent configuration across agent harnesses

GitHub Open Website

buddy-agent-harness

1.0.0

Major Changes

d8ef1eb: Moves to cyber-agentkit 2.0. reference show is now reference load and reference select is now reference customize. The --scope project option is now --scope repo, and references are read from the repository root. reference load exits 0 for a name it did not find. list --trace rows carry kind: selection where they had selection: true.

Minor Changes

b792140: enhance now reads a present section against an addition's retired wordings with cyber-agentkit's prose-update, and for an outdated section offers the merged text that keeps the owner's own sentences beside the current wording. The cyber-agentkit dependency moves to ^1.2.0.
e7efd5c: init writes an empty .gitkeep into .agents/skills/ and .agents/references/ when it leaves them empty, so a commit and clone keep the directories and .claude/skills does not dangle.

Patch Changes

a461f45: clibuilder moves from dependencies to an optional peer dependency at ^12.1.0. The buddy-agent-harness bin bundles its own copy and needs nothing installed; a host CLI that imports activate or a *Command export supplies its own clibuilder, at 12.1.0 or later so its copy and this package's work together.
5a5b61b: Documents the reference command as cyber-agentkit 2.0 defines it: reference load, reference customize --extends, --in <folder> for a folder's project section, --scope repo|user, and the merge operations replace, patch, combine, and remove. The docs, the spec, and llms.txt no longer name reference show, reference select, --scope project, or merge-sections, and the library page lists only the reference exports the package has.
ef03223: Include CHANGELOG.md in the published package.

0.22.0

Minor Changes

dad15c5: Moves to clibuilder 12 and @cyberuni/agent-harness 0.7. The package no longer uses @clibuilder/axi, and its skill scripts and dist/cli.mjs no longer carry clibuilder's runtime plugin and config loader: the three skill scripts shrink from 693 KB to 386 KB and dist/cli.mjs from 1.1 MB to 689 KB.

Command interfaces and documented output are unchanged. What a caller can see:
- A usage error (an unknown option or command, an unsupported --format) is now a coded report on stdout (error, code, and help lines in the chosen format) with exit code 2. It was prose and help on stderr.
- --format is clibuilder's global option, so every command, including mcp and reference, lists it in --help the same way. reference show|create|delete and governance show still default to text, and every other command to toon; the default is chosen from the command named in argv.
- initCommand, doctorCommand, governanceCommand, referenceCommand, harnessCommand, and activate are clibuilder 12 command objects. A host that mounts them needs clibuilder ^12.0.0; ^11 no longer works.
832fa4f: Moves from @cyberuni/agent-harness to cyber-agentkit 1.0, and the plugin dependency from cyber-agent-harness to cyber-agentkit; install that plugin on harnesses that read no plugin dependencies.

The reference command and its exports no longer read governances/ folders (project, user, and the machine-wide ones). Move those documents to the references/ folder of the same tier. The governance command is unchanged and still reads them. The machine-wide /etc/buddy-agent-harness/references folder is no longer read: the managed tier is a references/ folder beside the managed files of each detected harness.

The package no longer exports managedReferencesDir, MergeMode, ReferenceRow, TraceEntry, or UsedLayer. referenceLayers now resolves to ReferenceLayers, and ReferenceListing holds references and layers in place of rows. ReferenceListLayerRow and ReferenceListRow are exported.

Patch Changes

9728e92: Makes the shipped skills self-contained, for channels that link or copy one skill alone (pnpm 12.11 links each as pnpm-buddy-agent-harness-<skill>). The npx fallback is pinned to the exact release rather than a ^ range. A page one skill read from a sibling (agents-md.md, detection.md, global-instructions.md, the per-harness judgment pages) is now copied into the skill that reads it, and checked against its source. Every /buddy-agent-harness:<skill> reference, in the skills and in doctor output, carries the pnpm name beside it.

0.21.0

Minor Changes

0e4d7c0: --format now comes from @clibuilder/axi, the output contract clibuilder CLIs share, in place of this package's own copy. toon, json, and text output is byte-identical: axi's TOON encoder and text renderer are the same code.

An unknown --format value is now a usage error, the same as an unknown option. Before, doctor --format yaml (and every other command) wrote error: --format must be toon, json, or text. to stderr and exited 1. Now clibuilder rejects it before the command runs, with invalid value for option --format: expected one of: toon, json, text, received "yaml" and the command's usage text, and exits 2. A script that checked for exit 1 on a bad format should check for 2.

The --format help line now reads Output format: toon (default), json, text — toon for agents, json to pipe, text for humans. governance show keeps its own wording and its text default.

Patch Changes

9588c86: Fix the enhance and repair skills citing ../init/references/…, a path that does not exist; they now point at init-buddy-agent-harness. Drop a migration-relative sentence from the doctor-buddy-agent-harness skill.

0.20.0

Minor Changes

bc2b8bb: The reference command and the reference exports now come from @cyberuni/agent-harness. The same tiers, output, and exit codes, and the same library exports and options. The command gains reference delete, which removes the project or user copy of a reference and reports which copy answers the name afterwards; it never deletes a plugin-shipped or managed copy.
f7fa605: The reference skill moved to the cyber-agent-harness plugin, and the buddy-agent-harness plugin no longer ships it. The plugin now declares a dependency on cyber-agent-harness, which Claude Code resolves from the marketplace buddy-agent-harness is installed from, so installing buddy-agent-harness installs cyber-agent-harness and its reference skill with it. Cursor, Codex, and GitHub Copilot CLI read no plugin dependencies, so install cyber-agent-harness there yourself.

A calling skill's line changes from "in the buddy-agent-harness plugin" to "in the cyber-agent-harness plugin":
```
Load `skill-design` and `agent-tool-output` with the `reference` skill in the `cyber-agent-harness` plugin.
```
In Claude Code, the typed form changes from /buddy-agent-harness:reference to /cyber-agent-harness:reference. The buddy-agent-harness reference command is unchanged.

0.19.0

Minor Changes

adcaa2f: doctor's globalInstructions check now reads an empty CODEX_HOME, COPILOT_HOME, or CLAUDE_CONFIG_DIR the way that harness does. Codex and Copilot CLI read an empty value as unset, so nothing changes for them. Claude Code reads an empty CLAUDE_CONFIG_DIR as the directory it starts in. Its row now names ./CLAUDE.md, the file Claude Code reads when started in the repository, and a new global-instructions-emptied finding names $CLAUDE_CONFIG_DIR, with the step to unset it or set it to the folder you meant. The repair and enhance skills hand that step over like the others.

The library adds a start parameter to diagnoseGlobalInstructions: the directory Claude Code is taken to start in, defaulting to process.cwd(). diagnoseBridges passes root.

0.18.0

Minor Changes

10cbbdd: doctor's globalInstructions check now follows the variables that move a harness's directory: CODEX_HOME, COPILOT_HOME, and CLAUDE_CONFIG_DIR. Where one is set and non-empty, the row and the repair name the file under it, written from the variable, such as $CODEX_HOME/AGENTS.md.

It also catches Codex's AGENTS.override.md. Codex reads that file in place of AGENTS.md when it holds more than whitespace, so a bridged AGENTS.md beside it loads nothing. The row is then overridden, and a global-instructions-overridden finding names the override, with the step to move what it says into ~/.agents/AGENTS.md and remove it. The repair and enhance skills hand that step over like the others.

Copilot CLI is confirmed to follow a copilot-instructions.md symlink that points outside its directory, so the symlink bridge stands.

The library adds an env option to diagnoseBridges and an env parameter to diagnoseGlobalInstructions; omitted, no variable is followed.
3468500: doctor now reports whether each harness installed for you loads ~/.agents/AGENTS.md, in a new globalInstructions section. No harness reads that file by itself; each loads it only through a user-scope file of its own. On Claude Code that is an @~/.agents/AGENTS.md line in ~/.claude/CLAUDE.md. On Codex, Copilot CLI, and Gemini CLI it is ~/.codex/AGENTS.md, ~/.copilot/copilot-instructions.md, or ~/.gemini/GEMINI.md as a symlink to it. Gemini CLI's context.fileName setting cannot do it at user scope, because there it names files inside ~/.gemini/ only.

Where ~/.agents/AGENTS.md exists and a harness does not load it, doctor reports global-instructions-missing or global-instructions-unbridged. The repair names the exact line or symlink, for you to add yourself; nothing writes outside the repository. The repair skill passes that step to you unchanged. When the enhance skill hands a global placement over, it now says whether the harness in use loads the file, and gives you the bridge beside the text where it does not.

The library adds diagnoseGlobalInstructions, a home option on diagnoseBridges, and import and symlink variants of InstructionBridge.

0.17.0

Minor Changes

951313d: The enhance skill now offers a third addition, ## Session scope. It tells the agent to keep one session to one subject: finish deciding how something should work before building it, start the build in a new session from what the first one wrote down, and when the user turns to unrelated work, say what the old subject was rather than carrying it into the new one.

It is gated like the other two. The skill offers it only where the merged instructions do not already cover the subject, recommends the owner's global instruction file over the repository's AGENTS.md, and writes nothing without approval. No harness scores this wording yet, so where the skill cannot tell whether a section already in a file came from here, it offers two answers rather than three.

0.16.0

Minor Changes

a0e476e: New reference create <name> starts a reference in the project tier, or with --scope user in ~/.agents/references/. It copies --template <path> as it is, or writes a built-in template of top-level ## sections with no # title. When a lower layer already holds the name, it adds merge: merge-sections so the new file overrides section by section, unless the template sets merge itself. It never overwrites a file, refuses a copy above that would shadow the new one, warns on a # heading or a missing description, and --dry-run prints the path and content without writing. The reference skill's Create and Update modes now write project and user references through it.

Patch Changes

0dc25d9: Link the diagnoseBridges, diagnoseInstructions, buildDoctorReport, doctorCommand, bridgeRepairs, instructionRepairs, doctorRepairs, doctorSkill, and renderDoctorSkill exports and their types in the shipped llms.txt to their new documentation page instead of their source.
851cb51: Mark the governance library exports deprecated with a @deprecated tag naming each one's reference replacement, such as resolveGovernance to resolveReference. They keep their behavior until the next major version. The shipped llms.txt now links them to their new documentation page instead of their source.
03756a3: Link the run, initializeHarnesses, initCommand, harnessCommand, and activate exports in the shipped llms.txt to their new documentation page instead of their source.
6ace999: llms.txt now links the harness registry and MCP library exports — harnessRegistry, listMcpServers, diagnoseMcp, goldenSetPath, and their types — to their new docs page, Library: MCP and the harness registry, instead of to their source.
67ad576: llms.txt links the library's reference exports — referenceLayers, resolveReference, listReferences, searchReferences, referenceCommand, and their types — to their new docs page, instead of to the source.

0.15.0

Minor Changes

37bdd5a: Add reference where <name>, which shows where to write an override of a reference: the project file (relative to the reported root) and the user file, highest precedence first, with the plugin copy they would override. --caller <skill folder> reports that skill's own copy as the Load mode reads it. The reference skill's Inspect mode runs it when asked where to put an override.

Patch Changes

42cee2c: Ship a generated llms.txt in the package, also served from the docs site at /llms.txt: an orientation map of the CLI commands, the skills, the library exports, and the documentation pages, with absolute links to each.
4d3c72d: Hide the reference skill from the slash-command menu with user-invocable: false. Agents still load it by name.

0.14.0

Minor Changes

0ba0099: The load-reference skill is now the reference skill's Load mode, and the load-reference skill is removed. A calling skill's line changes from "with the load-reference skill" to "with the reference skill":
```
Load `skill-design` and `agent-tool-output` with the `reference` skill in the `buddy-agent-harness` plugin.
```
Loading works as before: one reference show run from the launcher bundled in the skill folder, no npx and no network, and the calling skill's own references/<name>.md when the command cannot run or no tier holds the name. The plugin now puts one skill description in every session for references, instead of two.
1071180: New reference skill for working with references yourself. It routes what you ask to reference show, list, or search, and it writes a new reference, or updates one, after you approve it, since the command is read-only.

When a plugin ships a reference, the skill names the file <plugin name>.<reference>.md, so a project's override of one plugin's document does not also replace another plugin's. Updating your own reference edits it in place. Updating a plugin's writes an override, and when more than one plugin holds that name, it warns you first. For a skill that needs a reference, it gives you the line that loads it with the same skill.

0.13.1

Patch Changes

a5b3580: Cursor reads AGENTS.md in every mode, and the skills no longer say otherwise. The previous claim — that Cursor reads it in Agent mode only, and that Chat and Composer would lose instructions consolidated into it — was sourced to third-party comparisons and marked contested. Cursor's own documentation contradicts it: "Project rules, user rules, and team rules apply in Agent, Ask, Plan, and Debug modes. The rules are included in every conversation regardless of which mode you're using." Chat, Composer, and Agent were merged into one interface in v0.46, and "Composer" now names a model, so the surfaces said to lose their instructions had not been separate readers for roughly a year and a half.

What changes in practice:
- init no longer reports an instruction gap for Cursor. Nothing is written for it, as before, and the skill no longer tells you a consolidation costs you coverage.
- A Cursor rule is offered on activation, not on readership. init used to offer consolidating a .cursorrules or .cursor/rules/*.mdc only alongside a generated copy left behind for the other modes. There are no other modes to keep working. The trade it names now is the real one: a rule carrying globs or a description loads when those match, and the same content in AGENTS.md loads on every turn.
- doctor's nonstandard-instructions repair drops the generated-bridge wording, since leaving one behind is a per-harness question rather than what every consolidation does.
- CLAUDE.md has a second reason not to exist. Cursor reads it the same way it reads AGENTS.md and applies it to every conversation regardless of alwaysApply. Claude Code reads it instead of AGENTS.md; Cursor loads it in addition to. The rule against writing one was argued from Claude Code alone and now holds twice over.
Evidence: E-CUR-05, E-CUR-06, E-CUR-07, superseding E-CUR-02. Disclosed under Corrections on the Sources page.

0.13.0

Minor Changes

e8491dd: The enhance skill no longer offers a section that your agent already reads from your global instructions. When the repository's AGENTS.md lacks an addition but instructions loaded from outside the repository carry its current text, the verdict is already global. Nothing is offered, and the report says a repository copy would reach your team but give you the text twice. The skill writes that copy only if you ask for it. When both places carry the text, the report names the duplicate.

The global destination it recommends is now ~/.agents/AGENTS.md. The skill also says that a harness reads that file only through its own user-scope file, such as ~/.claude/CLAUDE.md on Claude Code.
1c7ecac: The enhance skill now checks the copy of an addition in your global instructions, and says what it found when that copy and the repository's differ:
- Global instructions hold a retired wording, or your own words, and the repository has none. The skill no longer offers the addition. It hands you the current text to put in place of a retired global wording, and leaves your own words alone.
- Global instructions hold a retired wording, whatever the repository holds. You get the current text for the global copy, even where the repository's section is already current.
- The repository holds a retired wording, and your global instructions hold the current text. The replacement is still offered. It now says you would read the text twice, and offers removing the section as the other answer.
- The repository holds your own words, and your global instructions hold the current text. Nothing is offered, and the report says you read the subject twice.
cf26cf9: The enhance skill now offers a second addition, ## List identifiers. It tells the agent to label every list it presents: letters or numbers for a plain list, and a kind prefix for a typed one, such as P1 for proposals, Q1 for questions, or S1 for scenarios. Labels stay stable when the list is revised, and new items continue the sequence.

The skill offers it the same way as ## Delegation. It is offered only where the merged instructions do not already cover the subject, it recommends the owner's global instruction file, and it is written only on approval. Each addition is offered and reported on its own.
e538ecc: init and doctor now work with references instead of governances.
- init creates .agents/references/ instead of .agents/governances/. Its result reports references, the number of references the project tier holds, in place of governances. Documents in an existing .agents/governances/ are counted too.
- doctor reports a references section in place of governances. There is one row per name per layer, { name, tier, path, status }, for the managed, project, and user tiers. status is the one reference list gives, such as used or shadowed by project (first-wins). When no layer holds a reference, the section reads 0 references — no layer outside the plugin tier holds one.
The legacy governances/ folders are still read by reference, so nothing already written stops resolving.
f5855ab: New load-reference skill: the one way a skill loads a reference. A calling skill writes one line, such as "Load skill-design and agent-tool-output with the load-reference skill in the buddy-agent-harness plugin." The skill runs reference show for every name at once, from a launcher bundled in its own folder, with no npx and no network access. When a name is missing everywhere, or the launcher is absent because the plugin was installed from git, it reads the calling skill's own copy under references/ and tells you so.

The skill's README.md lists how each harness names it: /buddy-agent-harness:load-reference in Claude Code, /load-reference in Cursor and GitHub Copilot CLI, $load-reference in Codex. The table is generated from @cyberuni/agent-harness.

The launchers bundled into the shipped skills no longer break a command that takes several values. Minifying renamed the class the CLI parser uses to recognize them, so reference show rejected every name when run from a bundle.
3f850f5: buddy-agent-harness mcp project writes your golden MCP server set (.agents/buddy-agent-harness/mcp.toml) into each enabled harness's own MCP file: .mcp.json, .cursor/mcp.json, .codex/config.toml, and .gemini/settings.json. It is a dry run unless you pass --write.
```
actions:
  target                 server  action  detail
  .mcp.json              fs      add     creates the file
  .codex/config.toml     old     refuse  transport: Codex supports no SSE transport
  .gemini/settings.json  linear  add     appends the server
```
- Each harness gets its own spelling. You write a reference once as ${NAME}. Cursor gets ${env:NAME}. Claude Code and Gemini CLI take it as written. Codex gets env_vars, env_http_headers, or bearer_token_env_var. A timeout in milliseconds becomes Codex's tool_timeout_sec.
- It refuses rather than guesses. A server a harness cannot hold as written is refused, and the refusal names the field. So is a golden entry holding a literal credential.
- It never overwrites your edits. A server changed on the harness side is skipped.
- It keeps the rest of the file. Every byte outside the entry it writes stays as it was, comments included. That holds when it updates a server already there, in .gemini/settings.json and .codex/config.toml too. It will not rewrite an entry that holds a comment, or a Codex server written as an inline table. It lists those changes for you to apply instead.
- It records what it wrote. --write writes .agents/buddy-agent-harness/mcp.projected.json, which doctor already reads to tell which side moved.
The repair skill now handles mcp-unprojected and mcp-diverged-golden: it shows the plan and runs the command once you approve.

doctor now reads each harness's MCP file in that harness's own format:
- A Gemini CLI url reads as SSE, and httpUrl as streamable HTTP.
- A Codex server's headers, passed-through variables, and timeout are compared instead of ignored.
- A golden field a harness has no place for, such as Cursor and description, is no longer reported as drift.
bf1dd95: buddy-agent-harness mcp reconcile pulls a change made in a harness's MCP file back into your golden set (.agents/buddy-agent-harness/mcp.toml), one approved field at a time. It is a dry run unless you name a field with --accept.
```
fields:
  path                                          action  value
  .mcp.json#servers.linear.command              import  command = "bunx"
  .mcp.json#servers.docs.url                    import  url = "https://docs"
  .mcp.json#servers.docs.headers.Authorization  refuse
```
```
buddy-agent-harness mcp reconcile --accept '.mcp.json#servers.linear.command'
```
- One field per approval. There is no approve-all. A server the golden set lacks is added from the fields you approve, and one of them must be its command or url.
- Conflicts stay yours. A field both sides changed, or one no baseline can place, is reported and never imported.
- No credentials. A literal credential is refused and never shown. The server's other fields are still offered, so you can reference the secret as ${VAR}.
- Harness defaults are not your edits. A Codex or Gemini CLI timeout equal to that harness's default is not imported.
- Each harness's spelling comes back as ${NAME}. That covers Cursor's ${env:NAME} and Codex's bearer_token_env_var.
- Your comments stay. The golden set is edited in place, not rewritten. A field it spreads over a sub-table is listed for you to apply by hand.
The repair skill now handles mcp-diverged-target and mcp-undeclared. It offers each field on its own and passes only the ones you approve.
ba6d264: Add reference show|list|search, which reads on-demand reference documents by name. A reference costs no context until it is fetched, unlike a skill, whose description loads in every session.
- Tiers. A name resolves through the managed, project (.agents/references/), user (~/.agents/references/), and plugin tiers, highest first. The plugin tier is this package, the plugins your harness has enabled, and the dependencies declared in the nearest package.json; ask for <plugin>/<name> when two plugins hold a name.
- Your harness. The command detects the harness it runs under. It reads a references/ folder beside that harness's managed settings (for example /etc/claude-code/references), and the references/ of each plugin the harness has enabled, from the folder it installed the plugin in. A plugin that is installed but not enabled is never read. Policy kept in MDM, the Windows registry, or the vendor's servers cannot be read locally; --trace and list show it as not read, with the reason.
- Monorepos. The project tier is read at --root and each folder above it up to the repository root (.git, pnpm-workspace.yaml, or a package.json with workspaces), nearest first, so a package can override a reference the repository shares.
- Merge modes. The higher document chooses in its frontmatter: first-wins (default), combine, or merge-sections, which merges by heading and honors  and  under a heading.
- File names. <name>.md, <name>/README.md, <name>/index.md, or <name>/SKILL.md.
- Several names per call. show a b c returns each document between <reference> delimiters, in order; --format json returns an array. A missing name is reported in place, suggests close names, and makes the exit code 1.
- --trace shows every layer checked and why each was used or shadowed; list marks the same.
governance list|show is deprecated. It works as before and writes one line on stderr pointing to reference. reference still reads the governances/ folders, below references/ in each tier.

Patch Changes

e688aef: Read each harness's skills directories from @cyberuni/agent-harness instead of keeping a copy. The projection targets init and doctor use are unchanged: Claude Code is still the only harness projected into.
9176f62: The enhance skill's ## Delegation section now sizes the job rather than the step: a job made of many routine steps, or of waiting on something outside the agent, goes to a subagent as one job. It also splits a job by what each part needs, sending a hard part to whichever model does it best, and has the brief name what the user authorized and what the subagent must not do.

A repository holding the previous wording is offered the new one as a replacement.
cbeda67: The enhance skill no longer assumes that no harness scores the ## List identifiers wording. When it cannot tell whether an existing List identifiers section is yours, it offers to settle the question by measurement wherever the repository has a harness for that wording. It still offers two answers where there is none.
a0d0b0e: The enhance skill now states its stale check once, in the skill itself, instead of inside the ## Delegation reference. Each addition's reference names only its own history file and what is specific to it, so revising one addition's reference no longer changes how the other is judged. The already-current and already-global checks now share one stated containment test. How a section is classified is unchanged.
b876ce5: The init-buddy-agent-harness skill now states three rules it relied on the reader to infer. Declining one step drops only that write, and the other approved steps go ahead without being asked again. Creating a .gemini/settings.json that does not exist yet needs no approval. The report gives the reason each canonical-only artifact was left alone.
f2a29ee: run(argv) now returns the usage code 2 on an unknown option or command, where it returned 0 and left the code on process.exitCode. A caller can assign the result directly:
```
process.exitCode = await run(argv)
```
The executable and the skill launchers already exited 2 there and still do. This comes from clibuilder 11.3.0, whose parse() now returns the code it records.

0.12.0

Minor Changes

668e569: Claude Code reads AGENTS.md itself from v2.1.277, so the CLAUDE.md import bridge is gone from the model.

init writes no CLAUDE.md — not at the root, and not beside a nested AGENTS.md. Its instruction work is consolidation instead: a CLAUDE.md holding content of its own is now the urgent finding, because Claude Code reads it instead of AGENTS.md, and it is consolidated and removed on approval rather than left behind as a generated copy. A CLAUDE.md that is only @AGENTS.md, or a symlink to it, is offered for removal and kept on a no — the import is still the only way in for sessions that cannot read AGENTS.md directly, such as a third-party provider or a version before v2.1.277.

doctor reports two new findings in the instructions section: instructions-shadowing for a file read instead of the AGENTS.md beside it, and instructions-superseded for a bridge that still works and is no longer needed. Both are checked per directory holding an AGENTS.md, for CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md. It no longer reports a missing CLAUDE.md.

Gemini CLI is now the only harness in the registry that needs an instruction bridge. Nothing changes about skills projections: Claude Code still needs .claude/skills.
7c29ed6: The enhance skill now recommends the owner's own global instruction file for the ## Delegation section, rather than the repository's AGENTS.md.

Nothing in that text is about the repository in front of it: it says how to work with subagents, which holds in every repository the owner opens. Copying it into each one is a copy per repository to keep in step — the drift this package exists to remove, one level up from the file it removes it in. So an addition now declares where it belongs, the offer leads with that destination, and the alternative is named with what each one buys: the global file reaches every repository the owner opens and nobody else, and the project file reaches everyone who clones it at the cost of a copy per repository.

Where the agent's own always-loaded instructions already carry the text, the offer says so — the repository copy then adds the team and nothing else, and the owner carries the text twice. That is stated, not decided.

A global placement is handed over rather than written. The skill still writes the root AGENTS.md and nothing else, so it gives the text and the path and stops; on Claude Code that path is ~/.claude/CLAUDE.md. Where the harness in use documents no user-scope instruction file, no path is guessed.
fe1a601: Add buddy-agent-harness governance list and governance show <name>, and own the override layers a governance can be replaced in.

A governance is a version-pinned Markdown rule set a skill loads, such as skill-design or agent-tool-output. Each skill ships its own committed copy, which is the version it was tested against. This command reads the layers someone can override that copy in, in lookup order: the project's .agents/governances/, the user's ~/.agents/governances/, then two machine-wide directories, which are defaults rather than enforcement and therefore sit last. The layered resolver moved here from universal-plugin rather than being written again.

There are two machine-wide layers on purpose. A new install uses the directory this package owns (/etc/buddy-agent-harness/governances on Linux, /Library/Application Support/BuddyAgentHarness/governances on macOS, %ProgramData%\BuddyAgentHarness\governances on Windows). The directory universal-plugin wrote is still read one layer below it, so a machine already carrying governances keeps resolving them. Wherever that layer appears it is reported as deprecated: governance list carries a status on its row alone, and doctor names the directory each override was read from, so an admin can see both that there is somewhere else to put it and where it is now. Nothing is enforced — the old location still answers, so there is nothing to repair.

governance show writes the document itself on stdout by default; --format toon or --format json wraps it with the layer it came from. governance list reports every name at the layer that would win, alongside the layers themselves, so a reader knows where to write an override.

--overrides-only on either subcommand restricts the answer to those three layers and never returns a governance this package ships, exiting non-zero when none of them holds the name. That is what lets a skill decide whether an override exists without paying for a registry lookup: it runs the command only from an already-installed copy, and reads the exit code.

init now also creates .agents/governances/ when it is absent and reports how many documents it holds, the same contract it already has for .agents/skills. doctor now carries a governances section naming each override and the layer it came from, or stating the zero. An override is a choice someone made, so it is never a finding: doctor's existing findings, its repairs, its exit code, and its project-scope-only MCP policy are unchanged.
aa1b57a: Rename the init and doctor skills to init-buddy-agent-harness and doctor-buddy-agent-harness.

A plugin-scoped skill named init or doctor collides with the same names shipped by other plugins, so a harness loading several plugins could not tell which one a bare init or doctor invocation meant. Invoke them as /buddy-agent-harness:init-buddy-agent-harness and /buddy-agent-harness:doctor-buddy-agent-harness.

The CLI commands init and doctor keep their names — this only renames the two agent skills that wrap them.

Patch Changes

7d98f7e: The enhance skill's ## Delegation section now also tells the agent how to pick a subagent's reasoning effort: the lowest, unless it could not write down the steps that reach the answer.

A repository holding the previous wording is offered the new one as a replacement.
9c2bd77: The init skill now weighs a derived AGENTS.md line against the work a repository actually does, not only against whether the fact is worth knowing.

A line that passes the value test can still serve a minority of sessions, and every session pays for it. So a surviving line is now checked for the share of the repository's work it serves — read off the repository's own commit history — and one serving a minority is folded into a line that already earns its place, or cut with a note saying where the repository already catches it. Before cutting, the line is restated in its universal form: a narrow-sounding line is often a narrow phrasing of a fact that covers everything.

Two smaller rules come with it. Where the repository already keeps an index of where facts live, init reads it first and then names it in one line, instead of copying its rows into the file that points at it. And a command goes into AGENTS.md only after it has been run in the repository and done what the line claims, so a task list read out of a build config — or a second command the first already covers — is caught before it ships.

0.11.0

Minor Changes

75a5d3a: listMcpServers now also reads VS Code, Windsurf (under devin-desktop), OpenCode, and Zed at every scope those hosts document; Claude Code's project-local servers nested in ~/.claude.json; and the MCP servers an installed Claude Code plugin ships, gated on whether that plugin is enabled for the project. McpServerEntry.scope gained 'local' and 'plugin', and McpServerEntry gained an optional plugin field naming the plugin id. ListMcpServersOptions gained an optional platform override so the VS Code user directory is testable on every OS.

0.10.0

Minor Changes

945a3a5: Export listMcpServers — a redaction-safe inventory of every MCP server configured across the supported harnesses, for a project directory and (where a harness documents one) an injectable home directory.

It reuses diagnoseMcp's own parsing, model, and secret-redaction rather than re-implementing them, and it never surfaces a credential: command is trimmed to its basename, args drops any --flag=value pair a credential-bearing flag would carry literally, and url is trimmed to its origin and path. env and headers are not returned at all.

Unlike doctor, which stays project-scope only by design, this export also reads the user-scope MCP configuration each harness documents — Codex and Copilot CLI resolve theirs through CODEX_HOME/COPILOT_HOME first. It changes nothing about what doctor itself reads.

This is meant for a consumer that wants to bundle an MCP inventory without pulling in this package's CLI: the module this ships from imports nothing from clibuilder.

0.9.1

Patch Changes

53b3609: Bundle each shipped skill's script per skill folder, so it runs standalone from a copy of that folder alone — the state an installer that copies only the skill folder (skills add --skill <name>, a symlinked or partial install) actually leaves it in.

Previously each skill's scripts/<subcommand>.mjs walked four directories up from itself to dist/cli.mjs, which only resolves when the whole package sits above the skill. Each script is now a self-contained bundle — built from a small src/skill-scripts/<subcommand>.ts source, with every runtime dependency inlined — that reaches nothing outside its own file.

The bundle is a build artifact distributed through the npm package's files, not committed to git: pnpm build produces and copies it, and prepack runs it before publish. A skill installed from a git source, or a harness that cannot resolve or run the script path, falls back to the pinned npx -y buddy-agent-harness@^<version> <subcommand> invocation each SKILL.md documents — unchanged from before.

pnpm skill:gen:check no longer compares the bundle (there is nothing committed left to diff); a new pnpm pack:check packs the package the way npm publish would, unpacks it, and verifies every shipped script is present and one runs standalone with no node_modules above it. It runs as part of pnpm verify, after build.

0.9.0

Minor Changes

38f8b58: enhance now spots a section carrying a wording it has since retired, and offers the current one in its place.

Coverage was judged by meaning alone, so a repository holding an earlier form of ## Delegation read as covered and the current text was never surfaced. Coverage is now two questions: the first is unchanged, and only text that reads as covered is asked the second, which is about provenance rather than meaning — did this text come from the addition, at a wording it used to ship?

A present section is checked against the text the addition would offer before anything else: a section that already is that text is reported as already current, not as the owner's own, and nothing is offered. Otherwise each addition keeps every wording it has retired, verbatim, beside it; references/delegation.history.md is the first. To decide whether a section is stale, it is compared against those — never weighed against the text that would be offered, since differing from it is what a rewrite produces. A section reproducing one, edits and all, gets the replacement offered under the same approval gate as an addition, and on approval only that section changes. A section written from scratch on the same subject is left alone. Where it is honestly neither — part of a retired wording inside prose the owner clearly wrote — the skill says it cannot tell, shows all three texts, and asks rather than guessing.

That question carries three answers, and the third is to settle it by measurement: the repository's own evaluation harness, where it has one, scores the existing section against the current wording and reports both. This package's own repository uses its eval-delegation skill; a consumer repository has its own or none, and the skill checks before offering it. The replacement is offered only if the current wording wins; a section that scores level or better is kept, and said to be kept. It is never run unasked.

Patch Changes

1c6433e: Bundle the CLI's dependencies into dist/cli.mjs, so the shipped skill launchers actually work.

The skills/*/scripts/*.mjs launchers already preferred the shipped CLI over npx, but an installed plugin directory is a copy of a source checkout rather than an npm install, so its node_modules is absent or incomplete — running a launcher from one failed with Cannot find package 'type-plus' imported from .../clibuilder/esm/builder.js. The published dist/cli.mjs now inlines every runtime dependency and runs with no node_modules present at all.

Bundling also required pointing jsonc-parser (reached through clibuilder) at its ESM build. Its main is a UMD bundle whose factory calls require("./impl/format") and three siblings — specifiers a bundler cannot analyse, so those modules were silently left out and the CLI threw Cannot find module './impl/format' at startup.

The library entry (.) is unchanged. Its dependencies stay external on purpose: it exports activate / *Command for a host CLI to compose, and host and plugin must share one clibuilder instance rather than each holding a private copy.

0.8.0

Minor Changes

a5d5ddc: Rewrite the Delegation section enhance offers so it tells the agent to pick a spawned subagent's model.

The previous wording bounded how cheap a subagent may be but never asked for the choice, so an unset model kept inheriting the parent's. The section now names that inheritance, and makes the cheapest model the pick unless the agent cannot say what a right answer looks like or could not cheaply tell a wrong one.

c9fd249: Add dep-plugins: derive a marketplace catalog for plugins shipped by a repository's dependencies.

A dependency that ships an Agent Plugins manifest at its package root is a plugin the consuming repository could use, but no harness discovers one on its own. This command derives a marketplace catalog from the declared dependencies that ship a manifest, so a harness can install them through its own plugin mechanism. It reaches whole plugins — agents, commands, hooks, MCP servers — rather than only skills.

buddy-agent-harness dep-plugins                # write .agents/buddy-agent-harness/.claude-plugin/marketplace.json
buddy-agent-harness dep-plugins --check        # report whether it is current; writes nothing
buddy-agent-harness dep-plugins --format text  # human-readable report; `toon` is the default, `json` is also available
buddy-agent-harness dep-plugins --root ./pkg   # run against a directory other than the current one

Three decisions worth knowing:

Resolution, not scanning. Only declared dependencies and devDependencies are considered, located through the module resolver. Walking node_modules would pull in transitive dependencies nobody vetted, and a plugin is instruction text that steers an agent.
npm sources, not paths. A path source is resolved against the marketplace root and may not escape it, so a path-based catalog would have to sit at the repository root — where the repository's own public catalog already lives, leaking dependency plugins to anyone adding it. An npm source carries no path, so this catalog lives in its own directory. It also means the design is unaffected by pnpm's layout or by a missing node_modules.
Derived in full, never merged. A plugin added, removed, or moved to a new version all follow from regeneration, so there is no reconciliation logic to get wrong. --check compares bytes.

The catalog is the committed artifact. Registering it with a harness and installing from it are per-machine actions, so the command reports what the harness needs and the command that does it, and never touches harness state itself:

harness:
  runtime: claude-code
  actions:
    do: claude plugin marketplace update acme-web && claude plugin update review@acme-web --scope project
    why: installed 1.0.0, catalog pins 2.0.0

It reads each harness's own state files to compute that delta, covering the three cases a dependency change produces — a plugin appearing, a version moving, and a plugin whose dependency was removed. The last one matters most: nothing else removes it, so the harness leaves it installed and reporting a load failure. Every emitted verb carries --scope project, because all of them default to user scope, and user scope is shared across every repository on the machine — two repositories whose catalogs share a marketplace name collide there silently. A registration already pointing elsewhere is reported rather than overwritten.

Runtime support, each established by running the shipped CLI rather than from documentation:

Runtime	Consumes this catalog	Notes
Claude Code	yes	every verb defaults to user scope, so each carries `--scope project`; refresh is `plugin update`, since re-running `install` is a no-op
Codex	yes	no update verb and no scope — re-running `plugin add` re-reads the catalog and replaces the cached copy; the installed version appears only in the cache directory name
Copilot CLI	no	rejects an npm source (`plugins.0.source: Invalid input`); it accepts a path source, which cannot reach `node_modules` from a subdirectory
Cursor	no	exposes no plugin subcommand from a terminal

Only runtimes actually present on the machine are reported, so the output names work the reader can actually do.

0.7.0

Minor Changes

99db013: Give the CLI a callable entry point, so bin owns the process and skills stop mutating argv.

src/cli.ts exported main(), which built the app, read process.argv and wrote process.exitCode. Nothing could invoke a command without going through the process, and the cost showed up in generated code: every skill launcher spliced the subcommand into global process.argv and then side-effect-imported the executable.

The two boundaries are now separate. bin/buddy-agent-harness.mjs is the process boundary, the only place that reads process.argv or writes process.exitCode. src/cli.ts is the application boundary: it takes an argv and returns an exit code.

New export run(argv: string[]): Promise<number>. The clibuilder application stays internal — exporting it would make clibuilder's builder shape part of this package's public API, so a clibuilder major would become a major here. The generated launchers now compose an argv and call run, mutating nothing:
```
const code = await run([...process.argv.slice(0, 2), 'doctor', ...process.argv.slice(2)])
if (code !== 0) process.exitCode = code
```
The code is applied only when non-zero because clibuilder reports an unknown option or unknown command by writing process.exitCode itself and returning nothing, so run reports 0 on a path where the process must still exit 2.

doctor and init now return their exit codes rather than writing process.exitCode. A command that writes the code reports its failure past the caller instead of to it, so run would have returned 0 for the commonest failure there is. Nothing changes for a shell caller.

New export buildDoctorReport, with its DoctorReport type. doctor's assembled report — the bin line, the healthy-answer sentence, the deduped help section — was reachable only by running the CLI and re-parsing its own TOON. Three layers are now each reachable on their own: diagnoseBridges and its siblings return the raw diagnosis, buildDoctorReport returns the report as a value, and run returns that report serialized plus an exit code.

Two fixes in the lines this touched:
- Errors went to stdout. doctor's default output is TOON that agents parse, and the error line landed in the stream they were parsing. It goes to stderr.
- --version was wrong. It reported 0.1.0 while the package was at 0.6.0, five minors behind. It is read from the manifest.
Also fixed: skills/repair/'s launcher was labelled generated but was not on the generator's list, so nothing rewrote it and nothing caught it going stale. The generator now keys each launcher by the subcommand it runs, and a test asserts every shipped launcher is a target it checks.
3550496: The doctor skill is split into a lean SKILL.md and lazy-loaded reference pages, the way init is.

Everything doctor knows was in one 125-line file, so an agent acting on a single MCP credential finding read the skills-bridge table, the instruction-bridge table, the configuration table and the Windows case to get there. SKILL.md is now 62 lines — how to run it, how to read the report, the routing rule, and a pointer table — and the finding tables live one family per page under references/, with a page per harness under references/harnesses/.

The pages are generated from the same guidance table and the harness registry that the command reports from, so they cannot drift from it. Editorial judgment about a harness stays hand-written in the init skill, and each generated harness page links to it where one exists; which harnesses have one is read off the filesystem rather than listed.

Three checks come with the split: every reference page matches what the generator would write, every page the pointer table names exists, and every cross-reference into the init skill resolves.
3550496: doctor reports agent configuration that only one harness can read.

Four finding families all answered a version of "is something broken". None of them asked how far the configuration that is there actually reaches, so a .cursor/rules/*.mdc — which works, in Cursor, and nowhere else — was invisible to the one command that is safe to run from a session-start hook. The guidance in it reaches one tool, and nobody finds out except by noticing an agent behave differently somewhere else.

The new family reports each artifact with the canonical form it converts to: legacy instruction files and always-on rules to AGENTS.md, harness commands and harness-directory skills to .agents/skills. A .mdc rule splits on whether its frontmatter binds it to globs — always-on prose is what AGENTS.md holds verbatim, while a rule bound to paths converts to a skill only where the scoping is incidental. A subagent names no owner at all: no cross-harness format exists, so the finding reports that gap rather than promising a conversion.

Nothing here is repaired by repair, which corrects configuration that is wrong; nothing here is wrong. Nothing is offered by enhance, which adds guidance a repository is missing; this guidance is present. Every conversion with a destination is init's, and every one is approved before it lands.

The artifacts are declared per harness in the registry, beside that harness's other paths, and the per-harness reference pages are generated from the same declaration. Hooks, LSP settings, and output styles are deliberately not covered: their shapes differ per harness with no safe projection, so no canonical form can be named for them.
2927512: doctor now reports each repair as a runnable command and a prose instruction, instead of wrapping every repair in Run

Every help entry used to be rendered as Run `<repair>` , whether or not the repair was a command. Most are not, so the report published lines like Run `remove .windsurf/skills and enable the harness that replaced it` — an invitation to paste prose into a shell.

help is now one row per repair with two columns:
```
help[3]{command,instruction}:
  buddy-agent-harness init --copy --force,run `buddy-agent-harness init --copy --force` to rebuild .claude/skills as a real directory
  buddy-agent-harness init,run `buddy-agent-harness init` to create the bridge at .windsurf/skills
  "","hand .gemini/settings.json to `/buddy-agent-harness:init`, which writes the bridge into it"
```
command runs verbatim and completes the repair. It is empty when no single invocation does, which is the signal to act on instruction instead — and it stays empty for a repair whose prose quotes a runnable diagnostic, so a caller that executes every non-empty command never rebuilds a diverged bridge over the side holding the newer edit.

Both keys are always emitted, so TOON renders help in its tabular form rather than degrading to a nested list.
3550496: init lists the configuration only one harness can read, and asks before migrating any of it.

doctor now reports these artifacts; init is the skill that acts on them. It reads the list from doctor rather than deriving a second one, presents each with the canonical form it is a candidate for, and asks per artifact — never for the set, because two rules can be in the list for opposite reasons and one approval would carry a file the owner never looked at.

Rules leave the canonical-only bucket. A rule whose paths are incidental to what it says converts to a skill, which every harness reads; a rule whose path scoping is the point has no equivalent and stays. Which one a given rule is cannot be read off the file, so it is offered rather than assumed. Subagents, hooks, output styles and MCP servers stay canonical-only and are reported as having no candidate at all, so the list is not read as a queue of pending work.

No conversion is offered that would leave fewer readers than before. Cursor reads AGENTS.md in Agent mode only, so consolidating .cursorrules and deleting it takes that guidance out of Chat and Composer; the offer is always the consolidation together with the generated copy that keeps them working. The existing rule against rewriting those files is not removed — it is the reason the migration is offered rather than applied.

The init skill now ships a doctor launcher beside its own, the way repair already does.
9be4f0b: doctor diagnoses a golden MCP server set.

A repository may now keep one canonical MCP server per entry at .agents/buddy-agent-harness/mcp.toml, in the superset of fields the supported hosts accept. Where that file exists, doctor compares it against each harness's own project-scope MCP configuration — Claude Code's .mcp.json, Cursor's .cursor/mcp.json, Codex's .codex/config.toml, and Gemini CLI's .gemini/settings.json — and reports how the two have drifted, in either direction. No golden set means no MCP findings, and init still converts nothing.

Comparison is semantic rather than textual: no two of those files ever share bytes, so each side is parsed into one model. A field the golden set leaves unset is never a difference, because a host restating its own default cannot be told apart from a deliberate edit. Direction comes from a last-projected record where there is one and from git history for a tracked target, and is reported as unknown rather than guessed when neither answers.

doctor also reports a literal credential sitting in any of those files, including the golden set. A finding carries the file, the server, and the field and never the value — no truncated preview either — and an unreadable golden set is reported by line and column, because a parser's own message quotes the line that holds the secret. A literal in a tracked file is reported as committed, and its repair is to rotate the credential rather than to move it.

doctor remains read-only. Projecting the golden set into a harness and reconciling a harness-side edit back into it are writes and are not part of this change.
2b3b42d: Add a repair skill, and grow doctor to detect what it repairs.

init consolidates what a repository has, enhance offers what it is missing, and doctor reports what is wrong. Configuration that is present but wrong had no home: not missing, so enhance would not offer it; user-authored, so init would not rewrite it.

doctor gains a third section alongside its bridge and instruction findings — configuration that resolves fine and is still wrong: deprecated-harness, ignored-bridge, unread-local-override, and unloadable-skill. It stays read-only, so it is still safe in a session-start hook.

The new repair skill runs doctor and repairs what it reported, detecting nothing itself, so detection cannot drift into two homes. Every correction is offered with its before and after and written only on approval. Bridge and instruction findings are handed to init, which writes both kinds of bridge in the first place — and writes a CLAUDE.md stub without asking, where repair asks for everything.

doctor's findings rows now carry a problem field naming the finding, alongside path and detail. Route on problem: detail is prose meant to be read, and improving its wording must not change what a caller does.

BridgeFinding gains a required problem field. Reading one is unaffected; code that constructs one needs the new field. This is the breaking edge of the release.

New exports: diagnoseConfiguration, and the types ConfigurationFinding, DiagnoseConfigurationOptions, ConfigurationFault, and ConfigurationProblem.
46a7b16: init --force now takes the targets to replace, so a run cannot reach past the conflict it was invoked for.

The flag was a single boolean: the command preflighted every projection target and, when it was set, replaced every conflicting one. Two harnesses whose targets were both occupied were both replaced by a run intended to fix one of them, and doctor emitted a bare init --force as the repair for a single bridge — so following that repair could silently delete a second harness's user-authored directory.

--force .claude/skills now replaces that projection and reports any other conflicting target as skipped instead of replacing it. Naming a target no enabled harness projects is an error rather than a run that quietly forces nothing. A bare --force still replaces every conflicting target, so existing invocations keep their meaning; the repairs doctor prints now name the bridge they are for.

The conflict message now prints its targets repo-relative, so what it names is what --force accepts back. The initialization result gains a skipped field listing the harnesses left untouched.

Patch Changes

990972f: Teach the enhance skill that a heading inside a fenced code block is not a heading.

Every addition enhance offers is a fenced block containing its own heading, so a repository that documents this tool — or an AGENTS.md that quotes an addition — carries the exact heading the addition would write while remaining entirely uncovered. Coverage is now judged only against the prose an agent reads as instruction, and the fence is stripped when the approved section is written, so an addition lands as prose rather than as a code block.
804a542: doctor reads each file once per commit while deciding which side of a diverged MCP server moved.

Naming the side that moved walks git history for the newest commit where the golden set and the harness config agreed on a field. That walk ran once per diverged field and re-read and re-parsed both files at every commit each time: three targets, five servers, two diverged fields each and fifty commits of history is on the order of three thousand git show calls and as many parses. Drift is the case the walk exists for, and the shipped doctor skill says the command is cheap enough to run from a session-start hook.

The parse is now memoized per commit and file, and the commit walk per target, for the lifetime of the one diagnosis. The reported direction is unchanged.
804a542: doctor names a dotted MCP server in full in its repair.

A finding's locator addresses a place inside a file — .cursor/mcp.json#servers.linear.command — and the two membership repairs recovered the server name from it by splitting on . and taking the last segment. For .codex/config.toml#servers.io.github.foo that gave foo, a server present in neither file, so the repair for an mcp-unprojected or mcp-undeclared finding named something the user could not act on. io.github.* is a common way to name an MCP server.

The file, server, and field now travel with the finding as parts and are assembled into the locator at the one place that renders it. Nothing splits a locator back apart, because no separator survives the dotted case.
41338f9: Correct the init skill's reason for leaving MCP servers alone. It said no safe cross-harness mapping exists; one does, published across fourteen hosts. The reason that survives is that the mapping 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. init still reports MCP configuration rather than converting it, and now says why accurately.
4177091: Route the repair skill's family split on the finding's problem name.

The skill told an agent that every doctor finding's repair in help names a skill, and to decide the init/repair split on that name. It does not: help carries the command rendering of a repair, which names a shell invocation for every bridge finding and nothing at all for every MCP finding. Only the instruction and configuration families name a skill there — eight of twenty-seven problems — so an agent following the rule literally had no match and no stated fallback for the other nineteen, including the whole MCP family, which the skill never mentioned.

Routing is now on problem, which every finding carries and which references/classes.md is keyed by: a problem with a section there is the skill's, and one without it is not. Who a handed-on finding goes to is read off its repair — init where the repair names it, a person where it names no skill — and the skill now says outright that an owner is never to be inferred.
aa7d27d: Judge a skill bridge by where it resolves, not by how it is spelled.

init and doctor both decided a symbolic link was correct by comparing its text against the one relative path init writes. A link that resolves to .agents/skills but is spelled differently — one a user wrote as an absolute path, or any repository reached through a symbolic link in a parent directory — was read as a foreign target: doctor reported it stale and init refused to run without --force. Both now compare resolved paths, so a bridge that works reports as working.

Write the link target the way the platform resolves it. Windows resolves a relative junction target against the process directory rather than the link's own, so the target is now absolute there and stays relative everywhere else, where a relative link survives the repository moving.

0.6.0

Minor Changes

74a17e8: Stop projecting .agents/skills into .gemini/skills. Gemini CLI reads the .agents/skills alias at project scope as well as user scope, and that alias takes precedence over .gemini/skills in each tier — confirmed against the vendor's own discovery code (packages/core/src/config/storage.ts, packages/core/src/skills/skillManager.ts) and its skills documentation, recorded as E-GEM-02.

init now writes nothing for gemini-cli, and doctor no longer reports a .gemini/skills bridge for it. Claude Code is the only harness left with a skills projection. Gemini CLI's instruction bridge is unaffected: it still does not read AGENTS.md, so context.fileName in .gemini/settings.json still has to name it.

An existing .gemini/skills symlink keeps working — that path is still scanned — so nothing has to be removed from a repository that already has one.
1a33cca: Model user scope as well as project scope in the harness registry. Harness now carries a project record and an optional user record, each with its own detect directory and optional skillsDirectory, so a harness that answers the canonical-directory question differently at each scope can be recorded truthfully — Gemini CLI needs a projection inside a repository and none at user scope. A missing user record means no vendor path is documented, as with Devin Desktop.

The published harnessRegistry entries change shape: read harness.project.detect and harness.project.skillsDirectory in place of harness.detect and harness.skillsDirectory. The Harness, HarnessScope, and HarnessScopeName types are now exported. init and doctor are unchanged and still act only inside the repository.
0ce8068: doctor now verifies the instruction bridges as well as the skill bridges. It reports a new instructions section covering the root CLAUDE.md import, one stub per nested AGENTS.md, and the context.fileName entry in .gemini/settings.json, gated per harness the same way the skill bridges are. Every repair there is /buddy-agent-harness:init: those files carry prose someone wrote, so restoring a bridge without discarding what displaced it is the init skill's judgment.

The harness registry records an instructionBridge per harness scope, so the checked set cannot drift from what the init skill writes.

Patch Changes

14a925c: init now says how to edit a user-authored settings file: amend it in place rather than round-tripping it through JSON.parse, keeping key order, indentation, and comments. .gemini/settings.json legally carries comments that a whole-file rewrite would silently delete; .claude/settings.json rejects them outright, so nothing may add one.

0.5.0

Minor Changes

090bfce: Add an enhance skill that offers guidance a repository's AGENTS.md is missing.

init consolidates what a repository already has and bridges the harnesses that cannot read it. It carries no opinions, which is what makes it safe to run anywhere. enhance is the other half: it proposes content the repository does not have, one vetted section at a time, and writes only what you approve. init now ends by asking whether to run it.

Detection decides every run. enhance reads the root AGENTS.md together with any harness instruction file whose content still belongs in it, because that combined text is what an agent effectively reads — guidance living in a Cursor always-on rule counts as already present. It reads those files and never consolidates them; that stays init's work. Coverage is judged by meaning rather than by heading, so a repository covering the subject under its own wording is left alone.

One addition ships: a ## Delegation section telling an agent when to hand work to a subagent, when to do the work itself, which decisions to keep, and what every brief must carry. It names no model, vendor, or version, so it does not go stale as model lineups change.

0.4.1

Patch Changes

e40dc14: Name the launcher relative to the skill, without a placeholder.

Both skills said node "<skill>/scripts/<name>.mjs", which asked the reader to substitute something the agent already knows. An agent reads the SKILL.md from a directory, so node scripts/<name>.mjs resolves against that directory on its own.

node stays in front. The launcher ships as mode 100644, so its shebang never runs it, and on Windows a shebang does nothing regardless of mode. Naming the file alone would fail on both counts.

0.4.0

Minor Changes

9f1ee23: Run the CLI that ships with the skill, and pin the npx fallback.

Both skills told an agent to run npx -y buddy-agent-harness, which downloads the package even when an installed plugin already has it on disk. Each skill now ships a launcher at skills/<name>/scripts/<name>.mjs that resolves the CLI from its own location, so it runs against the working directory without fetching anything.

npx stays documented as the fallback, now pinned to the caret range of the version that generated the skill. Unpinned, a skill from an older install drove whatever npm called latest, and its flags and findings table stopped describing the command it had just run.

The fallback is not redundant. A plugin installed from git is a source checkout whose dependencies are never installed, so the launcher cannot resolve clibuilder and npx is the only path that works. An npm-installed plugin has them and takes the launcher.

renderDoctorSkill now takes the version to pin, and scripts/generate-doctor-skill.ts becomes scripts/generate-skills.ts (pnpm skill:gen), which writes both launchers, regenerates the doctor skill, and rewrites the pinned fallback in the hand-written init skill. It runs during changeset version so the pin follows the release.

0.3.1

Patch Changes

bebd1d7: Use "agent harness" as the single term for a coding-agent runtime.

The published package description, the three plugin manifests, both READMEs, the project spec, and the init skill's description all said "coding-agent harness" while the rest of the project said "agent harness". One concept carried two names across exactly the metadata a user reads first, in a package whose own name is buddy-agent-harness.

Only the wording changes. The clause edited in the skill description sits after the harness names that do the trigger matching, so when the skill loads is unaffected.

0.3.0

Minor Changes

46d24e6: Teach the init skill to take arguments, so doctor can hand it a repair verbatim.

doctor names repairs like --copy --force, and until now the init skill had no documented way to receive them. It now reads flags and their prose equivalents out of the invocation, passes them through to the command in Phase 4, and still stops for the Phase 3 approval that --force would otherwise skip.

The mechanism is deliberately not a placeholder. Claude Code appends what the caller typed as ARGUMENTS: <value> whenever the body omits $ARGUMENTS, Codex skills have no argument mechanism at all, and the Agent Skills spec defines none — so a body that says how to read the invocation is the only form that works everywhere, while a literal $ARGUMENTS would resolve on one harness and stay on the page on the rest.

argument-hint is added for Claude Code's autocomplete. The new references explain why that field is the exception to harness-specific frontmatter being dropped in silence: claude.ai uploads and the Skills API reject it with a hard error.
ee027bb: Add a read-only doctor command and a generated doctor skill.

doctor reports whether the skill bridges init creates still resolve into .agents/skills, deriving the bridge list from the same harness registry init projects into. It detects the silent Windows failure — a checkout with core.symlinks=false materializes a committed symlink as a regular file holding the target path, and the harness loads zero project skills with no warning — along with missing bridges, symlinks pointing elsewhere, and copies that have drifted from the canonical directory.

A diverged copy is reported with a direction, computed against the last commit where the two sides agreed, so the report says which side moved rather than only that they differ. A tracked copy is also checked for its skip-worktree bit, which some checkout and merge operations clear.

The command writes nothing and exits 0 even with findings; each finding names its repair. The command names an init invocation for a person at a shell, while the skill hands the same repair to the init skill, because rebuilding a bridge can move skills a user wrote. skills/doctor/SKILL.md is generated from the same guidance the command prints, with pnpm skill:doctor:check in verify failing when the committed skill goes stale.
46d24e6: Mount the plugin's commands as agent-harness rather than harness.

repobuddy puts every plugin's commands in one namespace, where harness is generic enough for a second plugin to want it. The commands are otherwise unchanged: buddy agent-harness doctor and buddy agent-harness init.

This renames the mount point. A consumer running buddy harness init has to update the call; the npx buddy-agent-harness invocations are unaffected.
e46215a: Add --format text to init and doctor.

TOON stays the default because it is what an agent parses. --format text renders the same result for a person: scalars as key: value, each collection of records as a table with its columns aligned, and lists of names as bullets.

--format now rejects an unknown value with --format must be toon, json, or text.

Patch Changes

2992e06: Use codex,gemini-cli as the init --harness help example, matching doctor.

The previous example named windsurf, which is a deprecated alias for devin-desktop, so the one name the help text taught was the one the result reports back as deprecated.

0.2.0

Minor Changes

6fc3d80: Adopt the Agent Plugins 1.0.0 canonical manifest. plugin.json at the package root is now the single source the vendor manifests are generated from, with skills and per-harness settings under extensions["org.cyberuni.universal-plugin"]. The superseded .plugin/plugin.json is removed.
2988ece: Tell the init skill what belongs in AGENTS.md.

The skill created the file and said not to invent policy, which left a repository with no existing instruction content getting an empty heading. An empty AGENTS.md is worse than none: it looks authoritative and invites the next agent to fill it with guesses.

The new references/agents-md.md splits the two cases — consolidate existing instruction content preserving its wording, or derive candidates from the repository and confirm each one with the user before writing. Deriving a fact from package.json is not invention; asserting a rule nobody agreed to is.

It also carries the test for whether a line earns its place. AGENTS.md is read every session, so a fact the agent could get in one read costs more than it returns, and anything a linter or type checker already enforces is a second source of truth that goes stale. What survives is the constraint that fails a build in a non-obvious way, the workflow with an unguessable step, and the decision that resolves a real ambiguity. Everything else is pushed into a skill, where only its description stays resident and the body loads on match.
0d1b8af: Align initialization with how harnesses actually discover skills.

.agents/skills/ is read natively by Codex, Cursor, and GitHub Copilot CLI, so those harnesses no longer receive projected files. Only Claude Code, Gemini CLI, and Windsurf are linked, and the link is now a single directory-level symlink to .agents/skills rather than one symlink per skill — a skill added later appears in every enabled harness without re-running the command.

Claude Code and Cursor are always enabled; other harnesses are added by detection or with the new --harness option. The result reports native and linked harnesses separately so it is clear what was written to disk. Gemini CLI is now a supported harness, and the Cursor, Codex, and Windsurf skill paths have been corrected.

The init skill is rewritten as a guided survey → classify → confirm → apply → verify workflow. It detects agent configuration a repository already has — instruction files, skills, commands, subagents, rules, MCP servers, hooks — consolidates what has a safe canonical home, reports the rest, and never rewrites a user-authored file without approval. New references cover per-harness support and the cross-harness frontmatter rules that decide whether a shared skill loads at all.
0d1b8af: Add devin-desktop and deprecate windsurf.

Cognition rebranded Windsurf to Devin Desktop on 2026-06-02. More consequentially, Devin scans nine project-scope skill paths and lists .agents/skills/ first as the recommended one, so it reads the canonical directory natively and needs no projection at all.

devin-desktop is now a supported harness with no projection target. windsurf remains accepted as a deprecated alias and still creates the legacy .windsurf/skills symlink, which Devin continues to scan — existing repositories keep working unchanged. The initialization result gains a deprecated field listing any enabled superseded names alongside their replacements.

This leaves only Claude Code and Gemini CLI requiring a skills projection.

Documentation adds Antigravity and VS Code as native .agents/skills readers. Neither is a registry entry: both need nothing written, and neither has a safe project-scope detection marker — VS Code's .vscode/ indicates the editor rather than skills support. Harness Support also now records per-claim evidence confidence and the agent list published by npx skills.
3fe068e: Support portable plugin manifests for Claude Code, Cursor, Codex, and Copilot CLI.

Patch Changes

ab2589a: Update clibuilder to v10.
22fe775: Document the Claude Code marketplace as the single install path and drop the npx skills add instructions, which vendor a copy of the skill into the consumer's harness directories and make the init skill's own projection step fail. Rename the plugin marketplace to repobuddy so the documented buddy-agent-harness@repobuddy install resolves.