buddy-agent-harness 0.2.0 → 0.3.1

package/dist/init.command-BN_w5DRZ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.command-BN_w5DRZ.mjs","names":[],"sources":["../src/command-output/command-output.ts","../src/harness-registry/harness-registry.ts","../src/diagnose-bridges/directory-files.ts","../src/diagnose-bridges/doctor-guidance.ts","../src/diagnose-bridges/git-bridge-state.ts","../src/diagnose-bridges/diagnose-bridges.ts","../src/diagnose-bridges/doctor.command.ts","../src/skill-projection/skill-projection.ts","../src/initialize-harnesses/initialize-harnesses.ts","../src/initialize-harnesses/init.command.ts"],"sourcesContent":["import { sep } from 'node:path'\nimport { encode } from '@toon-format/toon'\n\nexport type OutputFormat = 'json' | 'toon' | 'text'\n\nconst formats: readonly OutputFormat[] = ['toon', 'json', 'text']\n\n/** Rejects anything but the supported formats so an unknown value never falls back silently. */\nexport function parseFormat(value: string | undefined): OutputFormat {\n\tif (!formats.includes(value as OutputFormat)) throw new Error('--format must be toon, json, or text.')\n\treturn value as OutputFormat\n}\n\n/** The single stdout boundary: internal logic stays on plain objects, encoding happens here. */\nexport function writeResult(value: object, format: OutputFormat): void {\n\tprocess.stdout.write(`${encodeResult(value, format)}\\n`)\n}\n\nfunction encodeResult(value: object, format: OutputFormat): string {\n\tif (format === 'json') return JSON.stringify(value)\n\treturn format === 'text' ? renderText(value) : encode(value)\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\nfunction cell(value: unknown): string {\n\treturn value === undefined ? '' : String(value)\n}\n\n/** A header row plus one row per record, every column padded to its widest cell. */\nfunction table(rows: Record<string, unknown>[]): string[] {\n\tconst columns = [...new Set(rows.flatMap((row) => Object.keys(row)))]\n\tconst widths = columns.map((column) => Math.max(column.length, ...rows.map((row) => cell(row[column]).length)))\n\tconst line = (values: string[]) =>\n\t\t`  ${values.map((value, index) => value.padEnd(widths[index] as number)).join('  ')}`.trimEnd()\n\treturn [line(columns), ...rows.map((row) => line(columns.map((column) => cell(row[column]))))]\n}\n\n/**\n * The same result rendered for a person rather than for an agent: scalars as `key: value`, records\n * as an aligned table, and everything else as a bulleted list. TOON stays the default because it is\n * what an agent parses; this is for reading over someone's shoulder.\n */\nexport function renderText(value: object): string {\n\tconst blocks = Object.entries(value).map(([key, item]) => {\n\t\tif (!Array.isArray(item)) return [`${key}: ${isRecord(item) ? JSON.stringify(item) : String(item)}`]\n\t\tif (!item.length) return [`${key}: (none)`]\n\t\tconst body = item.every(isRecord) ? table(item) : item.map((entry) => `  - ${String(entry)}`)\n\t\treturn [`${key}:`, ...body]\n\t})\n\n\t// A blank line wherever a multi-line block meets its neighbour, so a following scalar does not\n\t// read as another row of the table above it.\n\treturn blocks\n\t\t.flatMap((block, index) => {\n\t\t\tconst previous = blocks[index - 1]\n\t\t\treturn previous && (previous.length > 1 || block.length > 1) ? ['', ...block] : block\n\t\t})\n\t\t.join('\\n')\n}\n\n/** AXI §10: the executable's absolute path, with the user's home directory collapsed to `~`. */\nexport function binPath(home: string, executable: string | undefined): string {\n\tif (!executable) return 'buddy-agent-harness'\n\treturn home && executable.startsWith(home + sep) ? `~${executable.slice(home.length)}` : executable\n}\n","import { lstatSync } from 'node:fs'\nimport { join } from 'node:path'\n\nexport type HarnessName =\n\t| 'claude-code'\n\t| 'cursor'\n\t| 'codex'\n\t| 'copilot-cli'\n\t| 'gemini-cli'\n\t| 'devin-desktop'\n\t| 'windsurf'\n\n/**\n * `skillsDirectory` is the projection target a harness needs to see `.agents/skills`.\n * A harness that reads `.agents/skills` natively has none, and is never projected into.\n */\nexport type Harness = {\n\tname: HarnessName\n\tdetect: string\n\tskillsDirectory?: string\n\t/** Set when this name has been superseded; the value is the name that replaces it. */\n\tdeprecated?: HarnessName\n}\n\n/**\n * Codex, Cursor, Copilot CLI, and Devin Desktop read `.agents/skills` directly, so they need no\n * projection. Only Claude Code and Gemini CLI read solely their own directory.\n *\n * `windsurf` is the former name of Devin Desktop, rebranded 2026-06-02. It is retained as a\n * deprecated alias: Devin still scans the legacy `.windsurf/skills` path, so its projection keeps\n * working, but new repositories should enable `devin-desktop` and have nothing written for them.\n *\n * See `.research/agentic-configuration-standards/` for the per-harness sources.\n */\nexport const harnessRegistry: readonly Harness[] = [\n\t{ name: 'claude-code', detect: '.claude', skillsDirectory: '.claude/skills' },\n\t{ name: 'cursor', detect: '.cursor' },\n\t{ name: 'codex', detect: '.codex' },\n\t{ name: 'copilot-cli', detect: '.github/skills' },\n\t{ name: 'gemini-cli', detect: '.gemini', skillsDirectory: '.gemini/skills' },\n\t{ name: 'devin-desktop', detect: '.devin' },\n\t{ name: 'windsurf', detect: '.windsurf', skillsDirectory: '.windsurf/skills', deprecated: 'devin-desktop' },\n]\n\n/** Enabled whether or not the repository already contains their directories. */\nconst defaultHarnesses: readonly HarnessName[] = ['claude-code', 'cursor']\n\nfunction directoryExists(path: string): boolean {\n\ttry {\n\t\treturn lstatSync(path).isDirectory()\n\t} catch {\n\t\treturn false\n\t}\n}\n\n/** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */\nexport function selectHarnesses(root: string, preferred: readonly HarnessName[]): Harness[] {\n\tconst enabled = new Set<HarnessName>([...defaultHarnesses, ...preferred])\n\treturn harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.detect)))\n}\n","import { readdirSync } from 'node:fs'\nimport { join, posix, relative, sep } from 'node:path'\n\n/**\n * Every file below `directory`, as paths relative to it, POSIX-separated and sorted. A directory\n * that does not exist reads as empty: `doctor` never creates one to look at it.\n */\nexport function filesUnder(directory: string): string[] {\n\ttry {\n\t\treturn readdirSync(directory, { recursive: true, withFileTypes: true })\n\t\t\t.filter((entry) => entry.isFile())\n\t\t\t.map((entry) => relative(directory, join(entry.parentPath, entry.name)).split(sep).join(posix.sep))\n\t\t\t.sort()\n\t} catch {\n\t\treturn []\n\t}\n}\n","/**\n * The one place `doctor`'s guidance is written. The command reads `detail` and `repair` to fill its\n * `findings` and `help` sections; `skills/doctor/SKILL.md` is generated from the same table by\n * `scripts/generate-doctor-skill.ts`, so the shipped skill cannot drift from what the command says.\n */\n\n/** Every way a bridge can fail, in the order `doctor` reports them. */\nexport type BridgeProblem =\n\t| 'no-canonical'\n\t| 'missing'\n\t| 'degraded'\n\t| 'stale'\n\t| 'diverged-bridge'\n\t| 'diverged-canonical'\n\t| 'diverged-both'\n\t| 'diverged-unknown'\n\t| 'unpinned-copy'\n\nexport type Repair = {\n\tproblem: BridgeProblem\n\t/** What `doctor` prints in the `findings` row for this problem. */\n\tdetail: string\n\t/**\n\t * The command that fixes it, for `doctor`'s own output. `path` is the repository-relative bridge\n\t * path; `cli` is how to invoke this tool.\n\t */\n\trepair(path: string, cli: string): string\n\t/**\n\t * What the shipped skill tells an agent to do instead. A repair that rebuilds a bridge delegates\n\t * to the `init` skill rather than calling the `init` command, because rebuilding can move\n\t * user-authored skills and that judgment is the `init` skill's, not `doctor`'s.\n\t */\n\tskillRepair(path: string): string\n}\n\n/** How the command names itself. A skill may run without the binary on PATH, so it uses `npx`. */\nexport const commandInvocation = 'buddy-agent-harness'\nexport const skillInvocation = 'npx -y buddy-agent-harness'\n/** How the skill hands a repair back to `init`. */\nexport const initSkillInvocation = '/buddy-agent-harness:init'\n\nexport const doctorRepairs: readonly Repair[] = [\n\t{\n\t\tproblem: 'no-canonical',\n\t\tdetail: 'the canonical skill directory does not exist, so no bridge can resolve',\n\t\trepair: (_path, cli) => `${cli} init`,\n\t\tskillRepair: () => `run \\`${initSkillInvocation}\\`, which creates \\`.agents/skills\\` and the bridges`,\n\t},\n\t{\n\t\tproblem: 'missing',\n\t\tdetail: 'no bridge at this path — the harness sees zero project skills',\n\t\trepair: (_path, cli) => `${cli} init`,\n\t\tskillRepair: () => `run \\`${initSkillInvocation}\\``,\n\t},\n\t{\n\t\tproblem: 'degraded',\n\t\tdetail: 'expected a directory but found a regular file — checkout without core.symlinks',\n\t\trepair: (_path, cli) => `${cli} init --copy --force`,\n\t\tskillRepair: () => `run \\`${initSkillInvocation} --copy --force\\``,\n\t},\n\t{\n\t\tproblem: 'stale',\n\t\tdetail: 'symlink does not resolve to .agents/skills',\n\t\trepair: (_path, cli) => `${cli} init --force`,\n\t\tskillRepair: () => `run \\`${initSkillInvocation} --force\\``,\n\t},\n\t{\n\t\tproblem: 'diverged-bridge',\n\t\tdetail: 'only the bridge changed since the two last agreed — an agent wrote through the copy',\n\t\trepair: (path, cli) =>\n\t\t\t`replace .agents/skills with ${path} to keep the newer edit and then run ${cli} init --force`,\n\t\tskillRepair: (path) =>\n\t\t\t`replace .agents/skills with ${path} to keep the newer edit, then run \\`${initSkillInvocation} --force\\``,\n\t},\n\t{\n\t\tproblem: 'diverged-canonical',\n\t\tdetail: 'only .agents/skills changed since the two last agreed — the copy is stale',\n\t\trepair: (_path, cli) => `${cli} init --copy --force`,\n\t\tskillRepair: () => `run \\`${initSkillInvocation} --copy --force\\``,\n\t},\n\t{\n\t\tproblem: 'diverged-both',\n\t\tdetail: 'both sides changed since they last agreed — rebuilding would discard one of them',\n\t\trepair: (path) => `git diff --no-index .agents/skills ${path} and reconcile by hand`,\n\t\tskillRepair: (path) => `run \\`git diff --no-index .agents/skills ${path}\\` and reconcile by hand`,\n\t},\n\t{\n\t\tproblem: 'diverged-unknown',\n\t\tdetail: 'contents differ and no commit where they agreed was found — which side moved is unknown',\n\t\trepair: (path) => `git diff --no-index .agents/skills ${path} and reconcile by hand`,\n\t\tskillRepair: (path) => `run \\`git diff --no-index .agents/skills ${path}\\` and reconcile by hand`,\n\t},\n\t{\n\t\tproblem: 'unpinned-copy',\n\t\tdetail: 'tracked copy without the skip-worktree bit — the tree is dirty with content that must not be committed',\n\t\t// The index entry is the tracked symlink on a Windows checkout but the individual files in a\n\t\t// committed copy, so the paths are read back from git rather than assumed.\n\t\trepair: (path) => `git ls-files -z ${path} | xargs -0 git update-index --skip-worktree`,\n\t\tskillRepair: (path) => `run \\`git ls-files -z ${path} | xargs -0 git update-index --skip-worktree\\``,\n\t},\n]\n\nconst repairsByProblem = new Map(doctorRepairs.map((entry) => [entry.problem, entry]))\n\nexport function repairFor(problem: BridgeProblem): Repair {\n\treturn repairsByProblem.get(problem) as Repair\n}\n\nexport const doctorSkill = {\n\tname: 'doctor',\n\tdescription:\n\t\t'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.',\n} as const\n\n/** Written into the generated skill so a reader knows not to edit it in place. */\nexport const generatedSkillWarning =\n\t'<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-doctor-skill.ts. Do not edit by hand. -->'\n\n/** The shipped `doctor` skill, rendered from the same table the command prints. */\nexport function renderDoctorSkill(): string {\n\t// A repair may itself contain a pipe, which would otherwise end the table cell early.\n\tconst cell = (value: string) => value.replaceAll('|', '\\\\|')\n\tconst rows = doctorRepairs\n\t\t.map((entry) => `| \\`${entry.problem}\\` | ${entry.detail} | ${cell(entry.skillRepair('<path>'))} |`)\n\t\t.join('\\n')\n\n\treturn `---\nname: ${doctorSkill.name}\ndescription: ${doctorSkill.description}\n---\n\n${generatedSkillWarning}\n\n# Harness Doctor\n\n\\`.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.\n\nDiagnose it:\n\n\\`\\`\\`sh\n${skillInvocation} doctor\n\\`\\`\\`\n\nThe command is read-only. It never repairs anything, so it is safe to run at any point, including from a session-start hook.\n\n## Reading the report\n\n\\`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\\`.\n\n\\`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.\n\nWhen every bridge resolves, \\`findings\\` says so outright rather than being empty.\n\nThe 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\\`.\n\n## Findings and their repairs\n\n| Finding | What it means | Repair |\n| --- | --- | --- |\n${rows}\n\nSubstitute the reported bridge path for \\`<path>\\`.\n\n## The Windows case\n\nThe 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.\n\nA copy is a snapshot rather than a live projection, and an agent that edits a skill through it writes into the copy instead of into \\`.agents/skills\\`. That is what the \\`diverged\\` findings catch.\n\n## Rules\n\n- 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.\n- Edit skills at \\`.agents/skills/<name>/SKILL.md\\`. Editing through a bridge is only safe when that bridge is a symlink.\n- Do not add bridges to \\`.gitignore\\`. An untracked bridge swallows a real edit silently.\n`\n}\n","import { execFileSync } from 'node:child_process'\nimport { join } from 'node:path'\nimport { filesUnder } from './directory-files.ts'\n\n/** Which side of a diverged bridge moved since the last commit where the two agreed. */\nexport type DivergenceDirection = 'bridge' | 'canonical' | 'both' | 'unknown'\n\n/** Whether a path is tracked, and if so whether its skip-worktree bit is still set. */\nexport type TrackingState = 'untracked' | 'tracked' | 'skip-worktree'\n\nfunction git(root: string, args: string[], input?: string): string | undefined {\n\ttry {\n\t\treturn execFileSync('git', args, {\n\t\t\tcwd: root,\n\t\t\tencoding: 'utf8',\n\t\t\t...(input === undefined ? {} : { input }),\n\t\t\tstdio: ['pipe', 'pipe', 'pipe'],\n\t\t})\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\nfunction lines(output: string | undefined): string[] {\n\treturn (output ?? '').split('\\n').filter(Boolean)\n}\n\n/**\n * Reads git state for the two sides of a bridge. Every method degrades to \"cannot tell\" rather than\n * throwing, so `doctor` still reports on a tarball, a worktree without git, or a repository with no\n * commits.\n */\nexport class GitBridgeState {\n\t/** Path of `root` relative to the repository root, `''` at the top, `undefined` outside a repository. */\n\tprivate readonly prefix: string | undefined\n\n\tconstructor(private readonly root: string) {\n\t\tthis.prefix = git(root, ['rev-parse', '--show-prefix'])?.trim()\n\t}\n\n\t/**\n\t * `init --copy` marks a bridge skip-worktree so a machine-local copy over a tracked symlink stops\n\t * showing as a pending change. The bit is a hint that some checkouts clear, so it is verified\n\t * rather than assumed.\n\t */\n\ttrackingOf(path: string): TrackingState {\n\t\tif (this.prefix === undefined) return 'untracked'\n\t\tconst entries = lines(git(this.root, ['ls-files', '-v', '--', path]))\n\t\tif (!entries.length) return 'untracked'\n\t\treturn entries.every((entry) => entry.startsWith('S')) ? 'skip-worktree' : 'tracked'\n\t}\n\n\t/**\n\t * Names the side that moved by finding the newest commit whose two trees agreed, then asking which\n\t * of the working directories still matches it.\n\t */\n\tdirectionOf(bridge: string, canonical: string): DivergenceDirection {\n\t\tif (this.prefix === undefined) return 'unknown'\n\t\tconst base = this.lastAgreedTree(bridge, canonical)\n\t\tif (base === undefined) return 'unknown'\n\t\tconst bridgeMoved = !this.matchesTree(bridge, base)\n\t\tconst canonicalMoved = !this.matchesTree(canonical, base)\n\t\tif (bridgeMoved && canonicalMoved) return 'both'\n\t\tif (bridgeMoved) return 'bridge'\n\t\treturn 'canonical'\n\t}\n\n\t/** The tree of the newest commit where both paths held identical content. */\n\tprivate lastAgreedTree(bridge: string, canonical: string): string | undefined {\n\t\tfor (const commit of lines(git(this.root, ['rev-list', '-n', '200', 'HEAD', '--', bridge, canonical]))) {\n\t\t\tconst bridgeObject = git(this.root, ['rev-parse', '-q', '--verify', `${commit}:${this.prefix}${bridge}`])?.trim()\n\t\t\tif (!bridgeObject) continue\n\t\t\tconst canonicalObject = git(this.root, [\n\t\t\t\t'rev-parse',\n\t\t\t\t'-q',\n\t\t\t\t'--verify',\n\t\t\t\t`${commit}:${this.prefix}${canonical}`,\n\t\t\t])?.trim()\n\t\t\tif (bridgeObject === canonicalObject) return bridgeObject\n\t\t}\n\t\treturn undefined\n\t}\n\n\t/**\n\t * Compares a working directory against a git tree by object id. `hash-object` is used rather than\n\t * hashing in-process so the comparison follows whatever object format the repository uses.\n\t */\n\tprivate matchesTree(directory: string, tree: string): boolean {\n\t\tconst expected = new Map(\n\t\t\tlines(git(this.root, ['ls-tree', '-r', tree])).map((entry) => {\n\t\t\t\tconst [meta, path] = entry.split('\\t')\n\t\t\t\treturn [path, (meta as string).split(' ')[2] as string] as const\n\t\t\t}),\n\t\t)\n\t\tconst files = filesUnder(join(this.root, directory))\n\t\tif (files.length !== expected.size || files.some((file) => !expected.has(file))) return false\n\t\tconst hashed = lines(\n\t\t\tgit(this.root, ['hash-object', '--stdin-paths'], files.map((file) => join(directory, file)).join('\\n')),\n\t\t)\n\t\treturn hashed.length === files.length && files.every((file, index) => expected.get(file) === hashed[index])\n\t}\n}\n","import { lstatSync, readFileSync, readlinkSync, statSync } from 'node:fs'\nimport { dirname, join, relative } from 'node:path'\nimport { type Harness, type HarnessName, selectHarnesses } from '../harness-registry/harness-registry.ts'\nimport { filesUnder } from './directory-files.ts'\nimport { type BridgeProblem, repairFor } from './doctor-guidance.ts'\nimport { type DivergenceDirection, GitBridgeState } from './git-bridge-state.ts'\n\nexport type BridgeKind = 'symlink' | 'copy' | 'file' | 'none'\nexport type BridgeStatus = 'ok' | 'missing' | 'degraded' | 'stale' | 'diverged'\n\nexport type BridgeReport = {\n\tharness: HarnessName\n\t/** Repository-relative, as the harness registry declares it. */\n\tpath: string\n\tkind: BridgeKind\n\tstatus: BridgeStatus\n}\n\nexport type BridgeFinding = {\n\tpath: string\n\tdetail: string\n\t/** The command that repairs this finding, already carrying the bridge path. */\n\trepair: string\n}\n\nexport type DivergenceReport = {\n\tpath: string\n\tdirection: DivergenceDirection\n}\n\nexport type DiagnoseOptions = {\n\troot: string\n\tharnesses?: HarnessName[]\n\t/** How to name this tool in the repair commands. */\n\tcli: string\n}\n\nexport type DiagnoseResult = {\n\tbridges: BridgeReport[]\n\tdivergence: DivergenceReport[]\n\tfindings: BridgeFinding[]\n}\n\nconst canonicalPath = '.agents/skills'\n\nfunction pathState(target: string): 'missing' | 'symlink' | 'directory' | 'file' {\n\ttry {\n\t\tconst stats = lstatSync(target)\n\t\tif (stats.isSymbolicLink()) return 'symlink'\n\t\treturn stats.isDirectory() ? 'directory' : 'file'\n\t} catch {\n\t\treturn 'missing'\n\t}\n}\n\nfunction isDirectory(path: string): boolean {\n\ttry {\n\t\treturn statSync(path).isDirectory()\n\t} catch {\n\t\treturn false\n\t}\n}\n\n/** The same test `init` uses to decide a projection is already correct, plus that it still resolves. */\nfunction resolvesToCanonical(target: string, canonical: string): boolean {\n\treturn readlinkSync(target) === relative(dirname(target), canonical) && isDirectory(target)\n}\n\nfunction sameContent(left: string, right: string): boolean {\n\tconst leftFiles = filesUnder(left)\n\tconst rightFiles = filesUnder(right)\n\treturn (\n\t\tleftFiles.length === rightFiles.length &&\n\t\tleftFiles.every(\n\t\t\t(file, index) =>\n\t\t\t\trightFiles[index] === file && readFileSync(join(left, file)).equals(readFileSync(join(right, file))),\n\t\t)\n\t)\n}\n\ntype Inspection = {\n\tkind: BridgeKind\n\tstatus: BridgeStatus\n\tproblem?: BridgeProblem\n\tdirection?: DivergenceDirection\n}\n\nfunction inspect(target: string, path: string, canonical: string, git: GitBridgeState): Inspection {\n\tswitch (pathState(target)) {\n\t\tcase 'missing':\n\t\t\treturn { kind: 'none', status: 'missing', problem: 'missing' }\n\t\t// The flagship Windows failure: git with `core.symlinks=false` writes the link out as a\n\t\t// regular file holding the target path, and the harness silently loads nothing.\n\t\tcase 'file':\n\t\t\treturn { kind: 'file', status: 'degraded', problem: 'degraded' }\n\t\tcase 'symlink':\n\t\t\treturn resolvesToCanonical(target, canonical)\n\t\t\t\t? { kind: 'symlink', status: 'ok' }\n\t\t\t\t: { kind: 'symlink', status: 'stale', problem: 'stale' }\n\t\tdefault: {\n\t\t\tif (!sameContent(target, canonical)) {\n\t\t\t\tconst direction = git.directionOf(path, canonicalPath)\n\t\t\t\treturn { kind: 'copy', status: 'diverged', problem: `diverged-${direction}`, direction }\n\t\t\t}\n\t\t\t// A copy over a tracked symlink only stays out of `git status` while its skip-worktree bit\n\t\t\t// survives, and some checkout and merge operations clear it.\n\t\t\treturn git.trackingOf(path) === 'tracked'\n\t\t\t\t? { kind: 'copy', status: 'ok', problem: 'unpinned-copy' }\n\t\t\t\t: { kind: 'copy', status: 'ok' }\n\t\t}\n\t}\n}\n\n/**\n * Reports whether every bridge `init` would create for this repository still resolves into\n * `.agents/skills`. Read-only: nothing is created, moved, or repaired, so the caller decides what\n * to run from the repair each finding carries.\n */\nexport function diagnoseBridges({ root, harnesses: preferred = [], cli }: DiagnoseOptions): DiagnoseResult {\n\tconst canonical = join(root, '.agents', 'skills')\n\tconst git = new GitBridgeState(root)\n\tconst bridged = selectHarnesses(root, preferred).filter((harness): harness is Harness & { skillsDirectory: string } =>\n\t\tBoolean(harness.skillsDirectory),\n\t)\n\n\tconst bridges: BridgeReport[] = []\n\tconst divergence: DivergenceReport[] = []\n\tconst findings: BridgeFinding[] = []\n\n\tif (!isDirectory(canonical)) {\n\t\tconst { detail, repair } = repairFor('no-canonical')\n\t\tfindings.push({ path: canonicalPath, detail, repair: repair(canonicalPath, cli) })\n\t}\n\n\tfor (const harness of bridged) {\n\t\tconst path = harness.skillsDirectory\n\t\tconst inspection = inspect(join(root, path), path, canonical, git)\n\t\tbridges.push({ harness: harness.name, path, kind: inspection.kind, status: inspection.status })\n\t\tif (inspection.direction) divergence.push({ path, direction: inspection.direction })\n\t\tif (inspection.problem) {\n\t\t\tconst { detail, repair } = repairFor(inspection.problem)\n\t\t\tfindings.push({ path, detail, repair: repair(path, cli) })\n\t\t}\n\t}\n\n\treturn { bridges, divergence, findings }\n}\n","import { homedir } from 'node:os'\nimport type { cli } from 'clibuilder'\nimport { command, z } from 'clibuilder'\nimport { binPath, parseFormat, writeResult } from '../command-output/command-output.ts'\nimport { type HarnessName, harnessRegistry } from '../harness-registry/harness-registry.ts'\nimport { type DiagnoseResult, diagnoseBridges } from './diagnose-bridges.ts'\nimport { commandInvocation } from './doctor-guidance.ts'\n\ntype DoctorReport = {\n\tbin: string\n\tbridges: DiagnoseResult['bridges']\n\tdivergence?: DiagnoseResult['divergence']\n\t/** The repair is lifted out into `help`, so a finding row stays to the diagnosis itself. */\n\tfindings: Omit<DiagnoseResult['findings'][number], 'repair'>[] | string\n\thelp?: string[]\n}\n\n/**\n * AXI §5: the healthy answer states the zero with context, so an agent does not re-run with other\n * flags to confirm that an empty section really meant \"nothing wrong\".\n */\nexport function buildReport(bin: string, result: DiagnoseResult): DoctorReport {\n\tif (!result.findings.length) {\n\t\tconst count = result.bridges.length\n\t\treturn {\n\t\t\tbin,\n\t\t\tbridges: result.bridges,\n\t\t\tfindings:\n\t\t\t\tcount === 1 ? '0 problems found — the 1 bridge resolves' : `0 problems found — all ${count} bridges resolve`,\n\t\t}\n\t}\n\n\treturn {\n\t\tbin,\n\t\tbridges: result.bridges,\n\t\t...(result.divergence.length ? { divergence: result.divergence } : {}),\n\t\tfindings: result.findings.map(({ path, detail }) => ({ path, detail })),\n\t\thelp: [...new Set(result.findings.map((finding) => `Run \\`${finding.repair}\\``))],\n\t}\n}\n\nexport const doctorCommand: cli.Command = command({\n\tname: 'doctor',\n\tdescription: 'Report whether the harness skill bridges in this repository still resolve. Read-only.',\n\toptions: {\n\t\troot: {\n\t\t\tdescription: 'Repository or package directory. Defaults to the current directory.',\n\t\t\ttype: z.optional(z.string()),\n\t\t},\n\t\tharness: {\n\t\t\tdescription: 'Comma-separated harnesses to check in addition to Claude Code and Cursor, e.g. codex,gemini-cli.',\n\t\t\ttype: z.optional(z.string()),\n\t\t},\n\t\tformat: {\n\t\t\tdescription: 'Output format: toon (default), json, or text for a human-readable report.',\n\t\t\ttype: z.optional(z.string()),\n\t\t\tdefault: 'toon',\n\t\t},\n\t},\n\trun(args) {\n\t\ttry {\n\t\t\tconst format = parseFormat(args.format)\n\t\t\tconst requested = args.harness\n\t\t\t\t?.split(',')\n\t\t\t\t.map((name) => name.trim())\n\t\t\t\t.filter(Boolean)\n\t\t\tconst unsupported = requested?.filter((name) => !harnessRegistry.some((harness) => harness.name === name))\n\t\t\tif (unsupported?.length)\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Unsupported harness: ${unsupported.join(', ')}. Supported: ${harnessRegistry\n\t\t\t\t\t\t.map((harness) => harness.name)\n\t\t\t\t\t\t.join(', ')}.`,\n\t\t\t\t)\n\t\t\tconst result = diagnoseBridges({\n\t\t\t\troot: args.root ?? process.cwd(),\n\t\t\t\t...(requested?.length ? { harnesses: requested as HarnessName[] } : {}),\n\t\t\t\tcli: commandInvocation,\n\t\t\t})\n\t\t\t// Exit stays 0 even with findings: the diagnosis succeeded, and a non-zero code reads to an\n\t\t\t// agent as \"this command is broken, try something else\".\n\t\t\twriteResult(buildReport(binPath(homedir(), process.argv[1]), result), format)\n\t\t} catch (error) {\n\t\t\tprocess.stderr.write(`error: ${error instanceof Error ? error.message : 'Harness diagnosis failed.'}\\n`)\n\t\t\tprocess.exitCode = 1\n\t\t}\n\t},\n})\n","import { cpSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync } from 'node:fs'\nimport { dirname, join, relative } from 'node:path'\nimport type { Harness, HarnessName } from '../harness-registry/harness-registry.ts'\n\nfunction skillNames(skillsDirectory: string): string[] {\n\treturn readdirSync(skillsDirectory, { withFileTypes: true })\n\t\t.filter((entry) => entry.isDirectory())\n\t\t.map((entry) => entry.name)\n\t\t.sort()\n}\n\nfunction pathOccupied(path: string): boolean {\n\ttry {\n\t\tlstatSync(path)\n\t\treturn true\n\t} catch {\n\t\treturn false\n\t}\n}\n\nfunction isCorrectLink(target: string, source: string): boolean {\n\treturn lstatSync(target).isSymbolicLink() && readlinkSync(target) === relative(dirname(target), source)\n}\n\n/** Creates the canonical directory when absent, so a fresh repository reports zero skills. */\nexport function countSkills(canonicalSkills: string): number {\n\tmkdirSync(canonicalSkills, { recursive: true })\n\treturn skillNames(canonicalSkills).length\n}\n\nexport type ProjectSkillsOptions = {\n\troot: string\n\tcanonicalSkills: string\n\tharnesses: readonly Harness[]\n\tcopy: boolean\n\tforce: boolean\n}\n\n/**\n * Points every harness that cannot read `.agents/skills` at the canonical directory. Symlinking is\n * preferred; a platform that refuses the link falls back to a copy. Returns the projected harnesses.\n */\nexport function projectSkills({ root, canonicalSkills, harnesses, copy, force }: ProjectSkillsOptions): HarnessName[] {\n\tconst projections = harnesses\n\t\t.filter((harness) => harness.skillsDirectory)\n\t\t.map((harness) => ({\n\t\t\tharness,\n\t\t\ttarget: join(root, harness.skillsDirectory as string),\n\t\t}))\n\n\tconst conflicts = projections\n\t\t.filter(({ target }) => pathOccupied(target) && !isCorrectLink(target, canonicalSkills))\n\t\t.map(({ target }) => target)\n\n\tif (conflicts.length && !force) {\n\t\tthrow new Error(\n\t\t\t`Refusing to replace existing skill targets:\\n${conflicts.map((target) => `- ${target}`).join('\\n')}`,\n\t\t)\n\t}\n\n\tfor (const { target } of projections) {\n\t\tmkdirSync(dirname(target), { recursive: true })\n\t\tif (pathOccupied(target) && isCorrectLink(target, canonicalSkills)) continue\n\t\tif (pathOccupied(target)) rmSync(target, { recursive: true, force: true })\n\t\tif (copy) {\n\t\t\tcpSync(canonicalSkills, target, { recursive: true })\n\t\t\tcontinue\n\t\t}\n\t\ttry {\n\t\t\tsymlinkSync(relative(dirname(target), canonicalSkills), target, 'junction')\n\t\t} catch (error) {\n\t\t\tif (pathOccupied(target)) throw error\n\t\t\tcpSync(canonicalSkills, target, { recursive: true })\n\t\t}\n\t}\n\n\treturn projections.map(({ harness }) => harness.name)\n}\n","import { join } from 'node:path'\nimport { type HarnessName, selectHarnesses } from '../harness-registry/harness-registry.ts'\nimport { countSkills, projectSkills } from '../skill-projection/skill-projection.ts'\n\nexport type InitializeOptions = {\n\troot: string\n\tharnesses?: HarnessName[]\n\tcopy?: boolean\n\tforce?: boolean\n}\nexport type InitializeResult = {\n\troot: string\n\tharnesses: HarnessName[]\n\tnative: HarnessName[]\n\tlinked: HarnessName[]\n\t/** Enabled harnesses whose name has been superseded, as `{ name, replacedBy }`. */\n\tdeprecated: { name: HarnessName; replacedBy: HarnessName }[]\n\tskills: number\n\tcopied: boolean\n}\n\nexport function initializeHarnesses({\n\troot,\n\tharnesses: preferred = [],\n\tcopy = false,\n\tforce = false,\n}: InitializeOptions): InitializeResult {\n\tconst canonicalSkills = join(root, '.agents', 'skills')\n\tconst skills = countSkills(canonicalSkills)\n\tconst harnesses = selectHarnesses(root, preferred)\n\tconst linked = projectSkills({ root, canonicalSkills, harnesses, copy, force })\n\n\treturn {\n\t\troot,\n\t\tharnesses: harnesses.map((harness) => harness.name),\n\t\tnative: harnesses.filter((harness) => !harness.skillsDirectory).map((harness) => harness.name),\n\t\tlinked,\n\t\tdeprecated: harnesses\n\t\t\t.filter((harness) => harness.deprecated)\n\t\t\t.map((harness) => ({ name: harness.name, replacedBy: harness.deprecated as HarnessName })),\n\t\tskills,\n\t\tcopied: copy,\n\t}\n}\n","import type { cli } from 'clibuilder'\nimport { command, z } from 'clibuilder'\nimport { parseFormat, writeResult } from '../command-output/command-output.ts'\nimport { doctorCommand } from '../diagnose-bridges/doctor.command.ts'\nimport { type HarnessName, harnessRegistry } from '../harness-registry/harness-registry.ts'\nimport { initializeHarnesses } from './initialize-harnesses.ts'\n\nexport const initCommand: cli.Command = command({\n\tname: 'init',\n\tdescription: 'Set up canonical agent skills for the harnesses already enabled in a repository.',\n\toptions: {\n\t\troot: {\n\t\t\tdescription: 'Repository or package directory. Defaults to the current directory.',\n\t\t\ttype: z.optional(z.string()),\n\t\t},\n\t\tharness: {\n\t\t\tdescription: 'Comma-separated harnesses to enable in addition to Claude Code and Cursor, e.g. codex,gemini-cli.',\n\t\t\ttype: z.optional(z.string()),\n\t\t},\n\t\tcopy: {\n\t\t\tdescription: 'Copy skills instead of linking them.',\n\t\t\ttype: z.optional(z.boolean()),\n\t\t},\n\t\tforce: {\n\t\t\tdescription: 'Replace conflicting target skill directories.',\n\t\t\ttype: z.optional(z.boolean()),\n\t\t},\n\t\tformat: {\n\t\t\tdescription: 'Output format: toon (default), json, or text for a human-readable report.',\n\t\t\ttype: z.optional(z.string()),\n\t\t\tdefault: 'toon',\n\t\t},\n\t},\n\trun(args) {\n\t\ttry {\n\t\t\tconst format = parseFormat(args.format)\n\t\t\tconst requested = args.harness\n\t\t\t\t?.split(',')\n\t\t\t\t.map((name) => name.trim())\n\t\t\t\t.filter(Boolean)\n\t\t\tconst unsupported = requested?.filter((name) => !harnessRegistry.some((harness) => harness.name === name))\n\t\t\tif (unsupported?.length)\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Unsupported harness: ${unsupported.join(', ')}. Supported: ${harnessRegistry\n\t\t\t\t\t\t.map((harness) => harness.name)\n\t\t\t\t\t\t.join(', ')}.`,\n\t\t\t\t)\n\t\t\twriteResult(\n\t\t\t\tinitializeHarnesses({\n\t\t\t\t\troot: args.root ?? process.cwd(),\n\t\t\t\t\t...(requested?.length ? { harnesses: requested as HarnessName[] } : {}),\n\t\t\t\t\t...(args.copy === undefined ? {} : { copy: args.copy }),\n\t\t\t\t\t...(args.force === undefined ? {} : { force: args.force }),\n\t\t\t\t}),\n\t\t\t\tformat,\n\t\t\t)\n\t\t} catch (error) {\n\t\t\tprocess.stderr.write(`error: ${error instanceof Error ? error.message : 'Harness initialization failed.'}\\n`)\n\t\t\tprocess.exitCode = 1\n\t\t}\n\t},\n})\n\n// Named for the package rather than shortened to `harness`: `repobuddy` mounts every plugin into one\n// command namespace, where `harness` is generic enough to collide with another plugin's.\nexport const harnessCommand: cli.Command = command({\n\tname: 'agent-harness',\n\tdescription: 'Commands for configuring agent harness compatibility.',\n\tcommands: [initCommand, doctorCommand],\n})\n\nexport function activate({ addCommand }: { addCommand(command: typeof harnessCommand): void }): void {\n\taddCommand(harnessCommand)\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "buddy-agent-harness",
-  "version": "0.2.0",
-  "description": "Initialize standards-based agent configuration across coding-agent harnesses",
+  "version": "0.3.1",
+  "description": "Initialize standards-based agent configuration across agent harnesses",
   "keywords": [
     "repobuddy",
     "agent",
@@ -60,6 +60,8 @@
     "build": "tsdown",
     "coverage": "vitest run --coverage",
     "dev": "node bin/buddy-agent-harness.mjs",
+    "skill:doctor": "tsx scripts/generate-doctor-skill.ts",
+    "skill:doctor:check": "tsx scripts/generate-doctor-skill.ts --check",
     "test": "vitest run",
     "test:dist": "tsc --noEmit -p tsconfig.dist.json && vitest run --config vitest.dist.config.ts",
     "typecheck": "tsc --noEmit"

package/plugin.json

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

package/skills/doctor/README.md

@@ -0,0 +1,33 @@
+# Harness Doctor
+
+Report whether the harness skill bridges in a repository still resolve into `.agents/skills`.
+
+## What it does
+
+`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` skill, because rebuilding a bridge can move skills a user wrote.
+
+```sh
+npx -y buddy-agent-harness doctor
+```
+
+## Why it exists
+
+The failure it is built for is silent. 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 committed symlink out as a regular file whose contents are the target path. The harness looks for a directory, finds a file, and loads zero project skills with no warning anywhere.
+
+`core.symlinks` is per-clone and cannot be enforced from the repository, so detection is the only reliable lever. It is also cheap: the path exists but is not a directory.
+
+## Read-only by design
+
+There is no `--fix`. Every repair is already expressible with `init` flags, and reimplementing them here would drift. On the Windows case it would likely drift wrongly: the naive repair is to recreate the link, which is exactly the operation that failed on that machine. `--copy` is the branch that works there, and `init` already has it.
+
+Staying read-only also means the command is safe to wire into a session-start hook without reasoning about whether the hook passes a mutating flag.
+
+The exit code is `0` even when findings exist. The diagnosis succeeded; a non-zero code reads to an agent as "this command is broken, try something else."
+
+## Divergence
+
+A copy is a snapshot rather than a live projection, so writes flow the wrong way through it: an agent asked to update a skill edits `.claude/skills/<name>/SKILL.md` and the change lands in the copy instead of in `.agents/skills`. When the two sides differ, `doctor` names which one moved — using the last commit where they agreed as the base — because "these two differ" is not actionable on its own. When both moved it says so and refuses to guess, since rebuilding would discard one of the edits.
+
+## Generated from the command
+
+`SKILL.md` is generated from `src/diagnose-bridges/doctor-guidance.ts`, the same table the command prints its findings and repairs from, so the skill cannot drift from the CLI. `pnpm skill:doctor` rewrites it and `pnpm skill:doctor:check` — part of `pnpm verify` — fails when the committed copy is stale.

package/skills/doctor/SKILL.md

@@ -0,0 +1,56 @@
+---
+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.
+---
+
+<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-doctor-skill.ts. Do not edit by hand. -->
+
+# 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.
+
+Diagnose it:
+
+```sh
+npx -y buddy-agent-harness doctor
+```
+
+The command is read-only. It never repairs anything, so it is safe to run at any point, including from a session-start hook.
+
+## 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`.
+
+`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 `/buddy-agent-harness:init` instead.
+
+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
+
+| Finding | What it means | Repair |
+| --- | --- | --- |
+| `no-canonical` | the canonical skill directory does not exist, so no bridge can resolve | run `/buddy-agent-harness:init`, which creates `.agents/skills` and the bridges |
+| `missing` | no bridge at this path — the harness sees zero project skills | run `/buddy-agent-harness:init` |
+| `degraded` | expected a directory but found a regular file — checkout without core.symlinks | run `/buddy-agent-harness:init --copy --force` |
+| `stale` | symlink does not resolve to .agents/skills | run `/buddy-agent-harness:init --force` |
+| `diverged-bridge` | only the bridge changed since the two last agreed — an agent wrote through the copy | replace .agents/skills with <path> to keep the newer edit, then run `/buddy-agent-harness:init --force` |
+| `diverged-canonical` | only .agents/skills changed since the two last agreed — the copy is stale | run `/buddy-agent-harness:init --copy --force` |
+| `diverged-both` | both sides changed since they last agreed — rebuilding would discard one of them | run `git diff --no-index .agents/skills <path>` and reconcile by hand |
+| `diverged-unknown` | contents differ and no commit where they agreed was found — which side moved is unknown | run `git diff --no-index .agents/skills <path>` and reconcile by hand |
+| `unpinned-copy` | tracked copy without the skip-worktree bit — the tree is dirty with content that must not be committed | run `git ls-files -z <path> \| xargs -0 git update-index --skip-worktree` |
+
+Substitute the reported bridge path for `<path>`.
+
+## 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. `/buddy-agent-harness:init --copy --force` rebuilds the bridges as real directories on that machine.
+
+A copy is a snapshot rather than a live projection, and an agent that edits a skill through it writes into the copy instead of into `.agents/skills`. That is what the `diverged` findings catch.
+
+## Rules
+
+- 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.

package/skills/init/README.md

@@ -10,11 +10,7 @@ It detects agent configuration you already have — instruction files, skills, c
 
 ## Why the projection step is small
 
-Codex, Cursor, GitHub Copilot CLI, and Devin Desktop read `.agents/skills/` natively, so they need nothing. Only Claude Code and Gemini CLI need a link:
-
-```sh
-npx -y buddy-agent-harness init
-```
+Codex, Cursor, GitHub Copilot CLI, and Devin Desktop read `.agents/skills/` natively, so they need nothing. Only Claude Code and Gemini CLI need a link, which the skill creates by running the `init` command in Phase 4.
 
 Claude Code also reads `CLAUDE.md` rather than `AGENTS.md`, so the skill sets up a `CLAUDE.md` that imports `@AGENTS.md`.
 

package/skills/init/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: init
-description: 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 coding-agent harnesses.
+description: 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.
+argument-hint: '[--root <dir>] [--harness <names>] [--copy] [--force]'
 ---
 
 # Harness Init
@@ -22,6 +23,17 @@ Most of the field already reads `.agents/skills/` natively: Codex, Cursor, GitHu
 
 `init` writes skills projections only. Every instruction bridge above is manual work in Phase 4.
 
+## Arguments
+
+An invocation may carry the command's own flags, most often when `doctor` hands back a repair: `/buddy-agent-harness:init --copy --force`.
+
+Read them from the invocation itself rather than from a placeholder. Claude Code appends what the caller typed as `ARGUMENTS: <value>`, and Codex substitutes nothing at all, so on every harness the flags arrive as text you can read. Writing `$ARGUMENTS` into this body would resolve on Claude Code and stay literal everywhere else.
+
+- `--root`, `--harness`, `--copy`, `--force`, and `--format` pass through to the command in Phase 4.
+- Prose carries the same weight: "links are unavailable here" means `--copy`, and "replace the bridge" means `--force`.
+- An argument never skips a phase. `--force` still needs the Phase 3 approval, and the survey still runs first.
+- Say what you did not recognize and carry on. Never guess at a flag.
+
 Work in five phases. Do not skip Phase 3.
 
 ## 1. Survey

package/skills/init/references/frontmatter.md

@@ -50,10 +50,17 @@ Enforcing `name` == directory name is also worth doing even though it is only a
 | `disable-model-invocation` | Claude Code, Cursor |
 | `paths`, legacy `globs` | Cursor only |
 | `model` | Copilot CLI only |
+| `argument-hint`, `arguments` | Claude Code only |
 | hook configuration | Claude Code, Cline, Kiro CLI |
 
 Codex additionally reads an `agents/openai.yaml` **sidecar file** beside `SKILL.md` — not frontmatter. See `harnesses/codex.md`; never add one unprompted.
 
+## Arguments are the one field group that fails loudly
+
+Most harness-specific fields are dropped in silence. `argument-hint` and `arguments` are the exception: they are Claude Code extensions, and the spec's own distribution paths — claude.ai uploads, the Skills API, and `package_skill.py` — reject any field outside `name`, `description`, `license`, `compatibility`, `metadata`, and `allowed-tools` with a hard error rather than ignoring it.
+
+So a skill that takes arguments and also ships through claude.ai cannot use the fields at all. A skill distributed only through a plugin can. Either way the behavior belongs in the body, because no harness but Claude Code substitutes anything: Claude Code appends what the caller typed as `ARGUMENTS: <value>` when the body has no `$ARGUMENTS`, Codex has no argument mechanism for skills, and the spec defines none. A body that says how to read the invocation works on all of them; a `$ARGUMENTS` placeholder resolves on one and stays literal on the rest.
+
 ## What follows from that
 
 Claude Code has the largest field surface, so a skill authored for it and shared everywhere carries fields the other harnesses parse and discard. That is a small, unavoidable context cost — accept it rather than maintaining divergent copies.

package/skills/init/references/harnesses/claude-code.md

@@ -36,6 +36,7 @@ So a nested `AGENTS.md` needs its own `CLAUDE.md` stub to be visible at all, and
 Claude Code recognizes the most fields (`context: fork`, `agent:`, `disable-model-invocation`, `once`, `${CLAUDE_SKILL_DIR}`). Other harnesses drop them silently.
 
 - Restate anything load-bearing in the Markdown body.
+- `argument-hint` and `arguments` are Claude Code's argument fields, and the only ones that fail loudly elsewhere: claude.ai uploads and the Skills API reject them outright. Claude Code appends what the caller typed as `ARGUMENTS: <value>` when the body has no `$ARGUMENTS`, so a skill reads its arguments without either field. See `frontmatter.md`.
 - **Enforce `name` equal to the directory name.** Claude Code treats `name` as a display label only and resolves the command from the directory name; matching them removes the discrepancy.
 
 ## Leave alone — canonical-only

package/skills/init/references/harnesses/codex.md

@@ -6,6 +6,12 @@
 - Detection directory is `.codex`. Its presence enables Codex in the config record and changes nothing on disk.
 - Apply `frontmatter.md` as normal. Codex requires `name` and `description`, and rejects unquoted colons like every other harness.
 
+## Arguments
+
+Codex skills have none. No placeholder syntax is documented for `SKILL.md`, and the sidecar below has no argument field. The `$1`–`$9` and `$ARGUMENTS` placeholders belong to custom prompts (`~/.codex/prompts/`), which OpenAI has deprecated in favor of skills.
+
+A skill that must take arguments states in its body how to read them from the invocation. That is the one mechanism every harness shares.
+
 ## Optional sidecar
 
 Codex alone reads `agents/openai.yaml` inside a skill directory (display name, icons, brand color, `allow_implicit_invocation`, MCP dependencies).

package/src/cli.ts

@@ -1,4 +1,5 @@
 import { cli } from 'clibuilder'
+import { doctorCommand } from './diagnose-bridges/doctor.command.ts'
 import { initCommand } from './initialize-harnesses/init.command.ts'
 
 export async function main(): Promise<void> {
@@ -8,7 +9,7 @@ export async function main(): Promise<void> {
 		description: 'Initialize agent harness skill compatibility in consumer repositories.',
 	})
 	try {
-		await app.command(initCommand).parse(process.argv)
+		await app.command(initCommand).command(doctorCommand).parse(process.argv)
 	} catch (error) {
 		process.stdout.write(`error: ${error instanceof Error ? error.message : 'Invalid command.'}\n`)
 		process.exitCode = 2

package/src/command-output/command-output.ts

@@ -0,0 +1,68 @@
+import { sep } from 'node:path'
+import { encode } from '@toon-format/toon'
+
+export type OutputFormat = 'json' | 'toon' | 'text'
+
+const formats: readonly OutputFormat[] = ['toon', 'json', 'text']
+
+/** Rejects anything but the supported formats so an unknown value never falls back silently. */
+export function parseFormat(value: string | undefined): OutputFormat {
+	if (!formats.includes(value as OutputFormat)) throw new Error('--format must be toon, json, or text.')
+	return value as OutputFormat
+}
+
+/** The single stdout boundary: internal logic stays on plain objects, encoding happens here. */
+export function writeResult(value: object, format: OutputFormat): void {
+	process.stdout.write(`${encodeResult(value, format)}\n`)
+}
+
+function encodeResult(value: object, format: OutputFormat): string {
+	if (format === 'json') return JSON.stringify(value)
+	return format === 'text' ? renderText(value) : encode(value)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function cell(value: unknown): string {
+	return value === undefined ? '' : String(value)
+}
+
+/** A header row plus one row per record, every column padded to its widest cell. */
+function table(rows: Record<string, unknown>[]): string[] {
+	const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))]
+	const widths = columns.map((column) => Math.max(column.length, ...rows.map((row) => cell(row[column]).length)))
+	const line = (values: string[]) =>
+		`  ${values.map((value, index) => value.padEnd(widths[index] as number)).join('  ')}`.trimEnd()
+	return [line(columns), ...rows.map((row) => line(columns.map((column) => cell(row[column]))))]
+}
+
+/**
+ * The same result rendered for a person rather than for an agent: scalars as `key: value`, records
+ * as an aligned table, and everything else as a bulleted list. TOON stays the default because it is
+ * what an agent parses; this is for reading over someone's shoulder.
+ */
+export function renderText(value: object): string {
+	const blocks = Object.entries(value).map(([key, item]) => {
+		if (!Array.isArray(item)) return [`${key}: ${isRecord(item) ? JSON.stringify(item) : String(item)}`]
+		if (!item.length) return [`${key}: (none)`]
+		const body = item.every(isRecord) ? table(item) : item.map((entry) => `  - ${String(entry)}`)
+		return [`${key}:`, ...body]
+	})
+
+	// A blank line wherever a multi-line block meets its neighbour, so a following scalar does not
+	// read as another row of the table above it.
+	return blocks
+		.flatMap((block, index) => {
+			const previous = blocks[index - 1]
+			return previous && (previous.length > 1 || block.length > 1) ? ['', ...block] : block
+		})
+		.join('\n')
+}
+
+/** AXI §10: the executable's absolute path, with the user's home directory collapsed to `~`. */
+export function binPath(home: string, executable: string | undefined): string {
+	if (!executable) return 'buddy-agent-harness'
+	return home && executable.startsWith(home + sep) ? `~${executable.slice(home.length)}` : executable
+}

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

@@ -0,0 +1,147 @@
+import { lstatSync, readFileSync, readlinkSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { type Harness, type HarnessName, selectHarnesses } from '../harness-registry/harness-registry.ts'
+import { filesUnder } from './directory-files.ts'
+import { type BridgeProblem, repairFor } from './doctor-guidance.ts'
+import { type DivergenceDirection, GitBridgeState } from './git-bridge-state.ts'
+
+export type BridgeKind = 'symlink' | 'copy' | 'file' | 'none'
+export type BridgeStatus = 'ok' | 'missing' | 'degraded' | 'stale' | 'diverged'
+
+export type BridgeReport = {
+	harness: HarnessName
+	/** Repository-relative, as the harness registry declares it. */
+	path: string
+	kind: BridgeKind
+	status: BridgeStatus
+}
+
+export type BridgeFinding = {
+	path: string
+	detail: string
+	/** The command that repairs this finding, already carrying the bridge path. */
+	repair: string
+}
+
+export type DivergenceReport = {
+	path: string
+	direction: DivergenceDirection
+}
+
+export type DiagnoseOptions = {
+	root: string
+	harnesses?: HarnessName[]
+	/** How to name this tool in the repair commands. */
+	cli: string
+}
+
+export type DiagnoseResult = {
+	bridges: BridgeReport[]
+	divergence: DivergenceReport[]
+	findings: BridgeFinding[]
+}
+
+const canonicalPath = '.agents/skills'
+
+function pathState(target: string): 'missing' | 'symlink' | 'directory' | 'file' {
+	try {
+		const stats = lstatSync(target)
+		if (stats.isSymbolicLink()) return 'symlink'
+		return stats.isDirectory() ? 'directory' : 'file'
+	} catch {
+		return 'missing'
+	}
+}
+
+function isDirectory(path: string): boolean {
+	try {
+		return statSync(path).isDirectory()
+	} catch {
+		return false
+	}
+}
+
+/** The same test `init` uses to decide a projection is already correct, plus that it still resolves. */
+function resolvesToCanonical(target: string, canonical: string): boolean {
+	return readlinkSync(target) === relative(dirname(target), canonical) && isDirectory(target)
+}
+
+function sameContent(left: string, right: string): boolean {
+	const leftFiles = filesUnder(left)
+	const rightFiles = filesUnder(right)
+	return (
+		leftFiles.length === rightFiles.length &&
+		leftFiles.every(
+			(file, index) =>
+				rightFiles[index] === file && readFileSync(join(left, file)).equals(readFileSync(join(right, file))),
+		)
+	)
+}
+
+type Inspection = {
+	kind: BridgeKind
+	status: BridgeStatus
+	problem?: BridgeProblem
+	direction?: DivergenceDirection
+}
+
+function inspect(target: string, path: string, canonical: string, git: GitBridgeState): Inspection {
+	switch (pathState(target)) {
+		case 'missing':
+			return { kind: 'none', status: 'missing', problem: 'missing' }
+		// The flagship Windows failure: git with `core.symlinks=false` writes the link out as a
+		// regular file holding the target path, and the harness silently loads nothing.
+		case 'file':
+			return { kind: 'file', status: 'degraded', problem: 'degraded' }
+		case 'symlink':
+			return resolvesToCanonical(target, canonical)
+				? { kind: 'symlink', status: 'ok' }
+				: { kind: 'symlink', status: 'stale', problem: 'stale' }
+		default: {
+			if (!sameContent(target, canonical)) {
+				const direction = git.directionOf(path, canonicalPath)
+				return { kind: 'copy', status: 'diverged', problem: `diverged-${direction}`, direction }
+			}
+			// A copy over a tracked symlink only stays out of `git status` while its skip-worktree bit
+			// survives, and some checkout and merge operations clear it.
+			return git.trackingOf(path) === 'tracked'
+				? { kind: 'copy', status: 'ok', problem: 'unpinned-copy' }
+				: { kind: 'copy', status: 'ok' }
+		}
+	}
+}
+
+/**
+ * Reports whether every bridge `init` would create for this repository still resolves into
+ * `.agents/skills`. Read-only: nothing is created, moved, or repaired, so the caller decides what
+ * to run from the repair each finding carries.
+ */
+export function diagnoseBridges({ root, harnesses: preferred = [], cli }: DiagnoseOptions): DiagnoseResult {
+	const canonical = join(root, '.agents', 'skills')
+	const git = new GitBridgeState(root)
+	const bridged = selectHarnesses(root, preferred).filter((harness): harness is Harness & { skillsDirectory: string } =>
+		Boolean(harness.skillsDirectory),
+	)
+
+	const bridges: BridgeReport[] = []
+	const divergence: DivergenceReport[] = []
+	const findings: BridgeFinding[] = []
+
+	if (!isDirectory(canonical)) {
+		const { detail, repair } = repairFor('no-canonical')
+		findings.push({ path: canonicalPath, detail, repair: repair(canonicalPath, cli) })
+	}
+
+	for (const harness of bridged) {
+		const path = harness.skillsDirectory
+		const inspection = inspect(join(root, path), path, canonical, git)
+		bridges.push({ harness: harness.name, path, kind: inspection.kind, status: inspection.status })
+		if (inspection.direction) divergence.push({ path, direction: inspection.direction })
+		if (inspection.problem) {
+			const { detail, repair } = repairFor(inspection.problem)
+			findings.push({ path, detail, repair: repair(path, cli) })
+		}
+	}
+
+	return { bridges, divergence, findings }
+}

package/src/diagnose-bridges/directory-files.ts

@@ -0,0 +1,17 @@
+import { readdirSync } from 'node:fs'
+import { join, posix, relative, sep } from 'node:path'
+
+/**
+ * Every file below `directory`, as paths relative to it, POSIX-separated and sorted. A directory
+ * that does not exist reads as empty: `doctor` never creates one to look at it.
+ */
+export function filesUnder(directory: string): string[] {
+	try {
+		return readdirSync(directory, { recursive: true, withFileTypes: true })
+			.filter((entry) => entry.isFile())
+			.map((entry) => relative(directory, join(entry.parentPath, entry.name)).split(sep).join(posix.sep))
+			.sort()
+	} catch {
+		return []
+	}
+}