buddy-agent-harness 0.1.0 → 0.3.0

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 []
+	}
+}

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

@@ -0,0 +1,176 @@
+/**
+ * The one place `doctor`'s guidance is written. The command reads `detail` and `repair` to fill its
+ * `findings` and `help` sections; `skills/doctor/SKILL.md` is generated from the same table by
+ * `scripts/generate-doctor-skill.ts`, so the shipped skill cannot drift from what the command says.
+ */
+
+/** Every way a bridge can fail, in the order `doctor` reports them. */
+export type BridgeProblem =
+	| 'no-canonical'
+	| 'missing'
+	| 'degraded'
+	| 'stale'
+	| 'diverged-bridge'
+	| 'diverged-canonical'
+	| 'diverged-both'
+	| 'diverged-unknown'
+	| 'unpinned-copy'
+
+export type Repair = {
+	problem: BridgeProblem
+	/** What `doctor` prints in the `findings` row for this problem. */
+	detail: string
+	/**
+	 * The command that fixes it, for `doctor`'s own output. `path` is the repository-relative bridge
+	 * path; `cli` is how to invoke this tool.
+	 */
+	repair(path: string, cli: string): string
+	/**
+	 * What the shipped skill tells an agent to do instead. A repair that rebuilds a bridge delegates
+	 * to the `init` skill rather than calling the `init` command, because rebuilding can move
+	 * user-authored skills and that judgment is the `init` skill's, not `doctor`'s.
+	 */
+	skillRepair(path: string): string
+}
+
+/** How the command names itself. A skill may run without the binary on PATH, so it uses `npx`. */
+export const commandInvocation = 'buddy-agent-harness'
+export const skillInvocation = 'npx -y buddy-agent-harness'
+/** How the skill hands a repair back to `init`. */
+export const initSkillInvocation = '/buddy-agent-harness:init'
+
+export const doctorRepairs: readonly Repair[] = [
+	{
+		problem: 'no-canonical',
+		detail: 'the canonical skill directory does not exist, so no bridge can resolve',
+		repair: (_path, cli) => `${cli} init`,
+		skillRepair: () => `run \`${initSkillInvocation}\`, which creates \`.agents/skills\` and the bridges`,
+	},
+	{
+		problem: 'missing',
+		detail: 'no bridge at this path — the harness sees zero project skills',
+		repair: (_path, cli) => `${cli} init`,
+		skillRepair: () => `run \`${initSkillInvocation}\``,
+	},
+	{
+		problem: 'degraded',
+		detail: 'expected a directory but found a regular file — checkout without core.symlinks',
+		repair: (_path, cli) => `${cli} init --copy --force`,
+		skillRepair: () => `run \`${initSkillInvocation} --copy --force\``,
+	},
+	{
+		problem: 'stale',
+		detail: 'symlink does not resolve to .agents/skills',
+		repair: (_path, cli) => `${cli} init --force`,
+		skillRepair: () => `run \`${initSkillInvocation} --force\``,
+	},
+	{
+		problem: 'diverged-bridge',
+		detail: 'only the bridge changed since the two last agreed — an agent wrote through the copy',
+		repair: (path, cli) =>
+			`replace .agents/skills with ${path} to keep the newer edit and then run ${cli} init --force`,
+		skillRepair: (path) =>
+			`replace .agents/skills with ${path} to keep the newer edit, then run \`${initSkillInvocation} --force\``,
+	},
+	{
+		problem: 'diverged-canonical',
+		detail: 'only .agents/skills changed since the two last agreed — the copy is stale',
+		repair: (_path, cli) => `${cli} init --copy --force`,
+		skillRepair: () => `run \`${initSkillInvocation} --copy --force\``,
+	},
+	{
+		problem: 'diverged-both',
+		detail: 'both sides changed since they last agreed — rebuilding would discard one of them',
+		repair: (path) => `git diff --no-index .agents/skills ${path} and reconcile by hand`,
+		skillRepair: (path) => `run \`git diff --no-index .agents/skills ${path}\` and reconcile by hand`,
+	},
+	{
+		problem: 'diverged-unknown',
+		detail: 'contents differ and no commit where they agreed was found — which side moved is unknown',
+		repair: (path) => `git diff --no-index .agents/skills ${path} and reconcile by hand`,
+		skillRepair: (path) => `run \`git diff --no-index .agents/skills ${path}\` and reconcile by hand`,
+	},
+	{
+		problem: 'unpinned-copy',
+		detail: 'tracked copy without the skip-worktree bit — the tree is dirty with content that must not be committed',
+		// The index entry is the tracked symlink on a Windows checkout but the individual files in a
+		// committed copy, so the paths are read back from git rather than assumed.
+		repair: (path) => `git ls-files -z ${path} | xargs -0 git update-index --skip-worktree`,
+		skillRepair: (path) => `run \`git ls-files -z ${path} | xargs -0 git update-index --skip-worktree\``,
+	},
+]
+
+const repairsByProblem = new Map(doctorRepairs.map((entry) => [entry.problem, entry]))
+
+export function repairFor(problem: BridgeProblem): 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.',
+} as const
+
+/** Written into the generated skill so a reader knows not to edit it in place. */
+export const generatedSkillWarning =
+	'<!-- Generated from src/diagnose-bridges/doctor-guidance.ts by scripts/generate-doctor-skill.ts. Do not edit by hand. -->'
+
+/** The shipped `doctor` skill, rendered from the same table the command prints. */
+export function renderDoctorSkill(): 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')
+
+	return `---
+name: ${doctorSkill.name}
+description: ${doctorSkill.description}
+---
+
+${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.
+
+Diagnose it:
+
+\`\`\`sh
+${skillInvocation} 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 \`${initSkillInvocation}\` 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 |
+| --- | --- | --- |
+${rows}
+
+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. \`${initSkillInvocation} --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/src/diagnose-bridges/doctor.command.ts

@@ -0,0 +1,87 @@
+import { homedir } from 'node:os'
+import type { cli } from 'clibuilder'
+import { command, z } from 'clibuilder'
+import { binPath, parseFormat, writeResult } from '../command-output/command-output.ts'
+import { type HarnessName, harnessRegistry } from '../harness-registry/harness-registry.ts'
+import { type DiagnoseResult, diagnoseBridges } from './diagnose-bridges.ts'
+import { commandInvocation } from './doctor-guidance.ts'
+
+type DoctorReport = {
+	bin: string
+	bridges: DiagnoseResult['bridges']
+	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
+	help?: string[]
+}
+
+/**
+ * AXI §5: the healthy answer states the zero with context, so an agent does not re-run with other
+ * flags to confirm that an empty section really meant "nothing wrong".
+ */
+export function buildReport(bin: string, result: DiagnoseResult): DoctorReport {
+	if (!result.findings.length) {
+		const count = result.bridges.length
+		return {
+			bin,
+			bridges: result.bridges,
+			findings:
+				count === 1 ? '0 problems found — the 1 bridge resolves' : `0 problems found — all ${count} bridges resolve`,
+		}
+	}
+
+	return {
+		bin,
+		bridges: result.bridges,
+		...(result.divergence.length ? { divergence: result.divergence } : {}),
+		findings: result.findings.map(({ path, detail }) => ({ path, detail })),
+		help: [...new Set(result.findings.map((finding) => `Run \`${finding.repair}\``))],
+	}
+}
+
+export const doctorCommand: cli.Command = command({
+	name: 'doctor',
+	description: 'Report whether the harness skill bridges in this repository still resolve. Read-only.',
+	options: {
+		root: {
+			description: 'Repository or package directory. Defaults to the current directory.',
+			type: z.optional(z.string()),
+		},
+		harness: {
+			description: 'Comma-separated harnesses to check in addition to Claude Code and Cursor, e.g. codex,gemini-cli.',
+			type: z.optional(z.string()),
+		},
+		format: {
+			description: 'Output format: toon (default), json, or text for a human-readable report.',
+			type: z.optional(z.string()),
+			default: 'toon',
+		},
+	},
+	run(args) {
+		try {
+			const format = parseFormat(args.format)
+			const requested = args.harness
+				?.split(',')
+				.map((name) => name.trim())
+				.filter(Boolean)
+			const unsupported = requested?.filter((name) => !harnessRegistry.some((harness) => harness.name === name))
+			if (unsupported?.length)
+				throw new Error(
+					`Unsupported harness: ${unsupported.join(', ')}. Supported: ${harnessRegistry
+						.map((harness) => harness.name)
+						.join(', ')}.`,
+				)
+			const result = diagnoseBridges({
+				root: args.root ?? process.cwd(),
+				...(requested?.length ? { harnesses: requested as HarnessName[] } : {}),
+				cli: commandInvocation,
+			})
+			// Exit stays 0 even with findings: the diagnosis succeeded, and a non-zero code reads to an
+			// agent as "this command is broken, try something else".
+			writeResult(buildReport(binPath(homedir(), process.argv[1]), result), format)
+		} catch (error) {
+			process.stderr.write(`error: ${error instanceof Error ? error.message : 'Harness diagnosis failed.'}\n`)
+			process.exitCode = 1
+		}
+	},
+})

package/src/diagnose-bridges/git-bridge-state.ts

@@ -0,0 +1,102 @@
+import { execFileSync } from 'node:child_process'
+import { join } from 'node:path'
+import { filesUnder } from './directory-files.ts'
+
+/** Which side of a diverged bridge moved since the last commit where the two agreed. */
+export type DivergenceDirection = 'bridge' | 'canonical' | 'both' | 'unknown'
+
+/** Whether a path is tracked, and if so whether its skip-worktree bit is still set. */
+export type TrackingState = 'untracked' | 'tracked' | 'skip-worktree'
+
+function git(root: string, args: string[], input?: string): string | undefined {
+	try {
+		return execFileSync('git', args, {
+			cwd: root,
+			encoding: 'utf8',
+			...(input === undefined ? {} : { input }),
+			stdio: ['pipe', 'pipe', 'pipe'],
+		})
+	} catch {
+		return undefined
+	}
+}
+
+function lines(output: string | undefined): string[] {
+	return (output ?? '').split('\n').filter(Boolean)
+}
+
+/**
+ * Reads git state for the two sides of a bridge. Every method degrades to "cannot tell" rather than
+ * throwing, so `doctor` still reports on a tarball, a worktree without git, or a repository with no
+ * commits.
+ */
+export class GitBridgeState {
+	/** Path of `root` relative to the repository root, `''` at the top, `undefined` outside a repository. */
+	private readonly prefix: string | undefined
+
+	constructor(private readonly root: string) {
+		this.prefix = git(root, ['rev-parse', '--show-prefix'])?.trim()
+	}
+
+	/**
+	 * `init --copy` marks a bridge skip-worktree so a machine-local copy over a tracked symlink stops
+	 * showing as a pending change. The bit is a hint that some checkouts clear, so it is verified
+	 * rather than assumed.
+	 */
+	trackingOf(path: string): TrackingState {
+		if (this.prefix === undefined) return 'untracked'
+		const entries = lines(git(this.root, ['ls-files', '-v', '--', path]))
+		if (!entries.length) return 'untracked'
+		return entries.every((entry) => entry.startsWith('S')) ? 'skip-worktree' : 'tracked'
+	}
+
+	/**
+	 * Names the side that moved by finding the newest commit whose two trees agreed, then asking which
+	 * of the working directories still matches it.
+	 */
+	directionOf(bridge: string, canonical: string): DivergenceDirection {
+		if (this.prefix === undefined) return 'unknown'
+		const base = this.lastAgreedTree(bridge, canonical)
+		if (base === undefined) return 'unknown'
+		const bridgeMoved = !this.matchesTree(bridge, base)
+		const canonicalMoved = !this.matchesTree(canonical, base)
+		if (bridgeMoved && canonicalMoved) return 'both'
+		if (bridgeMoved) return 'bridge'
+		return 'canonical'
+	}
+
+	/** The tree of the newest commit where both paths held identical content. */
+	private lastAgreedTree(bridge: string, canonical: string): string | undefined {
+		for (const commit of lines(git(this.root, ['rev-list', '-n', '200', 'HEAD', '--', bridge, canonical]))) {
+			const bridgeObject = git(this.root, ['rev-parse', '-q', '--verify', `${commit}:${this.prefix}${bridge}`])?.trim()
+			if (!bridgeObject) continue
+			const canonicalObject = git(this.root, [
+				'rev-parse',
+				'-q',
+				'--verify',
+				`${commit}:${this.prefix}${canonical}`,
+			])?.trim()
+			if (bridgeObject === canonicalObject) return bridgeObject
+		}
+		return undefined
+	}
+
+	/**
+	 * Compares a working directory against a git tree by object id. `hash-object` is used rather than
+	 * hashing in-process so the comparison follows whatever object format the repository uses.
+	 */
+	private matchesTree(directory: string, tree: string): boolean {
+		const expected = new Map(
+			lines(git(this.root, ['ls-tree', '-r', tree])).map((entry) => {
+				const [meta, path] = entry.split('\t')
+				return [path, (meta as string).split(' ')[2] as string] as const
+			}),
+		)
+		const files = filesUnder(join(this.root, directory))
+		if (files.length !== expected.size || files.some((file) => !expected.has(file))) return false
+		const hashed = lines(
+			git(this.root, ['hash-object', '--stdin-paths'], files.map((file) => join(directory, file)).join('\n')),
+		)
+		return hashed.length === files.length && files.every((file, index) => expected.get(file) === hashed[index])
+	}
+}

package/src/index.ts

@@ -1,3 +1,17 @@
+export type {
+	BridgeFinding,
+	BridgeKind,
+	BridgeReport,
+	BridgeStatus,
+	DiagnoseOptions,
+	DiagnoseResult,
+	DivergenceReport,
+} from './diagnose-bridges/diagnose-bridges.ts'
+export { diagnoseBridges } from './diagnose-bridges/diagnose-bridges.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 { DivergenceDirection } from './diagnose-bridges/git-bridge-state.ts'
 export type { HarnessName } from './harness-registry/harness-registry.ts'
 export { harnessRegistry } from './harness-registry/harness-registry.ts'
 export { activate, harnessCommand, initCommand } from './initialize-harnesses/init.command.ts'

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

@@ -1,13 +1,10 @@
-import { encode } from '@toon-format/toon'
 import type { cli } from 'clibuilder'
 import { command, z } from 'clibuilder'
+import { parseFormat, writeResult } from '../command-output/command-output.ts'
+import { doctorCommand } from '../diagnose-bridges/doctor.command.ts'
 import { type HarnessName, harnessRegistry } from '../harness-registry/harness-registry.ts'
 import { initializeHarnesses } from './initialize-harnesses.ts'
 
-function write(value: object, format: 'json' | 'toon' | undefined): void {
-	process.stdout.write(`${format === 'json' ? JSON.stringify(value) : encode(value)}\n`)
-}
-
 export const initCommand: cli.Command = command({
 	name: 'init',
 	description: 'Set up canonical agent skills for the harnesses already enabled in a repository.',
@@ -17,7 +14,7 @@ export const initCommand: cli.Command = command({
 			type: z.optional(z.string()),
 		},
 		harness: {
-			description: 'Comma-separated harnesses to enable in addition to Claude Code and Cursor, e.g. codex,windsurf.',
+			description: 'Comma-separated harnesses to enable in addition to Claude Code and Cursor, e.g. codex,gemini-cli.',
 			type: z.optional(z.string()),
 		},
 		copy: {
@@ -29,15 +26,14 @@ export const initCommand: cli.Command = command({
 			type: z.optional(z.boolean()),
 		},
 		format: {
-			description: 'Output format: toon (default) or json.',
+			description: 'Output format: toon (default), json, or text for a human-readable report.',
 			type: z.optional(z.string()),
 			default: 'toon',
 		},
 	},
 	run(args) {
 		try {
-			const format = args.format
-			if (format !== 'toon' && format !== 'json') throw new Error('--format must be toon or json.')
+			const format = parseFormat(args.format)
 			const requested = args.harness
 				?.split(',')
 				.map((name) => name.trim())
@@ -49,7 +45,7 @@ export const initCommand: cli.Command = command({
 						.map((harness) => harness.name)
 						.join(', ')}.`,
 				)
-			write(
+			writeResult(
 				initializeHarnesses({
 					root: args.root ?? process.cwd(),
 					...(requested?.length ? { harnesses: requested as HarnessName[] } : {}),
@@ -65,10 +61,12 @@ export const initCommand: cli.Command = command({
 	},
 })
 
+// Named for the package rather than shortened to `harness`: `repobuddy` mounts every plugin into one
+// command namespace, where `harness` is generic enough to collide with another plugin's.
 export const harnessCommand: cli.Command = command({
-	name: 'harness',
+	name: 'agent-harness',
 	description: 'Commands for configuring agent harness compatibility.',
-	commands: [initCommand],
+	commands: [initCommand, doctorCommand],
 })
 
 export function activate({ addCommand }: { addCommand(command: typeof harnessCommand): void }): void {

package/.plugin/plugin.json

@@ -1,30 +0,0 @@
-{
-	"$schema": "https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json",
-	"name": "buddy-agent-harness",
-	"version": "0.1.0",
-	"description": "Initialize standards-based agent configuration across coding-agent harnesses",
-	"author": {
-		"name": "repobuddy"
-	},
-	"repository": "https://github.com/repobuddy/buddy-agent-harness",
-	"license": "MIT",
-	"keywords": ["agent", "skills", "harness", "claude-code", "codex"],
-	"skills": "./skills/",
-	"vendorExtensions": {
-		"claude-code": {},
-		"cursor": {
-			"category": "productivity",
-			"tags": ["agent", "skills"]
-		},
-		"codex": {
-			"interface": {
-				"displayName": "Buddy Agent Harness",
-				"category": "productivity"
-			}
-		},
-		"copilot-cli": {
-			"category": "productivity",
-			"tags": ["agent", "skills"]
-		}
-	}
-}