首次建立文档管理体系

为尚未建立体系的项目确定：需要哪些文档、各自放什么、变化后更新哪里。一次性脚本通常不需要。

统一 setup

了解项目 → 复用主记录并补实际缺口 → 按需接入入口 → 检查。文档数量由现有材料和使用需要决定。

1. 了解项目。 定位项目根，读取现有入口、相关对话和已确认需求；有代码时核对实现与配置，并确认是否使用 Git。区分现状、计划与未知项，需求与代码冲突分别记录，关键缺口先澄清。
2. 复用主记录。 先判断现有 README、Spec 或 Issue 能否承载目标、约束、需求和验证入口；能承载时就地补充并结束建档，不生成产品包。确有资料归属或缺口时，再读记录范围与模板并按需调用 docs-structure 或下表专项 Skill，提供项目根、确认来源与范围。只创建已有内容需要长期维护的载体，不编造内容，不为凑目录或阶段创建空文档。
3. 按需补导航和状态。 多处资料或非显然路径影响定位时，才建立或完善 CLAUDE_MAP.md；存在需要持续交接且尚无主记录的风险、阻塞或删除提醒时，才建立或完善 PROJECT_STATUS.md。已有 README、Tracker 或同类载体就复用，小项目不默认补齐 MAP、STATUS。使用 Git 的项目不默认新建或要求维护 LOG；已有历史保留，不删改，后续维护沿用已确认约定。无 Git 时按追溯需要决定是否建立 LOG。
4. 接入并检查。 需要持续 Agent 协作时，由 agent-entrypoints 在共享入口写入实际主记录路径，按任务读取已有导航和风险，不引用尚未创建的载体；采用本插件开发流程时指向总路由的“模块变更流程”，按 docs-maintenance 的事实变化条件接入收尾。沿真实任务检查需求、实现与验证资料是否可达；入口有变化才执行入口检查。首次整体接入执行下方命令一次，后续局部补充按 change-impact 选相关检查。交付实际路径、维护方式、验证结果与缺口；重复执行且没有新事实时不再生成或改写文档。

python3 <插件目录>/scripts/audit-docs.py --root <目标根> --scope full

非零先区分实际问题与检查器布局限制；只有确认检查器不支持项目已选布局时才报告限制；项目策略要求 LOG 却缺失、已有历史被删除或断链仍须处理，不视为布局限制。专项不可用时报告缺口，不递归启动 setup；未测宿主加载或自动触发时标明未验证，部分配置不称完整完成。

复用已有授权，仅讨论方案时保持只读。setup 不包含业务实现，也不自动授权 Git 初始化、提交、推送、依赖安装或 Hook／CI 配置。获准安装 Hook 时检查 core.hooksPath，否则用 git rev-parse --git-path hooks/pre-commit 定位，不覆盖既有 Hook。

docs-structure 已纳入 documentation 分类；若部署环境缺少该 Skill，报告目录规划步骤未完成，不冒充已调用。

项目健康证据采集

只检查项目健康证据时，执行项目健康采集：采集项目入口、验证命令、CI 与显式回执，按需衔接既有专项 Skill。静态候选不代表验证通过；不检查全局配置或会话历史。

面向 AI 的文档写作

编写或优化 Skill、Agent 入口及 AI 按需读取的文档时，读取 skills/documentation/writing-for-agents/SKILL.md。传入已确认材料、目标与授权范围，按其方法组织内容并完成含义核对，再继续原有验证与同步；只读任务保持只读。

单项状态更新、路径修正与 LOG 追加不自动触发全文改写。仅在目标项目已启用此能力且入口配置在授权范围内时，通过 agent-entrypoints 留一行触发路标；不将规则全文导入项目入口。

其他任务入口

当前 Agent 按任务读取对应流程，首次 setup 不展开以下审计和日志管理。宿主调用方式见使用说明。

已有项目治理

尚未建立体系时执行统一 setup；已有体系的增量整理读取 docs-maintenance，传入本次变化与范围。仅追加 log: 一句话 时读取日志管理。

阶段同步

读取 docs-maintenance，传入阶段说明、相关会话与实际 diff。采用 PR 护栏时，再执行阶段同步的 PR 护栏。

只读审计

普通文档审计读取 docs-audit；显式 /governance-audit 或兼容 scope（spine/context/adr/artifacts/full）读取兼容文档审计。仅要求“全项目审计”不视为兼容 scope，各自沿用失败处理，默认不写文件。

日志归档与索引

读取日志管理，按事件数量判断是否需要归档，沿用既有确认要求。

日志复盘

日志统计读取日志复盘；从文档管理经历中提炼经验，读取 docs-retro。两者默认只读。