buddy-agent-harness 0.4.1 → 0.6.0

package/src/diagnose-bridges/diagnose-instructions.ts

@@ -0,0 +1,140 @@
+import { lstatSync, readFileSync, readlinkSync } from 'node:fs'
+import { join, posix } from 'node:path'
+import type { Harness, HarnessName } from '../harness-registry/harness-registry.ts'
+import type { InstructionBridge } from '../harness-registry/instruction-bridge.ts'
+import { agentsFileDirectories } from './agents-files.ts'
+import type { BridgeFinding } from './diagnose-bridges.ts'
+import { type InstructionProblem, repairFor } from './doctor-guidance.ts'
+import { parseJsonWithComments } from './json-with-comments.ts'
+
+/** What is on disk where an instruction bridge belongs. */
+export type InstructionKind = 'import' | 'symlink' | 'settings-entry' | 'file' | 'none'
+/**
+ * `unbridged` is the case a skills bridge has no equivalent of: the file is there, so nothing looks
+ * wrong, and it names `AGENTS.md` nowhere — a `CLAUDE.md` overwritten with real content, or a
+ * settings file another tool rewrote.
+ */
+export type InstructionStatus = 'ok' | 'missing' | 'unbridged' | 'unreadable'
+
+export type InstructionReport = {
+	harness: HarnessName
+	/** Repository-relative path of the file that carries the bridge. */
+	path: string
+	kind: InstructionKind
+	status: InstructionStatus
+}
+
+export const canonicalInstructions = 'AGENTS.md'
+
+type Inspection = {
+	kind: InstructionKind
+	status: InstructionStatus
+	problem?: InstructionProblem
+}
+
+/**
+ * An import bridges the `AGENTS.md` beside it and nothing else, so the check is per directory
+ * holding one rather than per harness. A line of its own is enough: the harness reference allows
+ * Claude-specific notes below the import, and a file that carries the import plus notes still
+ * bridges.
+ */
+function inspectImport(target: string): Inspection {
+	let stats: ReturnType<typeof lstatSync>
+	try {
+		stats = lstatSync(target)
+	} catch {
+		return { kind: 'none', status: 'missing', problem: 'instructions-missing' }
+	}
+
+	if (stats.isSymbolicLink()) {
+		return readlinkSync(target) === canonicalInstructions
+			? { kind: 'symlink', status: 'ok' }
+			: { kind: 'symlink', status: 'unbridged', problem: 'instructions-unbridged' }
+	}
+
+	const imported = readFileSync(target, 'utf8')
+		.split('\n')
+		.some((line) => line.trim() === `@${canonicalInstructions}`)
+	return imported
+		? { kind: 'import', status: 'ok' }
+		: { kind: 'file', status: 'unbridged', problem: 'instructions-unbridged' }
+}
+
+/** Reads a dotted key out of parsed JSON without asserting anything about the rest of the file. */
+function valueAt(settings: unknown, key: string): unknown {
+	return key.split('.').reduce<unknown>((value, segment) => {
+		if (typeof value !== 'object' || value === null) return undefined
+		return (value as Record<string, unknown>)[segment]
+	}, settings)
+}
+
+function inspectSettingsEntry(target: string, key: string): Inspection {
+	let source: string
+	try {
+		source = readFileSync(target, 'utf8')
+	} catch {
+		return { kind: 'none', status: 'missing', problem: 'instructions-missing' }
+	}
+
+	const settings = parseJsonWithComments(source)
+	if (settings === undefined) return { kind: 'file', status: 'unreadable', problem: 'instructions-unreadable' }
+
+	const entry = valueAt(settings, key)
+	return Array.isArray(entry) && entry.includes(canonicalInstructions)
+		? { kind: 'settings-entry', status: 'ok' }
+		: { kind: 'file', status: 'unbridged', problem: 'instructions-unbridged' }
+}
+
+/** Every path an instruction bridge of this kind belongs at, in report order. */
+function pathsFor(root: string, bridge: InstructionBridge): string[] {
+	if (bridge.kind !== 'import') return [bridge.path]
+	return agentsFileDirectories(root).map((directory) => (directory ? posix.join(directory, bridge.path) : bridge.path))
+}
+
+function inspect(target: string, bridge: InstructionBridge): Inspection {
+	return bridge.kind === 'import' ? inspectImport(target) : inspectSettingsEntry(target, bridge.key)
+}
+
+/**
+ * Reports whether every enabled harness can still read `AGENTS.md`.
+ *
+ * Losing one of these is quieter than losing a skills bridge and costs more: a harness with no
+ * instruction bridge reads none of the repository's instructions, and says nothing about it. The
+ * checks are read-only, and no repair is a command — rewriting an instruction file is the `init`
+ * skill's judgment.
+ */
+export function diagnoseInstructions(
+	root: string,
+	harnesses: readonly Harness[],
+	cli: string,
+): { instructions: InstructionReport[]; findings: BridgeFinding[] } {
+	// Project scope only: `doctor` diagnoses a repository, and the user-scope bridges are neither
+	// written nor read by this tool.
+	const bridged = harnesses
+		.map((harness) => ({ name: harness.name, bridge: harness.project.instructionBridge }))
+		.filter((harness): harness is { name: HarnessName; bridge: InstructionBridge } => Boolean(harness.bridge))
+
+	const instructions: InstructionReport[] = []
+	const findings: BridgeFinding[] = []
+	if (!bridged.length) return { instructions, findings }
+
+	// Only reported when something bridges into it. Every other harness reads `AGENTS.md` where it
+	// lies, so its absence is a repository that has not run `init` rather than a broken bridge.
+	if (!agentsFileDirectories(root).includes('')) {
+		const { detail, repair } = repairFor('no-instructions')
+		findings.push({ path: canonicalInstructions, detail, repair: repair(canonicalInstructions, cli) })
+	}
+
+	for (const { name, bridge } of bridged) {
+		for (const path of pathsFor(root, bridge)) {
+			const inspection = inspect(join(root, path), bridge)
+			instructions.push({ harness: name, path, kind: inspection.kind, status: inspection.status })
+			if (inspection.problem) {
+				const { detail, repair } = repairFor(inspection.problem)
+				findings.push({ path, detail, repair: repair(path, cli) })
+			}
+		}
+	}
+
+	return { instructions, findings }
+}

package/src/diagnose-bridges/doctor-guidance.ts

@@ -4,7 +4,7 @@
  * `scripts/generate-skills.ts`, so the shipped skill cannot drift from what the command says.
  */
 
-/** Every way a bridge can fail, in the order `doctor` reports them. */
+/** Every way a skills bridge can fail, in the order `doctor` reports them. */
 export type BridgeProblem =
 	| 'no-canonical'
 	| 'missing'
@@ -16,8 +16,22 @@ export type BridgeProblem =
 	| 'diverged-unknown'
 	| 'unpinned-copy'
 
+/**
+ * Every way an instruction bridge can fail. Separate from `BridgeProblem` because the two share no
+ * repair: a skills bridge is rebuilt with `init` flags, and an instruction bridge is a file whose
+ * content is the user's, so every repair here goes back to the `init` skill.
+ */
+export type InstructionProblem =
+	| 'no-instructions'
+	| 'instructions-missing'
+	| 'instructions-unbridged'
+	| 'instructions-unreadable'
+
+/** Everything `doctor` can report against, across both sections. */
+export type DoctorProblem = BridgeProblem | InstructionProblem
+
 export type Repair = {
-	problem: BridgeProblem
+	problem: DoctorProblem
 	/** What `doctor` prints in the `findings` row for this problem. */
 	detail: string
 	/**
@@ -83,7 +97,8 @@ await import(join(packageRoot, 'bin', '${commandInvocation}.mjs'))
 /** How the skill hands a repair back to `init`. */
 export const initSkillInvocation = '/buddy-agent-harness:init'
 
-export const doctorRepairs: readonly Repair[] = [
+/** The skills bridges, reported in `bridges`. */
+export const bridgeRepairs: readonly Repair[] = [
 	{
 		problem: 'no-canonical',
 		detail: 'the canonical skill directory does not exist, so no bridge can resolve',
@@ -144,16 +159,53 @@ export const doctorRepairs: readonly Repair[] = [
 	},
 ]
 
+/**
+ * The instruction bridges, reported in `instructions`. Every repair is the `init` skill: these are
+ * files a person wrote, or files carrying content beside the bridge, and deciding what to preserve
+ * while restoring the bridge is judgment no flag carries. `repair` therefore names the skill in
+ * both places rather than pretending a shell command exists.
+ */
+export const instructionRepairs: readonly Repair[] = [
+	{
+		problem: 'no-instructions',
+		detail: 'no AGENTS.md at the repository root, so every instruction bridge points at nothing',
+		repair: () => initSkillInvocation,
+		skillRepair: () => `run \`${initSkillInvocation}\`, which derives AGENTS.md and the bridges to it`,
+	},
+	{
+		problem: 'instructions-missing',
+		detail: 'no instruction bridge at this path — the harness reads none of AGENTS.md',
+		repair: () => initSkillInvocation,
+		skillRepair: () => `run \`${initSkillInvocation}\``,
+	},
+	{
+		problem: 'instructions-unbridged',
+		detail: 'the file is present but names AGENTS.md nowhere — the harness reads none of it',
+		repair: () => initSkillInvocation,
+		skillRepair: () =>
+			`run \`${initSkillInvocation}\`, which adds the bridge without discarding what the file already says`,
+	},
+	{
+		problem: 'instructions-unreadable',
+		detail: 'the settings file does not parse, so the harness reads none of it',
+		repair: () => initSkillInvocation,
+		skillRepair: () => `fix the JSON by hand, then run \`${initSkillInvocation}\``,
+	},
+]
+
+/** Both sections, in the order `doctor` reports them. */
+export const doctorRepairs: readonly Repair[] = [...bridgeRepairs, ...instructionRepairs]
+
 const repairsByProblem = new Map(doctorRepairs.map((entry) => [entry.problem, entry]))
 
-export function repairFor(problem: BridgeProblem): Repair {
+export function repairFor(problem: DoctorProblem): Repair {
 	return repairsByProblem.get(problem) as Repair
 }
 
 export const doctorSkill = {
 	name: 'doctor',
 	description:
-		'Use this skill when a repository loads no project skills, when skills are missing after a clone, or when checking whether the agent configuration bridges into .claude/skills and the other harness directories still resolve.',
+		'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, CLAUDE.md, and the other harness files still resolve.',
 } as const
 
 /** Written into the generated skill so a reader knows not to edit it in place. */
@@ -168,9 +220,10 @@ export const generatedSkillWarning =
 export function renderDoctorSkill(version: string): string {
 	// A repair may itself contain a pipe, which would otherwise end the table cell early.
 	const cell = (value: string) => value.replaceAll('|', '\\|')
-	const rows = doctorRepairs
-		.map((entry) => `| \`${entry.problem}\` | ${entry.detail} | ${cell(entry.skillRepair('<path>'))} |`)
-		.join('\n')
+	const rows = (repairs: readonly Repair[]) =>
+		repairs
+			.map((entry) => `| \`${entry.problem}\` | ${entry.detail} | ${cell(entry.skillRepair('<path>'))} |`)
+			.join('\n')
 
 	return `---
 name: ${doctorSkill.name}
@@ -181,7 +234,7 @@ ${generatedSkillWarning}
 
 # Harness Doctor
 
-\`.agents/skills\` is the canonical skill directory. Harnesses that cannot read it — Claude Code and Gemini CLI — get a bridge pointing at it, normally a directory symlink. A bridge that stops resolving is silent: the harness finds nothing and loads zero project skills, with no warning anywhere.
+A repository keeps one canonical configuration: \`.agents/skills\` for its skills and \`AGENTS.md\` for its instructions. Harnesses that cannot read those get bridges pointing at them: Claude Code needs both, and Gemini CLI needs the instruction bridge only — it reads \`.agents/skills\` itself. A bridge that stops resolving is silent: the harness finds nothing and loads zero project skills, with no warning anywhere. An instruction bridge fails the same way and costs more, because the harness then reads none of the repository's instructions at all.
 
 Diagnose it:
 
@@ -195,22 +248,36 @@ The command is read-only. It never repairs anything, so it is safe to run at any
 
 ## Reading the report
 
-\`bridges\` lists every bridge \`init\` would create for this repository, each with a \`status\` of \`ok\`, \`missing\`, \`degraded\`, \`stale\`, or \`diverged\`. \`findings\` explains each problem and \`help\` names its repair. Apply the repair from the table below, then re-run \`doctor\`.
+\`bridges\` lists every skills bridge \`init\` would create for this repository, each with a \`status\` of \`ok\`, \`missing\`, \`degraded\`, \`stale\`, or \`diverged\`.
+
+\`instructions\` lists every instruction bridge into \`AGENTS.md\`, with a \`status\` of \`ok\`, \`missing\`, \`unbridged\`, or \`unreadable\`. They are a separate section because nothing about them is shared: a different \`kind\`, a different status vocabulary, and a repair that is never a command.
+
+\`findings\` explains each problem from either section and \`help\` names its repair. Apply the repair from the tables below, then re-run \`doctor\`.
 
-\`help\` names the \`init\` command for a person at a shell. Do not run it yourself. Rebuilding a bridge can move skills a user wrote, and that judgment belongs to the \`init\` skill — hand the repair to \`${initSkillInvocation}\` instead.
+Do not run an \`init\` command yourself. Rebuilding a skills bridge can move skills a user wrote, and rewriting an instruction file touches prose a person authored — both are the \`init\` skill's judgment, so hand the repair to \`${initSkillInvocation}\` instead. A \`help\` line naming that skill has no shell equivalent at all.
 
 When every bridge resolves, \`findings\` says so outright rather than being empty.
 
 The default output is TOON, which is what you parse. Add \`--format text\` when you need to show the same report to a person, or \`--format json\`.
 
-## Findings and their repairs
+## Skills bridge findings
 
 | Finding | What it means | Repair |
 | --- | --- | --- |
-${rows}
+${rows(bridgeRepairs)}
 
 Substitute the reported bridge path for \`<path>\`.
 
+## Instruction bridge findings
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+${rows(instructionRepairs)}
+
+\`unbridged\` is the one to read carefully. The file is there and looks fine, and it names \`AGENTS.md\` nowhere — a \`CLAUDE.md\` someone overwrote with real content, or a \`.gemini/settings.json\` another tool rewrote without \`AGENTS.md\` in \`context.fileName\`. Never fix it by replacing the file: the content that displaced the bridge may be the only copy of something.
+
+An instruction bridge is reported per file, so a monorepo gets one row per \`AGENTS.md\` in the tree. Each nested \`AGENTS.md\` needs its own stub — an import bridges the file beside it and nothing deeper.
+
 ## The Windows case
 
 The common failure is \`degraded\`. Creating a symlink on Windows needs a privilege most accounts do not have, and Git for Windows gates it separately with \`core.symlinks\`, which its installer leaves off. With \`core.symlinks=false\` git does not error — it writes the symlink out as a regular file whose contents are the target path. \`${initSkillInvocation} --copy --force\` rebuilds the bridges as real directories on that machine.
@@ -222,5 +289,6 @@ A copy is a snapshot rather than a live projection, and an agent that edits a sk
 - Never repair a \`diverged-both\` or \`diverged-unknown\` bridge by re-running \`init\`. Rebuilding overwrites whichever side holds the newer edit. Reconcile the two directories first.
 - Edit skills at \`.agents/skills/<name>/SKILL.md\`. Editing through a bridge is only safe when that bridge is a symlink.
 - Do not add bridges to \`.gitignore\`. An untracked bridge swallows a real edit silently.
+- Write instructions in \`AGENTS.md\`, never in \`CLAUDE.md\`. A bridge file holds the import and any harness-specific notes; content written there reaches one harness and drifts from the canonical file.
 `
 }

package/src/diagnose-bridges/doctor.command.ts

@@ -9,6 +9,7 @@ import { commandInvocation } from './doctor-guidance.ts'
 type DoctorReport = {
 	bin: string
 	bridges: DiagnoseResult['bridges']
+	instructions: DiagnoseResult['instructions']
 	divergence?: DiagnoseResult['divergence']
 	/** The repair is lifted out into `help`, so a finding row stays to the diagnosis itself. */
 	findings: Omit<DiagnoseResult['findings'][number], 'repair'>[] | string
@@ -20,11 +21,14 @@ type DoctorReport = {
  * flags to confirm that an empty section really meant "nothing wrong".
  */
 export function buildReport(bin: string, result: DiagnoseResult): DoctorReport {
+	// Both sections are bridges, so the healthy line counts them together rather than making a reader
+	// add up two numbers to learn that nothing is wrong.
 	if (!result.findings.length) {
-		const count = result.bridges.length
+		const count = result.bridges.length + result.instructions.length
 		return {
 			bin,
 			bridges: result.bridges,
+			instructions: result.instructions,
 			findings:
 				count === 1 ? '0 problems found — the 1 bridge resolves' : `0 problems found — all ${count} bridges resolve`,
 		}
@@ -33,6 +37,7 @@ export function buildReport(bin: string, result: DiagnoseResult): DoctorReport {
 	return {
 		bin,
 		bridges: result.bridges,
+		instructions: result.instructions,
 		...(result.divergence.length ? { divergence: result.divergence } : {}),
 		findings: result.findings.map(({ path, detail }) => ({ path, detail })),
 		help: [...new Set(result.findings.map((finding) => `Run \`${finding.repair}\``))],
@@ -41,7 +46,8 @@ export function buildReport(bin: string, result: DiagnoseResult): DoctorReport {
 
 export const doctorCommand: cli.Command = command({
 	name: 'doctor',
-	description: 'Report whether the harness skill bridges in this repository still resolve. Read-only.',
+	description:
+		"Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md. Read-only.",
 	options: {
 		root: {
 			description: 'Repository or package directory. Defaults to the current directory.',

package/src/diagnose-bridges/json-with-comments.ts

@@ -0,0 +1,60 @@
+/**
+ * `.gemini/settings.json` may legally carry comments — the Gemini CLI loader strips them before
+ * parsing. A plain `JSON.parse` of a valid settings file therefore throws, and `doctor` would report
+ * a working bridge as unreadable. Comments are removed before parsing for that reason.
+ *
+ * Only comments. A trailing comma stays a parse error, because nothing documents it as accepted.
+ */
+export function stripJsonComments(source: string): string {
+	let output = ''
+	let index = 0
+	let inString = false
+	let escaped = false
+
+	while (index < source.length) {
+		const character = source[index] as string
+
+		if (inString) {
+			output += character
+			if (escaped) escaped = false
+			else if (character === '\\') escaped = true
+			else if (character === '"') inString = false
+			index += 1
+			continue
+		}
+
+		if (character === '"') {
+			inString = true
+			output += character
+			index += 1
+			continue
+		}
+
+		// A `//` inside a string is an ordinary URL; outside one it can only start a comment.
+		if (character === '/' && source[index + 1] === '/') {
+			while (index < source.length && source[index] !== '\n') index += 1
+			continue
+		}
+
+		if (character === '/' && source[index + 1] === '*') {
+			index += 2
+			while (index < source.length && !(source[index] === '*' && source[index + 1] === '/')) index += 1
+			index += 2
+			continue
+		}
+
+		output += character
+		index += 1
+	}
+
+	return output
+}
+
+/** The parsed value, or `undefined` when the file is not JSON even once its comments are gone. */
+export function parseJsonWithComments(source: string): unknown {
+	try {
+		return JSON.parse(stripJsonComments(source))
+	} catch {
+		return undefined
+	}
+}

package/src/harness-registry/harness-registry.ts

@@ -1,5 +1,6 @@
 import { lstatSync } from 'node:fs'
 import { join } from 'node:path'
+import type { InstructionBridge } from './instruction-bridge.ts'
 
 export type HarnessName =
 	| 'claude-code'
@@ -10,21 +11,56 @@ export type HarnessName =
 	| 'devin-desktop'
 	| 'windsurf'
 
+/** The two scopes a harness reads configuration at. Their roots differ; their shape does not. */
+export type HarnessScopeName = 'project' | 'user'
+
 /**
- * `skillsDirectory` is the projection target a harness needs to see `.agents/skills`.
- * A harness that reads `.agents/skills` natively has none, and is never projected into.
+ * What one harness does at one scope. Paths are relative to that scope's root: the repository root
+ * at project scope, the user's home directory at user scope.
+ *
+ * `detect` is the directory whose presence means this harness is configured at this scope — a
+ * different question per scope, which is why it is recorded per scope rather than once.
+ *
+ * `skillsDirectory` is the projection target the harness needs to see `.agents/skills` at this
+ * scope. A harness that reads `.agents/skills` natively there has none, and is never projected into.
+ *
+ * `instructionBridge` is the same question for `AGENTS.md`: what the harness needs at this scope in
+ * order to read it. It belongs per scope for the same reason `skillsDirectory` does — the file
+ * differs. Unlike `skillsDirectory`, the `init` command does not write it; the `init` skill does. It
+ * is recorded here to be diagnosed and gated per harness, not to be projected.
  */
-export type Harness = {
-	name: HarnessName
+export type HarnessScope = {
 	detect: string
 	skillsDirectory?: string
+	instructionBridge?: InstructionBridge
+}
+
+export type Harness = {
+	name: HarnessName
+	/** What this harness does inside a repository. `init` and `doctor` act only here. */
+	project: HarnessScope
+	/**
+	 * What this harness does for the user, outside any repository. Absent when no user-scope path is
+	 * primary-sourced — Devin documents none. Described and diagnosable; never written to.
+	 */
+	user?: HarnessScope
 	/** Set when this name has been superseded; the value is the name that replaces it. */
 	deprecated?: HarnessName
 }
 
 /**
- * Codex, Cursor, Copilot CLI, and Devin Desktop read `.agents/skills` directly, so they need no
- * projection. Only Claude Code and Gemini CLI read solely their own directory.
+ * The two scopes disagree in general, and a single answer per harness could only record one of them:
+ * Copilot CLI is `.github/skills` in a repository and `~/.copilot` for the user. Claude Code is the
+ * only harness that needs a skills projection, and it needs one at both scopes. Codex, Cursor,
+ * Copilot CLI, Gemini CLI, and Devin Desktop read `.agents/skills` themselves and are never
+ * projected into.
+ *
+ * Gemini CLI carried a `.gemini/skills` projection until E-GEM-02: it reads the `.agents/skills`
+ * alias at project scope too, where that alias takes precedence over `.gemini/skills`. It still
+ * needs an instruction bridge, which is a separate axis and unaffected.
+ *
+ * Instruction bridges are recorded at project scope only. The user-scope equivalents exist, but
+ * nothing writes or reads them yet: `init` works inside a repository, and so does `doctor`.
  *
  * `windsurf` is the former name of Devin Desktop, rebranded 2026-06-02. It is retained as a
  * deprecated alias: Devin still scans the legacy `.windsurf/skills` path, so its projection keeps
@@ -33,13 +69,32 @@ export type Harness = {
  * See `.research/agentic-configuration-standards/` for the per-harness sources.
  */
 export const harnessRegistry: readonly Harness[] = [
-	{ name: 'claude-code', detect: '.claude', skillsDirectory: '.claude/skills' },
-	{ name: 'cursor', detect: '.cursor' },
-	{ name: 'codex', detect: '.codex' },
-	{ name: 'copilot-cli', detect: '.github/skills' },
-	{ name: 'gemini-cli', detect: '.gemini', skillsDirectory: '.gemini/skills' },
-	{ name: 'devin-desktop', detect: '.devin' },
-	{ name: 'windsurf', detect: '.windsurf', skillsDirectory: '.windsurf/skills', deprecated: 'devin-desktop' },
+	{
+		name: 'claude-code',
+		project: {
+			detect: '.claude',
+			skillsDirectory: '.claude/skills',
+			instructionBridge: { kind: 'import', path: 'CLAUDE.md' },
+		},
+		user: { detect: '.claude', skillsDirectory: '.claude/skills' },
+	},
+	{ name: 'cursor', project: { detect: '.cursor' }, user: { detect: '.cursor' } },
+	{ name: 'codex', project: { detect: '.codex' }, user: { detect: '.codex' } },
+	{ name: 'copilot-cli', project: { detect: '.github/skills' }, user: { detect: '.copilot' } },
+	{
+		name: 'gemini-cli',
+		project: {
+			detect: '.gemini',
+			instructionBridge: { kind: 'settings-entry', path: '.gemini/settings.json', key: 'context.fileName' },
+		},
+		user: { detect: '.gemini' },
+	},
+	{ name: 'devin-desktop', project: { detect: '.devin' } },
+	{
+		name: 'windsurf',
+		project: { detect: '.windsurf', skillsDirectory: '.windsurf/skills' },
+		deprecated: 'devin-desktop',
+	},
 ]
 
 /** Enabled whether or not the repository already contains their directories. */
@@ -56,5 +111,7 @@ function directoryExists(path: string): boolean {
 /** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */
 export function selectHarnesses(root: string, preferred: readonly HarnessName[]): Harness[] {
 	const enabled = new Set<HarnessName>([...defaultHarnesses, ...preferred])
-	return harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.detect)))
+	return harnessRegistry.filter(
+		(harness) => enabled.has(harness.name) || directoryExists(join(root, harness.project.detect)),
+	)
 }

package/src/harness-registry/instruction-bridge.ts

@@ -0,0 +1,31 @@
+/**
+ * What a harness needs in order to read the repository's `AGENTS.md`.
+ *
+ * A skills projection is one shape — a directory pointing at `.agents/skills` — so the registry
+ * models it as a path. Instruction bridges are not one shape: Claude Code needs a Markdown file
+ * whose body imports `AGENTS.md`, and Gemini CLI needs `AGENTS.md` added to an array inside a JSON
+ * settings file. A second bare path field would describe the first and lie about the second, so the
+ * variant carries what its own check needs.
+ *
+ * The `init` command writes none of these. They are the `init` skill's work, which is why every
+ * finding against one names the skill rather than a flag.
+ */
+export type InstructionBridge =
+	| {
+			/**
+			 * A Markdown file whose body is an `@AGENTS.md` import, or a symlink to `AGENTS.md`. One is
+			 * needed beside every `AGENTS.md` in the tree, not only the root file: an import bridges the
+			 * one file next to it, so a nested `AGENTS.md` is invisible until it has its own.
+			 */
+			kind: 'import'
+			/** Repository-relative name, the same in every directory that holds an `AGENTS.md`. */
+			path: string
+	  }
+	| {
+			/** An `AGENTS.md` entry in an array inside a JSON settings file. */
+			kind: 'settings-entry'
+			/** Repository-relative path of the settings file. */
+			path: string
+			/** Dotted path to the array within it, as the harness documents it. */
+			key: string
+	  }

package/src/index.ts

@@ -8,12 +8,25 @@ export type {
 	DivergenceReport,
 } from './diagnose-bridges/diagnose-bridges.ts'
 export { diagnoseBridges } from './diagnose-bridges/diagnose-bridges.ts'
+export type {
+	InstructionKind,
+	InstructionReport,
+	InstructionStatus,
+} from './diagnose-bridges/diagnose-instructions.ts'
+export { diagnoseInstructions } from './diagnose-bridges/diagnose-instructions.ts'
 export { doctorCommand } from './diagnose-bridges/doctor.command.ts'
-export type { BridgeProblem, Repair } from './diagnose-bridges/doctor-guidance.ts'
-export { doctorRepairs, doctorSkill, renderDoctorSkill } from './diagnose-bridges/doctor-guidance.ts'
+export type { BridgeProblem, DoctorProblem, InstructionProblem, Repair } from './diagnose-bridges/doctor-guidance.ts'
+export {
+	bridgeRepairs,
+	doctorRepairs,
+	doctorSkill,
+	instructionRepairs,
+	renderDoctorSkill,
+} from './diagnose-bridges/doctor-guidance.ts'
 export type { DivergenceDirection } from './diagnose-bridges/git-bridge-state.ts'
-export type { HarnessName } from './harness-registry/harness-registry.ts'
+export type { Harness, HarnessName, HarnessScope, HarnessScopeName } from './harness-registry/harness-registry.ts'
 export { harnessRegistry } from './harness-registry/harness-registry.ts'
+export type { InstructionBridge } from './harness-registry/instruction-bridge.ts'
 export { activate, harnessCommand, initCommand } from './initialize-harnesses/init.command.ts'
 export type { InitializeOptions, InitializeResult } from './initialize-harnesses/initialize-harnesses.ts'
 export { initializeHarnesses } from './initialize-harnesses/initialize-harnesses.ts'

package/src/initialize-harnesses/initialize-harnesses.ts

@@ -33,7 +33,7 @@ export function initializeHarnesses({
 	return {
 		root,
 		harnesses: harnesses.map((harness) => harness.name),
-		native: harnesses.filter((harness) => !harness.skillsDirectory).map((harness) => harness.name),
+		native: harnesses.filter((harness) => !harness.project.skillsDirectory).map((harness) => harness.name),
 		linked,
 		deprecated: harnesses
 			.filter((harness) => harness.deprecated)

package/src/skill-projection/skill-projection.ts

@@ -42,10 +42,10 @@ export type ProjectSkillsOptions = {
  */
 export function projectSkills({ root, canonicalSkills, harnesses, copy, force }: ProjectSkillsOptions): HarnessName[] {
 	const projections = harnesses
-		.filter((harness) => harness.skillsDirectory)
+		.filter((harness) => harness.project.skillsDirectory)
 		.map((harness) => ({
 			harness,
-			target: join(root, harness.skillsDirectory as string),
+			target: join(root, harness.project.skillsDirectory as string),
 		}))
 
 	const conflicts = projections