buddy-agent-harness 1.0.1 → 1.2.0

package/llms.txt

@@ -21,7 +21,7 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
 - [`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.
 - [`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.
 - [`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.
-- [`buddy-agent-harness reference`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Read reference documents by name, composed from the managed, repo, user, plugin, and default tiers, and create, customize, or delete a contribution.
+- [`buddy-agent-harness reference`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Read reference documents by name, composed from the managed, repo, user, plugin, and default tiers, create, customize, or delete a contribution, and migrate version 1 files.
 - [`buddy-agent-harness reference load`](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.
 - [`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.
 - [`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.
@@ -29,6 +29,7 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
 - [`buddy-agent-harness reference create`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Start a contribution in the repo or user tier, a folder's project section, or a plugin's or a skill's source folder, from a template or an interface. Never overwrites a file with a body; writes a file a contribution above hides, with a warning.
 - [`buddy-agent-harness reference customize`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Customize a name for the repo or user tier, or a folder's project section, running no model: pick what it builds on (`extends`), write a body generated from a request with its record, or print what the generator reads (--base). Writes a file a contribution above hides, with a warning.
 - [`buddy-agent-harness reference delete`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Delete a repo or user contribution, a folder's project section, or one in a plugin's or a skill's source folder, with a non-Markdown file's metadata file, and report what answers the name afterwards. Never deletes an installed or managed one.
+- [`buddy-agent-harness reference migrate`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Rewrite reference files still in a form version 1 wrote, and rename files under a name a plugin renamed, in the repo and user tiers and every project section, or in one plugin or skill source folder. Prints the plan; `--write` applies it. Never changes a managed or installed file.
 - [`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.
 - [`buddy-agent-harness reference check`](https://repobuddy.github.io/buddy-agent-harness/cli/reference/): Check references, each composed as `load` composes it: an interface document against its shape, an implementation against its interface, and every document for the defects composing it raises. With no names, checks every name found. Every warning `load` raises is reported. A failure is an entry in `failed`, not an error; a warning never fails a check.
 - [`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.
@@ -38,10 +39,10 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
 ## Skills
 
 - [Skills](https://repobuddy.github.io/buddy-agent-harness/skills/): The skills the plugin ships, init, doctor, enhance and repair, the reference skill it brings with it, and when to run the CLI instead.
-- [`doctor-buddy-agent-harness`](https://repobuddy.github.io/buddy-agent-harness/skills/doctor-buddy-agent-harness/): Use this skill when a repository loads no project skills, when skills are missing after a clone, when a harness appears to be ignoring AGENTS.md, or when checking whether the agent configuration bridges into .claude/skills and the other harness files still resolve.
-- [`enhance`](https://repobuddy.github.io/buddy-agent-harness/skills/enhance/): Use this skill when a repository already has an AGENTS.md and you want to add guidance it is missing, or to refresh a vetted section it carries in an outdated form — offering each one at a time and writing only what the user approves. Runs on its own or straight after init.
-- [`init-buddy-agent-harness`](https://repobuddy.github.io/buddy-agent-harness/skills/init-buddy-agent-harness/): Use this skill when initializing, adopting, or migrating a repository's agent configuration to the open AGENTS.md and Agent Skills standards, so one canonical source works across Claude Code, Codex, Cursor, Copilot CLI, and other agent harnesses.
-- [`repair`](https://repobuddy.github.io/buddy-agent-harness/skills/repair/): Use this skill when a repository's agent configuration is present but wrong or outdated — a retired harness name, a git-ignored bridge, an AGENTS.local.md nothing reads, a skill a harness refuses to load, or an MCP server that differs between the golden set and a harness, on the side that is plainly ahead. Runs doctor to find them, then offers each correction with its before and after and writes only what is approved.
+- [`doctor-buddy-agent-harness`](https://repobuddy.github.io/buddy-agent-harness/skills/doctor-buddy-agent-harness/): Checks whether a repository's agent configuration bridges into .claude/skills and the other harness files still resolve — when a repository loads no project skills, when skills are missing after a clone, or when a harness appears to be ignoring AGENTS.md.
+- [`enhance`](https://repobuddy.github.io/buddy-agent-harness/skills/enhance/): Adds guidance missing from a repository's existing AGENTS.md, or refreshes a vetted section it carries in an outdated form — offering each one at a time and writing only what the user approves. Runs on its own or straight after init.
+- [`init-buddy-agent-harness`](https://repobuddy.github.io/buddy-agent-harness/skills/init-buddy-agent-harness/): Initializes, adopts, or migrates a repository's agent configuration to the open AGENTS.md and Agent Skills standards, so one canonical source works across Claude Code, Codex, Cursor, Copilot CLI, and other agent harnesses.
+- [`repair`](https://repobuddy.github.io/buddy-agent-harness/skills/repair/): Repairs a repository's agent configuration when it is present but wrong or outdated — a retired harness name, a git-ignored bridge, an AGENTS.local.md nothing reads, a skill a harness refuses to load, or an MCP server that differs between the golden set and a harness, on the side that is plainly ahead. Runs doctor to find them, then offers each correction with its before and after and writes only what is approved.
 
 ## Getting started
 
@@ -50,6 +51,7 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
 
 ## Agent configuration
 
+- [Agent Worktrees](https://repobuddy.github.io/buddy-agent-harness/agent-configuration/agent-worktrees/): Where Claude Code puts the git worktrees it creates for agents, why that breaks linters and git status, and the two settings a repository needs.
 - [Agent Configuration Best Practices](https://repobuddy.github.io/buddy-agent-harness/agent-configuration/best-practices/): Practices that apply across AGENTS.md, skills, and harness bridges, starting with the cost of every file an agent has to go and open.
 - [Harness Differences](https://repobuddy.github.io/buddy-agent-harness/agent-configuration/harness-differences/): Which agent harnesses read canonical configuration directly, and which need a bridge.
 - [Claude Code](https://repobuddy.github.io/buddy-agent-harness/agent-configuration/harnesses/claude-code/): Claude Code needs a skills projection, and reads AGENTS.md itself unless a CLAUDE.md beside it suppresses it.
@@ -86,7 +88,7 @@ Documentation site: [One canonical agent configuration](https://repobuddy.github
 - [Library: `diagnose-bridges/diagnose-global-instructions.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `diagnoseGlobalInstructions`, type `GlobalInstructionKind`, type `GlobalInstructionReport`, type `GlobalInstructionStatus`.
 - [Library: `diagnose-bridges/diagnose-instructions.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `diagnoseInstructions`, type `InstructionKind`, type `InstructionReport`, type `InstructionStatus`.
 - [Library: `diagnose-bridges/doctor.command.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `buildDoctorReport`, `doctorCommand`, type `DoctorReference`, type `DoctorReport`.
-- [Library: `diagnose-bridges/doctor-guidance.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `bridgeRepairs`, `doctorRepairs`, `doctorSkill`, `globalInstructionRepairs`, `instructionRepairs`, `renderDoctorSkill`, type `BridgeProblem`, type `ConfigurationFault`, type `ConfigurationProblem`, type `DoctorProblem`, type `GlobalInstructionProblem`, type `InstructionProblem`, type `McpProblem`, type `Repair`.
+- [Library: `diagnose-bridges/doctor-guidance.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports `bridgeRepairs`, `doctorRepairs`, `doctorSkill`, `globalInstructionRepairs`, `instructionRepairs`, `renderDoctorSkill`, type `BridgeProblem`, type `ConfigurationFault`, type `ConfigurationProblem`, type `DoctorProblem`, type `GlobalInstructionProblem`, type `InstructionProblem`, type `McpProblem`, type `Repair`, type `WorktreeProblem`.
 - [Library: `diagnose-bridges/git-bridge-state.ts`](https://repobuddy.github.io/buddy-agent-harness/library/doctor/): exports type `DivergenceDirection`.
 - [Library: `diagnose-mcp/diagnose-mcp.ts`](https://repobuddy.github.io/buddy-agent-harness/library/mcp/): exports `diagnoseMcp`, type `DiagnoseMcpOptions`.
 - [Library: `diagnose-mcp/mcp-baseline.ts`](https://repobuddy.github.io/buddy-agent-harness/library/mcp/): exports type `McpDirection`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buddy-agent-harness",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Initialize standards-based agent configuration across agent harnesses",
   "keywords": [
     "repobuddy",
@@ -37,6 +37,7 @@
     "!**/*.{test,spec}.ts",
     "!**/*.test-helper.ts",
     "skills",
+    "!skills/*/evals",
     "plugin.json",
     "llms.txt",
     ".claude-plugin",
@@ -48,14 +49,14 @@
     "node": ">=22"
   },
   "dependencies": {
-    "cyber-agentkit": "^2.0.0",
+    "cyber-agentkit": "^2.2.0",
     "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.8.0",
     "toml-eslint-parser": "^1.0.3",
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
-    "clibuilder": "^12.1.0"
+    "clibuilder": "^12.3.0"
   },
   "peerDependenciesMeta": {
     "clibuilder": {
@@ -65,7 +66,7 @@
   "devDependencies": {
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^5.0.0",
-    "clibuilder": "^12.1.0",
+    "clibuilder": "^12.3.0",
     "tsdown": "^0.23.0",
     "tsx": "^4.22.3",
     "typescript": "^7.0.0",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "buddy-agent-harness",
-	"version": "1.0.1",
+	"version": "1.2.0",
 	"description": "Initialize standards-based agent configuration across agent harnesses",
 	"author": {
 		"name": "repobuddy"

package/skills/doctor-buddy-agent-harness/README.md

@@ -7,7 +7,7 @@ Report whether the harness skill bridges in a repository still resolve into `.ag
 `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.
 
 ```sh
-npx -y buddy-agent-harness@1.0.1 doctor
+npx -y buddy-agent-harness@1.2.0 doctor
 ```
 
 ## Why it exists

package/skills/doctor-buddy-agent-harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doctor-buddy-agent-harness
-description: Use this skill when a repository loads no project skills, when skills are missing after a clone, when a harness appears to be ignoring AGENTS.md, or when checking whether the agent configuration bridges into .claude/skills and the other harness files still resolve.
+description: Checks whether a repository's agent configuration bridges into .claude/skills and the other harness files still resolve — when a repository loads no project skills, when skills are missing after a clone, or when a harness appears to be ignoring AGENTS.md.
 ---
 
 <!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
@@ -17,7 +17,7 @@ Diagnose it:
 node scripts/doctor.mjs
 ```
 
-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@1.0.1 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.
+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@1.2.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.
 
 The command is read-only. It never repairs anything, so it is safe to run at any point, including from a session-start hook.
 
@@ -56,6 +56,7 @@ Every `problem` name routes to exactly one page. Load the page for the finding i
 | `references/configuration.md` | a finding about the configuration around the bridges rather than a bridge |
 | `references/mcp.md` | any finding whose path is an MCP locator — **always** before acting on a credential finding |
 | `references/nonstandard.md` | a finding about configuration only one harness can read |
+| `references/worktrees.md` | a finding about the agent worktrees Claude Code creates under `.claude/worktrees/` |
 | `references/harnesses/<name>.md` | the paths and files one named harness uses |
 
 ## Rules
@@ -66,3 +67,9 @@ Every `problem` name routes to exactly one page. Load the page for the finding i
 - Never repeat a value from a file an `mcp-literal-secret` or `mcp-committed-secret` finding points at. The report withheld it on purpose, and quoting it back puts it in the transcript anyway.
 - Never write outside the repository. A `globalInstructions` repair is a step for the user to take in their own home directory; hand it over exactly as reported.
 - Write instructions in `AGENTS.md`, never in `CLAUDE.md`. Content written there reaches one harness, drifts from the canonical file, and — because Claude Code prefers it — takes `AGENTS.md` out of that harness's context entirely.
+
+## Done when
+
+- **C1.** The reply names each problem the report found and its cause, or, when the report found none, says the configuration is healthy and calls for no change.
+- **C2.** No bridge, skill, or instruction file changed: no `init` ran, and nothing was written to `CLAUDE.md`.
+- **C3.** The reply repeats no value that a secret finding withheld.

package/skills/doctor-buddy-agent-harness/references/worktrees.md

@@ -0,0 +1,17 @@
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->
+
+# Agent worktree findings
+
+Claude Code runs a session started with `--worktree`, and a subagent isolated in a worktree, in a git worktree under `.claude/worktrees/<name>/` inside the repository. That place is by design, and no setting moves it. These findings are what a repository needs so the worktrees there do no harm. `doctor` checks them only where a `.claude` directory exists.
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+| `worktrees-untracked` | .claude/worktrees/ is not git-ignored, so every agent worktree Claude Code creates there shows up as untracked in git status | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`) or `/buddy-agent-harness:enhance` (pnpm install: `pnpm-buddy-agent-harness-enhance`), which offers the .gitignore line |
+| `worktrees-scanned` | this config does not exclude .claude/worktrees, so the tool walks into each agent worktree, a whole checkout with its own config, and Biome stops on the nested root configuration | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`) or `/buddy-agent-harness:enhance` (pnpm install: `pnpm-buddy-agent-harness-enhance`), which offers the exclusion |
+| `worktree-base-unset` | worktree.baseRef is unset, so agent worktrees branch from the default branch rather than the current HEAD — work on a feature branch starts without its commits | run `/buddy-agent-harness:init-buddy-agent-harness` (pnpm install: `pnpm-buddy-agent-harness-init-buddy-agent-harness`) or `/buddy-agent-harness:enhance` (pnpm install: `pnpm-buddy-agent-harness-enhance`), which explains the trade-off and offers the setting |
+
+None of these is a fault in a file the owner wrote, and none is a `repair` correction. Each is an offer the `init-buddy-agent-harness` and `enhance` skills make, one at a time, and write only on approval.
+
+`worktree-base-unset` is a choice, not an error. The default branch suits agents given unrelated tasks; `"head"` suits agents asked to build on the branch in front of them. Put the trade-off to the owner, and report an explicit `"fresh"` as their answer rather than as a finding — `doctor` already does.
+
+`worktrees-scanned` is checked for Biome only, the one tool with a confirmed failure. A repository whose ESLint, Prettier, knip, or TypeScript configuration walks the tree can hit the same thing; the skills look for those when they make the offer.