buddy-agent-harness 0.7.0 → 0.9.0

package/skills/enhance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: enhance
-description: Use this skill when a repository already has an AGENTS.md and you want to add guidance it is missing — offering vetted sections one at a time and writing only what the user approves. Runs on its own or straight after init.
+description: Use this skill when a repository already has an AGENTS.md and you want to add guidance it is missing, or to refresh a vetted section it carries in an outdated form — offering each one at a time and writing only what the user approves. Runs on its own or straight after init.
 argument-hint: '[--root <dir>]'
 ---
 
@@ -12,11 +12,11 @@ The split matters: initialization has to run everywhere and invent nothing, so i
 
 Every addition is **offered, never written on sight**. An addition asserts something about how the repository is worked in — it stays true whether or not this tool ever ran — so it is material under the rule in `../init/references/agents-md.md`, and material content needs approval. Nothing here goes inside the `buddy-agent-harness` managed region; that region is for the tool's own bookkeeping.
 
-One addition ships today: `references/delegation.md`.
+One addition ships today: `references/delegation.md`. Each addition's reference file carries the text to offer, a `## Covered when` criterion for the subject already being present, and a `## Stale when` criterion for the file already carrying a **wording this addition has since retired**. The retired wordings themselves are kept beside it — for delegation, `references/delegation.history.md` — and are what a present section is compared against.
 
 ## 1. Find the instruction file
 
-Locate the Git repository root. The target is the root `AGENTS.md`.
+Where the invocation names `--root <dir>`, that directory is the repository: read and write inside it only. Otherwise locate the Git repository root. The target is the root `AGENTS.md`.
 
 If there is no root `AGENTS.md`, stop and say so. This skill adds to an existing file; creating one is `init`'s job, so point there and write nothing.
 
@@ -30,9 +30,9 @@ Judge against all of it together. That combined text is what an agent effectivel
 
 **Read those files; do not consolidate them.** Merging them into `AGENTS.md` is `init`'s work and belongs to `init` alone. If you find content that should be consolidated, say so and recommend `init` — then carry on with the coverage judgment.
 
-## 3. Judge coverage
+## 3. Classify each addition
 
-For each addition, ask: **does the merged view already tell the agent what this addition would tell it?**
+Ask the coverage question first: **does the merged view already tell the agent what this addition would tell it?**
 
 Judge by meaning, not by heading or wording. A repository covering delegation under `## Working with subagents`, or in three sentences inside a longer section, is covered. A repository that mentions subagents only to name a tool is not.
 
@@ -40,28 +40,72 @@ When in doubt, treat it as covered and say why. A missing offer costs the user n
 
 **A heading inside a fenced code block is not a heading.** Text between ``` or ~~~ fences is an example of a file, not part of this one, and an addition quoted inside a fence is being shown rather than adopted. This is not hypothetical: every addition here is offered as a fenced block containing its own heading, so a repository documenting this tool — or an `AGENTS.md` that quotes one — carries the exact heading the addition would write, inside a fence, while remaining entirely uncovered. Judge only the prose the agent actually reads as instruction.
 
+Then ask the second question **of text that read as covered, and only of that text**: did that text come from this addition, at a version it used to ship? Never ask it of text that read as uncovered, and never ask it first.
+
+Answer it against the addition's own texts, which its reference keeps beside it: the one it offers now, and the ones it has retired, in a sibling history file. The reference states how under `## Stale when`.
+
+**First, is the section already current?** It is when it carries every sentence of the text you would offer, in order — the owner may have added paragraphs of their own around or between them — and asserts no sentence found only in a retired wording. Say so and stop. Resemblance is not enough; containment is the test.
+
+**Otherwise, compare against the retired wordings, and never weigh a section against the current text to decide it is stale** — differing from the current wording tells you nothing, since differing is what a rewrite produces.
+
+Each addition ends this step in one of five states:
+
+- **already current** — the section carries the text you would offer. Offer nothing, and say that is why. Do **not** report it as the owner's own: they did not write it, this package did, and telling someone they authored your text is the same mistake as replacing what they did author.
+- **absent** — offer it as an addition.
+- **from a retired wording, in the root `AGENTS.md`** — offer the current text as a replacement.
+- **the owner's own** — offer nothing, and name what covers it.
+- **you cannot tell** — do not decide it either way. Put it to the owner (step 4).
+
+A section from a retired wording in a file that is **not** the root `AGENTS.md` — a `CLAUDE.md`, a `.cursorrules` — is reported by name and offered nothing. This skill writes one file; replacing the root copy while an older copy stays in a harness file leaves the repository holding two versions instead of one. Recommend `init` and carry on.
+
 ## 4. Offer
 
-Where an addition is uncovered, show its text **verbatim** — the whole thing, not a summary — say where it would go, and ask.
+Where an addition is **absent**, show its text **verbatim** — the whole thing, not a summary — say where it would go, and ask.
+
+Where an addition came from a **retired wording**, show the section as it stands in `AGENTS.md`, then the current text **verbatim**, say that it would replace that section and nothing else, and ask.
+
+**Name what the replacement would take with it.** A stale section often carries paragraphs the owner added to it — rules of their own, sitting under the same heading. Replacing the section removes those too. So before you ask, name every paragraph in that section that appears in no retired wording, say the replacement would remove it, and let the owner weigh that. An approval given for "refresh the wording" is not an approval to delete what they wrote.
 
-Do not argue for it past one sentence. The user is reading the actual text; that is the argument.
+Where you **cannot tell**, say that first, in those words. Then show three texts — the section as it stands, the retired wording it partly tracks, and the current text — and put three answers to the owner:
+
+- **it is theirs** — you leave it alone.
+- **it came from here** — you offer the replacement.
+- **settle it by measurement instead** — score both wordings and go with what wins.
+
+Put the third every time the repository can actually do it, because the owner may not remember either, and the question they care about is not where the section came from but **which wording serves them better**. Provenance is a stand-in for that; when the stand-in fails, ask the real question.
+
+Measurement means running each wording against a set of real tasks and comparing how the agent behaves — whatever harness this repository has for that. In this package's own repository it is the `eval-delegation` skill; a consumer repository will have its own or none. **Look before you offer it.** Where the repository has no such harness, say the third answer would need one it does not have, and put the other two.
+
+**Ask before running it, and never run it unasked** — it is many model runs, and the owner is the one paying for them.
+
+Where the owner asks for it, run it over the section as it stands and the current text, and report both scores.
+
+- The current text scores **better** — offer it as a replacement, on that basis and not on provenance. Say what it scored. The offer is an offer like any other: it still waits for a yes.
+- The section scores **as well or better** — offer nothing, say so, and leave it alone. A wording that serves this repository better than ours is not something to replace, whatever its history.
+
+Do not argue for any of it past one sentence. The user is reading the actual text; that is the argument.
 
 ## 5. Write what was approved
 
-On approval, append the section to the root `AGENTS.md`, outside the managed region, preserving the surrounding file exactly.
+On approval of an **addition**, write the section into the root `AGENTS.md` at the end of the owner's prose, outside the managed region, preserving the surrounding file exactly.
+
+On approval of a **replacement**, replace that one section in place — from its heading through to the next heading of the same or higher level — and leave every other byte of the file as it was. Do not relocate it, do not reformat around it, and do not touch the managed region.
 
 Strip the fence when you write. The ``` markers around the addition in its reference file are there so you can see where the text begins and ends; the section goes into `AGENTS.md` as prose, not as a code block.
 
-On a decline, write nothing.
+On a decline, write nothing. A declined replacement leaves the section exactly where it stands, and so does an unanswered question.
 
 ## 6. Report
 
-Report every run, whichever way it went: what you read, what you judged covered and why, what you offered, and what was written. A run that offers nothing still reports — that is the only way the user can tell "already covered" from "did not look".
+Report every run, whichever way it went: what you read, the verdict for each addition and why — already current, absent, the owner's own, from a retired wording, or undecidable — what you offered, and what was written. A run that offers nothing still reports — that is the only way the user can tell "already covered" from "did not look".
 
 ## Rules
 
 - **Detection decides every run.** There is no first-run path and no memory of a previous decline; run the same way every time. A section the user deleted reads as absent and is offered again, because absence is the whole state. If that becomes annoying, the fix is the user declining `init`'s offer to run this skill, not a flag here.
 - **Never write without approval.** The offer is the whole point.
+- **Never silently overwrite.** A replacement is an offer like any other; the same gate that governs an addition governs it, word for word.
+- **Never guess whose words they are.** Where you cannot tell an edited copy of a retired wording from the owner's own prose, say so and ask. Deciding it silently in either direction is the one failure this path exists to avoid.
+- **Never run an evaluation unasked.** It costs the owner many model runs. Offer it; wait.
 - **Never edit an addition to fit a repository.** The wording is fixed. Offer it as written or not at all.
 - **Never touch the managed region**, a nested `AGENTS.md`, or any file other than the root `AGENTS.md`.
 - Local agent configuration only. Do not change workflows, repository settings, or unrelated project files.

package/skills/enhance/references/delegation.history.md

@@ -0,0 +1,15 @@
+# Superseded wordings: Delegation
+
+Every wording this addition has retired, newest first, each exactly as it was offered. Read this
+file when a `## Delegation` section is already present and reads as covered; it is what the section
+in front of you is compared against.
+
+Nothing here is ever offered. The text to offer is in `delegation.md`.
+
+## Superseded 2026-09 — replaced by the current two-paragraph wording
+
+```markdown
+## Delegation
+
+If this harness can spawn subagents, delegate bulk-mechanical work and research whose answer is far smaller than the reading behind it. Do it yourself when the brief would cost more than the task — a one-line edit is not worth a subagent. Keep the judgment calls and final decisions; delegate the fact-gathering that feeds them. The cheaper the subagent, the less should break if it gets the answer wrong. Brief every one you spawn: it inherits no context, so give it the context, the why, and what done looks like.
+```

package/skills/enhance/references/delegation.md

@@ -11,12 +11,67 @@ The merged view already tells the agent **when to hand work to a subagent**. Any
 Naming a subagent tool, or listing available models, is not coverage. Neither is a delegation
 rule that appears only in a skill body — this addition is for the always-loaded file.
 
+## Stale when
+
+**First: is the section already current?** It is when it carries every sentence of the text below, in
+its order — the owner may have added paragraphs of their own around or between them, and those are
+theirs to keep — **and** asserts no sentence found only in a retired wording. Offer nothing, compare it
+against no retired wording, and report it as **already current**, not as the owner's own: this package
+wrote that text, and saying otherwise credits them with it.
+
+Containment, not resemblance. A section that carries the current text but also still asserts a
+retired sentence is holding two versions at once, and is not current: go on to the two questions.
+
+Otherwise, compare the `## Delegation` section already in the file against each wording in
+`delegation.history.md`. Those are the exact texts this addition used to offer. Ask two questions
+about the section, and only these two:
+
+1. **Do whole sentences of that wording survive verbatim in it?** Not a phrase — a whole sentence.
+2. **Does that wording's structure survive?** Its sentences, in its order, each doing its job.
+
+**Both questions answer yes or no, never neither** — where you cannot tell whether a sentence
+survives, or whether the structure does, the answer is **no**. That is what keeps the four cases
+below exhaustive.
+
+**When the two answers agree, they decide. When they disagree, you cannot tell.**
+
+| whole sentences | structure | |
+| --- | --- | --- |
+| yes | yes | **Stale.** It is that wording, edited. Offer the replacement. |
+| no | no | **The owner's.** Written from scratch. Offer nothing. |
+| yes | no | **You cannot tell.** A line of ours carried into prose they wrote — or a line they reached themselves. |
+| no | yes | **You cannot tell.** Their words in our shape — a reword of ours, or the order the subject naturally takes. |
+
+The two disagreeing cases are not a gap in the test; they are the test reporting honestly that the
+evidence points both ways. Say so, show the owner the three texts, and ask. **Do not decide them.**
+
+Match a sentence literally. A shared idea is not a sentence surviving, and a paraphrase of one is not
+that sentence — a whole passage does not turn up in prose someone wrote themselves, which is what
+makes question 1 worth asking; a memorable phrase does, which is why no phrase answers it.
+
+**A quoted sentence is not an asserted one, and does not count for question 1.** A sentence inside quotation marks, inside a fence, or in
+a sentence that disputes it is being *shown*, not followed — the same rule that makes a heading inside
+a fenced block not a heading. A section that quotes one in order to reject it is the owner arguing
+with this package, which is the strongest sign the prose is theirs.
+
+Once both answers are yes, offer the replacement. Do **not** then read the section's remaining
+sentences against the current text and reconsider — that comparison always finds differences, because
+differing sentences are what a rewrite is. That applies to the section's other prose only. It
+licenses nothing about the two questions, which are answered exactly as written.
+
+**Do not shortcut any of this on the subject a section talks about.** A section that mentions what
+model a subagent inherits, or picking one, is not thereby the current wording — anyone can write a
+sentence about choosing a model, including on top of a wording retired long ago. Only the two
+questions decide, and they decide against the texts themselves.
+
 ## Offer this text verbatim
 
 ```markdown
 ## Delegation
 
-If this harness can spawn subagents, delegate bulk-mechanical work and research whose answer is far smaller than the reading behind it. Do it yourself when the brief would cost more than the task — a one-line edit is not worth a subagent. Keep the judgment calls and final decisions; delegate the fact-gathering that feeds them. The cheaper the subagent, the less should break if it gets the answer wrong. Brief every one you spawn: it inherits no context, so give it the context, the why, and what done looks like.
+If this harness can spawn subagents, delegate the mechanical work and the research whose answer is far smaller than the reading behind it. Keep the judgment calls and the decisions; anything you would finish in less time than briefing it takes, do yourself.
+
+A subagent inherits your model if you do not pick one, and none of your context either way. Pick the cheapest, unless you cannot say what a right answer looks like or could not cheaply tell a wrong one. Give it the context, the why, and what done looks like.
 ```
 
 ## Do not edit it
@@ -25,4 +80,14 @@ The wording is fixed. In particular, do not add model names, tiers, or a table o
 section is written to stay correct as model lineups change, and naming one breaks that. Offer it
 as written or not at all.
 
+If the text is ever revised, the same change must do two things:
+
+- append the outgoing wording to `delegation.history.md`, newest first, exactly as it was offered;
+- add scenarios for the **shape of that revision** — which sentences the new text rewrote, dropped or
+  added against the outgoing one — and pass the gate against the new pair.
+
+The comparison above is checked against the wordings that exist, not against every revision someone
+might one day make. How a sentence-level comparison behaves depends on how the two texts differ, so a
+revision is the moment its behaviour is known and the moment it is verified.
+
 Place it at the end of the user's prose, outside the `buddy-agent-harness` managed region.

package/skills/init/SKILL.md

@@ -75,7 +75,7 @@ One case does need asking even though it only creates a file: a nested `AGENTS.m
 2. Move approved skills and commands to `.agents/skills/<name>/SKILL.md`, preferring `git mv` so history follows. Fix frontmatter per `references/frontmatter.md` — this is where cross-harness portability is won or lost.
 3. Merge approved instruction content into `AGENTS.md`, preserving the author's wording. Append; do not restructure. Replace a harness file with a pointer only where approved. Content only some tasks need belongs in a skill, not in `AGENTS.md`.
 4. Apply the conversions that were approved, one at a time, and nothing else from the list. A rule approved as a skill moves to `.agents/skills/<name>/SKILL.md` with frontmatter per `references/frontmatter.md`; instruction content approved for consolidation is appended as in the step above and its harness file left as a generated copy. Everything declined, and everything with no candidate, stays exactly where it is.
-5. Run `node scripts/init.mjs` at the repository root, resolving that path against this skill's own directory. The launcher runs the CLI that shipped beside it, so nothing is downloaded; fall back to `npx -y buddy-agent-harness@^0.7.0 init` when the path cannot be resolved. It links `.agents/skills` into the harnesses that need it and skips those that read it natively. Add harnesses the user names with `--harness codex,gemini-cli`.
+5. Run `node scripts/init.mjs` at the repository root, resolving that path against this skill's own directory. The launcher runs the CLI that shipped beside it, so nothing is downloaded; fall back to `npx -y buddy-agent-harness@^0.9.0 init` when the path cannot be resolved. It links `.agents/skills` into the harnesses that need it and skips those that read it natively. Add harnesses the user names with `--harness codex,gemini-cli`.
 6. If the command reports a conflict, resolve the named target and retry. Pass the target to `--force` — `--force .claude/skills` replaces that projection and reports any other conflict untouched, where a bare `--force` replaces every conflicting target at once. Reach for the bare form only when replacing all of them is what you came for. Use `--copy` only where links are unavailable — a copy is a snapshot, not a live projection, so say so when you fall back.
 7. Apply the instruction bridges `init` does not write. Claude Code reads `CLAUDE.md`, not `AGENTS.md` — create a `CLAUDE.md` containing `@AGENTS.md`. Gemini CLI needs `AGENTS.md` added to `context.fileName` in `.gemini/settings.json`. Both are detailed in the matching `references/harnesses/<harness>.md`; apply only the ones you enabled. Where nested `AGENTS.md` files exist, write the same stub in each directory holding one — `references/agents-md.md` covers the one case that stops for approval first.
 8. If any bridge now exists, write or restore the non-material region in `AGENTS.md` per `references/agents-md.md`, unless the markers are present and empty. Without it, an agent asked to change a skill edits `.claude/skills/<name>/SKILL.md` — which a link resolves back to canonical, but a copy silently forks. Skip this when every enabled harness reads `.agents/skills/` natively; with no bridge there is nothing to warn about.

package/src/cli.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { cli, exitCodes } from 'clibuilder'
+import { depPluginsCommand } from './dep-plugins/dep-plugins.command.ts'
 import { doctorCommand } from './diagnose-bridges/doctor.command.ts'
 import { initCommand } from './initialize-harnesses/init.command.ts'
 
@@ -24,6 +25,7 @@ function app() {
 	})
 		.command(initCommand)
 		.command(doctorCommand)
+		.command(depPluginsCommand)
 }
 
 /**

package/src/dep-plugins/dep-plugins.command.ts

@@ -0,0 +1,168 @@
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+import type { cli } from 'clibuilder'
+import { command, exitCodes, z } from 'clibuilder'
+import { parseFormat, writeResult } from '../command-output/command-output.ts'
+import { CATALOG_DIR, CATALOG_PATH, catalogStatus, deriveCatalog, type WriteOutcome, writeCatalog } from './generate.ts'
+import { COPILOT_LIMITATION, type PluginRuntime, runtimes } from './harness-plugins.ts'
+import { type Action, reconcile } from './reconcile.ts'
+
+export type DepPluginsReport = {
+	catalog: string
+	marketplace: string
+	outcome: WriteOutcome | 'would-change' | 'current'
+	/** Always emitted, so a healthy run states its zero rather than leaving a reader to infer it. */
+	plugins: { name: string; package: string; version: string }[] | string
+	/** Every runtime detected on this machine, and whether it matches the catalog. */
+	harness: { runtime: string; status: string }[] | string
+	/**
+	 * What each runtime needs in order to match the catalog, and the command that does it. Reported
+	 * rather than run: this writes outside the repository, and a generation step should not reach into
+	 * a developer's harness state without being asked.
+	 *
+	 * One flat row per action rather than actions nested under each runtime: a uniform record renders
+	 * as a table in both TOON and text, where a nested array collapses into a JSON blob.
+	 */
+	actions: { runtime: string; do: string; subject: string; why: string }[] | string
+	notes?: string[]
+	help?: string[]
+}
+
+/** The command that performs one action, so a reader is not left to look the verb up per runtime. */
+function commandFor(runtime: PluginRuntime, action: Action, marketplace: string): string {
+	switch (action.kind) {
+		case 'register':
+			return runtime.register(CATALOG_DIR)
+		case 'install':
+			return runtime.install(action.subject)
+		case 'update': {
+			// Where a runtime caches the catalog it has to be refreshed first, or the update reinstalls
+			// the version already cached rather than the one the catalog now pins. Codex re-reads a local
+			// catalog on every add and needs no such step, so it declares no refresh command.
+			const refresh = runtime.refreshMarketplace(marketplace)
+			const update = runtime.update(action.subject)
+			return refresh ? `${refresh} && ${update}` : update
+		}
+		case 'uninstall':
+			return runtime.uninstall(action.subject)
+	}
+}
+
+/**
+ * Notes name the conditions a caller cannot see from the entry list and would otherwise discover as a
+ * failure later — a dependency that is declared but absent, a marketplace name two repositories are
+ * likely to share, a resolver under which no dependency has a directory at all.
+ */
+function notesFor(derived: ReturnType<typeof deriveCatalog>): string[] {
+	const notes: string[] = []
+	if (derived.pnp) {
+		notes.push(
+			'Yarn Plug’n’Play is active: dependencies live inside zip archives, so no harness can install from them. Set nodeLinker: node-modules, or unplug the plugin dependencies.',
+		)
+	}
+	if (derived.genericName) {
+		notes.push(
+			`Marketplace name "${derived.catalog.name}" is generic. Registering a second marketplace under a name already in use replaces the first silently, and the install that follows reports "already installed" — the repository then runs the other one's versions.`,
+		)
+	}
+	for (const { package: pkg } of derived.unresolved) {
+		notes.push(`Declared dependency "${pkg}" is not installed; install dependencies before generating.`)
+	}
+	return notes
+}
+
+export const depPluginsCommand: cli.Command = command({
+	name: 'dep-plugins',
+	description:
+		'Derive the marketplace catalog for plugins shipped by this repository’s dependencies, so a harness can install them. Writes the catalog; installing is the harness’s own job.',
+	options: {
+		root: {
+			description: 'Repository directory. Defaults to the current directory.',
+			type: z.optional(z.string()),
+		},
+		check: {
+			description: 'Report whether the catalog is current without writing it. For CI and postinstall.',
+			type: z.optional(z.boolean()),
+		},
+		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 root = args.root ?? process.cwd()
+			const derived = deriveCatalog(root)
+
+			// `--check` compares without touching the disk, so it is safe from a postinstall hook and from
+			// CI, where the question is only whether the committed catalog still matches the declared
+			// dependencies.
+			const outcome = args.check
+				? catalogStatus(root, derived.catalog) === 'unchanged'
+					? ('current' as const)
+					: ('would-change' as const)
+				: writeCatalog(root, derived.catalog)
+
+			// Read-only, and against each harness's own state files rather than its CLI: asking a runtime
+			// what it has should not depend on that runtime being launchable from here. Only runtimes
+			// actually set up on this machine are reported, so a report names work a reader can do.
+			const home = homedir()
+			const notes = notesFor(derived)
+			const detected = runtimes.filter((candidate) => candidate.present(home))
+			const harness: { runtime: string; status: string }[] = []
+			const actions: { runtime: string; do: string; subject: string; why: string }[] = []
+
+			for (const runtime of detected) {
+				const state = runtime.state(home)
+				const delta = reconcile({
+					catalog: derived.catalog,
+					catalogDir: CATALOG_DIR,
+					root: resolve(root),
+					installed: state.installed,
+					marketplaces: state.marketplaces,
+					scoped: runtime.scoped,
+				})
+				if (delta.collision) {
+					notes.push(
+						`${runtime.name}: marketplace "${derived.catalog.name}" is already registered against ${delta.collision}. Registering over it replaces the other repository's silently, and the install that follows reports "already installed" — rename this repository's marketplace instead.`,
+					)
+				}
+				harness.push({
+					runtime: runtime.name,
+					status: delta.actions.length ? `${delta.actions.length} to apply` : 'in sync',
+				})
+				for (const action of delta.actions) {
+					actions.push({
+						runtime: runtime.name,
+						do: commandFor(runtime, action, derived.catalog.name),
+						subject: action.subject,
+						why: action.detail,
+					})
+				}
+			}
+			if (derived.plugins.length) notes.push(COPILOT_LIMITATION)
+
+			const report: DepPluginsReport = {
+				catalog: CATALOG_PATH,
+				marketplace: derived.catalog.name,
+				outcome,
+				plugins: derived.plugins.length
+					? derived.plugins.map(({ plugin, package: pkg, version }) => ({ name: plugin, package: pkg, version }))
+					: '0 dependencies ship a plugin — nothing to install',
+				harness: harness.length ? harness : 'no supported harness detected on this machine',
+				actions: actions.length ? actions : '0 actions — every detected harness matches the catalog',
+				...(notes.length ? { notes } : {}),
+			}
+			writeResult(report, format)
+
+			// A stale catalog under `--check` is the one failure this command reports through its exit
+			// code, because that is the whole question the flag asks. Everything else the report carries.
+			return outcome === 'would-change' ? exitCodes.error : exitCodes.success
+		} catch (error) {
+			process.stderr.write(`error: ${error instanceof Error ? error.message : 'Catalog generation failed.'}\n`)
+			return exitCodes.error
+		}
+	},
+})

package/src/dep-plugins/dep-plugins.ts

@@ -0,0 +1,131 @@
+/**
+ * Dependency-provided plugins: the catalog half.
+ *
+ * A dependency that ships an Agent Plugins manifest at its package root is a plugin the consuming
+ * repository can install through its harness. This module turns the set of such dependencies into a
+ * marketplace catalog; installing from that catalog is the runtime's own job, and the lifecycle half
+ * drives it.
+ *
+ * Everything here is pure. Resolution against `node_modules` lives in `resolve.ts`.
+ */
+
+/** One dependency that ships a plugin manifest. */
+export type DepPlugin = {
+	/** The npm package name — what a consumer declared, and what the catalog installs by. */
+	package: string
+	/** The plugin's own name from its manifest, which need not match the package name. */
+	plugin: string
+	/** The version actually installed, read from the dependency's own `package.json`. */
+	version: string
+	description?: string
+}
+
+/**
+ * A catalog entry's `npm` source. Deliberately not a path: a path source is resolved against the
+ * marketplace root and may not escape it, so a path-sourced catalog would have to sit at the
+ * repository root — the one place the repository's own public catalog already occupies. An `npm`
+ * source carries no path, so this catalog can live in its own directory and stay separate from
+ * whatever the repository publishes for its own consumers.
+ */
+export type NpmSource = {
+	source: 'npm'
+	package: string
+	version: string
+}
+
+export type CatalogEntry = {
+	name: string
+	source: NpmSource
+	description?: string
+}
+
+/**
+ * The Claude-shaped catalog, which Codex, Copilot CLI, and Cursor also read. `owner` is an object
+ * whose `name` is required — a string there is a schema error rather than a tolerated shorthand.
+ */
+export type Catalog = {
+	name: string
+	owner: { name: string }
+	description: string
+	plugins: CatalogEntry[]
+}
+
+/**
+ * Marketplace names generic enough that two repositories are likely to pick the same one. The
+ * collision is silent and costly: registering a second marketplace under a name already in use
+ * replaces the first, and the install that follows reports "already installed" and does nothing —
+ * so the repository silently runs the other one's plugin versions.
+ */
+const GENERIC_NAMES = new Set(['deps', 'dependencies', 'local', 'plugins', 'marketplace', 'plugin', 'default'])
+
+export function isGenericName(name: string): boolean {
+	return GENERIC_NAMES.has(name.toLowerCase())
+}
+
+/**
+ * A marketplace name derived from the consuming package's own name, so two repositories do not
+ * collide by default. A scope is folded into the name rather than dropped (`@acme/web` → `acme-web`)
+ * because the unscoped half is the part most likely to repeat across organizations.
+ */
+export function marketplaceName(packageName: string): string {
+	const folded = packageName.replace(/^@/, '').replace(/\//g, '-')
+	const cleaned = folded
+		.replace(/[^a-zA-Z0-9-_.]/g, '-')
+		.replace(/-+/g, '-')
+		.replace(/^-|-$/g, '')
+	return cleaned || 'agent-plugins'
+}
+
+/**
+ * Dependency names a repository declares, both runtime and development.
+ *
+ * Development dependencies are included on purpose: a plugin that supplies a project's testing or
+ * release workflow is a development dependency, and excluding them would drop most of the cases this
+ * exists for. Transitive dependencies are never included — see `resolve.ts`.
+ */
+export function declaredDependencies(manifest: unknown): string[] {
+	if (!manifest || typeof manifest !== 'object') return []
+	const record = manifest as Record<string, unknown>
+	const names = new Set<string>()
+	for (const field of ['dependencies', 'devDependencies']) {
+		const group = record[field]
+		if (!group || typeof group !== 'object') continue
+		for (const name of Object.keys(group as Record<string, unknown>)) names.add(name)
+	}
+	return [...names].sort()
+}
+
+export type BuildCatalogOptions = {
+	name: string
+	owner: string
+	plugins: readonly DepPlugin[]
+}
+
+/**
+ * The catalog is derived in full on every run and never merged into what is already on disk. That is
+ * what makes the three cases a consumer cares about — a plugin added, a plugin removed, a version
+ * moved — fall out of regeneration instead of needing reconciliation logic of their own.
+ *
+ * Entries are sorted by name so that a regeneration whose inputs did not change produces a
+ * byte-identical file, which is what lets a check mode compare rather than interpret.
+ */
+export function buildCatalog({ name, owner, plugins }: BuildCatalogOptions): Catalog {
+	const entries = [...plugins]
+		.sort((a, b) => a.plugin.localeCompare(b.plugin))
+		.map(({ plugin, package: pkg, version, description }): CatalogEntry => {
+			const source: NpmSource = { source: 'npm', package: pkg, version }
+			return description ? { name: plugin, source, description } : { name: plugin, source }
+		})
+
+	return {
+		name,
+		owner: { name: owner },
+		description: 'Plugins provided by this repository’s dependencies. Generated — do not edit.',
+		plugins: entries,
+	}
+}
+
+/** Serialized the way the repository formats JSON, with the trailing newline a text file needs. */
+export function serializeCatalog(catalog: Catalog): string {
+	return `${JSON.stringify(catalog, null, '\t')}\n`
+}