@bossmissing/agent-meta 0.1.0 → 0.2.0

package/dist/commands/review.js

@@ -0,0 +1,102 @@
+import { checkbox } from "@inquirer/prompts";
+import { loadConfig } from "../core/config.js";
+import { runCheck } from "./check.js";
+import { listDomainDirs } from "../validators/domain-validator.js";
+import { isHighRisk } from "../core/risk.js";
+import { resolveDocScopes } from "../core/doc-scopes.js";
+import { printChecklist, checklistToJson } from "../core/checklist.js";
+import { logger } from "../core/logger.js";
+/**
+ * Periodic repository review checklist. Items that map to deterministic
+ * `meta check` rules are evaluated live; the rest is a manual routine for
+ * the reviewing human (or agent) covering docs, code, tests and security.
+ */
+/**
+ * @param selectedScopes doc-scope keys confirmed by the human; undefined
+ *   means every scope is listed (missing ones marked as such).
+ */
+export function buildReviewChecklist(root, selectedScopes) {
+    const { config } = loadConfig(root);
+    const result = runCheck(root, {});
+    const files = (codes) => result.issues
+        .filter((i) => codes.includes(i.code))
+        .map((i) => i.file ?? i.message);
+    const highRisk = listDomainDirs(root, config.paths.domain_docs).filter((d) => isHighRisk(d, config.risk_keywords));
+    const auto = (id, section, text, offending) => ({
+        id,
+        section,
+        text,
+        kind: "auto",
+        status: offending.length === 0 ? "pass" : "fail",
+        details: offending,
+    });
+    const manual = (id, section, text, details) => ({
+        id,
+        section,
+        text,
+        kind: "manual",
+        status: "pending",
+        details,
+    });
+    const DOCS = "Docs（优化文档）";
+    const CODE = "Code（review 代码）";
+    const TESTS = "Tests（review 测试用例）";
+    const SECURITY = "Security（review 安全）";
+    return [
+        // Docs
+        auto("doc-stale", DOCS, "All constrained docs reviewed within their interval", files(["DOC_STALE"])),
+        auto("doc-owner", DOCS, "Every constrained doc has an owner", files(["DOC_FRONTMATTER_MISSING_OWNER", "DOMAIN_NO_OWNER"])),
+        auto("doc-hard-constraints", DOCS, "Every high-risk domain declares hard constraints", files(["HIGH_RISK_DOMAIN_MISSING_HARD_CONSTRAINTS"])),
+        manual("doc-hard-drift", DOCS, "Check for constraint drift: hard constraints enforced in code but not declared in rules.md / constraints.md"),
+        auto("doc-agents-budget", DOCS, "AGENTS.md files are within their line budget", files(["AGENTS_TOO_LONG"])),
+        auto("doc-duplicates", DOCS, "No duplicated or conflicting agent rules", files(["AGENTS_DUPLICATE_RULE", "AGENTS_POTENTIAL_CONFLICT"])),
+        // One item per documentation scope; the human confirms which scopes to
+        // tidy this round via --pick-docs.
+        ...resolveDocScopes(root, config)
+            .filter((s) => !selectedScopes || selectedScopes.includes(s.key))
+            .map((s) => manual(`doc-scope-${s.key}`, DOCS, s.exists
+            ? `整理 ${s.title}：re-read, fix drift, bump last_reviewed（${s.files.length} file(s)）`
+            : `整理 ${s.title}：not present yet（${s.paths.join(" / ")}）— create it if this project needs it`, s.exists ? s.files : undefined)),
+        manual("doc-indexes", DOCS, "Run `meta sync --indexes` after the docs are tidied"),
+        // Code
+        manual("code-highrisk", CODE, "Review high-risk domain code against its rules.md", highRisk.length > 0 ? highRisk : undefined),
+        manual("code-local-agents", CODE, "Verify local AGENTS.md rules still match the code"),
+        manual("code-thirdparty", CODE, "Confirm no third-party or vendored code was modified"),
+        // Tests
+        manual("test-highrisk", TESTS, "High-risk domains have tests for normal, boundary, retry and idempotency paths", highRisk.length > 0 ? highRisk : undefined),
+        manual("test-flaky", TESTS, "Review skipped, flaky and long-quarantined tests"),
+        manual("test-conventions", TESTS, "Test suite still follows docs/engineering/testing.md"),
+        // Security
+        manual("sec-permissions", SECURITY, "Permission and authorization checks match the documented rules"),
+        manual("sec-audit-log", SECURITY, "Audit logging still covers all high-risk flows"),
+        manual("sec-deps", SECURITY, "Run a dependency audit (e.g. pnpm audit) and triage findings"),
+        manual("sec-secrets", SECURITY, "No secrets or credentials committed; .env handling reviewed"),
+        manual("sec-callbacks", SECURITY, "Webhook/callback signature validation and deduplication are intact"),
+    ];
+}
+export async function runReview(root, opts = {}, pick = (scopes) => checkbox({
+    message: "本轮整理哪些文档？（空格勾选，回车确认）",
+    choices: scopes.map((s) => ({
+        name: s.exists ? `${s.title}（${s.files.length} file(s)）` : `${s.title}（未创建）`,
+        value: s.key,
+        checked: s.exists,
+    })),
+})) {
+    let selected;
+    if (opts.pickDocs) {
+        const { config } = loadConfig(root);
+        selected = await pick(resolveDocScopes(root, config));
+        if (selected.length === 0)
+            logger.info("No doc scopes selected — docs items omitted.");
+    }
+    const items = buildReviewChecklist(root, selected);
+    if (opts.json) {
+        console.log(JSON.stringify(checklistToJson(items), null, 2));
+        return;
+    }
+    printChecklist("Periodic Repository Review Checklist", items);
+    const failed = items.filter((i) => i.status === "fail");
+    if (failed.length > 0) {
+        console.log(`Run \`meta check\` for details on the ${failed.length} failing item(s).`);
+    }
+}

package/dist/core/checklist.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A checklist mixes two kinds of items: "auto" items are evaluated by the
+ * CLI against the repository (pass/fail), "manual" items require a human
+ * and stay pending until confirmed.
+ */
+export interface ChecklistItem {
+    id: string;
+    section: string;
+    text: string;
+    kind: "auto" | "manual";
+    status: "pass" | "fail" | "pending" | "confirmed" | "declined";
+    /** Supporting evidence, e.g. offending files for a failed auto item. */
+    details?: string[];
+}
+export declare function printChecklist(title: string, items: ChecklistItem[]): void;
+export declare function checklistToJson(items: ChecklistItem[]): {
+    items: {
+        id: string;
+        section: string;
+        text: string;
+        kind: "auto" | "manual";
+        status: "fail" | "pass" | "pending" | "confirmed" | "declined";
+        details: string[];
+    }[];
+    summary: {
+        total: number;
+        auto_passed: number;
+        auto_failed: number;
+        pending: number;
+    };
+};

package/dist/core/checklist.js

@@ -0,0 +1,43 @@
+import pc from "picocolors";
+const MAX_DETAILS = 10;
+export function printChecklist(title, items) {
+    console.log(pc.bold(title));
+    const sections = [...new Set(items.map((i) => i.section))];
+    for (const section of sections) {
+        console.log();
+        console.log(pc.bold(section));
+        for (const item of items.filter((i) => i.section === section)) {
+            const mark = item.status === "pass" || item.status === "confirmed"
+                ? pc.green("✓")
+                : item.status === "fail" || item.status === "declined"
+                    ? pc.red("✗")
+                    : pc.yellow("☐");
+            console.log(`  ${mark} ${item.text}`);
+            const details = item.details ?? [];
+            for (const d of details.slice(0, MAX_DETAILS))
+                console.log(`      - ${d}`);
+            if (details.length > MAX_DETAILS) {
+                console.log(`      … and ${details.length - MAX_DETAILS} more`);
+            }
+        }
+    }
+    console.log();
+}
+export function checklistToJson(items) {
+    return {
+        items: items.map(({ id, section, text, kind, status, details }) => ({
+            id,
+            section,
+            text,
+            kind,
+            status,
+            details: details ?? [],
+        })),
+        summary: {
+            total: items.length,
+            auto_passed: items.filter((i) => i.status === "pass").length,
+            auto_failed: items.filter((i) => i.status === "fail").length,
+            pending: items.filter((i) => i.status === "pending").length,
+        },
+    };
+}

package/dist/core/doc-scopes.d.ts

@@ -0,0 +1,18 @@
+import type { MetaConfig } from "../schemas/config.schema.js";
+/**
+ * Named documentation scopes for repository maintenance. The human confirms
+ * which scopes to tidy in a given review round (`meta review --pick-docs`).
+ */
+export interface DocScope {
+    key: string;
+    title: string;
+    /** Paths relative to the repo root (resolved from config where possible). */
+    paths: string[];
+}
+export interface ResolvedDocScope extends DocScope {
+    exists: boolean;
+    /** Markdown files currently in the scope. */
+    files: string[];
+}
+export declare function docScopes(config: MetaConfig): DocScope[];
+export declare function resolveDocScopes(root: string, config: MetaConfig): ResolvedDocScope[];

package/dist/core/doc-scopes.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import { listDomainDirs } from "../validators/domain-validator.js";
+function listMarkdownFiles(abs) {
+    if (!fs.existsSync(abs))
+        return [];
+    if (fs.statSync(abs).isFile())
+        return abs.endsWith(".md") ? [abs] : [];
+    const out = [];
+    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+        const child = path.join(abs, entry.name);
+        if (entry.isDirectory())
+            out.push(...listMarkdownFiles(child));
+        else if (entry.name.endsWith(".md"))
+            out.push(child);
+    }
+    return out;
+}
+export function docScopes(config) {
+    const docs = config.paths.docs;
+    return [
+        {
+            key: "product",
+            title: "产品文档（PRD / 需求）",
+            paths: [path.join(docs, "product"), path.join(docs, "prd.md")],
+        },
+        { key: "architecture", title: "技术架构文档", paths: [path.join(docs, "architecture")] },
+        { key: "api", title: "接口文档（API）", paths: [path.join(docs, "api")] },
+        { key: "domain", title: "领域文档（业务规则）", paths: [config.paths.domain_docs] },
+        { key: "adr", title: "架构决策记录（ADR）", paths: [config.paths.adr_docs] },
+        {
+            key: "engineering",
+            title: "工程规范（测试 / 硬限制）",
+            paths: [path.join(docs, "engineering")],
+        },
+        { key: "runbooks", title: "运维手册（Runbooks）", paths: [path.join(docs, "runbooks")] },
+        { key: "agents", title: "Agent 规则（AGENTS.md）", paths: [config.paths.root_agents] },
+        { key: "openspec", title: "OpenSpec specs", paths: [path.join(config.paths.openspec, "specs")] },
+    ];
+}
+export function resolveDocScopes(root, config) {
+    return docScopes(config).map((scope) => {
+        const files = scope.paths.flatMap((rel) => listMarkdownFiles(path.join(root, rel)).map((abs) => path.relative(root, abs)));
+        // Local AGENTS.md files belong to the agents scope.
+        if (scope.key === "agents") {
+            for (const domain of listDomainDirs(root, config.paths.domain_docs)) {
+                const rel = path.join(config.paths.domain_docs, domain, "AGENTS.md");
+                if (fs.existsSync(path.join(root, rel)))
+                    files.push(rel);
+            }
+        }
+        const exists = scope.paths.some((rel) => fs.existsSync(path.join(root, rel)));
+        return { ...scope, exists, files: files.sort() };
+    });
+}

package/dist/core/frontmatter.d.ts

@@ -1,3 +1,5 @@
+/** Heading names (contains-match, case-insensitive) that declare hard constraints. */
+export declare const HARD_CONSTRAINT_HEADINGS: string[];
 export interface ParsedDoc {
     file: string;
     data: Record<string, unknown>;
@@ -10,6 +12,11 @@ export declare function parseDocFile(absPath: string): ParsedDoc;
 export declare function extractHeadings(content: string): string[];
 /** True if any heading contains one of the given texts (case-insensitive). */
 export declare function hasSection(content: string, names: string[]): boolean;
+/**
+ * Body text of the first section whose heading matches one of the given
+ * names (HTML comments stripped, trimmed). Null when no heading matches.
+ */
+export declare function extractSection(content: string, names: string[]): string | null;
 /**
  * True if there is any non-empty, non-comment body text under a matching
  * heading. Sub-headings (deeper levels) belong to the section, so their body

package/dist/core/frontmatter.js

@@ -1,5 +1,7 @@
 import fs from "node:fs";
 import matter from "gray-matter";
+/** Heading names (contains-match, case-insensitive) that declare hard constraints. */
+export const HARD_CONSTRAINT_HEADINGS = ["硬限制", "hard constraint"];
 export function parseDocFile(absPath) {
     const raw = fs.readFileSync(absPath, "utf8");
     const hasFrontmatter = /^---\r?\n/.test(raw);
@@ -45,6 +47,39 @@ export function hasSection(content, names) {
     const headings = extractHeadings(content).map((h) => h.toLowerCase());
     return names.some((n) => headings.some((h) => h.includes(n.toLowerCase())));
 }
+/**
+ * Body text of the first section whose heading matches one of the given
+ * names (HTML comments stripped, trimmed). Null when no heading matches.
+ */
+export function extractSection(content, names) {
+    const lines = content.split(/\r?\n/);
+    let capturing = false;
+    let sectionLevel = 0;
+    let inFence = false;
+    let found = false;
+    const out = [];
+    for (const line of lines) {
+        if (/^\s*(```|~~~)/.test(line))
+            inFence = !inFence;
+        const m = !inFence ? /^(#{1,6})\s+(.+?)\s*$/.exec(line) : null;
+        if (m) {
+            const level = m[1].length;
+            if (!found && names.some((n) => m[2].toLowerCase().includes(n.toLowerCase()))) {
+                capturing = true;
+                found = true;
+                sectionLevel = level;
+                continue;
+            }
+            if (capturing && level <= sectionLevel)
+                capturing = false;
+        }
+        if (capturing)
+            out.push(line);
+    }
+    if (!found)
+        return null;
+    return out.join("\n").replace(/<!--[\s\S]*?-->/g, "").trim();
+}
 /**
  * True if there is any non-empty, non-comment body text under a matching
  * heading. Sub-headings (deeper levels) belong to the section, so their body

package/dist/core/mcp-packs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * An MCP pack bundles a remote MCP server endpoint with the project-level
+ * skills that teach agents how to use it. Installing a pack writes the
+ * server into `.mcp.json` and copies the skills into `.claude/skills/`,
+ * keeping everything repository-scoped (no user-level/global tooling).
+ */
+export interface McpPack {
+    name: string;
+    title: string;
+    /** Entry written verbatim into `.mcp.json` under mcpServers[name]. */
+    server?: Record<string, unknown>;
+    /** Whether the pack bundles skills under assets/skills/<name>/. */
+    hasSkills: boolean;
+    /** Merged into `.claude/settings.json` (existing values always win). */
+    settings?: Record<string, unknown>;
+    /** Rules appended to the root AGENTS.md Working Rules when installed via init. */
+    agentRules?: string[];
+}
+export declare const MCP_PACKS: Record<string, McpPack>;
+/** Human-readable one-liner of what the pack installs. */
+export declare function packServerSummary(pack: McpPack): string;
+export declare function getMcpPack(name: string): McpPack;
+/** Bundled skills live under <package root>/assets/skills/<pack>/. */
+export declare function packSkillsDir(pack: McpPack): string;
+/** Skill files of a pack as [relative path under .claude/skills/, absolute source path]. */
+export declare function listPackSkillFiles(pack: McpPack): [string, string][];

package/dist/core/mcp-packs.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXIT_CODES, MetaError } from "./errors.js";
+export const MCP_PACKS = {
+    ironbank: {
+        name: "ironbank",
+        title: "IronBank MCP (hillinsight)",
+        server: { type: "http", url: "https://test-ib-mcp.hillinsight.tech/mcp" },
+        hasSkills: true,
+    },
+    playwright: {
+        name: "playwright",
+        title: "Playwright MCP (browser automation, microsoft/playwright-mcp)",
+        server: { command: "npx", args: ["@playwright/mcp@latest"] },
+        hasSkills: false,
+    },
+    superpowers: {
+        name: "superpowers",
+        title: "Superpowers (obra/superpowers, Claude Code plugin: planning/TDD/debugging skills)",
+        hasSkills: false,
+        settings: {
+            extraKnownMarketplaces: {
+                "superpowers-marketplace": {
+                    source: { source: "github", repo: "obra/superpowers-marketplace" },
+                },
+            },
+            enabledPlugins: {
+                "superpowers@superpowers-marketplace": true,
+            },
+        },
+        agentRules: [
+            "Do not use the Superpowers brainstorming skill during development unless the human explicitly asks for it.",
+        ],
+    },
+};
+/** Human-readable one-liner of what the pack installs. */
+export function packServerSummary(pack) {
+    if (pack.server) {
+        const { url, command, args } = pack.server;
+        if (url)
+            return url;
+        return [command, ...(args ?? [])].filter(Boolean).join(" ");
+    }
+    if (pack.settings)
+        return "Claude Code plugin (.claude/settings.json)";
+    return "skills only";
+}
+export function getMcpPack(name) {
+    const pack = MCP_PACKS[name];
+    if (!pack) {
+        throw new MetaError(`Unknown MCP pack '${name}'. Available packs: ${Object.keys(MCP_PACKS).join(", ")}`, EXIT_CODES.BAD_ARGS);
+    }
+    return pack;
+}
+/** Bundled skills live under <package root>/assets/skills/<pack>/. */
+export function packSkillsDir(pack) {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../assets/skills", pack.name);
+}
+/** Skill files of a pack as [relative path under .claude/skills/, absolute source path]. */
+export function listPackSkillFiles(pack) {
+    if (!pack.hasSkills)
+        return [];
+    const dir = packSkillsDir(pack);
+    if (!fs.existsSync(dir)) {
+        throw new MetaError(`Bundled skills for MCP pack '${pack.name}' not found at ${dir}. The CLI installation may be corrupted.`, EXIT_CODES.TEMPLATE_ERROR);
+    }
+    const out = [];
+    const walk = (abs, rel) => {
+        for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+            if (entry.name === ".DS_Store")
+                continue;
+            const childAbs = path.join(abs, entry.name);
+            const childRel = rel ? path.join(rel, entry.name) : entry.name;
+            if (entry.isDirectory())
+                walk(childAbs, childRel);
+            else
+                out.push([childRel, childAbs]);
+        }
+    };
+    walk(dir, "");
+    return out.sort((a, b) => a[0].localeCompare(b[0]));
+}

package/dist/generators/hook-generator.d.ts

@@ -0,0 +1,14 @@
+/** The `meta check` invocation appropriate for the project's package manager. */
+export declare function metaCheckCommand(root: string): string;
+export interface LefthookResult {
+    action: "created" | "updated" | "unchanged";
+    /** Path relative to root. */
+    path: string;
+    command: string;
+}
+/**
+ * Create lefthook.yml with a pre-commit meta-check command, or add the
+ * command to an existing file. An existing meta-check entry is never
+ * overwritten.
+ */
+export declare function generateLefthookConfig(root: string, dryRun: boolean): LefthookResult;

package/dist/generators/hook-generator.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
+import { detectPackageManager } from "../commands/init.js";
+/** The `meta check` invocation appropriate for the project's package manager. */
+export function metaCheckCommand(root) {
+    switch (detectPackageManager(root)) {
+        case "pnpm":
+            return "pnpm exec meta check";
+        case "yarn":
+            return "yarn exec meta check";
+        case "npm":
+            return "npx meta check";
+        default:
+            return "meta check";
+    }
+}
+const LEFTHOOK_FILENAMES = ["lefthook.yml", "lefthook.yaml"];
+/**
+ * Create lefthook.yml with a pre-commit meta-check command, or add the
+ * command to an existing file. An existing meta-check entry is never
+ * overwritten.
+ */
+export function generateLefthookConfig(root, dryRun) {
+    const existing = LEFTHOOK_FILENAMES.find((f) => fs.existsSync(path.join(root, f)));
+    const rel = existing ?? "lefthook.yml";
+    const abs = path.join(root, rel);
+    const run = metaCheckCommand(root);
+    let doc = {};
+    if (existing) {
+        try {
+            doc = YAML.parse(fs.readFileSync(abs, "utf8")) ?? {};
+        }
+        catch (e) {
+            throw new MetaError(`Cannot parse ${rel}: ${e.message}`, EXIT_CODES.CONFIG_UNPARSABLE);
+        }
+    }
+    if (typeof doc["pre-commit"] !== "object" || doc["pre-commit"] === null) {
+        doc["pre-commit"] = {};
+    }
+    const preCommit = doc["pre-commit"];
+    if (typeof preCommit["commands"] !== "object" || preCommit["commands"] === null) {
+        preCommit["commands"] = {};
+    }
+    const commands = preCommit["commands"];
+    const current = commands["meta-check"];
+    if (current) {
+        return { action: "unchanged", path: rel, command: current.run ?? "" };
+    }
+    commands["meta-check"] = { run };
+    if (!dryRun)
+        fs.writeFileSync(abs, YAML.stringify(doc), "utf8");
+    return { action: existing ? "updated" : "created", path: rel, command: run };
+}

package/dist/generators/mcp-generator.d.ts

@@ -0,0 +1,9 @@
+import type { FileWriter } from "../core/filesystem.js";
+import { type McpPack } from "../core/mcp-packs.js";
+/**
+ * Install a tool pack into the target repository:
+ * - merge the MCP server into `.mcp.json` (existing servers are never touched)
+ * - merge plugin settings into `.claude/settings.json` (existing values always win)
+ * - copy the pack's skills into `.claude/skills/` (existing files are skipped)
+ */
+export declare function installMcpPack(writer: FileWriter, root: string, pack: McpPack): void;

package/dist/generators/mcp-generator.js

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import path from "node:path";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
+import { listPackSkillFiles } from "../core/mcp-packs.js";
+const MCP_JSON = ".mcp.json";
+const CLAUDE_SETTINGS = ".claude/settings.json";
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Deep-merge source into target, adding missing keys only — existing values always win. */
+function mergeMissing(target, source) {
+    let changed = false;
+    for (const [key, value] of Object.entries(source)) {
+        if (!(key in target)) {
+            target[key] = value;
+            changed = true;
+        }
+        else if (isPlainObject(target[key]) && isPlainObject(value)) {
+            changed = mergeMissing(target[key], value) || changed;
+        }
+        // Existing non-object values are kept as-is.
+    }
+    return changed;
+}
+function readJson(root, rel) {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(abs, "utf8")) ?? {};
+    }
+    catch (e) {
+        throw new MetaError(`Cannot parse ${rel}: ${e.message}`, EXIT_CODES.CONFIG_UNPARSABLE);
+    }
+}
+/**
+ * Install a tool pack into the target repository:
+ * - merge the MCP server into `.mcp.json` (existing servers are never touched)
+ * - merge plugin settings into `.claude/settings.json` (existing values always win)
+ * - copy the pack's skills into `.claude/skills/` (existing files are skipped)
+ */
+export function installMcpPack(writer, root, pack) {
+    if (pack.server) {
+        const doc = readJson(root, MCP_JSON);
+        if (!isPlainObject(doc.mcpServers))
+            doc.mcpServers = {};
+        const servers = doc.mcpServers;
+        if (servers[pack.name]) {
+            writer.actions.push({ type: "skip", path: MCP_JSON });
+        }
+        else {
+            servers[pack.name] = pack.server;
+            writer.write(MCP_JSON, JSON.stringify(doc, null, 2) + "\n", { overwrite: true });
+        }
+    }
+    if (pack.settings) {
+        const doc = readJson(root, CLAUDE_SETTINGS);
+        if (mergeMissing(doc, pack.settings)) {
+            writer.write(CLAUDE_SETTINGS, JSON.stringify(doc, null, 2) + "\n", { overwrite: true });
+        }
+        else {
+            writer.actions.push({ type: "skip", path: CLAUDE_SETTINGS });
+        }
+    }
+    for (const [rel, srcAbs] of listPackSkillFiles(pack)) {
+        writer.write(path.join(".claude", "skills", rel), fs.readFileSync(srcAbs, "utf8"));
+    }
+}

package/dist/templates/index.d.ts

@@ -4,9 +4,9 @@
  * paths.templates). Only {{variable}} substitution is supported.
  */
 export declare const BUILTIN_TEMPLATES: {
-    readonly "agents.md": "# AGENTS.md\n\n## Project Overview\n\n- Project type: {{project_type}}\n- Package manager: {{package_manager}}\n- Main application paths: {{main_paths}}\n\n## Important Documentation\n\n- Architecture: `docs/architecture/`\n- Domain rules: `docs/domain/`\n- API conventions: `docs/api/`\n- Engineering rules: `docs/engineering/`\n- Architecture decisions: `docs/adr/`\n- Product capability specs: `openspec/specs/`\n- Active changes: `openspec/changes/`\n\n## Working Rules\n\n- Read the nearest applicable `AGENTS.md` before modifying files.\n- Read related domain documentation before changing business behavior.\n- Do not duplicate domain rules in this file.\n- Update OpenSpec specs when externally observable behavior changes.\n- Add or update tests for behavior changes.\n- Do not mix unrelated refactors into a feature change.\n\n## High-Risk Areas\n\nBefore changing payment, order, commission, settlement, withdrawal, permissions, webhooks, inventory, or audit logging, read the applicable documentation under `docs/domain/`.\n\n## Definition of Done\n\n- Relevant tests pass.\n- Type checking and lint pass where configured.\n- Behavior changes include documentation or specification updates where applicable.\n- High-risk changes include rollback and failure-path consideration.\n";
+    readonly "agents.md": "# AGENTS.md\n\n## Project Overview\n\n- Project type: {{project_type}}\n- Package manager: {{package_manager}}\n- Main application paths: {{main_paths}}\n\n## Important Documentation\n\n- Architecture: `docs/architecture/`\n- Domain rules: `docs/domain/`\n- API conventions: `docs/api/`\n- Engineering rules: `docs/engineering/`\n- Architecture decisions: `docs/adr/`\n- Product capability specs: `openspec/specs/`\n- Active changes: `openspec/changes/`\n\n## Working Rules\n\n- Read the nearest applicable `AGENTS.md` before modifying files.\n- Read related domain documentation before changing business behavior.\n- Do not modify third-party or vendored code (`node_modules/`, `vendor/`, `third_party/`, `patches/`). Wrap or extend it instead; if patching is unavoidable, record an ADR first.\n- Do not use user-level (global) skills, plugins, or MCP tools unless the human explicitly asks for them. Prefer tools, scripts, and skills defined inside this repository.\n- Never violate declared hard constraints (`docs/domain/*/rules.md` 硬限制 sections and `docs/engineering/constraints.md`). If a limit is not declared, ask the human instead of assuming it is negotiable.\n- If you are guessing, fabricating, or cannot verify a conclusion, stop and ask the human.\n- Do not duplicate domain rules in this file.\n- Update OpenSpec specs when externally observable behavior changes.\n- Add or update tests for behavior changes.\n- Do not mix unrelated refactors into a feature change.\n{{extra_rules}}\n## High-Risk Areas\n\nBefore changing payment, order, commission, settlement, withdrawal, permissions, webhooks, inventory, or audit logging, read the applicable documentation under `docs/domain/`. Hard constraints for these areas are declared in each domain's `rules.md` under 硬限制（不可违反）.\n\n## Definition of Done\n\n- Relevant tests pass.\n- Type checking and lint pass where configured.\n- A human has reviewed the change.\n- All declared hard constraints hold.\n- Behavior changes include documentation or specification updates where applicable.\n- High-risk changes include rollback and failure-path consideration.\n";
     readonly "domain-readme.md": "---\ntitle: {{domain_title}}\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}\n\n## 职责\n\n<!-- 描述该领域负责的业务能力。 -->\n\n## 非职责\n\n<!-- 明确该领域不负责什么，避免模块边界扩散。 -->\n\n## 核心对象\n\n| 对象 | 说明 |\n|---|---|\n|  |  |\n\n## 上游依赖\n\n<!-- 哪些模块、事件、服务会驱动该领域。 -->\n\n## 下游影响\n\n<!-- 该领域变化会影响哪些模块、数据、接口或用户角色。 -->\n\n## 关键规则入口\n\n- [业务规则](./rules.md)\n{{state_machine_link}}{{glossary_link}}\n\n## 关联 ADR\n\n<!-- 例如：../adr/0004-withdrawal-idempotency.md -->\n";
-    readonly "domain-rules.md": "---\ntitle: {{domain_title}}业务规则\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}业务规则\n\n## 术语\n\n<!-- 仅列出该领域特有术语；通用术语应放到 docs/domain/glossary.md。 -->\n\n## 不变量\n\n<!-- 无论何时都必须成立的规则。 -->\n\n-\n-\n-\n\n## 权限规则\n\n| 角色 | 可执行操作 | 限制 |\n|---|---|---|\n|  |  |  |\n\n## 边界条件\n\n<!-- 写清重复请求、失败重试、并发、撤销、退款、异常状态等行为。 -->\n\n## 审计与追踪\n\n<!-- 是否需要审计日志、操作人、时间、状态变更原因等。 -->\n\n## 禁止行为\n\n-\n-\n";
+    readonly "domain-rules.md": "---\ntitle: {{domain_title}}业务规则\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}业务规则\n\n## 术语\n\n<!-- 仅列出该领域特有术语；通用术语应放到 docs/domain/glossary.md。 -->\n\n## 硬限制（不可违反）\n\n<!-- 安全、数据一致性、API 契约、性能预算、兼容性、合规。 -->\n<!-- 没写在这里的限制，AI 会当成可协商的。 -->\n\n-\n-\n-\n\n## 软限制（可权衡）\n\n<!-- 代码风格偏好、非关键路径的实现细节、可后续优化的部分。 -->\n\n-\n\n## 权限规则\n\n| 角色 | 可执行操作 | 限制 |\n|---|---|---|\n|  |  |  |\n\n## 边界条件\n\n<!-- 写清重复请求、失败重试、并发、撤销、退款、异常状态等行为。 -->\n\n## 审计与追踪\n\n<!-- 是否需要审计日志、操作人、时间、状态变更原因等。 -->\n";
     readonly "domain-state-machine.md": "---\ntitle: {{domain_title}}状态机\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}状态机\n\n## 状态列表\n\n| 状态 | 含义 | 是否终态 |\n|---|---|---|\n|  |  | 否 |\n\n## 状态流转\n\n```mermaid\nstateDiagram-v2\n  [*] --> pending\n  pending --> completed\n  pending --> cancelled\n```\n\n## 流转规则\n\n| 当前状态 | 触发事件 | 下一个状态 | 前置条件 | 副作用 |\n| ---- | ---- | ----- | ---- | --- |\n|      |      |       |      |     |\n\n## 幂等规则\n\n<!-- 对重复请求、重复事件、重复回调的处理规则。 -->\n";
     readonly "domain-glossary.md": "---\ntitle: {{domain_title}}术语表\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}术语表\n\n| 术语 | 定义 | 备注 |\n|---|---|---|\n|  |  |  |\n";
     readonly "domain-agents.md": "# {{domain_title}} Module Rules\n\n## Scope\n\nThis directory contains the {{domain_title}} domain.\n\n## Required Reading\n\n- `README.md`\n- `rules.md`\n{{state_machine_reading}}\n\n## Rules for Agents\n\n- Do not change domain behavior without updating the relevant domain documentation.\n- Do not introduce new states without updating `state-machine.md`.\n- Preserve existing audit and idempotency behavior.\n- Keep business rules out of controllers and UI components.\n- Add tests for normal, boundary, and retry scenarios.\n\n## Review Checklist\n\n- Are permissions affected?\n- Are money, inventory, or externally triggered callbacks affected?\n- Is retry or duplicate handling required?\n- Does this change require an ADR?\n";
@@ -18,6 +18,11 @@ export declare const BUILTIN_TEMPLATES: {
     readonly "system-overview.md": "---\ntitle: 系统架构总览\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# 系统架构总览\n\n## 系统边界\n\n<!-- 系统包含哪些应用 / 服务。 -->\n\n## 模块划分\n\n<!-- 主要模块与职责。 -->\n\n## 关键依赖\n\n<!-- 数据库、消息队列、第三方服务。 -->\n";
     readonly "api-conventions.md": "---\ntitle: API 约定\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# API 约定\n\n## 命名与版本\n\n## 错误码规范\n\n## 鉴权约定\n";
     readonly "engineering-testing.md": "---\ntitle: 测试规范\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# 测试规范\n\n## 必须覆盖的场景\n\n- 正常路径\n- 边界条件\n- 重试与幂等\n\n## 工具与命令\n";
+    readonly "engineering-constraints.md": "---\ntitle: 项目级硬限制\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# 项目级硬限制\n\n<!-- 跨领域的硬限制放这里；单个领域的硬限制放 docs/domain/<domain>/rules.md。 -->\n\n## 硬限制（不可违反）\n\n<!-- 类别参考：安全、数据一致性、API 契约、性能预算、兼容性、合规。 -->\n<!-- 没写在这里的限制，AI 会当成可协商的。 -->\n\n-\n-\n\n## 软限制（可权衡）\n\n<!-- 代码风格偏好、非关键路径的实现细节、可后续优化的部分。 -->\n\n-\n";
     readonly "runbooks-readme.md": "---\ntitle: Runbooks\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# Runbooks\n\n<!-- 运维手册与故障处理流程。 -->\n";
+    readonly "change-proposal.md": "# {{change_title}}\n\n## Why\n\n<!-- 为什么要做这个变更？解决什么问题？ -->\n\n## What Changes\n\n<!-- 变更内容概述：新增/修改/移除哪些能力。 -->\n\n## Impact\n\n- Affected domains: {{domain}}\n- Affected specs:\n- Affected code:\n";
+    readonly "change-design.md": "# {{change_title}} — Design\n\n## Context\n\n<!-- 现状与约束。 -->\n\n## Goals / Non-Goals\n\n- Goals:\n- Non-Goals:\n\n## Decisions\n\n<!-- 关键技术决策；长期决策请沉淀为 ADR（meta new-adr）。 -->\n\n## Hard Constraints（硬限制核对）\n\n<!-- 列出本变更涉及的已声明硬限制与核对结论。 -->\n<!-- 来源：docs/domain/<domain>/rules.md 硬限制章节、docs/engineering/constraints.md。 -->\n\n| 硬限制 | 来源 | 核对结论 |\n|---|---|---|\n|  |  |  |\n\n## Risks / Trade-offs\n\n<!-- 风险与权衡。 -->\n";
+    readonly "change-tasks.md": "# {{change_title}} — Tasks\n\n## 1. Implementation\n\n- [ ] 1.1\n- [ ] 1.2\n\n## 2. Validation\n\n- [ ] 2.1 Tests updated\n- [ ] 2.2 `meta check` passes\n";
+    readonly "change-risk-review.md": "# {{change_title}} — Risk Review\n\n- Related domain: {{domain}}\n- Date: {{date}}\n\n## Checklist\n\n- [ ] Money representation（金额表示与精度）\n- [ ] Idempotency（幂等）\n- [ ] Retry behavior（重试行为）\n- [ ] Callback deduplication（回调去重）\n- [ ] Audit logging（审计日志）\n- [ ] Permission boundaries（权限边界）\n- [ ] Rollback plan（回滚方案）\n- [ ] Declared hard constraints checked（已声明的硬限制全部核对）\n\n## Notes\n\n<!-- 每项勾选前写清结论或“不适用”的原因。 -->\n";
 };
 export type TemplateName = keyof typeof BUILTIN_TEMPLATES;