@xgent-ai/skills 0.3.0 → 0.4.0

package/skills/dev-plan/references/plan-skeleton.md

@@ -3,12 +3,16 @@
 > 除非用户显式指定其他模板，dev-plan 一律使用本骨架，不依赖目标仓库存在模板文件。
 > 按改动面与风险裁剪章节；删除不适用的占位和写作指引，不为满足形式填充内容。
 > 目标读者是后续实现者，因此事实、决策、接口、迁移、失败和验收必须闭环。
-> 同理，写作过程不进计划：用了哪份 skill、骨架或参考资料，读过哪些规则文件、哪些确认无约束，实现者都不需要知道。
+> 同一信息只展开一次：已有 PRD 用 ID 与来源引用，账本已含完整设计/验收落点时删 §13；其余章节与里程碑引用定义和检查 ID。模块内测试就近完成，昂贵集成验收按可行性集中到阶段收口，独立风险门保留。
+> 同理，写作过程不进计划：用了哪份 skill、骨架或参考资料，读过哪些规则文件、哪些确认无约束，调查、复核与评审改稿的经过，以及“本次只写计划、未实施”这类写作当时的状态，实现者都不需要知道；计划只陈述当前结论。
 > 仓库规则里真正约束实现的条目落成 §0.1 的 `C-*` 或 §12 的一行一坑，带规则路径与被约束的具体行为。
+> 开头的「实施须知」与「实施者定位」「实施进度」两节是实施期的完整合同：实施者只读计划、不加载本 skill，所以实施需要的规则只能写在这两节里。「实施须知」与两节的协议文字原样带入，其中唯一的填空是 `<进度校验命令>`；恢复快照与完成记录按真实状态初始化。
 
 ```markdown
 # <代号> · <项目名> · <功能名>（<形态 · 关键架构特征>）
 
+> **实施须知：实施或续做本计划时不要加载 `dev-plan` skill。** 它只用于撰写和评审计划；实施所需约定已全部写在下方「实施者定位」「实施进度」两节，加载它只会白占上下文。
+>
 > **计划状态：<Ready / Proposed / Blocked>**
 >
 > 调查基线：<YYYY-MM-DD> · <commit/version> · <clean/dirty；dirty 时说明事实基于当前工作树>。
@@ -19,25 +23,24 @@
 
 ## 实施者定位
 
-执行本计划的 agent 是**资深软件工程师**：Kent Beck 式的 TDD 纪律加上《程序员修炼之道》式的精确。本节由骨架原样带入，不随项目改写；开始任何里程碑前先接受以下约定。
+执行本计划的 agent 是**资深软件工程师**，依据本计划、仓库规则和当前代码实施。
 
-- **表达方式**：极简，每句话都可引用。说到代码给文件路径，说到需求或验收给本计划的 ID（需求账本 R-* / NFR-* / C-* / A-*，决策 D* / ADR-*，里程碑 M*）。不写铺垫、不写感想、不复述计划。
-- **完成的定义**：没有通过验证的任务不算完成。里程碑退出条件里的测试、断言和走查全部通过，才能在「实施进度」记为完成；验证没跑、失败或环境缺失，就如实记为缺口或阻塞。
-- **工作顺序**：需要行为测试的改动先红、再绿、最后重构。按前置依赖推进；同一或不同里程碑中，前置已满足、契约稳定、文件与运行资源互不干扰的任务，应启动多个 subagents 并发完成。共享文件单人负责，共享数据库、端口、浏览器会话等资源须隔离或串行；工具不可用或无法安全拆分时说明原因并串行。
-- **并行交付**：无特别要求时 subagent 使用与主 agent 相同的模型，启动时默认继承，不主动覆盖模型。主 agent 划定各任务的目标、文件/资源边界、验收条件与独立记录路径；subagent 只写自己的改动和记录，回报简要结论与链接。主 agent 统一集成验证，单独负责计划回写和里程碑记录；不以子任务通过代替整个里程碑验收。
-- **源码干净**：注释解释为什么，不解释是什么。源码里不出现工单或需求编号（如 `# FR-12`、`// BUG-42`）、本计划的 R-* / M* 编号、agent 工作流标记或任何规划元数据；追溯关系记在计划摘要、独立实现/验收记录和提交说明里。交付的是可直接上生产的代码：干净、最小，没有多余防御、空洞注释或重复样板这类 AI 生成痕迹。
+- **表达与源码**：报告用路径、需求/检查/里程碑 ID 定位，不复述计划。源码不放需求编号、agent 标记或规划元数据，注释解释必要原因；追溯放记录或提交说明。
+- **完成的定义**：本里程碑退出检查全部通过才能记完成；未运行、失败、环境缺失分别记缺口，不冒充通过。集中到阶段收口的终验由收口里程碑负责，通过前不宣称整期或跨期需求已验收。
+- **工作顺序**：需要行为测试的改动先红、再绿、再重构。按实际前置成果及检查推进，不等无关终验，数据、安全、发布及用户分期门不得绕过；稳定契约下可用 fixture 开发，不能替代真实集成。按 §9 执行局部检查与集中验收，同环境走查可合并；相关代码、配置、依赖、输入与环境未变可引用已通过证据，否则重跑受影响检查，收口仍跑必要集成回归。
+- **并行交付**：独立任务在收益超过委派/集成成本且工具可用时使用 subagents，模型默认继承。任务说明只给目标/ID、稳定契约、可写与禁改路径、运行资源和检查；共享文件单人负责，数据库、端口、浏览器等隔离或串行。子 agent 返回结果、路径、验证证据与缺口，默认不另写任务文档；主 agent 审查并集成验收。边界变化先回报，失败只阻塞依赖任务；结束对话前收集或停止仍在运行的任务。
 
 ## 实施进度（实施期持续更新）
 
-本节由骨架原样带入，不随项目改写。它是跨对话恢复的**唯一汇总入口**：先读仓库规则、本节、当前任务相关正文和工作树；只有继续未完任务、核验证据、排错或审查时，才按链接读取对应实现/验收记录。不要默认加载全部记录或原始日志。
+本节是跨对话恢复的**唯一汇总入口**，协议文字不随实施改写，实施期只更新「恢复快照」和「完成记录」。续做时先读仓库规则、本节、当前任务相关正文与依赖，再核对 `git status` 和相关 diff；记录与工作树不符时先查明原因，不凭记录覆盖用户改动，也不凭代码存在推断验收已通过。只有继续未完任务、核验前置验收、排错或审查时，才按链接读取对应记录的相关部分；不要默认加载全部记录或原始日志。
 
-**回写时机**：每完成一个里程碑，立即先保存独立实现/验收记录，再回写本节的简要进度与引用；早于报告完成、提交代码或启动依赖该成果的任务，不等整批并行任务结束。已独立运行的任务可继续。实质进展后暂停、受阻、切换任务、发现偏差或结束对话时，也须保存已有成果与缺口，刷新快照。
+**回写时机**：里程碑完成后立即回写，再报告完成或提交；下游只需部分成果时，所需前置检查通过并在记录保存证据即可推进。实质进展后受阻、暂停、交接、发现偏差或结束对话时也保存成果与缺口；普通子任务切换不单独回写。
 
-**一次回写**：由主 agent 先更新对应里程碑的独立记录，再同步「恢复快照」全部 7 行及「完成记录」中该里程碑的一行；状态/摘要就地更新，不追加流水。详情按里程碑保存在计划旁的同名 `.records/` 目录，以 `M1.md` 等命名，分“实现记录”和“验收记录”写交付行为、关键路径、偏差、验证命令/步骤、环境、结果和代码基线，未完成时写缺口与继续动作。subagent 详情用独立任务文件，由里程碑记录引用。记录链接只放在完成记录中，计划不复制详情。实现偏差涉及范围、决策、接口、数据、风险或退出条件时，同时修订正文对应章节，快照只点明变化。
+**一次回写**：主 agent 更新对应记录，再同步快照变化字段和完成记录一行，不重写无变化内容或追加流水。快照写当前任务、进展与下一步，命令及证据只进记录。首次回写删占位行，每个已记进展的里程碑恰好一行，状态仅「进行中 / 阻塞 / 已完成」；完成时移至已完成行末，最近完成取该行。更新时间带时区，摘要 1–2 句，记录填相对计划的链接（如 `[M1 记录](FEATURE.records/M1.md)`）。范围、决策、接口、数据、风险或退出条件有偏差时，就地修订对应正文，不追加勘误历史。
 
-**记完成的门槛**：退出条件全部通过才可记完成。验证没跑、跑红或因环境缺失跳过，就如实写进「当前状态」/「当前阻塞」，不写“基本完成”“应该可用”。
+**独立记录**：按需建 `<计划名>.records/M<n>.md`，头部写计划链接、更新时区、状态及验证基线（commit SHA；未提交写 dirty@起始SHA 与关键改动路径）。正文只写交付行为/路径、必要偏差、未完项与继续动作；验收按 `检查 ID/覆盖范围 | 命令或步骤 | 结果/必要证据` 记录，共同环境和基线在头部写一次，有差异再单列。同一测试组可覆盖多条退出条件，须逐条可追溯；引用原证据与复用依据，不复制断言全文、成功日志或调试流水。未运行、失败、环境缺失明确区分；只有复杂交接、排错或证据需独立保存时才另建任务记录/日志/截图并链接。
 
-**回写后自查**：「当前进度 n/N」的 N 等于里程碑总数，n 只计状态为「已完成」的行；每个里程碑最多一行，转为已完成时将原行移至已完成记录末尾，按实际完成先后排列；「最近完成」对应最后一条已完成记录，不按编号推算；链接指向已落盘文件，完成判定有真实验收证据。校验只读取计划与引用文件存在性，详情按需复核。
+**回写后自查**：「当前进度 n/N」的 N 等于里程碑总数，n 只计状态为「已完成」的行；「最近完成」对应最后一条已完成记录，不按编号推算；链接指向已落盘文件。每次回写后运行 `<进度校验命令>`：它只查上述结构、计数与链接存在性，不证明验收真实通过。
 
 ### 恢复快照
 
@@ -55,7 +58,7 @@
 | --- | --- | --- | --- | --- |
 | — | — | — | 尚未开始任何里程碑 | — |
 
-<首次有进展时删掉占位行，为该里程碑增加一行；之后就地更新。状态仅用「进行中 / 阻塞 / 已完成」，更新时间带时区，摘要 1–2 句写交付结果或已做到哪里、还差什么，记录列填相对 Markdown 链接，例如 [M1 记录](FEATURE.records/M1.md)。初稿不预建空记录、不填写虚假完成事实。命令、走查步骤、调试过程、改动清单只进独立记录；阅读规则/加载 skill 不算进展。>
+<初稿保留上面的占位行，不预建空记录、不填写虚假完成事实；本条写作指引不带入计划。>
 
 ## 0. 需求、范围与决策
 
@@ -68,7 +71,7 @@
 | C-1 | 约束 | <规则/代码路径> | <技术栈/兼容/交付约束> | <影响章节> | 已确认 |
 | A-1 | 假设 | <为何暂时依赖> | <假设内容> | <验证办法 + 责任人 + 最晚确认点> | 开放/阻塞 |
 
-<只列受本需求影响的 NFR；没有来源的 p95、吞吐、SLA、RPO/RTO 或预算不得编造。>
+<已有 PRD 沿用其 ID，内容仅写能力摘要或本期差异，不重抄需求/验收原文；设计/验收落点引用正文和 §9 检查 ID，不能只有里程碑编号。只列相关 NFR，不编造数字。本表已完整覆盖映射时删除 §13。>
 
 ### 0.2 决策表
 
@@ -187,7 +190,14 @@
 
 ### 9.1 行为与接口验证
 
-<通过公开接口验证不变量、错误、权限、幂等和状态转换；避免绑定内部实现。>
+<按下表定义检查，后续里程碑与验收记录引用 ID。已有 PRD/测试定义用链接 + 本期增量断言，不重复展开；通过公开接口验证行为，避免绑定内部实现。>
+
+| 检查 ID | 需求/验收行与可观察结果 | 命令/入口与环境 | 执行时点 |
+| --- | --- | --- | --- |
+| V-1 | <需求 ID/验收行 + 新增行为/边界> | <实际测试入口与 fixture/环境> | <所需能力/环境就绪后；是下游前置则写清> |
+| V-2 | <跨模块主路径/API + UI> | <同一部署与用户/角色> | <阶段收口；可合并的走查范围> |
+
+<以下 §9.2–§9.5 只补本表未表达的回归、故障、真实环境与静态检查；已在表中定义则引用 ID 或省略对应小节。>
 
 ### 9.2 集成与回归
 
@@ -199,22 +209,24 @@
 
 ### 9.4 真实环境与 UI
 
-<从登录/配置到核心结果的步骤级走查；角色、语言、主题、错误、另一租户/账户边界。>
+<从登录/配置到核心结果的走查；角色、语言、主题、错误、另一租户/账户边界。同环境的 API/UI 走查合并执行，前期已核实的未变部分引用证据，收口验证受影响范围与完整主路径。>
 
 ### 9.5 静态校验
 
 <项目实际提供的 typecheck/lint/build/schema/i18n/依赖检查命令。>
 
-## 10. 里程碑（每步可独立验收）
+## 10. 里程碑与验收安排
+
+<围绕可验证的能力/交付切片分组，不按模块或工种拆里程碑。同能力、同环境且无独立风险门可合并，内部任务保留局部检查；阶段收口集中昂贵集成、走查、故障演练和评测。发布、迁移、不可逆操作、安全边界和用户约定的分期门保留必要检查。>
 
 | # | 里程碑 | 前置依赖 | 内容与并行边界 | 验证/退出条件 |
 | --- | --- | --- | --- | --- |
-| M1 | <行为基线/骨架> | <无或明确前置> | <最小改动；可独立任务与共享文件/资源归属> | <既有回归 + 新断言>；回写「实施进度」 |
-| Mn | <收尾> | <依赖的里程碑/契约> | <迁移、文档、总验证；集成负责人> | <集成回归 + 真实环境 + Ready 门>；回写「实施进度」 |
+| M1 | <行为基线/骨架> | <实际需要的成果 + 前置检查 ID，不默认等整个里程碑> | <最小改动；独立任务与共享文件/资源归属> | <§9 局部检查 ID + 必要风险门>；回写「实施进度」 |
+| Mn | <阶段收口/终验> | <本阶段交付物齐备 + 所需前置检查> | <统一部署、集成、走查、评测；负责人> | <§9 集成/终验检查 ID，覆盖本阶段全部验收>；回写「实施进度」 |
 
-<每一行的退出条件都以「回写『实施进度』」结尾，逐行写出——实施者是按行核对退出条件的，只在表下写一句总约定会被跳过。>
+<每行退出条件以「回写『实施进度』」结尾；只引用检查 ID 和本里程碑独有条件，不再抄需求验收清单。局部完成不等于阶段终验通过。>
 
-<并行范围说明到可写路径与运行资源即可；独立任务必须实际委派 subagents，不把“不同目录”等同于“无依赖”。共享契约先定、共享文件单人修改，最后统一集成验收。没有安全并行空间时写明具体依赖或冲突，不为并行硬拆任务。>
+<依赖区分开发/集成/终验；已验证的子任务可解除对应开发前置，无关走查或发布排练不阻塞代码开发，除非用户分期或风险门要求。并行说明到可写路径与资源，按收益决定委派；共享契约先定、共享文件单人修改，统一集成，不为并行硬拆。>
 
 ## 11. 风险、开放问题与就绪状态
 
@@ -229,7 +241,9 @@
 
 - <一行一坑 + 规则/事故/进度文档路径；说明本计划如何规避>。
 
-## 13. 需求 → 设计 → 验证映射
+## 13. 需求 → 设计 → 验证映射（§0.1 未完整映射时使用）
+
+<与 §0.1 二选一作为完整映射入口；使用本节时 §0.1 不重复设计/验收落点，不重抄需求内容。>
 
 | ID | 需求/约束/假设 | 设计落点 | 验证/解除办法 | 结果 |
 | --- | --- | --- | --- | --- |
@@ -244,13 +258,14 @@
 
 - [ ] 默认使用本文件；未探测或依赖目标仓库中的模板。
 - [ ] 计划记录调查日期、commit/version 和 dirty 状态。
-- [ ] 全文没有写作过程元信息：用了哪份 skill/骨架/参考、读过哪些规则文件的清单、调查步骤；相关约束已落成 `C-*` 或 §12。
+- [ ] 除开头「实施须知」外，全文没有写作过程元信息：用了哪份 skill/骨架/参考、读过哪些规则文件的清单、调查步骤、评审处置与改稿经过、“本次只写计划”类状态；相关约束已落成 `C-*` 或 §12。
 - [ ] 顶部实施进度已按真实状态初始化，0/N、M1、里程碑总数和代码基线互相一致；没有预填虚假完成记录。
-- [ ] 「实施进度」的回写协议为骨架原文在位；每个里程碑的退出条件都以「回写『实施进度』」结尾。
-- [ ] 计划只留简要进度与记录链接；详情按里程碑独立保存、按需读取，进行中/阻塞不计完成。
-- [ ] 依赖和并行边界明确；无冲突任务使用 subagents，共享文件/资源单人负责或隔离，主 agent 集成验收并单写计划。
-- [ ] 顶部“实施者定位”为骨架原文，未改写、未删减。
-- [ ] R/NFR/C/A 全部映射；未知数字未被伪造成目标。
+- [ ] 「实施进度」的回写协议为骨架原文在位，`<进度校验命令>` 已替换；每个里程碑的退出条件都以「回写『实施进度』」结尾。
+- [ ] 计划只留简要进度与链接；记录按检查组保留可追溯证据，不默认建子任务文档，进行中/阻塞不计完成。
+- [ ] 依赖落到实际成果和前置检查；合并验收有覆盖范围与收口负责人，独立风险/分期门保留，局部通过不冒充终验。
+- [ ] 并行收益与边界明确，共享文件/资源单人负责或隔离，主 agent 集成验收并单写计划。
+- [ ] 开头“实施须知”与“实施者定位”为骨架原文，未改写、未删减。
+- [ ] R/NFR/C/A 在账本或 §13 全部映射，未重复展开需求/断言；未知数字未被伪造成目标。
 - [ ] 关键决策有真实备选、正负后果和重新评估触发；普通选择未被 ADR 化。
 - [ ] 复杂设计写清模块、接口、接缝、依赖分类与测试面；没有假想抽象。
 - [ ] 契约均为“已核实足够 / 已核实缺口 / 未核实阻塞”之一。

package/skills/dev-plan/scripts/check_progress.sh

@@ -59,6 +59,10 @@ done
 while IFS= read -r l; do
   [ -n "$l" ] && err "恢复快照残留模板占位:$(trim "$l")"
 done < <(sed 's/`[^`]*`//g' <<<"$snap" | grep -E '<[^<>]+>' || true)
+# 协议里唯一的填空:实施者不加载写计划的 skill,留着占位就等于没有校验命令。
+if grep -qF '<进度校验命令>' <<<"$prog"; then
+  err "「回写后自查」的 <进度校验命令> 未替换为可运行命令或人工核对说明"
+fi
 
 # ③ 识别新摘要索引与旧内联证据表,核对 ID 和记录字段。
 mcount="$(mrows "$mile" | grep -c . || true)"

package/skills/documentation-writer/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: documentation-writer
+description: 基于代码事实写和更新技术文档：README、API 文档（HTTP 接口 / OpenAPI / 库与 SDK 参考）、架构文档、代码库说明文档（docs/codebase/ 成套）、用户手册与操作指南。每条结论都能追到仓库里的文件，文字去 AI 味；需要架构图、流程图、时序图时，本地装了 archify skill 就优先用它出图，没有再用 Mermaid。凡用户要求写或更新 README、补接口文档、生成 OpenAPI、写架构文档、画系统架构、梳理仓库、写新人上手文档、写用户手册 / 使用说明 / 教程，或改完代码要同步文档，都用本 skill，即使用户没说「文档」二字。Use for READMEs, API/OpenAPI/SDK reference, architecture docs, codebase onboarding docs, user manuals, tutorials and how-to guides, or syncing docs after code changes.
+disable-model-invocation: true
+---
+
+# documentation-writer · 基于代码事实的技术文档
+
+**路径约定**：`references/`、`scripts/`、`assets/` 都相对于本 `SKILL.md` 所在目录。运行脚本前先设 `SKILL_DIR="<本 SKILL.md 所在目录>"`；文档路径、仓库根等参数按目标仓填写。
+
+这份 skill 要的文档有三个特点：说的都是仓库里真实存在的东西；读者拿到就能用（命令能跑、例子能抄、图能看懂）；读起来像熟悉这套代码的工程师写的，不像模型生成的。三者冲突时，准确优先。
+
+## 选文档类型
+
+| 用户要的 | 读者 | 先读 | 默认位置（仓库已有约定时从约定） |
+|---|---|---|---|
+| README：新建、补全、按代码变更同步 | 第一次接触项目的人 | [references/readme.md](references/readme.md) | 仓库根或子包根的 `README.md` |
+| API 文档：HTTP 接口、OpenAPI、库 / SDK 参考 | 调用方开发者 | [references/api-docs.md](references/api-docs.md) | `docs/api/` 或服务目录下 `docs/` |
+| 架构文档：系统怎么搭起来、为什么这样搭 | 新加入的工程师、评审者 | [references/architecture.md](references/architecture.md) | `docs/architecture.md` 或 `ARCHITECTURE.md` |
+| 代码库说明：成套的结构、约定、功能、测试、风险文档 | 日常改代码的人和 AI agent | [references/codebase-map.md](references/codebase-map.md) | `docs/codebase/` |
+| 用户手册、教程、操作指南、运维手册 | 最终用户、运营、运维 | [references/user-manual.md](references/user-manual.md) | `docs/user-guide/` 或 `docs/manual/` |
+
+架构文档和代码库说明容易混。用户要**一份**能从头读到尾的「系统是怎么工作的」，走架构文档；要一**套**放在仓库里、按主题随查随用的参考（技术栈、目录、约定、功能清单、测试、风险），或者明确说「代码库说明 / 功能说明 / map this codebase」，走代码库说明。拿不准时问一句，问不了就写架构文档，并在交付说明里提一句另一种选择。
+
+一个请求涉及多类文档（比如「给这个服务写 README 和接口文档」），按类型分别读对应参考，各写各的，互相链接，不要把 API 参考塞进 README。
+
+**不归本 skill 管**：只改代码注释或 docstring、写 commit message、写 PRD（用 prd skill）、写开发计划（用 dev-plan skill）、制定迁移或现代化方案。
+
+## 通用流程
+
+每类文档都走这六步，差别在参考文件里。
+
+### 1. 定读者、目的和范围
+
+先弄清三件事：谁读、读完要能做什么、覆盖哪些不覆盖哪些。按 [Diátaxis](https://diataxis.fr/) 分清这份文档属于哪一类，四类写法不同，不要混在一起：
+
+- **教程**：带新手完整做成一件事，一步一个结果，不讲原理。
+- **操作指南**：解决一个具体问题，假设读者已经会基本操作。
+- **参考**：准确、完整、结构统一，像字典，不讲故事。
+- **解释**：讲清楚为什么这样设计、有哪些取舍。
+
+能从请求和仓库推断出来的，不要问。真正缺的信息一次问完。新写大文档（架构文档、用户手册、代码库说明）时，先把大纲给用户看：章节、每节一句话、打算画哪几张图，确认后再写。用户已经给了结构、说了「直接写」，或者当前环境没法提问，就把假设写进交付说明，直接写。
+
+输出语言：目标仓已有文档用什么语言就用什么语言；仓库没有文档时用对话的语言。目标仓的 `AGENTS.md` / `CLAUDE.md` / `CONTRIBUTING.md` 里有文档约定（位置、格式、术语）的，照约定来。
+
+### 2. 摸清事实（本地优先）
+
+文档描述的是**眼前这份代码**，所以事实从本地 checkout 里取，不从记忆、网络或远端仓库取。
+
+1. **锚定快照**：`git remote -v`、`git branch --show-current`、`git log -1 --format='%h %ad %s' --date=short`。架构文档和代码库说明要把这三项写进文档，读者才知道描述的是哪个版本。remote URL 里如果带了凭据（`https://<token>@host/...`），写进文档前删掉。
+2. **读真实的清单文件**：`package.json`、`go.mod`、`pyproject.toml`、`Cargo.toml`、`pom.xml` 这类 manifest，`Makefile` 或其他任务脚本，CI 配置，`.env.example`，已有的 `README` / `docs/`。技术栈和命令以这些文件为准，不以你对框架的印象为准。栈不明确时读 [references/stack-detection.md](references/stack-detection.md)。
+3. **仓库大或者陌生时先扫一遍**：在目标目录下跑
+
+   ```bash
+   python3 "$SKILL_DIR/scripts/scan.py" --output /tmp/codebase-scan.txt
+   ```
+
+   会输出目录树、manifest、入口、lint 配置、环境变量模板、TODO、近期提交、高频改动文件、CI、容器、代码量。monorepo 里只写一个子包时，在子包目录里跑。扫描结果是线索，结论仍要回到源文件确认。
+4. **已有文档是意图，不是事实**。README 常常写的是「打算怎么做」。和代码对不上时以代码为准，把分歧记下来，交付时告诉用户。
+5. **只写源码，不写产物**。`dist/`、`build/`、`generated/`、`.next/`、`__pycache__/`、`node_modules/` 里的东西不当作项目约定。
+
+找不到答案的，网络查询是最后手段，只在事实确实影响文档、又无法从本地确定时用，而且要标 `[UNVERIFIED]` 说明来源。
+
+### 3. 写
+
+按对应参考文件的结构写。贯穿所有类型的规矩见下文「证据纪律」和「写作风格」。
+
+### 4. 出图
+
+见下文「出图：archify 优先，Mermaid 兜底」。
+
+### 5. 自检
+
+写完先跑检查脚本，它会核对文中引用的路径是否存在、行号是否越界，扫出凭据、没填的模板占位、AI 腔词汇和破折号密度：
+
+```bash
+python3 "$SKILL_DIR/scripts/check_doc.py" <文档路径...> --repo-root <仓库根>
+```
+
+脚本报「路径不存在」的逐条修掉；报 AI 腔的逐条看，确属术语或引用原文的可以保留。然后人工过一遍：
+
+- [ ] 写到的命令都在 manifest / 任务脚本 / CI 里出现过；没亲自跑过、又有疑问的，标出来
+- [ ] 例子里的字段名、取值形状来自 schema、测试或 seed，不是编的；密钥、token 用占位符
+- [ ] 数量写具体数字（「13 个路由文件」），不写「很多」
+- [ ] 不确定的地方都打了标记
+- [ ] 图的文件存在，链接能点开
+- [ ] 按 [references/writing-style.md](references/writing-style.md) 的清单去一遍 AI 腔
+
+### 6. 交付说明
+
+回复用户时说清：
+
+- 新建或改动了哪些文件（路径）
+- 图用了 archify 还是 Mermaid；用 archify 的，列出每张图的 HTML 路径、`deliver` 结果和 `visual-check` 状态（通过 / 失败 / 跳过），不要把没做过的检查说成做过
+- 所有 `[ASK USER]` 问题，编号列出
+- 文档和代码对不上的地方（README 说 A，代码是 B）
+- 写作时做的假设
+
+## 证据纪律
+
+文档的价值在于读者可以直接信，不用自己再核一遍。所以：
+
+- **非显而易见的结论都要有出处**。架构文档、代码库说明、API 文档里，用相对仓库根的路径加行号引用：`apps/api/src/index.ts:42` 或 `src/routes/users.ts#L10-L35`。引用了哪一行，就要真的读过那一行。README 和用户手册面向的读者不看源码，正文不放行号引用，但写之前同样要核实。
+- **统一用这四个标记**，含义不同，不要混用：
+
+  | 标记 | 用在 |
+  |---|---|
+  | `[INFERRED]` | 从代码推理出来的，但没有哪里直接写明 |
+  | `[UNVERIFIED]` | 转述了别处的说法，自己没核实（例如文档里写的构建耗时、CI 是否是必需检查） |
+  | `[TODO]` | 仓库里查不到，需要后续补 |
+  | `[ASK USER]` | 取决于团队意图，只有人能回答 |
+
+  标记用英文原样，中文文档也一样，方便 grep。
+- **矛盾要裁定，不要转述**。两个来源说法不同（manifest 写的版本和代码里的常量不一致），去读代码，给出结论，并写一句「已核对：X 写的是 A，实际生效的是 B，因为……」。
+- **能数就数**。「共 73 个 service 包」读起来是核实过的，「有很多服务」读起来是猜的。
+- **诚实的空白比虚假的完整有用**。写不出来的部分标 `[TODO]`，不要用泛泛之词填满。
+
+## 出图：archify 优先，Mermaid 兜底
+
+### 先想清楚要不要画
+
+图用来表达文字说不清的东西：组件之间怎么连、请求怎么穿过系统、状态怎么流转。三步以内的线性流程，用一句话或编号列表就够了。一份文档通常一到四张图，每张图正文里要有一句话说明它在讲什么、读者该看哪里。
+
+### 探测 archify
+
+由 Agent 自行检查当前环境的可用 skill 列表；列表中未找到或列表未提供时，直接查找本 skill 同级目录及当前环境的项目级、用户级 skill 目录中的 `archify/SKILL.md`。找到后加载或读取它，按其流程出图；没有安装时用 Mermaid。不新增或调用 archify 安装检测脚本，不自动安装 skill。
+
+### 用 archify 出图
+
+怎么写 JSON、怎么校验、怎么修布局，全按 archify 自己的 `SKILL.md` 来，这里不复述。本 skill 只约定和文档衔接的部分：
+
+**类型对应**
+
+| 文档里的图 | archify 类型 |
+|---|---|
+| 系统上下文图、容器图、部署拓扑、模块依赖 | `architecture` |
+| 请求链路、接口调用时序、鉴权 / token 交换握手 | `sequence` |
+| 业务流程、审批流、CI/CD、操作步骤 | `workflow` |
+| 数据管道、ETL、数据血缘、事件流 | `dataflow` |
+| 状态机、订单或任务的状态流转、重试与终态 | `lifecycle` |
+
+**文件放在哪**：在文档所在目录下建 `diagrams/`，源文件和产物同名：`docs/diagrams/system-context.json` 和 `docs/diagrams/system-context.html`。源 JSON 要留着，以后改图从它改。
+
+**图里的文字**和文档同语言，中文文档设 `meta.locale: "zh-CN"`。节点名、接口路径、命令等标识符保持原样。
+
+**在 Markdown 里怎么放**：先跑 archify 的 `deliver`，再跑 `visual-check`（需要本机有 Chrome / Chromium）。`visual-check` 成功时会在 HTML 旁边留下截图 `<名字>.visual-check.1440x900.light.png`，把它嵌进正文，下面给出交互版链接：
+
+```markdown
+![系统上下文图](diagrams/system-context.visual-check.1440x900.light.png)
+
+交互版：[diagrams/system-context.html](diagrams/system-context.html)，用浏览器打开，可缩放、搜索、追踪调用链。
+```
+
+`visual-check` 失败或被跳过时，只放交互版链接，并在交付说明里写明截图没有生成。同一张图不再另画一份 Mermaid，两份会各改各的，最后对不上。
+
+**只留三个文件**：每张图在仓库里保留 `<名字>.json`（源）、`<名字>.html`（交互版）和正文嵌入的 `<名字>.visual-check.1440x900.light.png`。`visual-check` 另外生成的深色和 2048 尺寸截图、`<名字>.visual-check.html` 汇总页、`<名字>.visual-check.json` 回执都是检查证据，把检查结果写进交付说明后删掉，不然一张图会在 `diagrams/` 里留下八个文件。
+
+**修不好就退回**：某张图按 archify 的修复流程连续两轮没有改善，这一张改用 Mermaid，交付说明里写清楚原因和 archify 的报错。
+
+### 用 Mermaid 出图
+
+- 类型：结构用 `flowchart`，时序用 `sequenceDiagram`，状态用 `stateDiagram-v2`。
+- 一张图不超过 12 个节点，超了就拆成两张，或者只画主干。
+- 节点标签用读者认识的名字（服务名、模块名），不用内部变量名。
+- 在紧挨着图的正文里写一句这张图在说什么。
+- 交付说明里提一句：装了 archify 可以得到可交互、可导出的图（仓库地址 `https://github.com/tt-a1i/archify`）。只提一次，不要反复推销。
+
+## 写作风格
+
+技术文档去 AI 味，靠的是具体、直接、可核对，不靠加个性。完整清单和中英文例子在 [references/writing-style.md](references/writing-style.md)，写完对照检查。最常见的几条：
+
+- **开头直接说是什么、给谁用、能做什么**。不写「在当今……的背景下」「随着……的快速发展」。
+- **删空话**：赋能、助力、打造、一站式、全方位、无缝、强大的、极致、深度融合、值得注意的是、综上所述；英文的 delve、leverage、seamless、robust、comprehensive、cutting-edge。删掉之后句子不成立，说明原来就没有内容，换成具体事实（数字、名称、行为）。
+- **不给标题和列表加 emoji**，不写「**性能：** 性能得到提升」这种加粗小标题列表。参考类文档里「**术语**：定义」的格式是正常的，可以用。
+- **术语前后一致**。同一个东西第一次叫「租户」，后面就一直叫「租户」，不要换成「组织」「空间」「团队」轮着用。
+- **不写总结、展望式结尾**。文档讲完就停。
+- **参考文档保持中性**，不加第一人称和观点。教程和 README 可以用「你」直接跟读者说话，可以写真实踩过的坑（「第一次跑 `db:migrate` 会失败，因为 Redis 还没起」），这是技术文档里合适的「人味」。
+- **更新已有文档时沿用它的风格**：标题层级、术语、emoji 习惯、中英文混排方式都照旧，只保证你新增和改动的部分没有 AI 腔。
+
+## 更新已有文档
+
+用户说「同步一下文档」「README 过时了」「接口改了，更新文档」时：
+
+1. 先通读现有文档，再看代码变更（`git diff`、`git log -p -- <路径>`，或用户描述的改动）。
+2. 列出文档里和现状不符的地方，逐条对应到要改的段落。代码变更和文档章节的对应关系见 [references/readme.md](references/readme.md) 的「变更映射」。
+3. 只改需要改的段落，结构、语气、格式保持不变。不借机重写整篇。
+4. 删掉已经不存在的功能、参数、命令，不要只加不减。
+5. 交付说明里列出改了哪几处、为什么。
+
+## 参考文件索引
+
+| 文件 | 什么时候读 |
+|---|---|
+| [references/readme.md](references/readme.md) | 写或更新 README |
+| [references/api-docs.md](references/api-docs.md) | 写 HTTP 接口文档、OpenAPI、库 / SDK 参考 |
+| [references/architecture.md](references/architecture.md) | 写架构文档、系统设计说明 |
+| [references/codebase-map.md](references/codebase-map.md) | 写 `docs/codebase/` 成套说明 |
+| [references/inquiry-checkpoints.md](references/inquiry-checkpoints.md) | 写代码库说明时，每份文档要回答的问题 |
+| [references/user-manual.md](references/user-manual.md) | 写用户手册、教程、操作指南、运维手册 |
+| [references/writing-style.md](references/writing-style.md) | 每次交付前，去 AI 味 |
+| [references/stack-detection.md](references/stack-detection.md) | 技术栈不明确、多种 manifest 并存时 |
+| `assets/templates/*.md` | 代码库说明的八份模板 |
+| `scripts/scan.py` | 大仓或陌生仓，动笔前扫描 |
+| `scripts/check_doc.py` | 交付前自检 |

package/skills/documentation-writer/assets/templates/ARCHITECTURE.md

@@ -0,0 +1,49 @@
+# Architecture
+
+## Core Sections (Required)
+
+### 1) Architectural Style
+
+- Primary style: [layered/feature/event-driven/other]
+- Why this classification: [short evidence-backed rationale]
+- Primary constraints: [2-3 constraints that shape design]
+
+### 2) System Flow
+
+```text
+[entry] -> [processing] -> [domain logic] -> [data/integration] -> [response/output]
+```
+
+Describe the flow in 4-6 steps using file-backed evidence.
+
+### 3) Layer/Module Responsibilities
+
+| Layer or module | Owns | Must not own | Evidence |
+|-----------------|------|--------------|----------|
+| [name] | [responsibility] | [non-responsibility] | [file] |
+
+### 4) Reused Patterns
+
+| Pattern | Where found | Why it exists |
+|---------|-------------|---------------|
+| [singleton/repository/adapter/etc] | [path] | [reason] |
+
+### 5) Known Architectural Risks
+
+- [Risk 1 + impact]
+- [Risk 2 + impact]
+
+### 6) Evidence
+
+- [path/to/entrypoint]
+- [path/to/main-layer-files]
+- [path/to/data-or-integration-layer]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Startup or initialization order details
+- Async/event topology diagrams
+- Anti-pattern catalog with refactoring paths
+- Failure-mode analysis and resilience posture

package/skills/documentation-writer/assets/templates/CONCERNS.md

@@ -0,0 +1,56 @@
+# Codebase Concerns
+
+## Core Sections (Required)
+
+### 1) Top Risks (Prioritized)
+
+| Severity | Concern | Evidence | Impact | Suggested action |
+|----------|---------|----------|--------|------------------|
+| [high/med/low] | [issue] | [file or scan output] | [impact] | [next action] |
+
+### 2) Technical Debt
+
+List the most important debt items only.
+
+| Debt item | Why it exists | Where | Risk if ignored | Suggested fix |
+|-----------|---------------|-------|-----------------|---------------|
+| [item] | [reason] | [path] | [risk] | [fix] |
+
+### 3) Security Concerns
+
+| Risk | OWASP category (if applicable) | Evidence | Current mitigation | Gap |
+|------|--------------------------------|----------|--------------------|-----|
+| [risk] | [A01/A03/etc or N/A] | [path] | [what exists] | [what is missing] |
+
+### 4) Performance and Scaling Concerns
+
+| Concern | Evidence | Current symptom | Scaling risk | Suggested improvement |
+|---------|----------|-----------------|-------------|-----------------------|
+| [issue] | [path/metric] | [symptom] | [risk] | [action] |
+
+### 5) Fragile/High-Churn Areas
+
+| Area | Why fragile | Churn signal | Safe change strategy |
+|------|-------------|-------------|----------------------|
+| [path] | [reason] | [recent churn evidence] | [approach] |
+
+### 6) `[ASK USER]` Questions
+
+Add unresolved intent-dependent questions as a numbered list.
+
+1. [ASK USER] [question]
+
+### 7) Evidence
+
+- [scan output section reference]
+- [path/to/code-file]
+- [path/to/config-or-history-evidence]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Full bug inventory
+- Component-level remediation roadmap
+- Cost/effort estimates by concern
+- Dependency-risk and ownership mapping

package/skills/documentation-writer/assets/templates/CONVENTIONS.md

@@ -0,0 +1,52 @@
+# Coding Conventions
+
+## Core Sections (Required)
+
+### 1) Naming Rules
+
+| Item | Rule | Example | Evidence |
+|------|------|---------|----------|
+| Files | [RULE] | [EXAMPLE] | [FILE] |
+| Functions/methods | [RULE] | [EXAMPLE] | [FILE] |
+| Types/interfaces | [RULE] | [EXAMPLE] | [FILE] |
+| Constants/env vars | [RULE] | [EXAMPLE] | [FILE] |
+
+### 2) Formatting and Linting
+
+- Formatter: [TOOL + CONFIG FILE]
+- Linter: [TOOL + CONFIG FILE]
+- Most relevant enforced rules: [RULE_1], [RULE_2], [RULE_3]
+- Run commands: [COMMANDS]
+
+### 3) Import and Module Conventions
+
+- Import grouping/order: [RULE]
+- Alias vs relative import policy: [RULE]
+- Public exports/barrel policy: [RULE]
+
+### 4) Error and Logging Conventions
+
+- Error strategy by layer: [SHORT SUMMARY]
+- Logging style and required context fields: [SUMMARY]
+- Sensitive-data redaction rules: [SUMMARY]
+
+### 5) Testing Conventions
+
+- Test file naming/location rule: [RULE]
+- Mocking strategy norm: [RULE]
+- Coverage expectation: [RULE or TODO]
+
+### 6) Evidence
+
+- [path/to/lint-config]
+- [path/to/format-config]
+- [path/to/representative-source-file]
+
+## Extended Sections (Optional)
+
+Add only for large or inconsistent codebases:
+
+- Layer-specific error handling matrix
+- Language-specific strictness options
+- Repo-specific commit/branching conventions
+- Known convention violations to clean up

package/skills/documentation-writer/assets/templates/FEATURES.md

@@ -0,0 +1,43 @@
+# Features
+
+## Core Sections (Required)
+
+### 1) Feature Inventory
+
+List every user- or caller-facing capability found in routes, pages, CLI commands, menus, or permission definitions. Group by domain.
+
+| Feature | What it does (observable behavior) | Entry point (route/page/command) | Core logic | Data touched | Evidence |
+|---------|-----------------------------------|----------------------------------|-----------|--------------|----------|
+| [name] | [behavior] | [route or page] | [path] | [tables/services] | [file] |
+
+Total: [N] features across [M] domains.
+
+### 2) Key Feature Walkthroughs
+
+Pick the 3-5 most important features (most used, most changed, or most complex). For each:
+
+- Trigger: [who does what, where]
+- Path through the code: [entry file:line] -> [service file:line] -> [data/integration file:line]
+- Side effects: [events, notifications, audit logs, external calls]
+- Failure modes: [what can go wrong and how it surfaces to the user]
+
+### 3) Switches That Change Behavior
+
+| Switch | Type (feature flag/tenant setting/plan limit/env var) | Affects | Default | Evidence |
+|--------|------------------------------------------------------|---------|---------|----------|
+| [name] | [type] | [feature] | [value] | [file] |
+
+### 4) Evidence
+
+- [path/to/route-or-page-registry]
+- [path/to/permission-or-menu-definition]
+- [path/to/key-service-file]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Role/permission x feature matrix
+- Features declared but not wired to an entry point (dead or unfinished)
+- Feature-level dependency map
+- Per-feature test coverage notes

package/skills/documentation-writer/assets/templates/INTEGRATIONS.md

@@ -0,0 +1,48 @@
+# External Integrations
+
+## Core Sections (Required)
+
+### 1) Integration Inventory
+
+| System | Type (API/DB/Queue/etc) | Purpose | Auth model | Criticality | Evidence |
+|--------|---------------------------|---------|------------|-------------|----------|
+| [name] | [type] | [purpose] | [auth] | [high/med/low] | [file] |
+
+### 2) Data Stores
+
+| Store | Role | Access layer | Key risk | Evidence |
+|-------|------|--------------|----------|----------|
+| [db/cache/etc] | [role] | [module] | [risk] | [file] |
+
+### 3) Secrets and Credentials Handling
+
+- Credential sources: [env/secrets manager/config]
+- Hardcoding checks: [result]
+- Rotation or lifecycle notes: [known/unknown]
+
+### 4) Reliability and Failure Behavior
+
+- Retry/backoff behavior: [implemented/none/partial]
+- Timeout policy: [where configured]
+- Circuit-breaker or fallback behavior: [if any]
+
+### 5) Observability for Integrations
+
+- Logging around external calls: [yes/no + where]
+- Metrics/tracing coverage: [yes/no + where]
+- Missing visibility gaps: [list]
+
+### 6) Evidence
+
+- [path/to/integration-wrapper]
+- [path/to/config-or-env-template]
+- [path/to/monitoring-or-logging-config]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Endpoint-by-endpoint catalog
+- Auth flow sequence diagrams
+- SLA/SLO per integration
+- Region/failover topology notes