@bossmissing/agent-meta 0.1.0

package/dist/schemas/config.schema.d.ts

@@ -0,0 +1,208 @@
+import { z } from "zod";
+export declare const DEFAULT_RISK_KEYWORDS: string[];
+export declare const configSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodNumber>;
+    project: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        type: z.ZodDefault<z.ZodString>;
+        package_manager: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        type: string;
+        package_manager: string;
+    }, {
+        name?: string | undefined;
+        type?: string | undefined;
+        package_manager?: string | undefined;
+    }>>;
+    paths: z.ZodDefault<z.ZodObject<{
+        root_agents: z.ZodDefault<z.ZodString>;
+        docs: z.ZodDefault<z.ZodString>;
+        domain_docs: z.ZodDefault<z.ZodString>;
+        adr_docs: z.ZodDefault<z.ZodString>;
+        openspec: z.ZodDefault<z.ZodString>;
+        templates: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        root_agents: string;
+        docs: string;
+        domain_docs: string;
+        adr_docs: string;
+        openspec: string;
+        templates: string;
+    }, {
+        root_agents?: string | undefined;
+        docs?: string | undefined;
+        domain_docs?: string | undefined;
+        adr_docs?: string | undefined;
+        openspec?: string | undefined;
+        templates?: string | undefined;
+    }>>;
+    defaults: z.ZodDefault<z.ZodObject<{
+        doc_status: z.ZodDefault<z.ZodString>;
+        review_interval_days: z.ZodDefault<z.ZodNumber>;
+        adr_padding: z.ZodDefault<z.ZodNumber>;
+        agents_max_lines: z.ZodDefault<z.ZodNumber>;
+        local_agents_max_lines: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        doc_status: string;
+        review_interval_days: number;
+        adr_padding: number;
+        agents_max_lines: number;
+        local_agents_max_lines: number;
+    }, {
+        doc_status?: string | undefined;
+        review_interval_days?: number | undefined;
+        adr_padding?: number | undefined;
+        agents_max_lines?: number | undefined;
+        local_agents_max_lines?: number | undefined;
+    }>>;
+    features: z.ZodDefault<z.ZodObject<{
+        openspec: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"auto">]>>;
+        hooks: z.ZodDefault<z.ZodBoolean>;
+        docs_frontmatter: z.ZodDefault<z.ZodBoolean>;
+        generate_indexes: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        openspec: boolean | "auto";
+        hooks: boolean;
+        docs_frontmatter: boolean;
+        generate_indexes: boolean;
+    }, {
+        openspec?: boolean | "auto" | undefined;
+        hooks?: boolean | undefined;
+        docs_frontmatter?: boolean | undefined;
+        generate_indexes?: boolean | undefined;
+    }>>;
+    domain: z.ZodDefault<z.ZodObject<{
+        create_local_agents_by_default: z.ZodDefault<z.ZodBoolean>;
+        create_rules_by_default: z.ZodDefault<z.ZodBoolean>;
+        create_state_machine_by_default: z.ZodDefault<z.ZodBoolean>;
+        create_glossary_by_default: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        create_local_agents_by_default: boolean;
+        create_rules_by_default: boolean;
+        create_state_machine_by_default: boolean;
+        create_glossary_by_default: boolean;
+    }, {
+        create_local_agents_by_default?: boolean | undefined;
+        create_rules_by_default?: boolean | undefined;
+        create_state_machine_by_default?: boolean | undefined;
+        create_glossary_by_default?: boolean | undefined;
+    }>>;
+    validation: z.ZodDefault<z.ZodObject<{
+        require_doc_frontmatter: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        required_frontmatter: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        stale_review_days: z.ZodDefault<z.ZodObject<{
+            active: z.ZodDefault<z.ZodNumber>;
+            draft: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            active: number;
+            draft: number;
+        }, {
+            active?: number | undefined;
+            draft?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        require_doc_frontmatter: string[];
+        required_frontmatter: string[];
+        stale_review_days: {
+            active: number;
+            draft: number;
+        };
+    }, {
+        require_doc_frontmatter?: string[] | undefined;
+        required_frontmatter?: string[] | undefined;
+        stale_review_days?: {
+            active?: number | undefined;
+            draft?: number | undefined;
+        } | undefined;
+    }>>;
+    risk_keywords: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    version: number;
+    validation: {
+        require_doc_frontmatter: string[];
+        required_frontmatter: string[];
+        stale_review_days: {
+            active: number;
+            draft: number;
+        };
+    };
+    project: {
+        name: string;
+        type: string;
+        package_manager: string;
+    };
+    paths: {
+        root_agents: string;
+        docs: string;
+        domain_docs: string;
+        adr_docs: string;
+        openspec: string;
+        templates: string;
+    };
+    defaults: {
+        doc_status: string;
+        review_interval_days: number;
+        adr_padding: number;
+        agents_max_lines: number;
+        local_agents_max_lines: number;
+    };
+    features: {
+        openspec: boolean | "auto";
+        hooks: boolean;
+        docs_frontmatter: boolean;
+        generate_indexes: boolean;
+    };
+    domain: {
+        create_local_agents_by_default: boolean;
+        create_rules_by_default: boolean;
+        create_state_machine_by_default: boolean;
+        create_glossary_by_default: boolean;
+    };
+    risk_keywords: string[];
+}, {
+    version?: number | undefined;
+    validation?: {
+        require_doc_frontmatter?: string[] | undefined;
+        required_frontmatter?: string[] | undefined;
+        stale_review_days?: {
+            active?: number | undefined;
+            draft?: number | undefined;
+        } | undefined;
+    } | undefined;
+    project?: {
+        name?: string | undefined;
+        type?: string | undefined;
+        package_manager?: string | undefined;
+    } | undefined;
+    paths?: {
+        root_agents?: string | undefined;
+        docs?: string | undefined;
+        domain_docs?: string | undefined;
+        adr_docs?: string | undefined;
+        openspec?: string | undefined;
+        templates?: string | undefined;
+    } | undefined;
+    defaults?: {
+        doc_status?: string | undefined;
+        review_interval_days?: number | undefined;
+        adr_padding?: number | undefined;
+        agents_max_lines?: number | undefined;
+        local_agents_max_lines?: number | undefined;
+    } | undefined;
+    features?: {
+        openspec?: boolean | "auto" | undefined;
+        hooks?: boolean | undefined;
+        docs_frontmatter?: boolean | undefined;
+        generate_indexes?: boolean | undefined;
+    } | undefined;
+    domain?: {
+        create_local_agents_by_default?: boolean | undefined;
+        create_rules_by_default?: boolean | undefined;
+        create_state_machine_by_default?: boolean | undefined;
+        create_glossary_by_default?: boolean | undefined;
+    } | undefined;
+    risk_keywords?: string[] | undefined;
+}>;
+export type MetaConfig = z.infer<typeof configSchema>;
+export declare const DEFAULT_CONFIG: MetaConfig;

package/dist/schemas/config.schema.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+export const DEFAULT_RISK_KEYWORDS = [
+    "payment",
+    "withdrawal",
+    "settlement",
+    "commission",
+    "refund",
+    "inventory",
+    "permission",
+    "authorization",
+    "audit",
+    "webhook",
+    "callback",
+];
+export const configSchema = z.object({
+    version: z.number().default(1),
+    project: z
+        .object({
+        name: z.string().default(""),
+        type: z.string().default("auto"),
+        package_manager: z.string().default("auto"),
+    })
+        .default({}),
+    paths: z
+        .object({
+        root_agents: z.string().default("AGENTS.md"),
+        docs: z.string().default("docs"),
+        domain_docs: z.string().default("docs/domain"),
+        adr_docs: z.string().default("docs/adr"),
+        openspec: z.string().default("openspec"),
+        templates: z.string().default("templates/agent-meta"),
+    })
+        .default({}),
+    defaults: z
+        .object({
+        doc_status: z.string().default("active"),
+        review_interval_days: z.number().default(180),
+        adr_padding: z.number().int().min(1).default(4),
+        agents_max_lines: z.number().default(180),
+        local_agents_max_lines: z.number().default(120),
+    })
+        .default({}),
+    features: z
+        .object({
+        openspec: z.union([z.boolean(), z.literal("auto")]).default("auto"),
+        hooks: z.boolean().default(false),
+        docs_frontmatter: z.boolean().default(true),
+        generate_indexes: z.boolean().default(true),
+    })
+        .default({}),
+    domain: z
+        .object({
+        create_local_agents_by_default: z.boolean().default(true),
+        create_rules_by_default: z.boolean().default(true),
+        create_state_machine_by_default: z.boolean().default(false),
+        create_glossary_by_default: z.boolean().default(false),
+    })
+        .default({}),
+    validation: z
+        .object({
+        require_doc_frontmatter: z
+            .array(z.string())
+            .default([
+            "docs/domain/**/*.md",
+            "docs/architecture/**/*.md",
+            "docs/api/**/*.md",
+            "docs/engineering/**/*.md",
+            "docs/runbooks/**/*.md",
+        ]),
+        required_frontmatter: z
+            .array(z.string())
+            .default(["title", "status", "owner", "last_reviewed"]),
+        stale_review_days: z
+            .object({
+            active: z.number().default(180),
+            draft: z.number().default(365),
+        })
+            .default({}),
+    })
+        .default({}),
+    risk_keywords: z.array(z.string()).default(DEFAULT_RISK_KEYWORDS),
+});
+export const DEFAULT_CONFIG = configSchema.parse({});

package/dist/templates/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Built-in templates. A project can override any of them by placing a file
+ * named `<key>.tmpl` under `templates/agent-meta/` (configurable via
+ * 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 "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-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";
+    readonly "adr.md": "---\ntitle: ADR-{{adr_number}}：{{title}}\nstatus: {{status}}\ndate: {{date}}\nowners:\n  - {{owner}}\nsupersedes: []\nsuperseded_by: []\ntags: []\n---\n\n# ADR-{{adr_number}}：{{title}}\n\n## 背景\n\n<!-- 当前问题是什么？为什么需要做决策？ -->\n\n## 决策\n\n<!-- 明确采用什么方案。必须能被以后的人理解和执行。 -->\n\n## 不采用的方案\n\n### 方案 A\n\n<!-- 为什么不选。 -->\n\n### 方案 B\n\n<!-- 为什么不选。 -->\n\n## 后果\n\n### 正向影响\n\n-\n\n### 代价与限制\n\n-\n\n### 后续约束\n\n-\n\n## 关联内容\n\n- Domain docs:\n- OpenSpec changes:\n- Related ADRs:\n- Related APIs:\n";
+    readonly "adr-0001.md": "---\ntitle: ADR-{{adr_number}}：Repository conventions\nstatus: accepted\ndate: {{date}}\nowners:\n  - {{owner}}\nsupersedes: []\nsuperseded_by: []\ntags: [conventions]\n---\n\n# ADR-{{adr_number}}：Repository conventions\n\n## 背景\n\n项目接入 AI Agent 协作，需要统一仓库元数据结构：AGENTS.md、领域文档、ADR、frontmatter 与校验规则。\n\n## 决策\n\n采用 Agent Meta 约定：\n\n- 根 `AGENTS.md` 只保留操作性规则与文档入口，不复制领域规则。\n- 领域规则统一放在 `docs/domain/<domain>/`。\n- 长期架构决策记录在 `docs/adr/`，四位递增编号，不复用编号。\n- 受约束文档必须包含 frontmatter：title、status、owner、last_reviewed。\n- 通过 `meta check` 在本地与 CI 校验元数据完整性。\n\n## 不采用的方案\n\n### 单一大 AGENTS.md\n\n规则集中在单文件会不可维护，且 Agent 无法按目录感知局部规则。\n\n## 后果\n\n### 正向影响\n\n- 规则只写一次，可被机器校验。\n\n### 代价与限制\n\n- 需要维护文档 frontmatter 与审核时间。\n\n### 后续约束\n\n- 新领域必须通过 `meta new-domain` 创建。\n\n## 关联内容\n\n- Domain docs: docs/domain/\n- Related ADRs:\n";
+    readonly "domain-index-readme.md": "---\ntitle: Domain Index\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: false\napplies_to: []\n---\n\n# Domain Index\n\n<!-- meta:domain-index:start -->\n<!-- Generated by `meta sync --indexes`. Do not edit between markers. -->\n<!-- meta:domain-index:end -->\n";
+    readonly "adr-index-readme.md": "---\ntitle: ADR Index\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: false\napplies_to: []\n---\n\n# ADR Index\n\n<!-- meta:adr-index:start -->\n<!-- Generated by `meta sync --indexes`. Do not edit between markers. -->\n<!-- meta:adr-index:end -->\n";
+    readonly "glossary.md": "---\ntitle: 术语表\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# 术语表\n\n<!-- 跨领域通用术语。领域特有术语放在各领域目录下。 -->\n\n| 术语 | 定义 | 备注 |\n|---|---|---|\n|  |  |  |\n";
+    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 "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";
+};
+export type TemplateName = keyof typeof BUILTIN_TEMPLATES;