agents.yaml 0.1.0

package/AGENTS.md

@@ -0,0 +1,20 @@
+# agents.yaml CLI Guidance
+
+This package provides the `agents` CLI for maintaining an `agents.yaml` file.
+
+`agents.yaml` is a curated table of contents for active agent-readable documentation. It does not define a new instruction language, replace `AGENTS.md`, or automatically load every dependency document.
+
+The file format is intentionally small:
+
+```yaml
+version: 1
+
+documents:
+  - path: ./node_modules/example-package/AGENTS.md
+```
+
+Agents should treat only the paths listed in `documents` as active supplemental guidance for the project.
+
+The CLI can help discover package and local `AGENTS.md` files, add selected paths to `agents.yaml`, remove paths, initialize the root breadcrumb, and validate that referenced files still exist.
+
+Discovery only considers direct dependencies under a project's `node_modules`; nested dependency `AGENTS.md` files are not automatically activated.

package/README.md

@@ -0,0 +1,41 @@
+# agents.yaml
+
+A lightweight CLI for discovering and curating agent-readable documentation.
+
+`agents.yaml` is a curated table of contents. It points agents at dependency-specific and supplemental `AGENTS.md` documents without copying, flattening, or auto-loading every file in a dependency tree.
+
+## Install
+
+```sh
+mise install
+pnpm install
+pnpm run build
+```
+
+## Usage
+
+```sh
+agents init
+agents discover
+agents add ./node_modules/react/AGENTS.md
+agents validate
+```
+
+Run `agents` with no command for the interactive flow.
+
+## File Format
+
+```yaml
+version: 1
+
+documents:
+  - path: ./node_modules/react/AGENTS.md
+```
+
+Add this breadcrumb to your root `AGENTS.md`:
+
+```md
+For dependency-specific and supplemental guidance, consult `./agents.yaml`.
+
+Only the documents listed there should be considered active external guidance for this project.
+```

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/index.mjs

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+import * as clack from "@clack/prompts";
+import { access, opendir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import * as YAML from "yaml";
+import { z } from "zod";
+//#region src/paths.ts
+function cwd() {
+	return process.cwd();
+}
+function resolveFromRoot(root, input) {
+	return path.isAbsolute(input) ? path.normalize(input) : path.resolve(root, input);
+}
+function formatProjectPath(root, target) {
+	const relative = path.relative(root, target).split(path.sep).join(path.posix.sep);
+	if (relative.startsWith("..")) return target;
+	return relative.startsWith(".") ? relative : `./${relative}`;
+}
+//#endregion
+//#region src/agents-file.ts
+const fileSchema = z.object({
+	version: z.literal(1),
+	documents: z.array(z.object({ path: z.string().min(1) }))
+});
+const breadcrumb = `For dependency-specific and supplemental guidance, consult \`./agents.yaml\`.
+
+Only the documents listed there should be considered active external guidance for this project.`;
+async function loadAgentsFile(root) {
+	const filePath = agentsPath(root);
+	try {
+		const source = await readFile(filePath, "utf8");
+		const parsed = YAML.parse(source);
+		return fileSchema.parse(parsed);
+	} catch (error) {
+		if (isNotFound(error)) return {
+			version: 1,
+			documents: []
+		};
+		if (error instanceof z.ZodError) throw new Error(`Invalid agents.yaml: ${error.issues.map((issue) => issue.message).join(", ")}`);
+		throw error;
+	}
+}
+async function saveAgentsFile(root, file) {
+	const normalized = {
+		version: file.version,
+		documents: file.documents.map((doc) => ({ path: doc.path }))
+	};
+	await writeFile(agentsPath(root), YAML.stringify(normalized, { lineWidth: 0 }), "utf8");
+}
+async function addDocuments(root, documents) {
+	const file = await loadAgentsFile(root);
+	const byPath = new Map(file.documents.map((doc) => [doc.path, doc]));
+	for (const document of documents) byPath.set(document.path, document);
+	const next = {
+		version: 1,
+		documents: [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path))
+	};
+	await saveAgentsFile(root, next);
+	return next;
+}
+async function removeDocuments(root, paths) {
+	const file = await loadAgentsFile(root);
+	const pathSet = new Set(paths);
+	const removed = [];
+	const next = {
+		version: 1,
+		documents: file.documents.filter((doc) => {
+			if (pathSet.has(doc.path)) {
+				removed.push(doc.path);
+				return false;
+			}
+			return true;
+		})
+	};
+	await saveAgentsFile(root, next);
+	return {
+		file: next,
+		removed
+	};
+}
+async function validateAgentsFile(root) {
+	const errors = [];
+	const warnings = [];
+	let file;
+	try {
+		file = await loadAgentsFile(root);
+	} catch (error) {
+		return {
+			ok: false,
+			errors: [error instanceof Error ? error.message : String(error)],
+			warnings
+		};
+	}
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, document] of file.documents.entries()) {
+		const label = `documents[${index}] ${document.path}`;
+		if (seen.has(document.path)) errors.push(`${label}: duplicate path`);
+		seen.add(document.path);
+		if (path.basename(document.path) !== "AGENTS.md") warnings.push(`${label}: path does not end with AGENTS.md`);
+		try {
+			await access(resolveFromRoot(root, document.path));
+		} catch {
+			errors.push(`${label}: file does not exist`);
+		}
+	}
+	try {
+		const source = await readFile(path.join(root, "AGENTS.md"), "utf8");
+		if (!source.includes("./agents.yaml") && !source.includes("agents.yaml")) warnings.push("AGENTS.md does not mention agents.yaml");
+	} catch {
+		warnings.push("AGENTS.md is missing the agents.yaml breadcrumb");
+	}
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+async function initProject(root, options) {
+	const messages = [];
+	try {
+		await access(agentsPath(root));
+		messages.push("agents.yaml already exists");
+	} catch {
+		await saveAgentsFile(root, {
+			version: 1,
+			documents: []
+		});
+		messages.push("created agents.yaml");
+	}
+	const projectAgentsPath = path.join(root, "AGENTS.md");
+	try {
+		const source = await readFile(projectAgentsPath, "utf8");
+		if (source.includes("agents.yaml") && !options.force) {
+			messages.push("AGENTS.md already mentions agents.yaml");
+			return { messages };
+		}
+		await writeFile(projectAgentsPath, source.trimEnd().length === 0 ? `# Project Instructions\n\n${breadcrumb}\n` : `${source.trimEnd()}\n\n${breadcrumb}\n`, "utf8");
+		messages.push("updated AGENTS.md");
+	} catch (error) {
+		if (!isNotFound(error)) throw error;
+		await writeFile(projectAgentsPath, `# Project Instructions\n\n${breadcrumb}\n`, "utf8");
+		messages.push("created AGENTS.md");
+	}
+	return { messages };
+}
+function agentsPath(root) {
+	return path.join(root, "agents.yaml");
+}
+function isNotFound(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+//#region src/discover.ts
+const skippedDirectories = new Set([
+	".git",
+	".hg",
+	".svn",
+	".turbo",
+	".next",
+	"coverage",
+	"dist",
+	"build"
+]);
+async function discoverAgentDocuments(root) {
+	const found = [];
+	await walk(root, root, found);
+	return found.filter((document) => document.path !== "./AGENTS.md").sort((left, right) => left.path.localeCompare(right.path));
+}
+async function walk(root, directory, found) {
+	let handle;
+	try {
+		handle = await opendir(directory);
+	} catch {
+		return;
+	}
+	for await (const entry of handle) {
+		const absolutePath = path.join(directory, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name === "node_modules") {
+				await scanDirectNodeModules(root, absolutePath, found);
+				continue;
+			}
+			if (!skippedDirectories.has(entry.name)) await walk(root, absolutePath, found);
+			continue;
+		}
+		if (entry.isFile() && entry.name === "AGENTS.md") found.push({ path: formatProjectPath(root, absolutePath) });
+	}
+}
+async function scanDirectNodeModules(root, nodeModulesPath, found) {
+	let handle;
+	try {
+		handle = await opendir(nodeModulesPath);
+	} catch {
+		return;
+	}
+	for await (const entry of handle) {
+		if (!entry.isDirectory() && !entry.isSymbolicLink() || entry.name.startsWith(".")) continue;
+		const packagePath = path.join(nodeModulesPath, entry.name);
+		if (entry.name.startsWith("@")) {
+			await scanScopedPackages(root, packagePath, found);
+			continue;
+		}
+		await addPackageAgentsDocument(root, packagePath, found);
+	}
+}
+async function scanScopedPackages(root, scopePath, found) {
+	let handle;
+	try {
+		handle = await opendir(scopePath);
+	} catch {
+		return;
+	}
+	for await (const entry of handle) if (entry.isDirectory() || entry.isSymbolicLink()) await addPackageAgentsDocument(root, path.join(scopePath, entry.name), found);
+}
+async function addPackageAgentsDocument(root, packagePath, found) {
+	const agentsPath = path.join(packagePath, "AGENTS.md");
+	try {
+		await access(agentsPath);
+		found.push({ path: formatProjectPath(root, agentsPath) });
+	} catch {}
+}
+//#endregion
+//#region src/run.ts
+const helpText = `agents
+
+Usage:
+  agents
+  agents init [--force]
+  agents discover [--json]
+  agents add <path...>
+  agents remove <path...>
+  agents validate [--json]
+
+agents.yaml is a curated table of contents for active external AGENTS.md guidance.`;
+async function run(argv) {
+	const parsed = parseArgs(argv);
+	const root = cwd();
+	switch (parsed.command) {
+		case void 0:
+			await interactive(root);
+			return;
+		case "help":
+			console.log(helpText);
+			return;
+		case "version":
+			console.log("0.1.0");
+			return;
+		case "init":
+			await commandInit(root, parsed.flags.get("force") === true);
+			return;
+		case "discover":
+			await commandDiscover(root, parsed.flags.get("json") === true);
+			return;
+		case "add":
+			await commandAdd(root, parsed.values);
+			return;
+		case "remove":
+			await commandRemove(root, parsed.values);
+			return;
+		case "validate":
+			await commandValidate(root, parsed.flags.get("json") === true);
+			return;
+	}
+}
+function parseArgs(argv) {
+	const flags = /* @__PURE__ */ new Map();
+	const values = [];
+	let command;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (!arg) continue;
+		if (arg === "--help" || arg === "-h") {
+			command = "help";
+			continue;
+		}
+		if (arg === "--version" || arg === "-v") {
+			command = "version";
+			continue;
+		}
+		if (arg.startsWith("--")) {
+			const [rawName, inlineValue] = arg.slice(2).split("=", 2);
+			if (!rawName) continue;
+			if (inlineValue !== void 0) {
+				flags.set(rawName, inlineValue);
+				continue;
+			}
+			flags.set(rawName, true);
+			continue;
+		}
+		if (!command && isCommand(arg)) {
+			command = arg;
+			continue;
+		}
+		values.push(arg);
+	}
+	return {
+		command,
+		values,
+		flags
+	};
+}
+function isCommand(value) {
+	return [
+		"add",
+		"discover",
+		"help",
+		"init",
+		"remove",
+		"validate",
+		"version"
+	].includes(value);
+}
+async function commandInit(root, force) {
+	clack.intro("agents init");
+	const result = await initProject(root, { force });
+	clack.note(result.messages.join("\n"), "Updated");
+	clack.outro("Project breadcrumb is ready.");
+}
+async function commandDiscover(root, json) {
+	const documents = await discoverAgentDocuments(root);
+	if (json) {
+		console.log(JSON.stringify(documents, null, 2));
+		return;
+	}
+	clack.intro("agents discover");
+	if (documents.length === 0) {
+		clack.outro("No supplemental AGENTS.md files found.");
+		return;
+	}
+	clack.note(documents.map((doc) => doc.path).join("\n"), `Found ${documents.length}`);
+	clack.outro("Use agents add <path> to enable one.");
+}
+async function commandAdd(root, paths) {
+	if (paths.length === 0) throw new Error("add requires at least one AGENTS.md path");
+	const documents = paths.map((path) => ({ path: formatProjectPath(root, resolveFromRoot(root, path)) }));
+	const file = await addDocuments(root, documents);
+	clack.intro("agents add");
+	clack.note(file.documents.map((doc) => doc.path).join("\n"), "Active documents");
+	clack.outro(`Added ${documents.length} document${documents.length === 1 ? "" : "s"}.`);
+}
+async function commandRemove(root, paths) {
+	if (paths.length === 0) throw new Error("remove requires at least one path");
+	const result = await removeDocuments(root, paths.map((path) => formatProjectPath(root, resolveFromRoot(root, path))));
+	clack.intro("agents remove");
+	clack.note(result.removed.join("\n") || "No matching documents were active.", "Removed");
+	clack.outro(`agents.yaml now has ${result.file.documents.length} active document${result.file.documents.length === 1 ? "" : "s"}.`);
+}
+async function commandValidate(root, json) {
+	const result = await validateAgentsFile(root);
+	if (json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+	clack.intro("agents validate");
+	if (result.errors.length > 0) clack.note(result.errors.join("\n"), "Errors");
+	if (result.warnings.length > 0) clack.note(result.warnings.join("\n"), "Warnings");
+	clack.outro(result.ok ? "agents.yaml is valid." : "agents.yaml needs attention.");
+	if (!result.ok) process.exitCode = 1;
+}
+async function interactive(root) {
+	clack.intro("agents");
+	const action = await clack.select({
+		message: "What would you like to do?",
+		options: [
+			{
+				value: "discover",
+				label: "Discover and enable AGENTS.md files"
+			},
+			{
+				value: "validate",
+				label: "Validate agents.yaml"
+			},
+			{
+				value: "init",
+				label: "Initialize breadcrumb files"
+			}
+		]
+	});
+	if (clack.isCancel(action)) {
+		clack.cancel("Cancelled.");
+		return;
+	}
+	if (action === "init") {
+		await commandInit(root, false);
+		return;
+	}
+	if (action === "validate") {
+		await commandValidate(root, false);
+		return;
+	}
+	const existing = await loadAgentsFile(root);
+	const candidates = (await discoverAgentDocuments(root)).filter((doc) => !existing.documents.some((active) => active.path === doc.path));
+	if (candidates.length === 0) {
+		clack.outro("No inactive supplemental AGENTS.md files found.");
+		return;
+	}
+	const selected = await clack.multiselect({
+		message: "Choose documents to enable",
+		options: candidates.map((doc) => ({
+			value: doc.path,
+			label: doc.path
+		})),
+		required: false
+	});
+	if (clack.isCancel(selected) || selected.length === 0) {
+		clack.cancel("No documents selected.");
+		return;
+	}
+	await commandAdd(root, selected);
+}
+//#endregion
+//#region src/index.ts
+run(process.argv.slice(2)).catch((error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(`agents: ${message}`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agents.yaml",
+  "version": "0.1.0",
+  "description": "A CLI for discovering and curating agent-readable documentation in agents.yaml.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremybanka/agents.yaml.git"
+  },
+  "bin": {
+    "agents": "./dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "tsc --noEmit && tsdown"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.5.1",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "25.9.2",
+    "tsdown": "0.22.2",
+    "typescript": "6.0.3"
+  },
+  "engines": {
+    "node": "26.3.0",
+    "pnpm": "11.5.2"
+  },
+  "packageManager": "pnpm@11.5.2"
+}

package/src/agents-file.ts

@@ -0,0 +1,201 @@
+import { access, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import * as YAML from 'yaml'
+import { z } from 'zod'
+import { resolveFromRoot } from './paths.ts'
+
+export type AgentsDocumentEntry = {
+  path: string
+}
+
+export type AgentsFile = {
+  version: 1
+  documents: AgentsDocumentEntry[]
+}
+
+export type ValidationResult = {
+  ok: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+const fileSchema = z.object({
+  version: z.literal(1),
+  documents: z.array(
+    z.object({
+      path: z.string().min(1),
+    }),
+  ),
+})
+
+const breadcrumb = `For dependency-specific and supplemental guidance, consult \`./agents.yaml\`.
+
+Only the documents listed there should be considered active external guidance for this project.`
+
+export async function loadAgentsFile(root: string): Promise<AgentsFile> {
+  const filePath = agentsPath(root)
+
+  try {
+    const source = await readFile(filePath, 'utf8')
+    const parsed = YAML.parse(source) as unknown
+    return fileSchema.parse(parsed)
+  } catch (error) {
+    if (isNotFound(error)) {
+      return { version: 1, documents: [] }
+    }
+
+    if (error instanceof z.ZodError) {
+      throw new Error(
+        `Invalid agents.yaml: ${error.issues.map((issue) => issue.message).join(', ')}`,
+      )
+    }
+
+    throw error
+  }
+}
+
+export async function saveAgentsFile(root: string, file: AgentsFile): Promise<void> {
+  const normalized = {
+    version: file.version,
+    documents: file.documents.map((doc) => ({ path: doc.path })),
+  }
+
+  await writeFile(agentsPath(root), YAML.stringify(normalized, { lineWidth: 0 }), 'utf8')
+}
+
+export async function addDocuments(
+  root: string,
+  documents: AgentsDocumentEntry[],
+): Promise<AgentsFile> {
+  const file = await loadAgentsFile(root)
+  const byPath = new Map(file.documents.map((doc) => [doc.path, doc]))
+
+  for (const document of documents) {
+    byPath.set(document.path, document)
+  }
+
+  const next = {
+    version: 1 as const,
+    documents: [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path)),
+  }
+
+  await saveAgentsFile(root, next)
+  return next
+}
+
+export async function removeDocuments(
+  root: string,
+  paths: string[],
+): Promise<{ file: AgentsFile; removed: string[] }> {
+  const file = await loadAgentsFile(root)
+  const pathSet = new Set(paths)
+  const removed: string[] = []
+  const documents = file.documents.filter((doc) => {
+    if (pathSet.has(doc.path)) {
+      removed.push(doc.path)
+      return false
+    }
+
+    return true
+  })
+
+  const next = { version: 1 as const, documents }
+  await saveAgentsFile(root, next)
+  return { file: next, removed }
+}
+
+export async function validateAgentsFile(root: string): Promise<ValidationResult> {
+  const errors: string[] = []
+  const warnings: string[] = []
+  let file: AgentsFile
+
+  try {
+    file = await loadAgentsFile(root)
+  } catch (error) {
+    return {
+      ok: false,
+      errors: [error instanceof Error ? error.message : String(error)],
+      warnings,
+    }
+  }
+
+  const seen = new Set<string>()
+  for (const [index, document] of file.documents.entries()) {
+    const label = `documents[${index}] ${document.path}`
+
+    if (seen.has(document.path)) {
+      errors.push(`${label}: duplicate path`)
+    }
+    seen.add(document.path)
+
+    if (path.basename(document.path) !== 'AGENTS.md') {
+      warnings.push(`${label}: path does not end with AGENTS.md`)
+    }
+
+    try {
+      await access(resolveFromRoot(root, document.path))
+    } catch {
+      errors.push(`${label}: file does not exist`)
+    }
+  }
+
+  try {
+    const source = await readFile(path.join(root, 'AGENTS.md'), 'utf8')
+    if (!source.includes('./agents.yaml') && !source.includes('agents.yaml')) {
+      warnings.push('AGENTS.md does not mention agents.yaml')
+    }
+  } catch {
+    warnings.push('AGENTS.md is missing the agents.yaml breadcrumb')
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+export async function initProject(
+  root: string,
+  options: { force: boolean },
+): Promise<{ messages: string[] }> {
+  const messages: string[] = []
+
+  try {
+    await access(agentsPath(root))
+    messages.push('agents.yaml already exists')
+  } catch {
+    await saveAgentsFile(root, { version: 1, documents: [] })
+    messages.push('created agents.yaml')
+  }
+
+  const projectAgentsPath = path.join(root, 'AGENTS.md')
+  try {
+    const source = await readFile(projectAgentsPath, 'utf8')
+    if (source.includes('agents.yaml') && !options.force) {
+      messages.push('AGENTS.md already mentions agents.yaml')
+      return { messages }
+    }
+
+    const next =
+      source.trimEnd().length === 0
+        ? `# Project Instructions\n\n${breadcrumb}\n`
+        : `${source.trimEnd()}\n\n${breadcrumb}\n`
+    await writeFile(projectAgentsPath, next, 'utf8')
+    messages.push('updated AGENTS.md')
+  } catch (error) {
+    if (!isNotFound(error)) throw error
+    await writeFile(projectAgentsPath, `# Project Instructions\n\n${breadcrumb}\n`, 'utf8')
+    messages.push('created AGENTS.md')
+  }
+
+  return { messages }
+}
+
+function agentsPath(root: string): string {
+  return path.join(root, 'agents.yaml')
+}
+
+function isNotFound(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}

package/src/discover.test.ts

@@ -0,0 +1,71 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { addDocuments, loadAgentsFile } from './agents-file.ts'
+import { discoverAgentDocuments } from './discover.ts'
+
+const tempRoots: string[] = []
+
+describe('agents.yaml dependency discovery', () => {
+  afterEach(async () => {
+    await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+  })
+
+  it('discovers a direct dependency with an AGENTS.md and adds it to agents.yaml', async () => {
+    const root = await createTempProject()
+    const dependencyAgentsPath = path.join(root, 'node_modules', 'direct-lib', 'AGENTS.md')
+    await mkdir(path.dirname(dependencyAgentsPath), { recursive: true })
+    await writeFile(dependencyAgentsPath, '# Direct dependency guidance\n', 'utf8')
+
+    const discovered = await discoverAgentDocuments(root)
+    expect(discovered).toEqual([{ path: './node_modules/direct-lib/AGENTS.md' }])
+
+    await addDocuments(root, [
+      {
+        path: discovered[0]!.path,
+      },
+    ])
+
+    await expect(loadAgentsFile(root)).resolves.toEqual({
+      version: 1,
+      documents: [
+        {
+          path: './node_modules/direct-lib/AGENTS.md',
+        },
+      ],
+    })
+  })
+
+  it('does not discover an indirect dependency that has an AGENTS.md', async () => {
+    const root = await createTempProject()
+    const directAgentsPath = path.join(root, 'node_modules', 'direct-lib', 'AGENTS.md')
+    const indirectAgentsPath = path.join(
+      root,
+      'node_modules',
+      'direct-lib',
+      'node_modules',
+      'indirect-lib',
+      'AGENTS.md',
+    )
+
+    await mkdir(path.dirname(directAgentsPath), { recursive: true })
+    await mkdir(path.dirname(indirectAgentsPath), { recursive: true })
+    await writeFile(directAgentsPath, '# Direct dependency guidance\n', 'utf8')
+    await writeFile(indirectAgentsPath, '# Indirect dependency guidance\n', 'utf8')
+
+    await expect(discoverAgentDocuments(root)).resolves.toEqual([
+      { path: './node_modules/direct-lib/AGENTS.md' },
+    ])
+  })
+})
+
+async function createTempProject(): Promise<string> {
+  const root = await mkdtemp(path.join(tmpdir(), 'agents-yaml-'))
+  tempRoots.push(root)
+
+  await writeFile(path.join(root, 'agents.yaml'), 'version: 1\n\ndocuments: []\n', 'utf8')
+  await writeFile(path.join(root, 'AGENTS.md'), 'Consult ./agents.yaml.\n', 'utf8')
+
+  return root
+}

package/src/discover.ts

@@ -0,0 +1,115 @@
+import { access, opendir } from 'node:fs/promises'
+import path from 'node:path'
+import { formatProjectPath } from './paths.ts'
+
+export type DiscoveredDocument = {
+  path: string
+}
+
+const skippedDirectories = new Set([
+  '.git',
+  '.hg',
+  '.svn',
+  '.turbo',
+  '.next',
+  'coverage',
+  'dist',
+  'build',
+])
+
+export async function discoverAgentDocuments(root: string): Promise<DiscoveredDocument[]> {
+  const found: DiscoveredDocument[] = []
+  await walk(root, root, found)
+  return found
+    .filter((document) => document.path !== './AGENTS.md')
+    .sort((left, right) => left.path.localeCompare(right.path))
+}
+
+async function walk(root: string, directory: string, found: DiscoveredDocument[]): Promise<void> {
+  let handle
+  try {
+    handle = await opendir(directory)
+  } catch {
+    return
+  }
+
+  for await (const entry of handle) {
+    const absolutePath = path.join(directory, entry.name)
+
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules') {
+        await scanDirectNodeModules(root, absolutePath, found)
+        continue
+      }
+
+      if (!skippedDirectories.has(entry.name)) {
+        await walk(root, absolutePath, found)
+      }
+      continue
+    }
+
+    if (entry.isFile() && entry.name === 'AGENTS.md') {
+      found.push({ path: formatProjectPath(root, absolutePath) })
+    }
+  }
+}
+
+async function scanDirectNodeModules(
+  root: string,
+  nodeModulesPath: string,
+  found: DiscoveredDocument[],
+): Promise<void> {
+  let handle
+  try {
+    handle = await opendir(nodeModulesPath)
+  } catch {
+    return
+  }
+
+  for await (const entry of handle) {
+    if ((!entry.isDirectory() && !entry.isSymbolicLink()) || entry.name.startsWith('.')) {
+      continue
+    }
+
+    const packagePath = path.join(nodeModulesPath, entry.name)
+    if (entry.name.startsWith('@')) {
+      await scanScopedPackages(root, packagePath, found)
+      continue
+    }
+
+    await addPackageAgentsDocument(root, packagePath, found)
+  }
+}
+
+async function scanScopedPackages(
+  root: string,
+  scopePath: string,
+  found: DiscoveredDocument[],
+): Promise<void> {
+  let handle
+  try {
+    handle = await opendir(scopePath)
+  } catch {
+    return
+  }
+
+  for await (const entry of handle) {
+    if (entry.isDirectory() || entry.isSymbolicLink()) {
+      await addPackageAgentsDocument(root, path.join(scopePath, entry.name), found)
+    }
+  }
+}
+
+async function addPackageAgentsDocument(
+  root: string,
+  packagePath: string,
+  found: DiscoveredDocument[],
+): Promise<void> {
+  const agentsPath = path.join(packagePath, 'AGENTS.md')
+  try {
+    await access(agentsPath)
+    found.push({ path: formatProjectPath(root, agentsPath) })
+  } catch {
+    // Packages without AGENTS.md are simply not candidates.
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { run } from './run.ts'
+
+run(process.argv.slice(2)).catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`agents: ${message}`)
+  process.exitCode = 1
+})

package/src/paths.ts

@@ -0,0 +1,18 @@
+import path from 'node:path'
+
+export function cwd(): string {
+  return process.cwd()
+}
+
+export function resolveFromRoot(root: string, input: string): string {
+  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(root, input)
+}
+
+export function formatProjectPath(root: string, target: string): string {
+  const relative = path.relative(root, target).split(path.sep).join(path.posix.sep)
+  if (relative.startsWith('..')) {
+    return target
+  }
+
+  return relative.startsWith('.') ? relative : `./${relative}`
+}

package/src/run.ts

@@ -0,0 +1,233 @@
+import * as clack from '@clack/prompts'
+import {
+  addDocuments,
+  initProject,
+  loadAgentsFile,
+  removeDocuments,
+  validateAgentsFile,
+} from './agents-file.ts'
+import { discoverAgentDocuments } from './discover.ts'
+import { cwd, formatProjectPath, resolveFromRoot } from './paths.ts'
+
+type Command = 'add' | 'discover' | 'help' | 'init' | 'remove' | 'validate' | 'version'
+
+type ParsedArgs = {
+  command: Command | undefined
+  values: string[]
+  flags: Map<string, string | boolean>
+}
+
+const helpText = `agents
+
+Usage:
+  agents
+  agents init [--force]
+  agents discover [--json]
+  agents add <path...>
+  agents remove <path...>
+  agents validate [--json]
+
+agents.yaml is a curated table of contents for active external AGENTS.md guidance.`
+
+export async function run(argv: string[]): Promise<void> {
+  const parsed = parseArgs(argv)
+  const root = cwd()
+
+  switch (parsed.command) {
+    case undefined:
+      await interactive(root)
+      return
+    case 'help':
+      console.log(helpText)
+      return
+    case 'version':
+      console.log('0.1.0')
+      return
+    case 'init':
+      await commandInit(root, parsed.flags.get('force') === true)
+      return
+    case 'discover':
+      await commandDiscover(root, parsed.flags.get('json') === true)
+      return
+    case 'add':
+      await commandAdd(root, parsed.values)
+      return
+    case 'remove':
+      await commandRemove(root, parsed.values)
+      return
+    case 'validate':
+      await commandValidate(root, parsed.flags.get('json') === true)
+      return
+  }
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const flags = new Map<string, string | boolean>()
+  const values: string[] = []
+  let command: Command | undefined
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (!arg) continue
+
+    if (arg === '--help' || arg === '-h') {
+      command = 'help'
+      continue
+    }
+
+    if (arg === '--version' || arg === '-v') {
+      command = 'version'
+      continue
+    }
+
+    if (arg.startsWith('--')) {
+      const [rawName, inlineValue] = arg.slice(2).split('=', 2)
+      if (!rawName) continue
+      if (inlineValue !== undefined) {
+        flags.set(rawName, inlineValue)
+        continue
+      }
+
+      flags.set(rawName, true)
+      continue
+    }
+
+    if (!command && isCommand(arg)) {
+      command = arg
+      continue
+    }
+
+    values.push(arg)
+  }
+
+  return { command, values, flags }
+}
+
+function isCommand(value: string): value is Command {
+  return ['add', 'discover', 'help', 'init', 'remove', 'validate', 'version'].includes(value)
+}
+
+async function commandInit(root: string, force: boolean): Promise<void> {
+  clack.intro('agents init')
+  const result = await initProject(root, { force })
+  clack.note(result.messages.join('\n'), 'Updated')
+  clack.outro('Project breadcrumb is ready.')
+}
+
+async function commandDiscover(root: string, json: boolean): Promise<void> {
+  const documents = await discoverAgentDocuments(root)
+  if (json) {
+    console.log(JSON.stringify(documents, null, 2))
+    return
+  }
+
+  clack.intro('agents discover')
+  if (documents.length === 0) {
+    clack.outro('No supplemental AGENTS.md files found.')
+    return
+  }
+
+  clack.note(documents.map((doc) => doc.path).join('\n'), `Found ${documents.length}`)
+  clack.outro('Use agents add <path> to enable one.')
+}
+
+async function commandAdd(root: string, paths: string[]): Promise<void> {
+  if (paths.length === 0) {
+    throw new Error('add requires at least one AGENTS.md path')
+  }
+
+  const documents = paths.map((path) => ({
+    path: formatProjectPath(root, resolveFromRoot(root, path)),
+  }))
+
+  const file = await addDocuments(root, documents)
+  clack.intro('agents add')
+  clack.note(file.documents.map((doc) => doc.path).join('\n'), 'Active documents')
+  clack.outro(`Added ${documents.length} document${documents.length === 1 ? '' : 's'}.`)
+}
+
+async function commandRemove(root: string, paths: string[]): Promise<void> {
+  if (paths.length === 0) {
+    throw new Error('remove requires at least one path')
+  }
+
+  const normalizedPaths = paths.map((path) => formatProjectPath(root, resolveFromRoot(root, path)))
+  const result = await removeDocuments(root, normalizedPaths)
+  clack.intro('agents remove')
+  clack.note(result.removed.join('\n') || 'No matching documents were active.', 'Removed')
+  clack.outro(
+    `agents.yaml now has ${result.file.documents.length} active document${result.file.documents.length === 1 ? '' : 's'}.`,
+  )
+}
+
+async function commandValidate(root: string, json: boolean): Promise<void> {
+  const result = await validateAgentsFile(root)
+  if (json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  clack.intro('agents validate')
+  if (result.errors.length > 0) {
+    clack.note(result.errors.join('\n'), 'Errors')
+  }
+  if (result.warnings.length > 0) {
+    clack.note(result.warnings.join('\n'), 'Warnings')
+  }
+
+  clack.outro(result.ok ? 'agents.yaml is valid.' : 'agents.yaml needs attention.')
+  if (!result.ok) {
+    process.exitCode = 1
+  }
+}
+
+async function interactive(root: string): Promise<void> {
+  clack.intro('agents')
+  const action = await clack.select({
+    message: 'What would you like to do?',
+    options: [
+      { value: 'discover', label: 'Discover and enable AGENTS.md files' },
+      { value: 'validate', label: 'Validate agents.yaml' },
+      { value: 'init', label: 'Initialize breadcrumb files' },
+    ],
+  })
+
+  if (clack.isCancel(action)) {
+    clack.cancel('Cancelled.')
+    return
+  }
+
+  if (action === 'init') {
+    await commandInit(root, false)
+    return
+  }
+
+  if (action === 'validate') {
+    await commandValidate(root, false)
+    return
+  }
+
+  const existing = await loadAgentsFile(root)
+  const discovered = await discoverAgentDocuments(root)
+  const candidates = discovered.filter(
+    (doc) => !existing.documents.some((active) => active.path === doc.path),
+  )
+
+  if (candidates.length === 0) {
+    clack.outro('No inactive supplemental AGENTS.md files found.')
+    return
+  }
+
+  const selected = await clack.multiselect({
+    message: 'Choose documents to enable',
+    options: candidates.map((doc) => ({ value: doc.path, label: doc.path })),
+    required: false,
+  })
+
+  if (clack.isCancel(selected) || selected.length === 0) {
+    clack.cancel('No documents selected.')
+    return
+  }
+
+  await commandAdd(root, selected)
+}