@bossmissing/agent-meta 0.1.0

package/dist/commands/check.js

@@ -0,0 +1,109 @@
+import pc from "picocolors";
+import { loadConfig } from "../core/config.js";
+import { EXIT_CODES } from "../core/errors.js";
+import { summarize } from "../core/types.js";
+import { validateProject } from "../validators/project-validator.js";
+import { validateDocs } from "../validators/docs-validator.js";
+import { validateAdrs } from "../validators/adr-validator.js";
+import { validateAgents } from "../validators/agents-validator.js";
+import { validateDomains } from "../validators/domain-validator.js";
+import { validateOpenSpec } from "../validators/openspec-validator.js";
+export function runCheck(root, opts = {}) {
+    const { config, configPath } = loadConfig(root);
+    const ctx = { root, config, configFound: configPath !== null };
+    const scoped = Boolean(opts.docs || opts.adr || opts.agents || opts.openspec);
+    const issues = [];
+    let checkedFiles = 0;
+    const run = (fn) => {
+        // A single broken validator must not crash the whole check.
+        try {
+            const r = fn(ctx);
+            issues.push(...r.issues);
+            checkedFiles += r.checkedFiles;
+        }
+        catch (e) {
+            issues.push({
+                code: "CHECK_INTERNAL_ERROR",
+                severity: "error",
+                message: `Validator crashed: ${e.message}`,
+            });
+        }
+    };
+    if (!scoped) {
+        run(validateProject);
+        run(validateDocs);
+        run(validateAdrs);
+        run(validateAgents);
+        run(validateDomains);
+        run(validateOpenSpec);
+    }
+    else {
+        if (opts.docs)
+            run(validateDocs);
+        if (opts.adr)
+            run(validateAdrs);
+        if (opts.agents)
+            run(validateAgents);
+        if (opts.openspec)
+            run(validateOpenSpec);
+    }
+    return summarize(issues, checkedFiles);
+}
+export function printCheckResult(result, strict) {
+    console.log(pc.bold("Agent Meta Check"));
+    console.log();
+    const errors = result.issues.filter((i) => i.severity === "error");
+    const warnings = result.issues.filter((i) => i.severity === "warning");
+    if (result.issues.length === 0) {
+        console.log(`${pc.green("✓")} No issues found (${result.summary.checkedFiles} files checked)`);
+    }
+    for (const issue of errors) {
+        console.log(`${pc.red("ERROR")} ${pc.bold(issue.code)}`);
+        if (issue.file)
+            console.log(`${issue.file}${issue.line ? `:${issue.line}` : ""}`);
+        console.log();
+        console.log(issue.message);
+        if (issue.suggestion) {
+            console.log();
+            console.log("Fix:");
+            console.log(issue.suggestion);
+        }
+        console.log();
+    }
+    for (const issue of warnings) {
+        console.log(`${pc.yellow("WARN")} ${issue.file ?? ""}${issue.line ? `:${issue.line}` : ""}`);
+        console.log(`  ${issue.message}`);
+        if (issue.suggestion)
+            console.log(`  Suggestion: ${issue.suggestion}`);
+        console.log();
+    }
+    const label = result.status === "failed"
+        ? pc.red("FAILED")
+        : result.status === "passed_with_warnings"
+            ? strict
+                ? pc.red("FAILED (strict: warnings treated as errors)")
+                : pc.yellow("PASS WITH WARNINGS")
+            : pc.green("PASS");
+    console.log(`Result: ${label}`);
+    console.log(`Errors: ${result.summary.errors}`);
+    console.log(`Warnings: ${result.summary.warnings}`);
+}
+export function checkExitCode(result, strict) {
+    if (result.summary.errors > 0)
+        return EXIT_CODES.CHECK_FAILED;
+    if (strict && result.summary.warnings > 0)
+        return EXIT_CODES.CHECK_FAILED;
+    return EXIT_CODES.OK;
+}
+export function toJsonOutput(result) {
+    return {
+        status: result.status,
+        errors: result.issues
+            .filter((i) => i.severity === "error")
+            .map(({ code, file, line, message, suggestion }) => ({ code, file, line, message, suggestion })),
+        warnings: result.issues
+            .filter((i) => i.severity === "warning")
+            .map(({ code, file, line, message, suggestion }) => ({ code, file, line, message, suggestion })),
+        summary: result.summary,
+    };
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+export declare function runConfigList(root: string): void;
+export declare function runConfigSet(root: string, key: string, value: string): void;

package/dist/commands/config.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { loadConfig, CONFIG_FILENAME } from "../core/config.js";
+import { configSchema } from "../schemas/config.schema.js";
+import { logger } from "../core/logger.js";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
+function flatten(obj, prefix = "") {
+    if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+        return [[prefix, obj]];
+    }
+    const out = [];
+    for (const [k, v] of Object.entries(obj)) {
+        out.push(...flatten(v, prefix ? `${prefix}.${k}` : k));
+    }
+    return out;
+}
+export function runConfigList(root) {
+    const { config } = loadConfig(root);
+    for (const [key, value] of flatten(config)) {
+        const rendered = Array.isArray(value) ? `[${value.join(", ")}]` : String(value);
+        logger.info(`${key} = ${rendered}`);
+    }
+}
+function coerce(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (/^-?\d+$/.test(value))
+        return parseInt(value, 10);
+    if (/^-?\d+\.\d+$/.test(value))
+        return parseFloat(value);
+    return value;
+}
+export function runConfigSet(root, key, value) {
+    const configPath = path.join(root, CONFIG_FILENAME);
+    if (!fs.existsSync(configPath)) {
+        throw new MetaError(`${CONFIG_FILENAME} not found. Run \`meta init\` first.`, EXIT_CODES.CONFIG_UNPARSABLE);
+    }
+    const doc = YAML.parse(fs.readFileSync(configPath, "utf8")) ?? {};
+    const parts = key.split(".");
+    let cursor = doc;
+    for (const part of parts.slice(0, -1)) {
+        if (typeof cursor[part] !== "object" || cursor[part] === null)
+            cursor[part] = {};
+        cursor = cursor[part];
+    }
+    cursor[parts[parts.length - 1]] = coerce(value);
+    const validated = configSchema.safeParse(doc);
+    if (!validated.success) {
+        const details = validated.error.issues
+            .map((i) => `  ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new MetaError(`Invalid value for ${key}:\n${details}`, EXIT_CODES.BAD_ARGS);
+    }
+    fs.writeFileSync(configPath, YAML.stringify(doc), "utf8");
+    logger.ok(`Set ${key} = ${value}`);
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,8 @@
+export interface InitOptions {
+    yes?: boolean;
+    type?: string;
+    dryRun?: boolean;
+}
+export declare function detectProjectType(root: string): string;
+export declare function detectPackageManager(root: string): string;
+export declare function runInit(root: string, opts: InitOptions): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { input, select } from "@inquirer/prompts";
+import { FileWriter } from "../core/filesystem.js";
+import { logger } from "../core/logger.js";
+import { renderNamedTemplate } from "../core/templates.js";
+import { todayISO } from "../core/paths.js";
+import { configSchema, DEFAULT_CONFIG } from "../schemas/config.schema.js";
+import { CONFIG_FILENAME, configExists } from "../core/config.js";
+import { padAdrNumber } from "../generators/adr-generator.js";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
+const PROJECT_TYPES = ["node", "monorepo", "nextjs", "cocos", "backend", "other"];
+export function detectProjectType(root) {
+    if (fs.existsSync(path.join(root, "pnpm-workspace.yaml")))
+        return "monorepo";
+    const pkgPath = path.join(root, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps?.next)
+                return "nextjs";
+            if (deps?.["@nestjs/core"])
+                return "backend";
+            return "node";
+        }
+        catch {
+            return "node";
+        }
+    }
+    if (fs.existsSync(path.join(root, "project.json")) && fs.existsSync(path.join(root, "assets")))
+        return "cocos";
+    return "other";
+}
+export function detectPackageManager(root) {
+    if (fs.existsSync(path.join(root, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (fs.existsSync(path.join(root, "yarn.lock")))
+        return "yarn";
+    if (fs.existsSync(path.join(root, "package-lock.json")))
+        return "npm";
+    if (fs.existsSync(path.join(root, "package.json")))
+        return "npm";
+    return "none";
+}
+export async function runInit(root, opts) {
+    const dryRun = Boolean(opts.dryRun);
+    const writer = new FileWriter(root, dryRun);
+    const templatesDir = DEFAULT_CONFIG.paths.templates;
+    const date = todayISO();
+    const detectedType = detectProjectType(root);
+    const packageManager = detectPackageManager(root);
+    let projectName = path.basename(root);
+    let projectType = opts.type ?? detectedType;
+    if (opts.type && !PROJECT_TYPES.includes(opts.type)) {
+        throw new MetaError(`Unknown project type '${opts.type}'. Valid types: ${PROJECT_TYPES.join(", ")}`, EXIT_CODES.BAD_ARGS);
+    }
+    if (!opts.yes) {
+        projectName = await input({ message: "项目名称：", default: projectName });
+        if (!opts.type) {
+            projectType = await select({
+                message: "项目类型：",
+                choices: [
+                    { name: "Node.js / TypeScript", value: "node" },
+                    { name: "Monorepo", value: "monorepo" },
+                    { name: "Next.js / Fullstack", value: "nextjs" },
+                    { name: "Cocos / 游戏", value: "cocos" },
+                    { name: "Backend Service", value: "backend" },
+                    { name: "Other", value: "other" },
+                ],
+                default: detectedType,
+            });
+        }
+    }
+    // Existing AGENTS.md handling.
+    const agentsRel = DEFAULT_CONFIG.paths.root_agents;
+    let agentsAction = writer.exists(agentsRel) ? "keep" : "create";
+    if (agentsAction === "keep" && !opts.yes) {
+        const choice = await select({
+            message: `发现已有 ${agentsRel}。如何处理？`,
+            choices: [
+                { name: "保留，不修改", value: "keep" },
+                { name: "备份为 AGENTS.md.bak 后重新生成", value: "backup" },
+                { name: "退出", value: "exit" },
+            ],
+            default: "keep",
+        });
+        if (choice === "exit") {
+            logger.info("Aborted.");
+            return;
+        }
+        agentsAction = choice;
+    }
+    logger.blank();
+    if (dryRun)
+        logger.info("Dry run — no files will be written.\n");
+    // 1. agent-meta.config.yaml
+    if (!configExists(root)) {
+        const config = configSchema.parse({
+            project: { name: projectName, type: projectType, package_manager: packageManager },
+        });
+        writer.write(CONFIG_FILENAME, YAML.stringify(config));
+    }
+    else {
+        writer.actions.push({ type: "skip", path: CONFIG_FILENAME });
+    }
+    // 2. AGENTS.md
+    const agentsVars = {
+        project_type: projectType,
+        package_manager: packageManager,
+        main_paths: "src/",
+    };
+    if (agentsAction === "backup") {
+        writer.backup(agentsRel);
+        writer.write(agentsRel, renderNamedTemplate("agents.md", root, templatesDir, agentsVars), {
+            overwrite: true,
+        });
+    }
+    else if (agentsAction === "create") {
+        writer.write(agentsRel, renderNamedTemplate("agents.md", root, templatesDir, agentsVars));
+    }
+    else {
+        writer.actions.push({ type: "skip", path: agentsRel });
+    }
+    // 3. docs skeleton
+    const owner = projectName || "team";
+    const vars = { owner, date };
+    writer.write("docs/domain/README.md", renderNamedTemplate("domain-index-readme.md", root, templatesDir, vars));
+    writer.write("docs/domain/glossary.md", renderNamedTemplate("glossary.md", root, templatesDir, vars));
+    writer.write("docs/adr/README.md", renderNamedTemplate("adr-index-readme.md", root, templatesDir, vars));
+    writer.write("docs/architecture/system-overview.md", renderNamedTemplate("system-overview.md", root, templatesDir, vars));
+    writer.write("docs/api/conventions.md", renderNamedTemplate("api-conventions.md", root, templatesDir, vars));
+    writer.write("docs/engineering/testing.md", renderNamedTemplate("engineering-testing.md", root, templatesDir, vars));
+    writer.write("docs/runbooks/README.md", renderNamedTemplate("runbooks-readme.md", root, templatesDir, vars));
+    // 4. First ADR
+    const adrNumber = padAdrNumber(1, DEFAULT_CONFIG.defaults.adr_padding);
+    writer.write(`docs/adr/${adrNumber}-repository-conventions.md`, renderNamedTemplate("adr-0001.md", root, templatesDir, { adr_number: adrNumber, owner, date }));
+    // Report
+    if (dryRun) {
+        const created = writer.created();
+        if (created.length > 0) {
+            logger.info("Would create:");
+            for (const a of created)
+                logger.info(`  ${a.path}`);
+        }
+        const updated = writer.actions.filter((a) => a.type === "update" || a.type === "backup");
+        if (updated.length > 0) {
+            logger.info("Would update:");
+            for (const a of updated)
+                logger.info(`  ${a.path}`);
+        }
+        const skipped = writer.skipped();
+        if (skipped.length > 0) {
+            logger.info("Would skip (already exists):");
+            for (const a of skipped)
+                logger.info(`  ${a.path}`);
+        }
+        return;
+    }
+    for (const a of writer.actions) {
+        if (a.type === "create")
+            logger.ok(`Created ${a.path}`);
+        else if (a.type === "update")
+            logger.ok(`Updated ${a.path}`);
+        else if (a.type === "backup")
+            logger.ok(`Backed up to ${a.path}`);
+        else
+            logger.info(`- Skipped ${a.path} (already exists)`);
+    }
+    if (fs.existsSync(path.join(root, DEFAULT_CONFIG.paths.openspec))) {
+        logger.ok(`OpenSpec detected at ${DEFAULT_CONFIG.paths.openspec}/`);
+    }
+    logger.blank();
+    logger.info("Next steps:");
+    logger.info("1. Fill in AGENTS.md project commands.");
+    logger.info("2. Add domain docs for core business modules: meta new-domain <name>");
+    logger.info("3. Run: meta check");
+}

package/dist/commands/new-adr.d.ts

@@ -0,0 +1,8 @@
+export interface NewAdrOptions {
+    title?: string;
+    owner?: string;
+    status?: string;
+    path?: string;
+    dryRun?: boolean;
+}
+export declare function runNewAdr(root: string, name: string, opts: NewAdrOptions): void;

package/dist/commands/new-adr.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { FileWriter } from "../core/filesystem.js";
+import { logger } from "../core/logger.js";
+import { loadConfig } from "../core/config.js";
+import { renderNamedTemplate } from "../core/templates.js";
+import { slugify, todayISO } from "../core/paths.js";
+import { nextAdrNumber, padAdrNumber, listAdrFiles } from "../generators/adr-generator.js";
+import { updateAdrIndex } from "../generators/index-generator.js";
+import { VALID_ADR_STATUSES } from "../validators/adr-validator.js";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
+export function runNewAdr(root, name, opts) {
+    const { config } = loadConfig(root);
+    const slug = slugify(name);
+    if (!slug) {
+        throw new MetaError(`Cannot derive a slug from '${name}'.`, EXIT_CODES.BAD_ARGS);
+    }
+    const status = opts.status ?? "proposed";
+    if (!VALID_ADR_STATUSES.includes(status)) {
+        throw new MetaError(`Invalid ADR status '${status}'. Valid: ${VALID_ADR_STATUSES.join(", ")}`, EXIT_CODES.BAD_ARGS);
+    }
+    const relDir = opts.path ?? config.paths.adr_docs;
+    const absDir = path.join(root, relDir);
+    const duplicateSlug = listAdrFiles(absDir).find((f) => f.slug === slug);
+    if (duplicateSlug) {
+        throw new MetaError(`An ADR with slug '${slug}' already exists: ${path.basename(duplicateSlug.file)}`, EXIT_CODES.CHECK_FAILED);
+    }
+    const number = nextAdrNumber(absDir);
+    const numberStr = padAdrNumber(number, config.defaults.adr_padding);
+    const fileRel = path.join(relDir, `${numberStr}-${slug}.md`);
+    const title = opts.title ?? slug;
+    const owner = opts.owner || config.project.name || "team";
+    const content = renderNamedTemplate("adr.md", root, config.paths.templates, {
+        adr_number: numberStr,
+        title,
+        status,
+        date: todayISO(),
+        owner,
+        slug,
+    });
+    const writer = new FileWriter(root, Boolean(opts.dryRun));
+    try {
+        // Exclusive create: two concurrent invocations can never share a number.
+        writer.writeExclusive(fileRel, content);
+    }
+    catch (e) {
+        throw new MetaError(e.message, EXIT_CODES.CHECK_FAILED);
+    }
+    if (config.features.generate_indexes && !opts.dryRun) {
+        updateAdrIndex(writer, root, config);
+    }
+    if (opts.dryRun) {
+        logger.info("Would create:");
+        logger.info(`  ${fileRel}`);
+        if (config.features.generate_indexes) {
+            logger.info("Would update:");
+            logger.info(`  ${path.join(relDir, "README.md")}`);
+        }
+    }
+    else {
+        logger.ok(`Created ${fileRel}`);
+        if (config.features.generate_indexes) {
+            logger.ok(`Updated ${path.join(relDir, "README.md")}`);
+        }
+    }
+}

package/dist/commands/new-domain.d.ts

@@ -0,0 +1,13 @@
+export interface NewDomainOptions {
+    title?: string;
+    owner?: string;
+    path?: string;
+    withStateMachine?: boolean;
+    withGlossary?: boolean;
+    withLocalAgents?: boolean;
+    /** Commander sets this to false for --no-local-agents. */
+    localAgents?: boolean;
+    force?: boolean;
+    dryRun?: boolean;
+}
+export declare function runNewDomain(root: string, name: string, opts: NewDomainOptions): void;

package/dist/commands/new-domain.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FileWriter } from "../core/filesystem.js";
+import { logger } from "../core/logger.js";
+import { loadConfig } from "../core/config.js";
+import { renderNamedTemplate } from "../core/templates.js";
+import { slugify, todayISO } from "../core/paths.js";
+import { matchRiskKeywords } from "../core/risk.js";
+import { updateDomainIndex } from "../generators/index-generator.js";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
+export function runNewDomain(root, name, opts) {
+    const { config } = loadConfig(root);
+    const slug = slugify(name);
+    if (!slug) {
+        throw new MetaError(`Cannot derive a kebab-case directory name from '${name}'. Use an ASCII name and set the Chinese title via --title.`, EXIT_CODES.BAD_ARGS);
+    }
+    const relDir = opts.path ?? path.join(config.paths.domain_docs, slug);
+    const absDir = path.join(root, relDir);
+    const dirExists = fs.existsSync(absDir);
+    if (dirExists && !opts.force) {
+        throw new MetaError(`Domain directory already exists: ${relDir}\nUse --force to create missing files only (existing content is never overwritten).`, EXIT_CODES.CHECK_FAILED);
+    }
+    const title = opts.title ?? name;
+    const owner = opts.owner || config.project.name || "team";
+    const date = todayISO();
+    const templatesDir = config.paths.templates;
+    const withStateMachine = opts.withStateMachine ?? config.domain.create_state_machine_by_default;
+    const withGlossary = opts.withGlossary ?? config.domain.create_glossary_by_default;
+    const withLocalAgents = opts.localAgents === false
+        ? false
+        : (opts.withLocalAgents ?? config.domain.create_local_agents_by_default);
+    const withRules = config.domain.create_rules_by_default;
+    const vars = {
+        domain_name: slug,
+        domain_title: title,
+        owner,
+        date,
+        slug,
+        state_machine_link: withStateMachine ? "- [状态机](./state-machine.md)\n" : "",
+        glossary_link: withGlossary ? "- [术语表](./glossary.md)\n" : "",
+        state_machine_reading: withStateMachine ? "- `state-machine.md`" : "",
+    };
+    const writer = new FileWriter(root, Boolean(opts.dryRun));
+    // --force only fills in missing files; FileWriter.write never overwrites here.
+    writer.write(path.join(relDir, "README.md"), renderNamedTemplate("domain-readme.md", root, templatesDir, vars));
+    if (withRules) {
+        writer.write(path.join(relDir, "rules.md"), renderNamedTemplate("domain-rules.md", root, templatesDir, vars));
+    }
+    if (withStateMachine) {
+        writer.write(path.join(relDir, "state-machine.md"), renderNamedTemplate("domain-state-machine.md", root, templatesDir, vars));
+    }
+    if (withGlossary) {
+        writer.write(path.join(relDir, "glossary.md"), renderNamedTemplate("domain-glossary.md", root, templatesDir, vars));
+    }
+    if (withLocalAgents) {
+        writer.write(path.join(relDir, "AGENTS.md"), renderNamedTemplate("domain-agents.md", root, templatesDir, vars));
+    }
+    if (config.features.generate_indexes && !opts.dryRun) {
+        updateDomainIndex(writer, root, config);
+    }
+    if (opts.dryRun) {
+        logger.info("Would create:");
+        for (const a of writer.created())
+            logger.info(`  ${a.path}`);
+        for (const a of writer.skipped())
+            logger.info(`  (skip, exists) ${a.path}`);
+        if (config.features.generate_indexes) {
+            logger.info("Would update:");
+            logger.info(`  ${path.join(config.paths.domain_docs, "README.md")}`);
+        }
+    }
+    else {
+        for (const a of writer.created())
+            logger.ok(`Created ${a.path}`);
+        for (const a of writer.updated())
+            logger.ok(`Updated ${a.path}`);
+        for (const a of writer.skipped())
+            logger.info(`- Skipped ${a.path} (already exists)`);
+    }
+    const riskHits = matchRiskKeywords(slug, config.risk_keywords);
+    if (riskHits.length > 0) {
+        logger.blank();
+        logger.warn(`⚠ High-risk domain detected: ${slug} (matched: ${riskHits.join(", ")})`);
+        logger.blank();
+        const missing = [];
+        if (!withStateMachine)
+            missing.push("  --with-state-machine");
+        if (!withLocalAgents)
+            missing.push("  --with-local-agents");
+        if (!withGlossary)
+            missing.push("  --with-glossary");
+        if (missing.length > 0) {
+            logger.info("Recommended options:");
+            for (const m of missing)
+                logger.info(m);
+            logger.blank();
+        }
+        logger.info("Also consider creating ADRs for:");
+        logger.info("  - idempotency");
+        logger.info("  - audit logging");
+        logger.info("  - money storage");
+        logger.info("  - retry strategy");
+        logger.blank();
+        logger.info(`Recommended next command:\n  meta new-adr ${slug}-idempotency`);
+    }
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,7 @@
+export interface SyncOptions {
+    indexes?: boolean;
+    openspec?: boolean;
+    templates?: boolean;
+    dryRun?: boolean;
+}
+export declare function runSync(root: string, opts: SyncOptions): void;

package/dist/commands/sync.js

@@ -0,0 +1,46 @@
+import { execSync } from "node:child_process";
+import path from "node:path";
+import fs from "node:fs";
+import { FileWriter } from "../core/filesystem.js";
+import { logger } from "../core/logger.js";
+import { loadConfig } from "../core/config.js";
+import { updateAdrIndex, updateDomainIndex } from "../generators/index-generator.js";
+export function runSync(root, opts) {
+    const { config } = loadConfig(root);
+    const all = !opts.indexes && !opts.openspec && !opts.templates;
+    if (all || opts.indexes) {
+        const writer = new FileWriter(root, Boolean(opts.dryRun));
+        updateDomainIndex(writer, root, config);
+        updateAdrIndex(writer, root, config);
+        for (const a of writer.actions) {
+            if (a.type === "skip")
+                continue;
+            if (opts.dryRun)
+                logger.info(`Would update: ${a.path}`);
+            else
+                logger.ok(`Updated ${a.path}`);
+        }
+    }
+    if (all || opts.openspec) {
+        const openspecDir = path.join(root, config.paths.openspec);
+        if (!fs.existsSync(openspecDir)) {
+            if (opts.openspec)
+                logger.info("No openspec/ directory found; skipping OpenSpec sync.");
+        }
+        else if (opts.dryRun) {
+            logger.info("Would run: openspec update");
+        }
+        else {
+            try {
+                execSync("openspec update", { cwd: root, stdio: "inherit" });
+                logger.ok("OpenSpec updated");
+            }
+            catch {
+                logger.warn("Could not run `openspec update` (is the OpenSpec CLI installed?). Skipped.");
+            }
+        }
+    }
+    if (opts.templates) {
+        logger.info("Template sync is planned for a later release (team template packs).");
+    }
+}

package/dist/core/config.d.ts

@@ -0,0 +1,15 @@
+import { type MetaConfig } from "../schemas/config.schema.js";
+export declare const CONFIG_FILENAME = "agent-meta.config.yaml";
+export interface LoadedConfig {
+    config: MetaConfig;
+    /** Absolute path of the config file, or null when running on built-in defaults. */
+    configPath: string | null;
+}
+/**
+ * Load agent-meta.config.yaml from the given directory, falling back to
+ * built-in defaults when the file does not exist. An unparsable or invalid
+ * config throws MetaError with exit code 3.
+ */
+export declare function loadConfig(cwd: string): LoadedConfig;
+export declare function configExists(cwd: string): boolean;
+export declare function saveConfig(cwd: string, config: MetaConfig): string;

package/dist/core/config.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { configSchema, DEFAULT_CONFIG } from "../schemas/config.schema.js";
+import { EXIT_CODES, MetaError } from "./errors.js";
+export const CONFIG_FILENAME = "agent-meta.config.yaml";
+/**
+ * Load agent-meta.config.yaml from the given directory, falling back to
+ * built-in defaults when the file does not exist. An unparsable or invalid
+ * config throws MetaError with exit code 3.
+ */
+export function loadConfig(cwd) {
+    const configPath = path.join(cwd, CONFIG_FILENAME);
+    if (!fs.existsSync(configPath)) {
+        return { config: DEFAULT_CONFIG, configPath: null };
+    }
+    let raw;
+    try {
+        raw = YAML.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch (e) {
+        throw new MetaError(`Cannot parse ${CONFIG_FILENAME}: ${e.message}`, EXIT_CODES.CONFIG_UNPARSABLE);
+    }
+    const parsed = configSchema.safeParse(raw ?? {});
+    if (!parsed.success) {
+        const details = parsed.error.issues
+            .map((i) => `  ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new MetaError(`Invalid ${CONFIG_FILENAME}:\n${details}`, EXIT_CODES.CONFIG_UNPARSABLE);
+    }
+    return { config: parsed.data, configPath };
+}
+export function configExists(cwd) {
+    return fs.existsSync(path.join(cwd, CONFIG_FILENAME));
+}
+export function saveConfig(cwd, config) {
+    const configPath = path.join(cwd, CONFIG_FILENAME);
+    fs.writeFileSync(configPath, YAML.stringify(config), "utf8");
+    return configPath;
+}