buddy-agent-harness 1.1.0 → 1.2.0

package/llms.txt

@@ -39,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
 
@@ -51,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.
@@ -87,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.1.0",
+  "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",

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.1.0",
+	"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.1.0 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.1.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.
+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.