buddy-agent-harness 0.5.0 → 0.7.0

package/src/diagnose-mcp/mcp-model.ts

@@ -0,0 +1,88 @@
+import { isRecord } from '../is-record/is-record.ts'
+/**
+ * The shape both sides of an MCP comparison are normalized into.
+ *
+ * No two MCP configuration files are ever byte-equal — the supported harnesses spread the same
+ * servers across six config keys and three serialization formats — so comparison cannot be a
+ * diff. Each side is parsed into this model and the models are compared.
+ *
+ * The field list is a **superset** of what the hosts accept, which is the whole premise of a
+ * golden set: `description`, `enabled`, and `timeout` are Goose's, `source` is Zed's, and a
+ * converter writing into either has to supply them. Supplying a value the user wrote is
+ * transcription; supplying one they did not is invention, and `init` invents nothing. See
+ * `.research/agentic-configuration-standards/` (E-MCP-05) for what each host makes up today.
+ */
+export type McpTransport = 'stdio' | 'http' | 'sse'
+
+export type McpServer = {
+	transport?: McpTransport
+	command?: string
+	args?: readonly string[]
+	env?: Readonly<Record<string, string>>
+	url?: string
+	headers?: Readonly<Record<string, string>>
+	description?: string
+	enabled?: boolean
+	timeout?: number
+	source?: string
+}
+
+/** Every field of the model, in the order a finding reports them. */
+export const mcpFields = [
+	'transport',
+	'command',
+	'args',
+	'env',
+	'url',
+	'headers',
+	'description',
+	'enabled',
+	'timeout',
+	'source',
+] as const
+
+export type McpField = (typeof mcpFields)[number]
+
+/** The two fields holding one value per name rather than a single value. */
+const mapFields = new Set<McpField>(['env', 'headers'])
+
+/**
+ * Whether two values of the same field agree. Arrays are ordered — `args` is a command line, and
+ * reordering it changes what runs. Maps are not, so they are compared by their sorted entries.
+ */
+function sameValue(field: McpField, left: unknown, right: unknown): boolean {
+	if (mapFields.has(field) && isRecord(left) && isRecord(right)) {
+		const keys = Object.keys(left)
+		return keys.length === Object.keys(right).length && keys.every((key) => left[key] === right[key])
+	}
+	return JSON.stringify(left) === JSON.stringify(right)
+}
+
+/**
+ * The fields on which a target disagrees with the golden set.
+ *
+ * Asymmetric by design, and this is the rule that keeps a golden set from accumulating noise. A
+ * field the golden set leaves unset is never a difference, however the target fills it: a host
+ * restating its own default and a user's deliberate edit are indistinguishable in that position,
+ * and pulling both back would grow the golden set on every round-trip. The golden set speaks only
+ * about what it says.
+ *
+ * `env` and `headers` are compared per name for the same reason — a variable only the target sets
+ * is that target's business, and one the golden set names must match.
+ */
+export function divergingFields(golden: McpServer, target: McpServer): McpField[] {
+	return mcpFields.filter((field) => {
+		const declared = golden[field]
+		if (declared === undefined) return false
+		if (mapFields.has(field) && isRecord(declared) && isRecord(target[field])) {
+			const observed = target[field] as Record<string, unknown>
+			return Object.keys(declared).some((key) => declared[key] !== observed[key])
+		}
+		return !sameValue(field, declared, target[field])
+	})
+}
+
+/** Whether one field of two models agrees, for naming the side that moved. */
+export function sameField(field: McpField, left: McpServer | undefined, right: McpServer | undefined): boolean {
+	return sameValue(field, left?.[field], right?.[field])
+}

package/src/diagnose-mcp/mcp-secrets.ts

@@ -0,0 +1,101 @@
+import type { McpServer } from './mcp-model.ts'
+
+/**
+ * Finding a literal credential in MCP configuration, without ever handling one.
+ *
+ * `doctor` is safe to run from a session-start hook, so its output lands in agent context on every
+ * session and from there into transcripts. A value it echoes is amplified far past the file it came
+ * from. Every function here answers **where**, never **what**: the return is a field path, and the
+ * value never leaves this module.
+ *
+ * That is also why the redaction lives here rather than in a formatter. `doctor` renders three ways
+ * — TOON, `--format text`, and `--format json` — and trusting each of them to mask is three chances
+ * to drift. A value that never enters the finding cannot be printed by any of them.
+ */
+
+/**
+ * Words that mark a field as credential-bearing wherever they appear in its name. Each is one that
+ * effectively never turns up inside an innocent word, so a bare substring test is safe and catches
+ * the run-together spellings a segment test would miss — `MYTOKEN`, `githubsecret`.
+ */
+const credentialWord = /token|secret|password|passwd|credential/i
+
+/**
+ * Words that mark a field only when they are a **segment** of its name. `key` and `auth` are the
+ * two that matter, and both are common inside words that carry nothing — `MONKEY`, `AUTHOR`,
+ * `KEYSTONE_URL`. Matching them as substrings reports those, and a scanner that cries wolf on a
+ * hook-run command is one people stop reading.
+ */
+const credentialSegment = new Set(['key', 'apikey', 'auth', 'authorization', 'bearer'])
+
+/** A field name split the two ways these are written: `API_KEY` and `apiKey` alike. */
+function segmentsOf(key: string): string[] {
+	return key
+		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean)
+		.map((segment) => segment.toLowerCase())
+}
+
+/**
+ * A value that **names** a secret instead of holding one, in the forms the supported hosts
+ * document: `${VAR}`, `$VAR`, and the `${env:VAR}` / `${input:id}` variants.
+ *
+ * Classification is by shape, not by content. An entropy test on the value would be a guess about
+ * a string this module has already decided not to look at, and it would fail in both directions —
+ * a short password is low-entropy and a base64 configuration blob is high.
+ */
+const reference = /\$\{[^}]+\}|\$[A-Za-z_][A-Za-z0-9_]*/
+
+/**
+ * A credential-bearing field passes when it carries a reference anywhere in it, because the common
+ * legitimate form is a template rather than a bare variable — `Bearer ${LINEAR_TOKEN}` is the
+ * documented way to write an authorization header, and requiring the whole value to be a reference
+ * would report every correct one.
+ */
+function holdsLiteral(value: string): boolean {
+	return !reference.test(value)
+}
+
+function credentialKey(key: string): boolean {
+	return credentialWord.test(key) || segmentsOf(key).some((segment) => credentialSegment.has(segment))
+}
+
+/**
+ * Whether a URL carries a credential in itself. Two shapes: a password in the userinfo component,
+ * and a credential-named query parameter holding a literal. Neither value is read past the test.
+ *
+ * A URL that does not parse is not reported. It is malformed rather than leaky, and guessing at its
+ * structure with a regular expression is how a scanner starts matching the thing it must not touch.
+ */
+function urlHoldsCredential(value: string): boolean {
+	let url: URL
+	try {
+		url = new URL(value)
+	} catch {
+		return false
+	}
+	if (url.password) return true
+	for (const [key, parameter] of url.searchParams) if (credentialKey(key) && holdsLiteral(parameter)) return true
+	return false
+}
+
+function literalsIn(field: 'env' | 'headers', values: Readonly<Record<string, string>> | undefined): string[] {
+	return Object.entries(values ?? {})
+		.filter(([key, value]) => credentialKey(key) && holdsLiteral(value))
+		.map(([key]) => `${field}.${key}`)
+}
+
+/**
+ * Every field of one server holding a literal credential, as a path within that server.
+ *
+ * The path is the whole answer. It is never a truncated value: `sk-ab…` is a leak into the same
+ * transcript and buys a reader nothing the field name does not already give them.
+ */
+export function credentialFields(server: McpServer): string[] {
+	return [
+		...literalsIn('env', server.env),
+		...literalsIn('headers', server.headers),
+		...(server.url && urlHoldsCredential(server.url) ? ['url'] : []),
+	]
+}

package/src/diagnose-mcp/mcp-sources.ts

@@ -0,0 +1,131 @@
+import { parse as parseToml } from 'smol-toml'
+import { parseJsonWithComments } from '../diagnose-bridges/json-with-comments.ts'
+import type { Position } from '../diagnose-bridges/locator.ts'
+import type { McpConfig } from '../harness-registry/mcp-config.ts'
+import { isRecord } from '../is-record/is-record.ts'
+import type { McpServer, McpTransport } from './mcp-model.ts'
+
+/** Where the golden set lives, and why it is namespaced rather than sitting at `.agents/mcp.json`. */
+export const goldenSetPath = '.agents/buddy-agent-harness/mcp.toml'
+
+/** The table the golden set keeps its servers under. */
+const goldenKey = 'servers'
+
+export type ParsedServers =
+	/** The file is absent. Nothing to compare, and not a fault. */
+	| { kind: 'absent' }
+	| { kind: 'servers'; servers: Map<string, McpServer> }
+	| { kind: 'unreadable'; position?: Position | undefined }
+
+function stringMap(value: unknown): Record<string, string> | undefined {
+	if (!isRecord(value)) return undefined
+	const entries = Object.entries(value).filter(([, item]) => typeof item === 'string') as [string, string][]
+	return entries.length ? Object.fromEntries(entries) : undefined
+}
+
+const transports = new Set<string>(['stdio', 'http', 'sse'])
+
+/**
+ * The transport a host entry describes. Hosts spell it `type` (Claude Code, VS Code) or
+ * `transport`, and several state it nowhere and leave it implied by which of `url` and `command`
+ * is present. Inferring it is what lets a `url` entry in one file compare equal to a `type: http`
+ * entry in another.
+ */
+function transportOf(entry: Record<string, unknown>): McpTransport | undefined {
+	const declared = entry['type'] ?? entry['transport']
+	if (typeof declared === 'string' && transports.has(declared)) return declared as McpTransport
+	if (typeof entry['url'] === 'string') return 'http'
+	if (typeof entry['command'] === 'string') return 'stdio'
+	return undefined
+}
+
+/**
+ * One host entry, or one golden entry, in the canonical model. The two formats carry the same
+ * field names — the divergence between hosts is the file, the top-level key, and the serialization,
+ * not the entry — so one reader serves both directions of the comparison.
+ *
+ * A field whose value is the wrong type is dropped rather than carried through. A `timeout` that
+ * is a string is not a timeout, and letting it into the model would report a divergence whose real
+ * cause is a typo the finding does not name.
+ */
+function serverFrom(entry: Record<string, unknown>): McpServer {
+	const args = Array.isArray(entry['args']) && entry['args'].every((item) => typeof item === 'string')
+	const transport = transportOf(entry)
+	const env = stringMap(entry['env'])
+	const headers = stringMap(entry['headers'])
+	return {
+		...(transport ? { transport } : {}),
+		...(typeof entry['command'] === 'string' ? { command: entry['command'] } : {}),
+		...(args ? { args: entry['args'] as string[] } : {}),
+		...(env ? { env } : {}),
+		...(typeof entry['url'] === 'string' ? { url: entry['url'] } : {}),
+		...(headers ? { headers } : {}),
+		...(typeof entry['description'] === 'string' ? { description: entry['description'] } : {}),
+		...(typeof entry['enabled'] === 'boolean' ? { enabled: entry['enabled'] } : {}),
+		...(typeof entry['timeout'] === 'number' ? { timeout: entry['timeout'] } : {}),
+		...(typeof entry['source'] === 'string' ? { source: entry['source'] } : {}),
+	}
+}
+
+function serversUnder(document: unknown, key: string): Map<string, McpServer> {
+	const table = isRecord(document) ? document[key] : undefined
+	if (!isRecord(table)) return new Map()
+	return new Map(
+		Object.entries(table)
+			.filter(([, entry]) => isRecord(entry))
+			.map(([name, entry]) => [name, serverFrom(entry as Record<string, unknown>)]),
+	)
+}
+
+/**
+ * The position out of a thrown parse error, and nothing else out of it.
+ *
+ * `smol-toml` reports `line` and `column` on the error alongside a `codeblock` quoting the source,
+ * and its `message` embeds that same code block. Both are unusable: in a file of MCP configuration
+ * the line a parser failed on is exactly the line holding the credential. Only the two numbers are
+ * read, and anything thrown that does not carry them is reported without a position rather than by
+ * reaching for its message.
+ *
+ * Exported because that restriction is the point of the function rather than an implementation
+ * detail of it, and it is verified directly.
+ */
+export function positionOf(error: unknown): Position | undefined {
+	if (!isRecord(error)) return undefined
+	const { line, column } = error
+	return typeof line === 'number' && typeof column === 'number' ? { line, column } : undefined
+}
+
+/** The golden set, parsed. Absent is the common case and is not a fault. */
+export function parseGoldenSet(source: string | undefined): ParsedServers {
+	if (source === undefined) return { kind: 'absent' }
+	try {
+		return { kind: 'servers', servers: serversUnder(parseToml(source), goldenKey) }
+	} catch (error) {
+		return { kind: 'unreadable', position: positionOf(error) }
+	}
+}
+
+/**
+ * One harness's MCP configuration, parsed. The file is read for its own key and nothing else:
+ * `.gemini/settings.json` also carries the instruction bridge, and a reader that treated the whole
+ * file as MCP would report the rest of a user's settings as servers it does not recognize.
+ *
+ * JSON is parsed with comments stripped, because Gemini CLI's loader strips them too and a
+ * settings file may legally carry them.
+ */
+export function parseTarget(config: McpConfig, source: string | undefined): ParsedServers {
+	if (source === undefined) return { kind: 'absent' }
+	if (config.format === 'toml') {
+		try {
+			return { kind: 'servers', servers: serversUnder(parseToml(source), config.key) }
+		} catch {
+			return { kind: 'unreadable' }
+		}
+	}
+	const document = parseJsonWithComments(source)
+	// `parseJsonWithComments` answers `undefined` for a file that does not parse. A file whose
+	// literal content is `null` parses and holds no servers, which reads the same here and is
+	// reported the same way it would be for `{}`.
+	if (document === undefined) return { kind: 'unreadable' }
+	return { kind: 'servers', servers: serversUnder(document, config.key) }
+}

package/src/diagnose-nonstandard/diagnose-nonstandard.ts

@@ -0,0 +1,109 @@
+import { lstatSync, readFileSync } from 'node:fs'
+import { join, posix } from 'node:path'
+import { filesUnder } from '../diagnose-bridges/directory-files.ts'
+import { type NonstandardProblem, type RepairAction, repairFor } from '../diagnose-bridges/doctor-guidance.ts'
+import { harnessRegistry } from '../harness-registry/harness-registry.ts'
+import type { NonstandardArtifact, NonstandardKind } from '../harness-registry/nonstandard-artifact.ts'
+
+/**
+ * The fifth section of `doctor`: configuration that works for exactly one harness.
+ *
+ * The other four ask whether something is broken. This one asks how far what is there reaches, and
+ * reports the answer when it is "one harness". Nothing here is a fault — a Cursor rule does what it
+ * says — so nothing here is repaired by correcting it. Each finding names the canonical form it
+ * would convert to, so a repository can be walked toward one where every harness file is generated
+ * from a canonical source rather than authored beside it.
+ *
+ * Read-only, like every other part of `doctor`.
+ */
+export type NonstandardFinding = {
+	/** Repository-relative path of the artifact, POSIX-separated. */
+	path: string
+	problem: NonstandardProblem
+	detail: string
+	/** The conversion. `command` is always empty: every one of these is judgment about content. */
+	repair: RepairAction
+}
+
+export type DiagnoseNonstandardOptions = {
+	root: string
+	/** How to name this tool in the repair commands. */
+	cli: string
+}
+
+const problemOf: Record<NonstandardKind, NonstandardProblem> = {
+	instructions: 'nonstandard-instructions',
+	rule: 'nonstandard-rule',
+	command: 'nonstandard-command',
+	skill: 'nonstandard-skill',
+	subagent: 'nonstandard-subagent',
+}
+
+/**
+ * A `.mdc` rule splits on whether its scoping is load-bearing. `globs:` with a value binds the rule
+ * to paths, and `AGENTS.md` has no equivalent — it scopes by directory nesting only — so that one
+ * converts to a skill, or stays. Without it the rule is always-on prose, which `AGENTS.md` holds
+ * verbatim. Read from frontmatter rather than assumed, because the two need different conversions
+ * and guessing wrong sends prose to the wrong destination.
+ */
+function scopedByGlobs(body: string): boolean {
+	const block = /^---\n([\s\S]*?)\n---/.exec(body)
+	if (!block) return false
+	const globs = /^globs:[ \t]*(.*)$/m.exec(block[1] as string)
+	const value = globs?.[1]?.trim()
+	return value !== undefined && value.length > 0 && value !== '[]'
+}
+
+/** Every skill directory below `directory`, named by its `SKILL.md`. */
+function skillFiles(directory: string): string[] {
+	return filesUnder(directory).filter((file) => file.endsWith('SKILL.md'))
+}
+
+/**
+ * A harness directory that is a symlink is a projection someone already made, not configuration
+ * authored here — reporting it would tell a repository to convert what it already converted.
+ */
+function authoredHere(path: string): boolean {
+	try {
+		return !lstatSync(path).isSymbolicLink()
+	} catch {
+		return false
+	}
+}
+
+function artifactFiles(root: string, artifact: NonstandardArtifact): string[] {
+	const absolute = join(root, artifact.path)
+	// A path that is not there fails this too — `lstat` throws and the catch reads as "not ours".
+	if (!authoredHere(absolute)) return []
+	if (artifact.shape === 'file') return [artifact.path]
+	const below = artifact.kind === 'skill' ? skillFiles(absolute) : filesUnder(absolute)
+	return below.map((file) => posix.join(artifact.path, file))
+}
+
+/**
+ * Unlike the other detectors this takes no harness preference and no enabled set. An artifact is
+ * reachable by one harness whether or not that harness is enabled here — a `.cursorrules` in a
+ * repository nobody opens in Cursor is still instruction content `AGENTS.md` does not carry — so
+ * filtering by the enabled set would hide exactly the drift worth converting.
+ */
+export function diagnoseNonstandard({ root, cli }: DiagnoseNonstandardOptions): NonstandardFinding[] {
+	const findings: NonstandardFinding[] = []
+
+	for (const harness of harnessRegistry) {
+		for (const artifact of harness.project.nonstandard ?? []) {
+			for (const path of artifactFiles(root, artifact)) {
+				const kind =
+					artifact.kind === 'rule' && path.endsWith('.mdc') && !scopedByGlobs(readFileSync(join(root, path), 'utf8'))
+						? 'instructions'
+						: artifact.kind
+				const problem = problemOf[kind]
+				const { detail, repair } = repairFor(problem)
+				findings.push({ path, problem, detail, repair: repair({ file: path }, cli) })
+			}
+		}
+	}
+
+	// No dedupe: one artifact is declared by one harness, and `harness-registry.test.ts` holds that
+	// invariant. Collapsing a duplicate here would hide the registry mistake rather than surface it.
+	return findings.sort((left, right) => left.path.localeCompare(right.path))
+}

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

@@ -1,5 +1,8 @@
 import { lstatSync } from 'node:fs'
 import { join } from 'node:path'
+import type { InstructionBridge } from './instruction-bridge.ts'
+import type { McpConfig } from './mcp-config.ts'
+import type { NonstandardArtifact } from './nonstandard-artifact.ts'
 
 export type HarnessName =
 	| 'claude-code'
@@ -10,21 +13,67 @@ 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.
+ *
+ * `mcpConfig` is where this harness keeps its MCP servers at this scope. Unlike the other two it
+ * is not a bridge into a canonical file the harness cannot read — it is the harness's own
+ * configuration, which `doctor` compares against the golden set and never writes.
+ *
+ * `nonstandard` is what this harness reads that no other harness can. Unlike the three above it is
+ * not something the tool maintains — it is what a repository accumulated before it was canonical,
+ * and `doctor` reports it so it can be converted. Declared here because the paths are per harness
+ * and belong beside the harness's other paths, not in a second list that would drift from this one.
+ *
+ * `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
+	mcpConfig?: McpConfig
+	nonstandard?: readonly NonstandardArtifact[]
+}
+
+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,15 +82,114 @@ 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' },
+			mcpConfig: { path: '.mcp.json', key: 'mcpServers', format: 'json' },
+			nonstandard: [
+				{ path: '.claude/commands', shape: 'directory', kind: 'command' },
+				{ path: '.claude/rules', shape: 'directory', kind: 'rule' },
+				{ path: '.claude/agents', shape: 'directory', kind: 'subagent' },
+			],
+		},
+		user: { detect: '.claude', skillsDirectory: '.claude/skills' },
+	},
+	{
+		name: 'cursor',
+		project: {
+			detect: '.cursor',
+			mcpConfig: { path: '.cursor/mcp.json', key: 'mcpServers', format: 'json' },
+			nonstandard: [
+				{ path: '.cursorrules', shape: 'file', kind: 'instructions' },
+				{ path: '.cursor/rules', shape: 'directory', kind: 'rule' },
+				{ path: '.cursor/commands', shape: 'directory', kind: 'command' },
+				{ path: '.cursor/skills', shape: 'directory', kind: 'skill' },
+			],
+		},
+		user: { detect: '.cursor' },
+	},
+	{
+		name: 'codex',
+		project: {
+			detect: '.codex',
+			mcpConfig: { path: '.codex/config.toml', key: 'mcp_servers', format: 'toml' },
+			nonstandard: [{ path: '.codex/skills', shape: 'directory', kind: 'skill' }],
+		},
+		user: { detect: '.codex' },
+	},
+	{
+		name: 'copilot-cli',
+		project: {
+			detect: '.github/skills',
+			nonstandard: [
+				{ path: '.github/copilot-instructions.md', shape: 'file', kind: 'instructions' },
+				{ path: '.github/instructions', shape: 'directory', kind: 'instructions' },
+				{ path: '.github/skills', shape: 'directory', kind: 'skill' },
+			],
+		},
+		user: { detect: '.copilot' },
+	},
+	{
+		name: 'gemini-cli',
+		project: {
+			detect: '.gemini',
+			instructionBridge: { kind: 'settings-entry', path: '.gemini/settings.json', key: 'context.fileName' },
+			mcpConfig: { path: '.gemini/settings.json', key: 'mcpServers', format: 'json', shared: true },
+			nonstandard: [
+				{ path: 'GEMINI.md', shape: 'file', kind: 'instructions' },
+				{ path: '.gemini/skills', shape: 'directory', kind: 'skill' },
+			],
+		},
+		user: { detect: '.gemini' },
+	},
+	{ name: 'devin-desktop', project: { detect: '.devin' } },
+	{
+		name: 'windsurf',
+		project: {
+			detect: '.windsurf',
+			skillsDirectory: '.windsurf/skills',
+			nonstandard: [
+				{ path: '.windsurfrules', shape: 'file', kind: 'instructions' },
+				{ path: '.windsurf/rules', shape: 'directory', kind: 'rule' },
+			],
+		},
+		deprecated: 'devin-desktop',
+	},
 ]
 
+const harnessNames = new Set<string>(harnessRegistry.map((harness) => harness.name))
+
+function isHarnessName(value: string): value is HarnessName {
+	return harnessNames.has(value)
+}
+
+/**
+ * The `--harness` option, as names this registry knows. Both commands take the option and neither
+ * owns what a name means, so the parse lives beside the list it validates against: a harness added
+ * to the registry is accepted by both commands with nothing else to change, and the rejection reads
+ * the same either way.
+ *
+ * An unknown name throws rather than being dropped. A caller that asked for a harness by name and
+ * got a report about the two default ones has been told the wrong thing about their repository.
+ */
+export function parseHarnesses(value: string | undefined): HarnessName[] {
+	const requested = (value ?? '')
+		.split(',')
+		.map((name) => name.trim())
+		.filter(Boolean)
+	const unsupported = requested.filter((name) => !isHarnessName(name))
+	if (unsupported.length)
+		throw new Error(
+			`Unsupported harness: ${unsupported.join(', ')}. Supported: ${harnessRegistry
+				.map((harness) => harness.name)
+				.join(', ')}.`,
+		)
+	return requested.filter(isHarnessName)
+}
+
 /** Enabled whether or not the repository already contains their directories. */
 const defaultHarnesses: readonly HarnessName[] = ['claude-code', 'cursor']
 
@@ -56,5 +204,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
+	  }