buddy-agent-harness 1.1.0 → 1.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "buddy-agent-harness",
-	"version": "1.1.0",
+	"version": "1.3.0",
 	"description": "Initialize standards-based agent configuration across agent harnesses",
 	"author": {
 		"name": "repobuddy"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "buddy-agent-harness",
-	"version": "1.1.0",
+	"version": "1.3.0",
 	"description": "Initialize standards-based agent configuration across agent harnesses",
 	"author": {
 		"name": "repobuddy"

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "buddy-agent-harness",
-	"version": "1.1.0",
+	"version": "1.3.0",
 	"description": "Initialize standards-based agent configuration across agent harnesses",
 	"author": {
 		"name": "repobuddy"

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # buddy-agent-harness
 
+## 1.3.0
+
+### Minor Changes
+
+- 840d2dc: `enhance` now asks, for each addition, whether to write it to your global `~/.agents/AGENTS.md` or to the repository's `AGENTS.md`. It leads with the destination the addition recommends. If you pick the global file, it writes the section at the end of `~/.agents/AGENTS.md`, creating the file if needed, instead of handing you the text. A retired wording in `~/.agents/AGENTS.md` is offered the current text in its place, and replaced on your yes. Steps that bridge a harness's own user-scope file, and a global copy kept in such a file, are still handed over.
+
+## 1.2.0
+
+### Minor Changes
+
+- 3d86bc2: Account for the git worktrees Claude Code creates under `.claude/worktrees/`, inside the repository.
+  
+  The `init-buddy-agent-harness` and `enhance` skills now offer two settings, each on its own and written only on approval: ignoring `.claude/worktrees/` in `.gitignore` and in each tree-scanning tool's config the repository has (Biome, ESLint, Prettier, knip, tsconfig), and setting `worktree.baseRef` to `"head"` in `.claude/settings.json`, with the trade-off explained first. Each worktree is a whole checkout, so Biome in the main checkout stops on its nested root configuration, and without `"head"` an agent asked to build on a feature branch starts from the default branch.
+  
+  `doctor` reports what is missing in a repository with a `.claude/` directory: `worktrees-untracked` for the `.gitignore` rule, `worktrees-scanned` for a `biome.json` that does not exclude the directory, and `worktree-base-unset` for a `.claude/settings.json` that leaves `worktree.baseRef` unset. An explicit `"fresh"` is the owner's choice and is not reported.
+- 8373121: The `enhance` skill now offers a fourth addition, `## References as links`. It tells the agent to write each issue, pull request, or commit it mentions as a Markdown link to its page rather than a bare `#222`, which is a link only on GitHub itself and names the wrong repository when the agent works across several.
+  
+  It is gated like the other three. 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. Its history file starts empty, so a section already in a file is compared against the current text, and no harness scores this wording yet, so where the skill cannot tell whose a section is, it offers two answers rather than three.
+
+### Patch Changes
+
+- ce2b780: The `doctor-buddy-agent-harness` skill now lists the outcomes it is done when, so its evals can check them.
+- 8588ad8: The shipped skill descriptions (`doctor-buddy-agent-harness`, `enhance`, `init-buddy-agent-harness`, `repair`) now open by saying what the skill does instead of "Use this skill when". Every trigger phrase is kept.
+- 4c76524: The `repair` skill no longer says that only the instruction, configuration, non-standard, and agent-worktree families name a skill in `help`. Four MCP findings name `repair` too: `mcp-unprojected`, `mcp-undeclared`, `mcp-diverged-target`, and `mcp-diverged-golden`. Its README now lists the MCP drift it corrects.
+
 ## 1.1.0
 
 ### Minor Changes

package/dist/cli.mjs

@@ -14110,7 +14110,7 @@ function gitIgnores(root, path) {
 }
 /** One answer per discovery, so a run resolving many names reads each `package.json` once. */
 const found = /* @__PURE__ */ new WeakMap();
-function readJson$2(path) {
+function readJson$3(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -14121,7 +14121,7 @@ function declared(top, folders) {
 	const plugins = [];
 	for (const folder of folders) {
 		const manifestPath = join(top, ...folder.split("/"), "package.json");
-		const manifest = readJson$2(manifestPath);
+		const manifest = readJson$3(manifestPath);
 		for (const pkg of declaredDependencies(manifest)) {
 			const dir = packageDir(pkg, manifestPath);
 			const plugin = dir && pluginManifestName(dir);
@@ -17752,7 +17752,7 @@ function serializeCatalog(catalog) {
 }
 //#endregion
 //#region src/dep-plugins/resolve.ts
-function readJson$1(path) {
+function readJson$2(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -17767,7 +17767,7 @@ function readDepPlugin(pkg, fromManifest) {
 		package: pkg,
 		reason: "unresolved"
 	};
-	const manifest = readJson$1(join(dir, "plugin.json"));
+	const manifest = readJson$2(join(dir, "plugin.json"));
 	if (!manifest || typeof manifest !== "object") return {
 		ok: false,
 		package: pkg,
@@ -17780,7 +17780,7 @@ function readDepPlugin(pkg, fromManifest) {
 		package: pkg,
 		reason: "unnamed"
 	};
-	const installed = readJson$1(join(dir, "package.json"));
+	const installed = readJson$2(join(dir, "package.json"));
 	const version = typeof installed?.version === "string" ? installed.version : void 0;
 	if (!version) return {
 		ok: false,
@@ -17873,7 +17873,7 @@ function writeCatalog(root, catalog) {
 //#endregion
 //#region src/dep-plugins/harness-plugins.ts
 const COPILOT_LIMITATION = "Copilot CLI rejects an npm marketplace source, so it cannot install from this catalog. It needs a path-sourced catalog, which cannot reach node_modules from a subdirectory.";
-function readJson(path) {
+function readJson$1(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -17891,7 +17891,7 @@ function claudeConfigDir(home, env = process.env) {
 	return env["CLAUDE_CONFIG_DIR"] || join(home, ".claude");
 }
 function readClaudeState(configDir) {
-	const installedFile = readJson(join(configDir, "plugins", "installed_plugins.json"));
+	const installedFile = readJson$1(join(configDir, "plugins", "installed_plugins.json"));
 	const installed = [];
 	for (const [id, entries] of Object.entries(installedFile?.plugins ?? {})) {
 		if (!Array.isArray(entries)) continue;
@@ -17914,7 +17914,7 @@ function readClaudeState(configDir) {
 			});
 		}
 	}
-	const knownFile = readJson(join(configDir, "plugins", "known_marketplaces.json"));
+	const knownFile = readJson$1(join(configDir, "plugins", "known_marketplaces.json"));
 	const marketplaces = [];
 	for (const [name, value] of Object.entries(knownFile ?? {})) marketplaces.push({
 		name,
@@ -18176,6 +18176,7 @@ const initSkillInvocation = `/buddy-agent-harness:init-buddy-agent-harness`;
 */
 const pnpmSkillRef = (invocation) => `\`${invocation}\` (pnpm install: \`pnpm-${commandInvocation}-${invocation.slice(invocation.indexOf(":") + 1)}\`)`;
 const initSkillRef = pnpmSkillRef(initSkillInvocation);
+const enhanceSkillRef = pnpmSkillRef("/buddy-agent-harness:enhance");
 const repairSkillRef = pnpmSkillRef(repairSkillInvocation);
 /** Where the user authors the golden MCP server set, named in every MCP repair that points at it. */
 const goldenSet = ".agents/buddy-agent-harness/mcp.toml";
@@ -18541,6 +18542,35 @@ const nonstandardTable = {
 	}
 };
 repairsOf(nonstandardTable);
+/** Who offers every worktree repair, named the same way in each row. */
+const worktreeOffer = `${initSkillRef} offers it, or ${enhanceSkillRef} where the repository already has an AGENTS.md`;
+const worktreeTable = {
+	"worktrees-untracked": {
+		detail: ".claude/worktrees/ is not git-ignored, so every agent worktree Claude Code creates there shows up as untracked in git status",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `add \`.claude/worktrees/\` to ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the .gitignore line`
+	},
+	"worktrees-scanned": {
+		detail: "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",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `add \`"!**/.claude/worktrees"\` to \`files.includes\` in ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the exclusion`
+	},
+	"worktree-base-unset": {
+		detail: "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",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `decide whether agent worktrees should branch from HEAD, and if so set \`"worktree": { "baseRef": "head" }\` in ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which explains the trade-off and offers the setting`
+	}
+};
+repairsOf(worktreeTable);
 /**
 * Annotated over the whole union rather than inferred, so an added problem fails to compile until
 * its section carries it.
@@ -18551,7 +18581,8 @@ const doctorTable = {
 	...globalInstructionTable,
 	...configurationTable,
 	...mcpTable,
-	...nonstandardTable
+	...nonstandardTable,
+	...worktreeTable
 };
 repairsOf(doctorTable);
 /** The repair for one problem. Total by construction: the table is keyed by the union. */
@@ -20340,6 +20371,43 @@ function diagnoseNonstandard({ root, cli }) {
 	}
 	return findings.sort((left, right) => left.path.localeCompare(right.path));
 }
+const biomeConfigs = ["biome.json", "biome.jsonc"];
+const claudeSettings = ".claude/settings.json";
+/** `undefined` when the file is missing or does not parse; either way Claude Code reads no base from it. */
+function readJson(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Checked only where `.claude/` exists, the sign the repository is worked in with Claude Code.
+* Biome is the one tool checked: it is the confirmed failure, and the others are offered by the
+* skills without a finding.
+*/
+function diagnoseWorktrees({ root, git, cli }) {
+	if (!existsSync(join(root, ".claude"))) return [];
+	const findings = [];
+	const add = (path, problem) => {
+		const { detail, repair } = repairFor(problem);
+		findings.push({
+			path,
+			problem,
+			detail,
+			repair: repair({ file: path }, cli)
+		});
+	};
+	if (git.isRepository() && !git.isIgnored(".claude/worktrees/")) add(".gitignore", "worktrees-untracked");
+	for (const config of biomeConfigs) {
+		const path = join(root, config);
+		if (existsSync(path) && !readFileSync(path, "utf8").includes(".claude/worktrees")) add(config, "worktrees-scanned");
+	}
+	const settings = readJson(join(root, claudeSettings));
+	const worktree = isRecord(settings) ? settings["worktree"] : void 0;
+	if (!isRecord(worktree) || worktree["baseRef"] === void 0) add(claudeSettings, "worktree-base-unset");
+	return findings;
+}
 //#endregion
 //#region ../../node_modules/.pnpm/cyber-agentkit@2.2.0_clibuilder@12.3.0_js-yaml@4.3.2_/node_modules/cyber-agentkit/dist/commands.js
 /**
@@ -22048,6 +22116,10 @@ var GitBridgeState = class {
 		this.root = root;
 		this.repoRootPrefix = git(root, ["rev-parse", "--show-prefix"])?.trim();
 	}
+	/** Whether `root` is inside a git work tree at all; a check that needs git's answer skips when not. */
+	isRepository() {
+		return this.repoRootPrefix !== void 0;
+	}
 	/** The skip-worktree bit is a hint some checkouts clear, so it is verified rather than assumed. */
 	trackingOf(path) {
 		if (this.repoRootPrefix === void 0) return "untracked";
@@ -22349,6 +22421,11 @@ async function diagnoseReport(args) {
 			...diagnoseNonstandard({
 				root,
 				cli: commandInvocation
+			}),
+			...diagnoseWorktrees({
+				root,
+				git,
+				cli: commandInvocation
 			})
 		];
 		const { layers: rows } = listReferences(await referenceLayers({

package/dist/index.d.mts

@@ -240,8 +240,13 @@ type NonstandardProblem = "nonstandard-instructions" | "nonstandard-rule" | "non
 type InstructionProblem = "no-instructions" | "instructions-missing" | "instructions-unbridged" | "instructions-unreadable" | "instructions-shadowing" | "instructions-superseded";
 /** Every way a harness's user-scope instruction file fails to load `~/.agents/AGENTS.md`. */
 type GlobalInstructionProblem = "global-instructions-missing" | "global-instructions-unbridged" | "global-instructions-overridden" | "global-instructions-emptied";
+/**
+ * What a repository lacks for the git worktrees Claude Code creates under `.claude/worktrees/`;
+ * each is an offer `init` and `enhance` make, never a fault in a file the owner wrote.
+ */
+type WorktreeProblem = "worktrees-untracked" | "worktrees-scanned" | "worktree-base-unset";
 /** Everything `doctor` can report against, across every section. */
-type DoctorProblem = BridgeProblem | InstructionProblem | GlobalInstructionProblem | ConfigurationFault | McpProblem | NonstandardProblem;
+type DoctorProblem = BridgeProblem | InstructionProblem | GlobalInstructionProblem | ConfigurationFault | McpProblem | NonstandardProblem | WorktreeProblem;
 /** Alias kept for callers that name the whole set rather than one section. */
 type ConfigurationProblem = DoctorProblem;
 type RepairAction = {
@@ -271,7 +276,7 @@ export declare const globalInstructionRepairs: readonly Repair[];
 export declare const doctorRepairs: readonly Repair[];
 export declare const doctorSkill: {
   readonly name: "doctor-buddy-agent-harness";
-  readonly 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.";
+  readonly 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.";
 };
 /**
  * The shipped `doctor-buddy-agent-harness` skill; the finding tables live in the reference pages
@@ -293,6 +298,8 @@ declare class GitBridgeState {
   /** `''` at the top, `undefined` outside a repository. */
   private readonly repoRootPrefix;
   constructor(root: string);
+  /** Whether `root` is inside a git work tree at all; a check that needs git's answer skips when not. */
+  isRepository(): boolean;
   /** The skip-worktree bit is a hint some checkouts clear, so it is verified rather than assumed. */
   trackingOf(path: string): TrackingState;
   /**
@@ -655,5 +662,5 @@ type ReferenceLayerOptions = Omit<ReferenceLayerOptions$1, "plugin"> & {
 export declare function referenceLayers({ packageRoot, ...options }: ReferenceLayerOptions): Promise<ReferenceLayers>;
 export declare const referenceCommand: cli$1.Command;
 //#endregion
-export { type BridgeFinding, type BridgeKind, type BridgeProblem, type BridgeReport, type BridgeStatus, type ConfigurationFault, type ConfigurationProblem, type DiagnoseMcpOptions, type DiagnoseOptions, type DiagnoseResult, type DivergenceDirection, type DivergenceReport, type DoctorProblem, type DoctorReference, type DoctorReport, type GlobalInstructionKind, type GlobalInstructionProblem, type GlobalInstructionReport, type GlobalInstructionStatus, type GovernanceDocument, type GovernanceEntry, type GovernanceLayer, type GovernanceListReport, type GovernanceScope, type GovernanceShowReport, type Harness, type HarnessName, type HarnessScope, type HarnessScopeName, type InitializeOptions, type InitializeResult, type InstructionBridge, type InstructionKind, type InstructionProblem, type InstructionReport, type InstructionStatus, type LayerOptions, type ListMcpServersOptions, type MatchKind, type McpConfig, type McpDirection, type McpField, type McpProblem, type McpServer, type McpServerEntry, type McpTransport, type ReferenceLayer, type ReferenceLayerOptions, type ReferenceListLayerRow, type ReferenceListReport, type ReferenceListRow, type ReferenceListing, type ReferenceLoadEntry, type ReferenceName, type ReferenceSearchReport, type ReferenceStatus, type ReferenceTier, type Repair, type ResolveOptions, type ResolvedReference, type SearchMatch, listReferences, parseReferenceName, resolveReference, searchReferences };
+export { type BridgeFinding, type BridgeKind, type BridgeProblem, type BridgeReport, type BridgeStatus, type ConfigurationFault, type ConfigurationProblem, type DiagnoseMcpOptions, type DiagnoseOptions, type DiagnoseResult, type DivergenceDirection, type DivergenceReport, type DoctorProblem, type DoctorReference, type DoctorReport, type GlobalInstructionKind, type GlobalInstructionProblem, type GlobalInstructionReport, type GlobalInstructionStatus, type GovernanceDocument, type GovernanceEntry, type GovernanceLayer, type GovernanceListReport, type GovernanceScope, type GovernanceShowReport, type Harness, type HarnessName, type HarnessScope, type HarnessScopeName, type InitializeOptions, type InitializeResult, type InstructionBridge, type InstructionKind, type InstructionProblem, type InstructionReport, type InstructionStatus, type LayerOptions, type ListMcpServersOptions, type MatchKind, type McpConfig, type McpDirection, type McpField, type McpProblem, type McpServer, type McpServerEntry, type McpTransport, type ReferenceLayer, type ReferenceLayerOptions, type ReferenceListLayerRow, type ReferenceListReport, type ReferenceListRow, type ReferenceListing, type ReferenceLoadEntry, type ReferenceName, type ReferenceSearchReport, type ReferenceStatus, type ReferenceTier, type Repair, type ResolveOptions, type ResolvedReference, type SearchMatch, type WorktreeProblem, listReferences, parseReferenceName, resolveReference, searchReferences };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/cli.ts","../src/harness-registry/instruction-bridge.ts","../src/diagnose-mcp/mcp-model.ts","../src/mcp-dialects/mcp-dialects.ts","../src/harness-registry/mcp-config.ts","../src/harness-registry/nonstandard-artifact.ts","../src/harness-registry/harness-registry.ts","../src/diagnose-bridges/diagnose-global-instructions.ts","../src/diagnose-bridges/diagnose-instructions.ts","../src/diagnose-bridges/locator.ts","../src/diagnose-bridges/doctor-guidance.ts","../src/diagnose-bridges/git-bridge-state.ts","../src/diagnose-bridges/diagnose-bridges.ts","../src/diagnose-configuration/diagnose-configuration.ts","../src/diagnose-bridges/doctor.command.ts","../src/diagnose-mcp/diagnose-mcp.ts","../src/diagnose-mcp/mcp-baseline.ts","../src/diagnose-mcp/mcp-sources.ts","../src/governance-overrides/governance-overrides.ts","../src/governance-overrides/governance.command.ts","../src/initialize-harnesses/init.command.ts","../src/skill-projection/skill-projection.ts","../src/initialize-harnesses/initialize-harnesses.ts","../src/mcp-inventory/mcp-inventory.ts","../src/references/references.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/cli.ts","../src/harness-registry/instruction-bridge.ts","../src/diagnose-mcp/mcp-model.ts","../src/mcp-dialects/mcp-dialects.ts","../src/harness-registry/mcp-config.ts","../src/harness-registry/nonstandard-artifact.ts","../src/harness-registry/harness-registry.ts","../src/diagnose-bridges/diagnose-global-instructions.ts","../src/diagnose-bridges/diagnose-instructions.ts","../src/diagnose-bridges/locator.ts","../src/diagnose-bridges/doctor-guidance.ts","../src/diagnose-bridges/git-bridge-state.ts","../src/diagnose-bridges/diagnose-bridges.ts","../src/diagnose-configuration/diagnose-configuration.ts","../src/diagnose-bridges/doctor.command.ts","../src/diagnose-mcp/diagnose-mcp.ts","../src/diagnose-mcp/mcp-baseline.ts","../src/diagnose-mcp/mcp-sources.ts","../src/governance-overrides/governance-overrides.ts","../src/governance-overrides/governance.command.ts","../src/initialize-harnesses/init.command.ts","../src/skill-projection/skill-projection.ts","../src/initialize-harnesses/initialize-harnesses.ts","../src/mcp-inventory/mcp-inventory.ts","../src/references/references.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -371,7 +371,7 @@ function serializeCatalog(catalog) {
 }
 //#endregion
 //#region src/dep-plugins/resolve.ts
-function readJson$1(path) {
+function readJson$2(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -386,7 +386,7 @@ function readDepPlugin(pkg, fromManifest) {
 		package: pkg,
 		reason: "unresolved"
 	};
-	const manifest = readJson$1(join(dir, "plugin.json"));
+	const manifest = readJson$2(join(dir, "plugin.json"));
 	if (!manifest || typeof manifest !== "object") return {
 		ok: false,
 		package: pkg,
@@ -399,7 +399,7 @@ function readDepPlugin(pkg, fromManifest) {
 		package: pkg,
 		reason: "unnamed"
 	};
-	const installed = readJson$1(join(dir, "package.json"));
+	const installed = readJson$2(join(dir, "package.json"));
 	const version = typeof installed?.version === "string" ? installed.version : void 0;
 	if (!version) return {
 		ok: false,
@@ -492,7 +492,7 @@ function writeCatalog(root, catalog) {
 //#endregion
 //#region src/dep-plugins/harness-plugins.ts
 const COPILOT_LIMITATION = "Copilot CLI rejects an npm marketplace source, so it cannot install from this catalog. It needs a path-sourced catalog, which cannot reach node_modules from a subdirectory.";
-function readJson(path) {
+function readJson$1(path) {
 	try {
 		return JSON.parse(readFileSync(path, "utf8"));
 	} catch {
@@ -510,7 +510,7 @@ function claudeConfigDir(home, env = process.env) {
 	return env["CLAUDE_CONFIG_DIR"] || join(home, ".claude");
 }
 function readClaudeState(configDir) {
-	const installedFile = readJson(join(configDir, "plugins", "installed_plugins.json"));
+	const installedFile = readJson$1(join(configDir, "plugins", "installed_plugins.json"));
 	const installed = [];
 	for (const [id, entries] of Object.entries(installedFile?.plugins ?? {})) {
 		if (!Array.isArray(entries)) continue;
@@ -533,7 +533,7 @@ function readClaudeState(configDir) {
 			});
 		}
 	}
-	const knownFile = readJson(join(configDir, "plugins", "known_marketplaces.json"));
+	const knownFile = readJson$1(join(configDir, "plugins", "known_marketplaces.json"));
 	const marketplaces = [];
 	for (const [name, value] of Object.entries(knownFile ?? {})) marketplaces.push({
 		name,
@@ -804,6 +804,7 @@ const initSkillInvocation = `/buddy-agent-harness:init-buddy-agent-harness`;
 */
 const pnpmSkillRef = (invocation) => `\`${invocation}\` (pnpm install: \`pnpm-${commandInvocation}-${invocation.slice(invocation.indexOf(":") + 1)}\`)`;
 const initSkillRef = pnpmSkillRef(initSkillInvocation);
+const enhanceSkillRef = pnpmSkillRef("/buddy-agent-harness:enhance");
 const repairSkillRef = pnpmSkillRef(repairSkillInvocation);
 /** Where the user authors the golden MCP server set, named in every MCP repair that points at it. */
 const goldenSet = ".agents/buddy-agent-harness/mcp.toml";
@@ -1169,6 +1170,35 @@ const nonstandardTable = {
 	}
 };
 repairsOf(nonstandardTable);
+/** Who offers every worktree repair, named the same way in each row. */
+const worktreeOffer = `${initSkillRef} offers it, or ${enhanceSkillRef} where the repository already has an AGENTS.md`;
+const worktreeTable = {
+	"worktrees-untracked": {
+		detail: ".claude/worktrees/ is not git-ignored, so every agent worktree Claude Code creates there shows up as untracked in git status",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `add \`.claude/worktrees/\` to ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the .gitignore line`
+	},
+	"worktrees-scanned": {
+		detail: "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",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `add \`"!**/.claude/worktrees"\` to \`files.includes\` in ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the exclusion`
+	},
+	"worktree-base-unset": {
+		detail: "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",
+		repair: ({ file }) => ({
+			command: "",
+			instruction: `decide whether agent worktrees should branch from HEAD, and if so set \`"worktree": { "baseRef": "head" }\` in ${file} — ${worktreeOffer}`
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which explains the trade-off and offers the setting`
+	}
+};
+repairsOf(worktreeTable);
 /**
 * Annotated over the whole union rather than inferred, so an added problem fails to compile until
 * its section carries it.
@@ -1179,7 +1209,8 @@ const doctorTable = {
 	...globalInstructionTable,
 	...configurationTable,
 	...mcpTable,
-	...nonstandardTable
+	...nonstandardTable,
+	...worktreeTable
 };
 const doctorRepairs = repairsOf(doctorTable);
 /** The repair for one problem. Total by construction: the table is keyed by the union. */
@@ -1191,7 +1222,7 @@ function repairFor(problem) {
 }
 const doctorSkill = {
 	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."
 };
 /** Written into the generated skill so a reader knows not to edit it in place. */
 const generatedSkillWarning = "<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-skills.ts. Do not edit by hand. -->";
@@ -1258,6 +1289,7 @@ Every \`problem\` name routes to exactly one page. Load the page for the finding
 | \`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
@@ -1268,6 +1300,12 @@ Every \`problem\` name routes to exactly one page. Load the page for the finding
 - 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.
 `;
 }
 //#endregion
@@ -2080,6 +2118,43 @@ function diagnoseNonstandard({ root, cli }) {
 	}
 	return findings.sort((left, right) => left.path.localeCompare(right.path));
 }
+const biomeConfigs = ["biome.json", "biome.jsonc"];
+const claudeSettings = ".claude/settings.json";
+/** `undefined` when the file is missing or does not parse; either way Claude Code reads no base from it. */
+function readJson(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Checked only where `.claude/` exists, the sign the repository is worked in with Claude Code.
+* Biome is the one tool checked: it is the confirmed failure, and the others are offered by the
+* skills without a finding.
+*/
+function diagnoseWorktrees({ root, git, cli }) {
+	if (!existsSync(join(root, ".claude"))) return [];
+	const findings = [];
+	const add = (path, problem) => {
+		const { detail, repair } = repairFor(problem);
+		findings.push({
+			path,
+			problem,
+			detail,
+			repair: repair({ file: path }, cli)
+		});
+	};
+	if (git.isRepository() && !git.isIgnored(".claude/worktrees/")) add(".gitignore", "worktrees-untracked");
+	for (const config of biomeConfigs) {
+		const path = join(root, config);
+		if (existsSync(path) && !readFileSync(path, "utf8").includes(".claude/worktrees")) add(config, "worktrees-scanned");
+	}
+	const settings = readJson(join(root, claudeSettings));
+	const worktree = isRecord(settings) ? settings["worktree"] : void 0;
+	if (!isRecord(worktree) || worktree["baseRef"] === void 0) add(claudeSettings, "worktree-base-unset");
+	return findings;
+}
 //#endregion
 //#region src/governance-overrides/governance-overrides.ts
 function machineWideDir(platform, programData, names) {
@@ -2691,6 +2766,10 @@ var GitBridgeState = class {
 		this.root = root;
 		this.repoRootPrefix = git(root, ["rev-parse", "--show-prefix"])?.trim();
 	}
+	/** Whether `root` is inside a git work tree at all; a check that needs git's answer skips when not. */
+	isRepository() {
+		return this.repoRootPrefix !== void 0;
+	}
 	/** The skip-worktree bit is a hint some checkouts clear, so it is verified rather than assumed. */
 	trackingOf(path) {
 		if (this.repoRootPrefix === void 0) return "untracked";
@@ -2992,6 +3071,11 @@ async function diagnoseReport(args) {
 			...diagnoseNonstandard({
 				root,
 				cli: commandInvocation
+			}),
+			...diagnoseWorktrees({
+				root,
+				git,
+				cli: commandInvocation
 			})
 		];
 		const { layers: rows } = listReferences$1(await referenceLayers({