agdocs 1.0.0

package/README.md

@@ -0,0 +1,26 @@
+# agdocs
+
+English | [简体中文](./README.zh-CN.md)
+
+Bootstrap agent-oriented docs in your project.
+
+## Usage
+
+```bash
+npx agdocs init
+```
+
+See `npx agdocs -h` for all commands and flags.
+
+## Layout
+
+```
+.
+├── AGENTS.md      # Agent rules
+├── CLAUDE.md      # Agent rules for Claude Code
+├── CONTEXT.md     # Domain glossary
+├── DESIGN.md      # UI / interaction conventions
+└── docs/
+    ├── adr/       # Architecture decision records (0001-<slug>.md)
+    └── prd/       # Product requirements (<feature-slug>.md)
+```

package/README.zh-CN.md

@@ -0,0 +1,26 @@
+# agdocs
+
+[English](./README.md) | 简体中文
+
+在项目中引导搭建面向 agent 的文档。
+
+## 用法
+
+```bash
+npx agdocs init
+```
+
+全部命令与 flags 见 `npx agdocs -h`。
+
+## 目录结构
+
+```
+.
+├── AGENTS.md      # Agent 规则
+├── CLAUDE.md      # Claude Code 的 Agent 规则
+├── CONTEXT.md     # 领域词汇表
+├── DESIGN.md      # UI / 交互约定
+└── docs/
+    ├── adr/       # 架构决策记录（0001-<slug>.md）
+    └── prd/       # 产品需求（<feature-slug>.md）
+```

package/dist/cli.mjs

@@ -0,0 +1,567 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError } from "commander";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cp, lstat, mkdir, readFile, readlink, rm, symlink, writeFile } from "node:fs/promises";
+import { cancel, confirm, isCancel, select } from "@clack/prompts";
+//#region src/content/agents-bootstrap.ts
+/** Injected into the target repo's AGENTS.md by `agdocs init`. */
+const AGENTS_BOOTSTRAP_START = "<!-- agdocs:begin -->";
+const AGENTS_BOOTSTRAP_END = "<!-- agdocs:end -->";
+const agentsBootstrapBody = `${AGENTS_BOOTSTRAP_START}
+
+## CONTEXT.md
+
+\`CONTEXT.md\` should be totally devoid of implementation details. Do not treat \`CONTEXT.md\` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+Use its canonical terms, and avoid the listed aliases, wherever a domain concept appears in docs, tests, or implementation. Update it whenever a term is added, renamed, or clarified.
+
+**File structure.** Single context: a root \`CONTEXT.md\` and \`docs/adr/\`.
+
+**Format.**
+
+\`\`\`md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+\`\`\`
+
+**Rules.**
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## docs/adr/
+
+ADRs live in \`docs/adr/\` and use sequential numbering: \`0001-slug.md\`, \`0002-slug.md\`, etc. Create the directory lazily — only when the first ADR is needed. Scan \`docs/adr/\` for the highest existing number and increment by one. Read the ADRs touching an area before changing it, and add or update one when a qualifying decision changes.
+
+**When to write one.**
+
+An ADR records a decision that is costly to reverse. Skip everyday implementation choices. Write one when the choice is:
+
+1. **Consequential** — it constrains future work, shapes the architecture, or would be expensive to undo
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+
+If both apply, write the ADR. If only one applies, use judgment. If neither applies, skip it.
+
+**Optional.**
+
+- **Status** frontmatter (\`proposed | accepted | deprecated | superseded by ADR-NNNN\`) — useful when decisions are revisited
+- **Alternatives considered** — useful when the rejected options are non-obvious
+
+## PRD (\`docs/prd/<feature-slug>.md\`)
+
+One PRD file per feature. Synthesize the PRD from the current conversation and codebase understanding — do NOT interview the user. Use the project's domain glossary vocabulary throughout, and respect any ADRs in the area you're touching. This repo keeps PRDs only: do not create issue or task files, and do not run a triage step, unless the user explicitly asks. Update the PRD when product scope, user flows, implementation decisions, or testing decisions change.
+
+\`\`\`md
+# <feature-slug>
+
+**<Feature Name>**
+
+## Problem Statement
+
+The problem that the user is facing.
+
+## Solution
+
+The solution that the user is proposing.
+
+## User Stories
+
+How the user will interact with the feature.
+
+## Implementation Decisions
+
+Key decisions that the user has made about the feature.
+
+## Testing Decisions
+
+Key decisions that the user has made about testing the feature.
+
+## Out of Scope
+
+The things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+\`\`\`
+
+## DESIGN.md
+
+The current workspace's visual and interaction direction. Read it before changing UI, and update it when those conventions stably change.
+
+${AGENTS_BOOTSTRAP_END}`;
+//#endregion
+//#region src/agents-md.ts
+function replaceRange(source, start, end, replacement) {
+	return `${source.slice(0, start)}${replacement}${source.slice(end)}`;
+}
+function upsertAgentsMd(existing) {
+	const block = `${agentsBootstrapBody}\n`;
+	if (!existing.trim()) return {
+		content: block,
+		action: "created"
+	};
+	const startIdx = existing.indexOf(AGENTS_BOOTSTRAP_START);
+	const endIdx = existing.indexOf(AGENTS_BOOTSTRAP_END);
+	const hasStart = startIdx !== -1;
+	const hasEnd = endIdx !== -1;
+	if (hasStart && hasEnd && startIdx < endIdx) {
+		const next = replaceRange(existing, startIdx, endIdx + 19, agentsBootstrapBody);
+		if (next === existing) return {
+			content: existing,
+			action: "unchanged"
+		};
+		return {
+			content: next,
+			action: "updated"
+		};
+	}
+	if (hasStart && !hasEnd) return {
+		content: replaceRange(existing, startIdx, existing.length, block),
+		action: "updated"
+	};
+	if (!hasStart && hasEnd) return {
+		content: replaceRange(existing, endIdx, endIdx + 19, agentsBootstrapBody),
+		action: "updated"
+	};
+	return {
+		content: `${existing}${existing.endsWith("\n") ? "\n" : "\n\n"}${block}`,
+		action: "updated"
+	};
+}
+//#endregion
+//#region src/fs/io.ts
+async function exists(path) {
+	try {
+		await lstat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function readText(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+async function writeText(path, content) {
+	await mkdir(dirname(path), { recursive: true });
+	if (await isSymlink(path)) await rm(path, { force: true });
+	await writeFile(path, content, "utf8");
+}
+async function isSymlink(path) {
+	try {
+		return (await lstat(path)).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+async function isDirectory(path) {
+	try {
+		const stat = await lstat(path);
+		return stat.isDirectory() && !stat.isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+async function isFile(path) {
+	try {
+		const stat = await lstat(path);
+		return stat.isFile() && !stat.isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+/** True when `path` is a symlink whose target equals `expected` (as stored). */
+async function isSymlinkTo(path, expected) {
+	try {
+		if (!(await lstat(path)).isSymbolicLink()) return false;
+		return await readlink(path) === expected;
+	} catch {
+		return false;
+	}
+}
+async function ensureDir(path) {
+	await mkdir(path, { recursive: true });
+}
+async function copyDir(src, dest) {
+	await rm(dest, {
+		force: true,
+		recursive: true
+	});
+	await cp(src, dest, {
+		recursive: true,
+		dereference: true
+	});
+}
+async function replaceWithSymlink(path, target) {
+	await rm(path, {
+		force: true,
+		recursive: true
+	});
+	await mkdir(dirname(path), { recursive: true });
+	await symlink(target, path);
+}
+function isInteractive() {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+//#endregion
+//#region src/fs/paths.ts
+function agentsMd(cwd) {
+	return join(cwd, "AGENTS.md");
+}
+function claudeMd(cwd) {
+	return join(cwd, "CLAUDE.md");
+}
+function agentsSkills(cwd) {
+	return join(cwd, ".agents", "skills");
+}
+function claudeSkills(cwd) {
+	return join(cwd, ".claude", "skills");
+}
+//#endregion
+//#region src/link/detect-md.ts
+function sameText(a, b) {
+	return a.trim() === b.trim();
+}
+/** Empty / whitespace-only files count as missing. */
+async function readPresentFile(path) {
+	if (!await exists(path) || !await isFile(path)) return null;
+	const text = await readText(path) ?? "";
+	return text.trim() ? text : null;
+}
+async function detectMd(cwd) {
+	const agentsPath = agentsMd(cwd);
+	const claudePath = claudeMd(cwd);
+	if (await isSymlinkTo(claudePath, "AGENTS.md")) return { kind: "correct-link" };
+	if (await exists(claudePath) && await isSymlink(claudePath)) return { kind: "bad-link" };
+	if (await exists(agentsPath) && await isSymlink(agentsPath)) return { kind: "other" };
+	const agents = await readPresentFile(agentsPath);
+	const claude = await readPresentFile(claudePath);
+	if (!agents && !claude) return { kind: "missing-both" };
+	if (agents && !claude) return {
+		kind: "agents-only",
+		agents
+	};
+	if (!agents && claude) return {
+		kind: "claude-only",
+		claude
+	};
+	if (agents && claude) {
+		if (sameText(agents, claude)) return {
+			kind: "same-content",
+			content: agents
+		};
+		return {
+			kind: "conflict",
+			agents,
+			claude
+		};
+	}
+	return { kind: "other" };
+}
+//#endregion
+//#region src/link/prompt.ts
+async function askLink(message, initialValue = true) {
+	const value = await confirm({
+		message,
+		initialValue
+	});
+	if (isCancel(value)) {
+		cancel("Cancelled.");
+		process.exit(0);
+	}
+	return value;
+}
+async function askKeep(message = "Keep which content?") {
+	const value = await select({
+		message,
+		options: [{
+			value: "agents",
+			label: "AGENTS.md"
+		}, {
+			value: "claude",
+			label: "CLAUDE.md"
+		}]
+	});
+	if (isCancel(value)) {
+		cancel("Cancelled.");
+		process.exit(0);
+	}
+	return value;
+}
+async function askKeepSkills() {
+	const value = await select({
+		message: "Keep which skills?",
+		options: [{
+			value: "agents",
+			label: ".agents/skills"
+		}, {
+			value: "claude",
+			label: ".claude/skills"
+		}]
+	});
+	if (isCancel(value)) {
+		cancel("Cancelled.");
+		process.exit(0);
+	}
+	return value;
+}
+//#endregion
+//#region src/link/resolve.ts
+var LinkConflictError = class extends Error {
+	constructor(target) {
+		super(`Conflict in ${target}: pass --keep-* or -y, or run in a TTY`);
+		this.name = "LinkConflictError";
+	}
+};
+function modeToBool(mode) {
+	if (mode === "link") return true;
+	if (mode === "skip") return false;
+}
+async function resolveWantLink(options, message, ask, choice) {
+	const explicit = modeToBool(choice);
+	if (explicit !== void 0) return explicit;
+	if (options.yes) return true;
+	if (isInteractive()) return ask(message);
+	return options.command === "link";
+}
+async function resolveKeep(options, ask, target, choice) {
+	if (choice) return choice;
+	if (options.yes) return "agents";
+	if (isInteractive()) return ask();
+	throw new LinkConflictError(target);
+}
+//#endregion
+//#region src/link/run-md.ts
+async function bodies(cwd, state) {
+	switch (state.kind) {
+		case "missing-both": return {
+			agents: "",
+			claude: ""
+		};
+		case "agents-only": return {
+			agents: state.agents,
+			claude: ""
+		};
+		case "claude-only": return {
+			agents: "",
+			claude: state.claude
+		};
+		case "same-content": return {
+			agents: state.content,
+			claude: state.content
+		};
+		case "conflict": return {
+			agents: state.agents,
+			claude: state.claude
+		};
+		case "bad-link": return {
+			agents: await readText(agentsMd(cwd)) ?? "",
+			claude: ""
+		};
+	}
+}
+async function planMd(options) {
+	const state = await detectMd(options.cwd);
+	if (state.kind === "correct-link") return { action: "skip" };
+	if (state.kind === "other") throw new Error("Cannot link AGENTS.md / CLAUDE.md in the current layout");
+	const want = await resolveWantLink(options, "Link CLAUDE.md → AGENTS.md?", askLink, options.md);
+	const { agents, claude } = await bodies(options.cwd, state);
+	if (!want) {
+		if (options.command === "link") return { action: "skip" };
+		return {
+			action: "separate",
+			agents,
+			claude
+		};
+	}
+	if (state.kind === "conflict") {
+		const kept = await resolveKeep(options, askKeep, "AGENTS.md / CLAUDE.md", options.keepMd);
+		return {
+			action: "link",
+			content: kept === "agents" ? agents : claude,
+			kept
+		};
+	}
+	return {
+		action: "link",
+		content: agents || claude
+	};
+}
+/** `map` transforms each file body (e.g. bootstrap upsert). */
+async function applyMdPlan(cwd, plan, map = (c) => c) {
+	if (plan.action === "skip") return { status: "skipped" };
+	if (plan.action === "link") {
+		await writeText(agentsMd(cwd), map(plan.content));
+		await replaceWithSymlink(claudeMd(cwd), "AGENTS.md");
+		return {
+			status: "linked",
+			kept: plan.kept
+		};
+	}
+	await writeText(agentsMd(cwd), map(plan.agents));
+	await writeText(claudeMd(cwd), map(plan.claude));
+	return { status: "unlinked" };
+}
+//#endregion
+//#region src/commands/init.ts
+async function writeIfMissing(path, content) {
+	if (await exists(path)) return false;
+	await writeText(path, content);
+	return true;
+}
+async function upsertAgentsInPlace(cwd) {
+	const { content, action } = upsertAgentsMd(await readText(agentsMd(cwd)) ?? "");
+	if (action !== "unchanged") await writeText(agentsMd(cwd), content);
+	console.log(action === "created" ? "Created AGENTS.md" : action === "updated" ? "Updated AGENTS.md" : "AGENTS.md up to date");
+}
+async function runInit(options) {
+	const opts = {
+		...options,
+		command: "init"
+	};
+	const plan = await planMd(opts);
+	if (plan.action === "skip") await upsertAgentsInPlace(opts.cwd);
+	else if ((await applyMdPlan(opts.cwd, plan, (body) => upsertAgentsMd(body).content)).status === "linked") console.log("Linked CLAUDE.md → AGENTS.md");
+	else console.log("Wrote AGENTS.md and CLAUDE.md");
+	const created = [];
+	const skipped = [];
+	for (const file of ["CONTEXT.md", "DESIGN.md"]) if (await writeIfMissing(join(opts.cwd, file), "")) created.push(file);
+	else skipped.push(file);
+	await mkdir(join(opts.cwd, "docs", "adr"), { recursive: true });
+	await mkdir(join(opts.cwd, "docs", "prd"), { recursive: true });
+	created.push("docs/adr/", "docs/prd/");
+	if (created.length) console.log(`Created: ${created.join(", ")}`);
+	if (skipped.length) console.log(`Skipped: ${skipped.join(", ")}`);
+}
+//#endregion
+//#region src/link/detect-skills.ts
+async function detectSkills(cwd) {
+	const agentsPath = agentsSkills(cwd);
+	const claudePath = claudeSkills(cwd);
+	const agentsExists = await exists(agentsPath);
+	const claudeExists = await exists(claudePath);
+	if (await isSymlinkTo(claudePath, "../.agents/skills")) return { kind: "correct-link" };
+	if (!agentsExists && !claudeExists) return { kind: "missing-both" };
+	if (claudeExists && await isSymlink(claudePath)) return { kind: "bad-link" };
+	if (agentsExists && await isSymlink(agentsPath)) return { kind: "other" };
+	const agentsDir = agentsExists && await isDirectory(agentsPath);
+	const claudeDir = claudeExists && await isDirectory(claudePath);
+	if (agentsDir && !claudeExists) return { kind: "agents-only" };
+	if (claudeDir && !agentsExists) return { kind: "claude-only" };
+	if (agentsDir && claudeDir) return { kind: "both-dirs" };
+	return { kind: "other" };
+}
+//#endregion
+//#region src/link/run-skills.ts
+async function runSkills(options) {
+	const state = await detectSkills(options.cwd);
+	if (state.kind === "correct-link") return { status: "skipped" };
+	if (state.kind === "other") throw new Error("Cannot link .agents/skills / .claude/skills in the current layout");
+	if (!await resolveWantLink(options, "Link .claude/skills → .agents/skills?", askLink, options.skills)) return { status: "skipped" };
+	if (state.kind === "both-dirs") {
+		const kept = await resolveKeep(options, askKeepSkills, ".agents/skills / .claude/skills", options.keepSkills);
+		if (kept === "claude") await copyDir(claudeSkills(options.cwd), agentsSkills(options.cwd));
+		await replaceWithSymlink(claudeSkills(options.cwd), "../.agents/skills");
+		return {
+			status: "linked",
+			kept
+		};
+	}
+	if (state.kind === "claude-only") await copyDir(claudeSkills(options.cwd), agentsSkills(options.cwd));
+	else await ensureDir(agentsSkills(options.cwd));
+	await replaceWithSymlink(claudeSkills(options.cwd), "../.agents/skills");
+	return { status: "linked" };
+}
+//#endregion
+//#region src/commands/link.ts
+async function runLink(options) {
+	const opts = {
+		...options,
+		command: "link"
+	};
+	const plan = await planMd(opts);
+	const md = await applyMdPlan(opts.cwd, plan);
+	if (md.status === "linked") console.log("Linked CLAUDE.md → AGENTS.md");
+	else if (md.status === "skipped") console.log("AGENTS.md / CLAUDE.md unchanged");
+	const skills = await runSkills(opts);
+	if (skills.status === "linked") console.log("Linked .claude/skills → .agents/skills");
+	else if (skills.status === "skipped") console.log(".agents/skills / .claude/skills unchanged");
+}
+//#endregion
+//#region src/cli.ts
+function readPackageVersion() {
+	const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+	return JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0";
+}
+function parseMode(value) {
+	if (value === "link" || value === "skip") return value;
+	throw new InvalidArgumentError("Expected link|skip");
+}
+function parseKeep(value) {
+	if (value === "agents" || value === "claude") return value;
+	throw new InvalidArgumentError("Expected agents|claude");
+}
+function toOptions(flags, command) {
+	return {
+		cwd: resolve(flags.cwd ?? process.cwd()),
+		command,
+		yes: flags.yes,
+		md: flags.md,
+		keepMd: flags.keepMd,
+		skills: flags.skills,
+		keepSkills: flags.keepSkills
+	};
+}
+const program = new Command().name("agdocs").description("Bootstrap agent-oriented docs and link Claude ↔ Agents").version(readPackageVersion()).addHelpText("after", `
+Flags (init & link):
+  -y, --yes              Link without prompts; keep agents on conflict
+  --md <link|skip>       Answer the MD link prompt
+  --keep-md <agents|claude>
+                         Keep which content on MD conflict
+  -C, --cwd <dir>        Target directory (default: cwd)
+
+Flags (link only):
+  --skills <link|skip>   Answer the skills link prompt
+  --keep-skills <agents|claude>
+                         Keep which skills on conflict
+`);
+function addSharedOptions(cmd) {
+	return cmd.option("-C, --cwd <dir>", "target directory").option("-y, --yes", "link without prompts; keep agents on conflict").option("--md <mode>", "link|skip", parseMode).option("--keep-md <side>", "agents|claude", parseKeep);
+}
+addSharedOptions(program.command("init").description("Bootstrap docs; optionally link CLAUDE.md (not skills)")).action(async (flags) => {
+	try {
+		await runInit(toOptions(flags, "init"));
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : error);
+		process.exitCode = 1;
+	}
+});
+addSharedOptions(program.command("link").description("Link CLAUDE.md and .claude/skills to Agents").option("--skills <mode>", "link|skip", parseMode).option("--keep-skills <side>", "agents|claude", parseKeep)).action(async (flags) => {
+	try {
+		await runLink(toOptions(flags, "link"));
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : error);
+		process.exitCode = 1;
+	}
+});
+program.parse();
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "agdocs",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Initialize AGENTS.md and docs scaffolding for AI-assisted development",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WBBB0730/agdocs.git"
+  },
+  "packageManager": "pnpm@10.30.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "play": "tsx scripts/play.ts",
+    "play:clean": "tsx scripts/play-clean.ts",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "bumpp": "^11.1.0",
+    "tsdown": "^0.22.0",
+    "tsx": "^4.20.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "bin": {
+    "agdocs": "dist/cli.mjs"
+  }
+}