Back to Details

documentation-manager

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Manager

文档管理器（Documentation Manager）

Living project knowledge for humans and AI agents. Code is the source of truth for how and for whether a claim is true.
AGENTS.md + docs/ capture what, why, decisions, and plans — but never override code when they disagree.
面向人类和 AI Agent 的鲜活项目知识库。代码是「实现方式」以及声明是否属实的唯一事实来源。
AGENTS.md + docs/ 记录「是什么」「为什么」、决策和计划——但当二者存在分歧时，永远不要覆盖代码。

Core rules

核心规则

  1. Prefer 
    AGENTS.md
     as the hub. If 
    agents.md
    already exists, use it. If only 
    CLAUDE.md
    exists, either extend it with a docs index or add 
    AGENTS.md
    and cross-link — do not create three competing hubs.
  2. Every generated/updated doc uses relative Markdown links back to the hub and related docs.
  3. Never delete durable knowledge without a reason; prefer Superseded by notes on ADRs.
  4. Do not auto-commit or auto-push. Leave git to the user.
  5. Write generated content in the user's language (or the repo's dominant language). This skill body is English for ecosystem compatibility.
  6. Prefer accuracy and usefulness over volume. Core set first; optional docs on demand.
  7. Intent first (project-level). Classify Intent: 
    integrate
    | 
    audit
    | 
    from-zero
    (and optional hybrid). See Step 0. Not required for pure feature/plan/sync.
  8. Code wins on conflict. Doc claims that fail structural verification are marked Contradicted/Missing — do not invent code to match docs; fix or flag the doc.
  9. Integrate-first (when Intent=integrate). The default tree is a proposal. If the repo evolved its layout, adopt it — never force the template over the captain (ADR-0002). Mature docs → index + gaps + canonical links; no parallel rewrite of product-vision/requirements/ADRs. See adopt-integrate.
  10. One authority per topic. Each topic has one canonical doc; everything else links.
  11. Coverage matrix on adopt/from-zero project. Product surfaces (nav, ModuleId, package) appear as documented / linked / gap.
  12. Feature atomicity. One slug ≈ one ModuleId or bounded context. Clusters = index + children.
  13. Status taxonomy. references/status-taxonomy.md.
  14. Sandbox opt-in / first-class from-zero. 
    Out: sandbox:path
    when user asks (
    test/
    , etc.). Sandbox hubs banner non-SSOT + promotion plan.
  15. Feature autopilot (v1.5 / v2). Plain “new feature X” / “documentá X” → skill chooses plan vs feature pack, applies default non-writes, sets Kind (new feature | spike | epic | redesign). Implementation bridge (placement / stubs) only on opt-in (“implementá”, “stubs”, “scaffold”) — default is docs-only + one-line hint. See modes.md §3 and implementation-bridge.md.
  16. Plan mode (v1.3+). Greenfield feature ideas land in 
    docs/plans/<slug>/
    , not a fake implementation pack and not a full project bootstrap. Promote to 
    docs/features/<slug>/
    when code is real (not stubs alone).
  17. ArkGate bridge (v1.4). If ArkGate is detected (
    ark.config.json
    , 
    ark-check
    , 
    .ark/
    , ark skills) or the user just finished a gate, run the bridge sub-flow: enrich inventory from the contract; after gate pass → scoped sync / audit; residual violations → mark claims Contradicted/Partial — never rewrite docs to excuse broken architecture. No Ark → no-op. Placement hints in Implementation bridge reuse Ark layers when detected. See arkgate-bridge.md and modes.md §9.
  18. Knowledge dashboard (v1.6). Optional static HTML view of plans/features/claims (
    scripts/generate-docs-dashboard.sh
    → 
    docs/audit/generated/dashboard.html
    ). Markdown is SSOT; HTML is gitignored view-only. Offer after audit once or on “dashboard” request. See knowledge-dashboard.md and modes.md §10.
  19. Skill hardening (v1.7). Maintainers: run 
    validate-skill.sh
    + 
    test-skill-hardening.sh
    before release. Agents: detect install/version via skill-discovery.md; suggest reinstall when outdated (no silent auto-patch).
  20. v2.0 package. Completes the 10× line: capabilities 1.4–1.7 plus docs/adoption-matrix.md tracking. Baseline install floor remains 2.0.0; polyglot 2.1.0; monorepo 2.2.0; team 2.3.0; Bridge complete 2.4.0; current line is 2.5.0+ (Knowledge OS first increment toward 100× — living claims + CI audit; not a second 10×).
  21. Polyglot stack detection (v2.1 Slice A / skill 2.1.0). On project discover (integrate / audit / from-zero / adopt), detect stack from filesystem (
    package.json
    , 
    pyproject.toml
    , 
    go.mod
    , …) via skill-discovery.md Polyglot stack detection (or 
    scripts/detect-stack.sh
    ). Use Inventory by stack and Docs layout guidance by stack — do not assume Node/TS. Never invent ModuleIds/endpoints for frameworks without code evidence. See modes.md §0.3.
  22. Monorepo hubs (v2.2 Slice B). Detect multi-package trees (
    pnpm-workspace.yaml
    , 
    package.json
    workspaces, 
    go.work
    , multi-package dirs) via skill-discovery.md Monorepo hubs (or 
    scripts/detect-packages.sh
    ). Root hub is a map + Package index, not a dump; multi-package coverage marks gap packages; default package non-writes when only indexing root. See modes.md §0.4.
  23. Team governance (v2.3 Slice C). Optional 
    docs/team/
    with owners + approval notes (last-approved style). Create vs link per team-governance.md; hub links Team without becoming an HR wiki; integrate-first — adding team must not rewrite product-vision / requirements / ADRs. No CODEOWNERS engine or BPM. See modes.md §11.
  24. Living claims + CI structural audit (v2.5 / Knowledge OS first increment). Audit matrices use living claims v0: 
    anchor.path
    / optional 
    anchor.symbol
    / optional 
    anchor.hash
    , 
    severity
    (
    critical
    | 
    normal
    ), verdicts unchanged. Matrix-first (audit-template.md); procedure living-claims.md; wire ADR-0001. Truth score stays advisory (dashboard heuristic); local air-gapped 
    scripts/audit-claims.sh
    / example 
    docs-audit
    CI is the gate (fail on critical Contradicted). No SaaS. Optional code-comment breadcrumbs (
    id
    + parent/plane + status) mirror the same 
    id
    — living-claims.md § Code breadcrumbs. Four on-demand loops on 
    audit-claims.sh
    : 
    --list-claims
    / 
    --upsert-claims
    / 
    --record-haken
    / 
    --cascade-recommend
    (Haken ≠ DB/daemon; still no graph walker). Audit / reconcile reads are diff-first (git change set only; never a full-tree scan unless the user opts in) — modes.md §6.0. See modes.md §6 / §13.
  1. 优先使用 
    AGENTS.md
     作为中心文档。如果已存在 
    agents.md
    ，则直接使用。如果仅存在 
    CLAUDE.md
    ，要么为其扩展文档索引，要么新增 
    AGENTS.md
    并双向链接——不要创建三个相互冲突的中心文档。
  2. 所有生成/更新的文档都使用相对 Markdown 链接回链到中心文档和相关文档。
  3. 不得无故删除长期有效的知识；对于 ADR，优先添加 Superseded by 说明。
  4. 不要自动提交或自动推送。git 操作交由用户自行处理。
  5. 生成的内容使用用户的语言（或仓库的主要语言）编写。出于生态兼容性考虑，本技能的主体内容为英文。
  6. 优先保证准确性和实用性，而非数量。先完成核心文档集；可选文档按需生成。
  7. 意图优先（项目级别）。 对Intent进行分类：
    integrate
    | 
    audit
    | 
    from-zero
    （也支持混合模式）。参见第0步。纯功能/计划/同步场景不需要分类意图。
  8. 冲突时以代码为准。 未通过结构验证的文档声明将被标记为 Contradicted/Missing——不要编造代码来匹配文档；应修复或标记文档问题。
  9. 整合优先（当 Intent=integrate 时）。 默认的目录结构是一个提案。如果仓库已经演化出自己的布局，采用现有布局——永远不要强制套用模板而违背实际主导者（ADR-0002）。对于成熟的文档 → 补充索引、缺口和规范链接；不要并行重写产品愿景/需求/ADR。参见 adopt-integrate。
  10. 每个主题只有一个权威来源。 每个主题都有一份规范文档；其他所有内容都链接到该文档。
  11. adopt/from-zero 项目需提供覆盖矩阵。 产品入口（导航、ModuleId、包）需标记为 已文档化 / 已链接 / 缺失。
  12. 功能原子性。 一个 slug 约对应一个 ModuleId 或限界上下文。功能集群 = 索引 + 子功能。
  13. 状态分类法。 参见 references/status-taxonomy.md。
  14. 可选沙箱 / 一等公民级从零搭建。 当用户要求时（如 
    test/
    等目录），使用 
    Out: sandbox:path
    。沙箱中心文档需标注非 SSOT + 升级计划。
  15. Feature autopilot（v1.5 / v2）。 简单的“new feature X” / “documentá X”指令 → 技能会自动选择 plan 或 feature pack，应用默认的非写入规则，设置Kind（new feature | spike | epic | redesign）。Implementation bridge（代码放置 / 桩代码）仅在用户明确要求时启用（“implementá”、“stubs”、“scaffold”）——默认仅生成文档 + 一行提示。参见 modes.md §3 和 implementation-bridge.md。
  16. 计划模式（v1.3+）。 全新的功能想法存放在 
    docs/plans/<slug>/
     中，既不是虚假的实现包，也不是完整的项目初始化。当代码真实存在（不只是桩代码）时，再升级到 
    docs/features/<slug>/
    。
  17. ArkGate bridge（v1.4）。 如果检测到 ArkGate（
    ark.config.json
    、
    ark-check
    、
    .ark/
    、ark 相关技能），或者用户刚完成一个关卡，则运行bridge子流程：从合约中丰富清单内容；关卡通过后 → 执行范围限定的同步 / 审计；剩余违规项 → 将声明标记为 Contradicted/Partial——永远不要重写文档来为有问题的架构找借口。没有 Ark → 不执行任何操作。如果检测到 Ark，Implementation bridge 中的代码放置提示会复用 Ark 的层级结构。参见 arkgate-bridge.md 和 modes.md §9。
  18. Knowledge dashboard（v1.6）。 可选的计划/功能/声明静态 HTML 视图（
    scripts/generate-docs-dashboard.sh
    → 
    docs/audit/generated/dashboard.html
    ）。Markdown 是 SSOT；HTML 是被 git 忽略的只读视图。可在审计后主动提供一次，或在用户请求“dashboard”时生成。参见 knowledge-dashboard.md 和 modes.md §10。
  19. 技能加固（v1.7）。 维护者：发布前需运行 
    validate-skill.sh
    + 
    test-skill-hardening.sh
    。Agent：通过 skill-discovery.md 检测安装情况和版本；过时则建议重新安装（不进行静默自动补丁）。
  20. v2.0 版本包。 完成了 10× 效率线：包含 1.4–1.7 版本的所有功能，加上 docs/adoption-matrix.md 跟踪。基线安装最低版本仍为 2.0.0；多语言（polyglot）支持为 2.1.0；monorepo 支持为 2.2.0；团队功能为 2.3.0；Bridge 完整功能为 2.4.0；当前版本线为 2.5.0+（Knowledge OS 迈向 100× 效率的首次增量——living claims + CI 审计；不是第二次 10× 提升）。
  21. 多语言技术栈检测（Polyglot stack detection，v2.1 Slice A / 技能 2.1.0）。 在项目发现阶段（integrate / audit / from-zero / adopt），通过 skill-discovery.md 的Polyglot stack detection（或 
    scripts/detect-stack.sh
    ）从文件系统（
    package.json
    、
    pyproject.toml
    、
    go.mod
    等）检测技术栈。使用按技术栈分类的清单和按技术栈提供的文档布局指南——不要默认是 Node/TS 技术栈。永远不要在没有代码证据的情况下为框架编造 ModuleId/接口端点。参见 modes.md §0.3。
  22. Monorepo 中心（v2.2 Slice B）。 通过 skill-discovery.md 的Monorepo hubs（或 
    scripts/detect-packages.sh
    ）检测多包树结构（
    pnpm-workspace.yaml
    、
    package.json
    workspaces、
    go.work
    、多包目录）。根中心文档是一个导航图 + 包索引，不是内容倾倒；多包覆盖情况会标记缺失的包；仅对根目录建索引时，默认不写入包级文档。参见 modes.md §0.4。
  23. 团队治理（Team governance，v2.3 Slice C）。 可选的 
    docs/team/
    目录，包含所有者（owners） + 审批记录（approval notes）（上次审批风格）。根据 team-governance.md 决定是创建还是链接；中心文档会链接团队相关内容，但不会变成 HR 维基；整合优先——添加团队内容不得重写产品愿景 / 需求 / ADR。不包含 CODEOWNERS 引擎或 BPM 系统。参见 modes.md §11。
  24. Living claims + CI 结构审计（v2.5 / Knowledge OS 首次增量）。 审计矩阵使用 living claims v0 格式：
    anchor.path
    / 可选 
    anchor.symbol
    / 可选 
    anchor.hash
    、
    severity
    （
    critical
    | 
    normal
    ），判定结果保持不变。以矩阵为核心（audit-template.md）；流程参见 living-claims.md；连线规范参见 ADR-0001。真实性评分仅作参考（仪表盘启发式估算）；本地离线的 
    scripts/audit-claims.sh
    / 示例 
    docs-audit
    CI 才是关卡（关键 Contradicted 项会导致失败）。无 SaaS 服务。可选的代码注释面包屑（
    id
    + 父级/层面 + 状态）会镜像相同的 
    id
    ——参见 living-claims.md § 代码面包屑。
    audit-claims.sh
    支持四个按需循环：
    --list-claims
    / 
    --upsert-claims
    / 
    --record-haken
    / 
    --cascade-recommend
    （Haken 不是数据库/守护进程；仍然没有图遍历器）。审计/对账读取采用 diff-first 策略（仅处理 git 变更集；除非用户选择，否则永远不进行全树扫描）——参见 modes.md §6.0。参见 modes.md §6 / §13。

Step 0 — Detect scope, mode, and Intent

第0步 — 检测范围、模式和意图

Scope (required):
ScopeWhenOutput focus
projectWhole product / “docs for the project”Hub + project docs (per Intent)
featureNamed feature/module with code (or refresh pack)
docs/features/<slug>/
+ hub link
planNamed new feature / epic before or without solid code
docs/plans/<slug>/
+ hub link
hybridFeature/plan when no hub yetPack or plan + minimal hub
Mode (required):
ModeSignals
bootstrapGreenfield, no hub/docs, or Intent from-zero on empty/thin
adoptCode exists; docs thin/missing or Intent integrate
audit“audit docs”, “docs vs code”, drift, validate claims; diff-first (git change set)
plan“new feature”, “plan”, “epic”, “vamos a construir X” without code
featureDocument one feature/module that has (or is) code
syncDiff / PR / update docs for a change; post-gate when Ark just passed
roadmapPlan release / epic list refresh
Intent (required for project-level work only):
IntentUser signals (examples)Behavior
integrate“mejorar docs”, “ordenar”, “sync hub”, mature improveadopt-integrate (or full if thin); adopt evolved layout; optional pre-audit if drift suspected
audit“auditar”, “¿las docs mienten?”, “docs vs code”, “validar paths”Code inventory + claim matrix only (or then hand off)
from-zero“toda nueva”, “de cero”, “generá docs en test/”, “full KB en carpeta X”Full knowledge base; prefer sandbox if path given; code-inferred; old docs = hypothesis only
Inference (do not over-ask):
  • “nueva feature X” / “new feature X” / “quiero agregar X” → Feature autopilot (plan if no code, feature if code; Kind from phrasing). Intent = n/a
  • “implementá X” / “generá stubs” / “scaffold X” → autopilot Stage A if needed + Implementation bridge opt-in (code only if stubs requested)
  • “generá toda la documentación en 
    test/
    ” → Intent: from-zero | Out: sandbox:test/
  • Mature repo + “mejorá / integrá / indexá” → Intent: integrate
  • “auditar docs” / “código vs docs” → Intent: audit
  • Ambiguous project work with existing 
    docs/
    → ask once: integrate | audit | from-zero
  • Named single surface → never require the user to list non-writes or choose folders
  • “after ark-check” / “post-gate docs” / gate just ran + docs intent → sync or audit with ArkGate bridge
  • “dashboard” / “docs HTML” / “knowledge report” → generate Knowledge dashboard (knowledge-dashboard.md)
  • “owners” / “quién es dueño” / “team docs” / “approval notes” / “docs/team” → Team governance (team-governance.md; modes §11)
  • “living claims” / “truth score” / “docs CI” / “fail on Contradicted” → Living claims + local CI gate (living-claims.md; modes §13)
Maturity (when relevant): thin | mixed | mature — see modes.md.
If scope/mode still ambiguous after inference, ask once. Load procedures from references/modes.md.
Announce before writing:
text
Scope: <x> | Mode: <y> | Intent: <integrate|audit|from-zero|n/a> | Variant: <full|integrate|arkgate-bridge|n/a> | Maturity: <…|n/a> | Out: <root|sandbox:path> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <yes|no|n/a> | ArkGate: <none|detected> | Slug: <slug|n/a>
When integrate, list non-writes (include package non-writes when monorepo root-index only) and whether layout was adopted (evolved) or proposed (thin / from-zero). When audit, list matrix path, Audit-scope (
diff-first
default, 
docs-universe
if the change set was valid-but-unusable, or 
full-tree
if the user opted in), change-set size, and top contradictions. When from-zero + sandbox, include promotion plan. When plan or feature, list path + default non-writes. When ArkGate bridge, list signals and post-gate sync vs audit-enrich. When project-level, include Stack and Monorepo from discovery.
范围（Scope）（必需）：
范围（Scope）适用场景输出重点
project整个产品 / “为项目生成文档”中心文档 + 项目文档（根据 Intent 确定）
feature已有对应代码的命名功能/模块（或更新包）
docs/features/<slug>/
+ 中心文档链接
plan尚无可靠代码（或还没有代码）的命名新功能 / 史诗级需求
docs/plans/<slug>/
+ 中心文档链接
hybrid尚无中心文档的功能/计划功能包或计划 + 最小化中心文档
模式（Mode）（必需）：
模式（Mode）触发信号
bootstrap全新项目、无中心文档/文档，或在空/薄弱项目上使用 from-zero Intent
adopt代码已存在；文档薄弱/缺失，或使用 integrate Intent
audit“audit docs”、“docs vs code”、文档漂移、验证声明；diff-first 策略（仅处理 git 变更集）
plan无代码情况下的“new feature”、“plan”、“epic”、“vamos a construir X”
feature为一个已有（或本身就是）代码的功能/模块编写文档
sync为变更同步 / PR / 更新文档；Ark 刚通过时为 post-gate 模式
roadmap计划发布 / 史诗级需求列表更新
意图（Intent）（仅项目级别工作必需）：
意图（Intent）用户信号（示例）行为
integrate“mejorar docs”、“ordenar”、“sync hub”、成熟项目优化adopt-integrate（如果文档薄弱则全量）；采用已演化的布局；如果怀疑有漂移可选择预审计
audit“auditar”、“¿las docs mienten?”、“docs vs code”、“validar paths”仅生成代码清单 + 声明矩阵（或之后移交）
from-zero“toda nueva”、“de cero”、“generá docs en test/”、“full KB en carpeta X”完整知识库；如果指定了路径优先使用沙箱；基于代码推断；旧文档仅作假设参考
推断规则（不要过度询问）：
  • “nueva feature X” / “new feature X” / “quiero agregar X” → Feature autopilot（无代码则为 plan，有代码则为 feature；Kind 根据措辞判断）。Intent = 不适用
  • “implementá X” / “generá stubs” / “scaffold X” → 必要时运行自动驾驶 Stage A + 可选启用 Implementation bridge（仅在请求桩代码时生成代码）
  • “generá toda la documentación en 
    test/
    ” → Intent: from-zero | Out: sandbox:test/
  • 成熟仓库 + “mejorá / integrá / indexá” → Intent: integrate
  • “auditar docs” / “código vs docs” → Intent: audit
  • 已有 
    docs/
    目录但项目工作范围不明确 → 询问一次：integrate | audit | from-zero
  • 已命名的单一入口 → 永远不要要求用户列出非写入项或选择文件夹
  • “after ark-check” / “post-gate docs” / 刚运行完关卡 + 文档意图 → 启用 ArkGate bridge 的 sync 或 audit 模式
  • “dashboard” / “docs HTML” / “knowledge report” → 生成 Knowledge dashboard（knowledge-dashboard.md）
  • “owners” / “quién es dueño” / “team docs” / “approval notes” / “docs/team” → Team governance（team-governance.md；模式 §11）
  • “living claims” / “truth score” / “docs CI” / “fail on Contradicted” → Living claims + 本地 CI 关卡（living-claims.md；模式 §13）
成熟度（Maturity）（如相关）：thin | mixed | mature — 参见 modes.md。
如果推断后范围/模式仍不明确，询问一次。从 references/modes.md 加载流程。
写入前需声明：
text
Scope: <x> | Mode: <y> | Intent: <integrate|audit|from-zero|n/a> | Variant: <full|integrate|arkgate-bridge|n/a> | Maturity: <…|n/a> | Out: <root|sandbox:path> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <yes|no|n/a> | ArkGate: <none|detected> | Slug: <slug|n/a>
当使用 integrate 模式时，列出非写入项（如果是 monorepo 仅根目录索引，需包含包级非写入项），以及布局是已采用（演化而来）还是提案（薄弱 / 从零搭建）。当使用 audit 模式时，列出矩阵路径、审计范围（Audit-scope）（默认为 
diff-first
，如果变更集有效但不可用则为 
docs-universe
，如果用户选择则为 
full-tree
）、变更集大小和主要矛盾项。当使用 from-zero + 沙箱模式时，包含升级计划。当使用 plan 或 feature 模式时，列出路径 + 默认非写入项。当使用 ArkGate bridge 模式时，列出检测信号以及关卡后是同步还是审计增强。当是项目级别工作时，包含发现阶段得到的技术栈（Stack）和Monorepo信息。

Recommended layout (proposal)

推荐布局（提案）

This tree is a proposal (bootstrap / from-zero / adopt-full on thin docs). If the repo already evolved a different layout, adopt it. Never force this tree over the captain (ADR-0002; modes.md §2).
project-root/
├── AGENTS.md
└── docs/
    ├── product-vision.md      # bootstrap / from-zero / adopt-full
    ├── requirements.md
    ├── architecture.md
    ├── roadmap.md
    ├── team/                  # v2.3 team governance (optional)
    │   ├── OWNERS.md
    │   └── approval-notes.md
    ├── audit/                 # Intent audit (optional)
    │   └── claims-matrix.md   # living claims v0 columns
    ├── adr/                   # package / project ADRs (optional)
    ├── plans/<slug>/          # v1.3 plan mode (pre-code / epic)
    │   └── README.md
    ├── decisions/
    └── features/<slug>/       # code-backed feature packs
Supporting docs only when justified (except from-zero, which may create a full minimal core set).
这个目录树是一个提案（用于 bootstrap / from-zero / 薄弱文档的 adopt-full 模式）。如果仓库已经演化出不同的布局，采用现有布局。永远不要强制套用此目录树而违背实际主导者（ADR-0002；modes.md §2）。
project-root/
├── AGENTS.md
└── docs/
    ├── product-vision.md      # bootstrap / from-zero / adopt-full
    ├── requirements.md
    ├── architecture.md
    ├── roadmap.md
    ├── team/                  # v2.3 team governance (optional)
    │   ├── OWNERS.md
    │   └── approval-notes.md
    ├── audit/                 # Intent audit (optional)
    │   └── claims-matrix.md   # living claims v0 columns
    ├── adr/                   # package / project ADRs (optional)
    ├── plans/<slug>/          # v1.3 plan mode (pre-code / epic)
    │   └── README.md
    ├── decisions/
    └── features/<slug>/       # code-backed feature packs
仅在有正当理由时才生成支持性文档（from-zero 模式除外，该模式可能创建完整的最小核心文档集）。

Artifact matrix (summary)

工件矩阵（摘要）

Artifactfrom-zero / bootstrapintegrate (mature)auditplanfeaturesync
Hubcreateextend / indexupdate status optionallink Planslinkif needed
Core narrative docsyesno rewriteno (read only)nonoif impact
Coverage matrixyesrequiredpart of inventoryrow optionalrowupdate
Claims matrixoptional prerecommended if driftrequiredn/ascoped if auditif drift
Plans 
docs/plans/
n/an/an/arequiredlink if existsif impact
Feature packskey domainsgaps / entriesno (unless asked)no (until promote)requiredif impact
Team 
docs/team/
if owners knowncreate/link if askednon/an/aif impact
Parallel full treesandbox okforbidden at rootn/an/an/an/a
工件from-zero / bootstrapintegrate（成熟项目）auditplanfeaturesync
中心文档（Hub）创建扩展 / 建索引可选更新状态链接计划链接按需
核心叙述文档是不重写否（只读）否否有影响时
覆盖矩阵是必需清单的一部分可选行行更新
声明矩阵可选预生成有漂移时推荐必需不适用审计时限定范围有漂移时
计划 
docs/plans/
不适用不适用不适用必需存在则链接有影响时
功能包核心领域缺口 / 条目否（除非要求）否（升级前）必需有影响时
团队 
docs/team/
已知所有者时要求时创建/链接否不适用不适用有影响时
并行完整目录树沙箱中允许根目录下禁止不适用不适用不适用不适用

Workflow (all modes)

工作流（所有模式）

  1. Step 0 — scope, mode, Intent (if project), maturity/variant, Out, slug; detect ArkGate signals when relevant; detect Stack and Monorepo for project work (skill-discovery.md Polyglot + Monorepo hubs).
  2. Discover code first — stack-aware inventory; if monorepo, Package index + per-package inventory; tree, manifests, entry points, sample tests. Then docs (if any): case-insensitive README (
    Readme.md
    counts); real ADR homes only (never 
    *adr*
    globs); cold-start claim/doc scope is 
    docs/
    + root + 
    .github
    and excludes 
    examples/**
    unless opted in (skill-discovery.md Cold-start survey heuristics). For named features, search that surface first. If Ark detected, enrich inventory per arkgate-bridge.md. If mode/Intent is audit or this is the reconciliation pass: diff-first (modes.md §6.0) — change set only; do not walk the tree.
  3. If audit or docs exist and Intent is integrate/from-zero with suspected drift: run reconciliation on the git change set only (modes.md § Audit, audit-template.md). Post-gate → bridge handoff (modes.md §9).
  4. Plan files — creates/updates and non-writes (defaults for feature/plan).
  5. Load templates → write/edit → hub pass.
  6. Summary — Intent/mode, files, non-writes, matrix stats, ArkGate note, promotion notes. No auto-commit.
  1. 第0步 — 确定范围、模式、Intent（项目级工作需要）、成熟度/变体、输出路径、slug；相关情况下检测 ArkGate 信号；项目级工作需检测技术栈（Stack）和Monorepo（skill-discovery.md 多语言 + Monorepo 中心）。
  2. 优先发现代码 — 感知技术栈的清单；如果是 monorepo，生成包索引 + 每个包的清单；包括目录树、清单文件、入口点、示例测试。然后是文档（如果有）：不区分大小写的 README（
    Readme.md
    也算）；仅识别真实的 ADR 存放目录（绝不使用 
    *adr*
    通配符）；冷启动声明/文档范围是 
    docs/
    + 根目录 + 
    .github
    ，排除 
    examples/**
    除非用户选择包含（skill-discovery.md 冷启动调查启发式规则）。对于命名功能，优先搜索该入口。如果检测到 Ark，根据 arkgate-bridge.md 丰富清单内容。如果模式/Intent 是 audit 或者这是对账阶段：采用 diff-first 策略（modes.md §6.0）——仅处理变更集；不遍历整个目录树。
  3. 如果是 audit 模式，或者文档存在且 Intent 为 integrate/from-zero 且怀疑有漂移：仅在 git 变更集上运行对账（modes.md § 审计、audit-template.md）。关卡通过后 → 移交 bridge 流程（modes.md §9）。
  4. 计划文件 — 创建/更新以及非写入项（feature/plan 的默认设置）。
  5. 加载模板 → 编写/编辑 → 中心文档更新。
  6. 总结 — Intent/模式、文件列表、非写入项、矩阵统计、ArkGate 说明、升级说明。不自动提交。

Bootstrap / from-zero

Bootstrap / from-zero

Greenfield interview or code archaeology for brownfield from-zero. Full core set + hub. Sandbox if Out says so. See modes.md and § from-zero.
全新项目访谈或遗留项目从零搭建时的代码考古。生成完整核心文档集 + 中心文档。如果输出路径指定了沙箱则使用沙箱。参见 modes.md 和 § from-zero。

Adopt / integrate

Adopt / integrate

Maturity → adopt-full or adopt-integrate. Default layout is a proposal; evolved layout wins — adopt it, do not reshape the tree. See modes.md §2.
根据成熟度选择 adopt-full 或 adopt-integrate。默认布局是一个提案；已演化的布局优先——采用现有布局，不要重塑目录树。参见 modes.md §2。

Audit

审计（Audit）

Diff-first: change set from 
git diff
/ changed files (or 
audit-claims.sh --list-changed
). Parse 
@claim
breadcrumbs with 
--list-claims
(same set only; HITL if malformed; do not invent ids); persist / record / cascade-recommend on demand with 
--upsert-claims
/ 
--record-haken
/ 
--cascade-recommend
(not a daemon; see living-claims.md + modes.md §6.7). Never a full-tree read by default. Valid-but-huge set → announce and constrain to the docs universe (modes.md §6.0); never a silent full-repo walk. Then structural claims → living-claims matrix (anchors + severity) → report. If a parent breadcrumb would require children, apply modes.md §6.7 (recommend review; no engine). Agent-written plans/MDs in the set: classify per modes.md §6.8 (evolution / regime change / orphan / contradiction). No living contradictions. AS-IS code wins; TO-BE one living SSOT (date does not auto-win on either plane). When cascade / reconcile / audit / narrative comments need eyes, recommend review to a human or agent (modes.md §6.9) — pointers only; no assign, notify, or merge. Non-
@claim
prose comments in the set that look stale/redundant/snapshot or assert a fact after a symbol change: report via modes.md §6.10 — never auto-edit. Code wins. CI gate separate from dashboard score. See modes.md §6.0, §6, §13, living-claims.md.
Diff-first 策略： 变更集来自 
git diff
/ 已更改文件（或 
audit-claims.sh --list-changed
）。使用 
--list-claims
解析 
@claim
面包屑（仅处理同一集合；格式错误时需 HITL；不要编造 id）；按需使用 
--upsert-claims
/ 
--record-haken
/ 
--cascade-recommend
进行持久化 / 记录 / 级联推荐（不是守护进程；参见 living-claims.md + modes.md §6.7）。默认情况下绝不进行全树读取。变更集有效但过大 → 声明并限制在文档范围内（modes.md §6.0）；绝不静默进行全仓库遍历。然后处理结构声明 → living-claims 矩阵（锚点 + 严重程度）→ 生成报告。如果父面包屑需要子项，应用 modes.md §6.7（建议审查；无自动引擎）。变更集中由 Agent 编写的计划/MD 文件：根据 modes.md §6.8 分类（演进 / 体制变更 / 孤立 / 矛盾）。不存在存活的矛盾项。 现状（AS-IS）以代码为准；目标（TO-BE）有一个存活的 SSOT（日期在任何层面都不会自动胜出）。当级联 / 对账 / 审计 / 叙述性评论需要人工介入时，建议由人类或Agent进行审查（modes.md §6.9）——仅提供指引；不分配、通知或合并。变更集中非 
@claim
的散文式评论，如果看起来过时/冗余/是快照，或者在符号变更后仍断言某个事实：通过 modes.md §6.10 报告——绝不自动编辑。代码为准。 CI 关卡与仪表盘评分相互独立。参见 modes.md §6.0、§6、§13、living-claims.md。

Plan / Feature (autopilot v2)

计划 / 功能（autopilot v2）

Named surface → plan (
docs/plans/<slug>/
) if no code / planning language; feature (
docs/features/<slug>/
) if code-backed. Kind spike/epic/redesign when signaled. Default non-writes always. Optional Implementation bridge on implement/stubs language. Promote plan → pack when code is real. See modes.md §3 and implementation-bridge.md.
命名入口 → 如果没有代码 / 是规划表述则为 plan（
docs/plans/<slug>/
）；如果有代码支撑则为 feature（
docs/features/<slug>/
）。有信号时设置 Kind 为 spike/epic/redesign。始终使用默认非写入项。遇到实现/桩代码相关表述时可选启用 Implementation bridge。当代码真实存在时，将 plan 升级为功能包。参见 modes.md §3 和 implementation-bridge.md。

Sync / Roadmap

同步 / 路线图（Sync / Roadmap）

Blast-radius sync; report stale/redundant comments in the change set (modes.md §6.10); never auto-edit. Roadmap links plans for net-new work. See modes §4–5.
影响范围同步；报告变更集中过时/冗余的评论（modes.md §6.10）；绝不自动编辑。路线图会链接全新工作的计划。参见模式 §4–5。

ArkGate bridge (v1.4)

ArkGate bridge（v1.4）

Detect Ark → post-gate sync/audit or inventory enrich; residual violations become claim debt, not narrative rewrites. See arkgate-bridge.md and modes §9.
检测到 Ark → 关卡后执行 sync/audit 或丰富清单；剩余违规项成为声明债务，而不是重写叙述内容。参见 arkgate-bridge.md 和模式 §9。

Knowledge dashboard (v1.6)

Knowledge dashboard（v1.6）

Static HTML from existing docs only (
generate-docs-dashboard.sh
). View-only; markdown SSOT. See knowledge-dashboard.md and modes §10.
仅从现有文档生成静态 HTML（
generate-docs-dashboard.sh
）。只读；Markdown 是 SSOT。参见 knowledge-dashboard.md 和模式 §10。

Team governance (v2.3)

Team governance（v2.3）

Optional 
docs/team/
owners + approval notes; create vs link; integrate-first. See team-governance.md and modes §11.
可选的 
docs/team/
所有者 + 审批记录；创建或链接；整合优先。参见 team-governance.md 和模式 §11。

Living claims + CI audit (v2.5)

Living claims + CI 审计（v2.5）

Matrix-first living claims; local 
audit-claims.sh
/ example docs-audit GHA; score advisory. See living-claims.md and modes §13.
以矩阵为核心的 living claims；本地 
audit-claims.sh
/ 示例 docs-audit GHA；评分仅作参考。参见 living-claims.md 和模式 §13。

Hub requirements

中心文档要求

  • Overview, nav links, agent instructions (read docs; update after significant work; ADRs; code wins), status line.
  • Link Plans (
    docs/plans/
    ) and Features (
    docs/features/
    ) when present.
  • Link Team (
    docs/team/OWNERS.md
    ) when team docs exist — pointer only, not an HR wiki.
  • Adopt / from-zero project: Surface coverage matrix (multi-package rows when monorepo).
  • Monorepo: Package index on root hub (map, not dump).
  • After audit: link to claims matrix if written.
Template: agents-md-template.md
  • 概述、导航链接、Agent 操作说明（阅读文档；重大工作后更新；ADR；代码为准）、状态行。
  • 存在计划（Plans）（
    docs/plans/
    ）和功能（Features）（
    docs/features/
    ）时需链接。
  • 存在团队文档时链接团队（Team）（
    docs/team/OWNERS.md
    ）——仅作指引，不是 HR 维基。
  • Adopt / from-zero 项目：入口覆盖矩阵（monorepo 时包含多包行）。
  • Monorepo：根中心文档包含包索引（是导航图，不是内容倾倒）。
  • 审计后：如果生成了声明矩阵则链接到该矩阵。
模板：agents-md-template.md

Quality bar

质量标准

Follow quality-checklist.md.
Anti-snapshot: no hardcoded table/route/endpoint counts.
遵循 quality-checklist.md。
反快照原则： 不要硬编码表格/路由/端点的数量。

Templates & references

模板与参考资料

FileUse
references/agents-md-template.mdHub + coverage
references/adr-template.mdADRs
references/plan-template.mdPlan mode (
docs/plans/<slug>/
)
references/implementation-bridge.mdImplementation bridge (Stage B, stubs opt-in)
references/feature-readme-template.mdFeature entry
references/feature-cluster-template.mdCluster index
references/architecture-template.mdArchitecture
references/status-taxonomy.mdStatus tokens
references/audit-template.mdClaims matrix + living-claims columns
references/living-claims.mdLiving claims v0 (anchors, severity, truth score vs CI)
references/modes.mdFull procedures
references/arkgate-bridge.mdArkGate bridge (detect, post-gate, violation→claim)
references/knowledge-dashboard.mdKnowledge dashboard (static HTML view; score advisory)
references/skill-discovery.mdDiscovery / upgrade + Polyglot + Monorepo hubs + Cold-start survey heuristics
references/team-governance.mdTeam governance (create/link, non-writes)
references/team-owners-template.mdConsumer 
docs/team/OWNERS.md
references/team-approval-notes-template.mdConsumer 
docs/team/approval-notes.md
references/quality-checklist.mdDone criteria
文件用途
references/agents-md-template.md中心文档 + 覆盖矩阵
references/adr-template.mdADR
references/plan-template.mdPlan mode（
docs/plans/<slug>/
）
references/implementation-bridge.mdImplementation bridge（Stage B，可选桩代码）
references/feature-readme-template.md功能入口文档
references/feature-cluster-template.md功能集群索引
references/architecture-template.md架构文档
references/status-taxonomy.md状态标记
references/audit-template.md声明矩阵 + living-claims 列
references/living-claims.mdLiving claims v0（锚点、严重程度、真实性评分 vs CI）
references/modes.md完整流程
references/arkgate-bridge.mdArkGate bridge（检测、关卡后、违规→声明）
references/knowledge-dashboard.mdKnowledge dashboard（静态 HTML 视图；评分仅作参考）
references/skill-discovery.md发现 / 升级 + Polyglot + Monorepo hubs + 冷启动调查启发式规则
references/team-governance.mdTeam governance（创建/链接、非写入项）
references/team-owners-template.md消费端 
docs/team/OWNERS.md
references/team-approval-notes-template.md消费端 
docs/team/approval-notes.md
references/quality-checklist.md完成标准

When NOT to use / defaults

不适用场景 / 默认规则

  • Pure code with no doc intent
  • Throwaway notes outside the repo
  • Silent overwrite of productive SSOT without Intent from-zero or explicit user order
  • Silent structure rewrite of an evolved layout to match the recommended tree (captain decides; HITL)
  • Mature improve without audit request → integrate (not full parallel tree)
  • Replacing MkDocs/Docusaurus wholesale — integrate with it
  • New feature request → do not run full project from-zero; use plan/feature autopilot
  • 纯代码工作，无文档相关意图
  • 仓库外的临时笔记
  • 没有 from-zero Intent 或用户明确指令时，静默覆盖生产环境的 SSOT
  • 为了匹配推荐目录树而静默重写已演化的布局（由实际主导者决定；需 HITL）
  • 没有审计请求的成熟项目优化 → integrate 模式（不是完整的并行目录树）
  • 完全替换 MkDocs/Docusaurus——应与其集成
  • 新功能请求 → 不要运行全项目从零搭建；使用 plan/feature autopilot

Activation

激活方式

Standalone or with coding skills (including ArkGate / 
ark-*
when present). Suggest doc updates after significant architecture/product changes; after a gate pass, offer bridge sync/audit once. Ask before large narrative rewrites unless Intent is from-zero or audit-driven patch.
After shipping a coded feature that only had a plan, suggest promote plan → feature pack.
可独立使用，也可与编码技能配合使用（包括存在的 ArkGate / 
ark-*
技能）。在重大架构/产品变更后建议更新文档；关卡通过后，主动提供一次 bridge 同步/审计服务。除非是 from-zero Intent 或审计驱动的修补，否则大规模重写叙述内容前需询问用户。
当一个只有计划的功能完成代码开发后，建议将 plan 升级为 feature pack。