@nathan33/nao-skill 0.16.2 → 0.17.3

package/.agents/checklists/deliverable-docs.md

@@ -14,7 +14,7 @@ description: 交付文档写作规范（PRD/ADR/报告/调研：简洁、可读
 3. **写决策不写过程，写差异不复述**：与代码 / 上游文档重复的内容一律用指针（`路径#小节`）。
 4. **超预算就删，不是加长**：每份文档有长度上限；超了先删「常识 / 过程 / 全量罗列」，仍超才另附文件。
 
-- **PRD**：上限 ≤150 行；必须留下 9 模块结论、范围/非范围、AC；禁止 抄竞品原文、贴代码。
+- **PRD**：上限 ≤150 行；必须留下 9 模块结论、范围/非范围、AC；禁止 抄竞品原文、贴代码；**非范围必带理由**。模板见 `@.agents/templates/prd.md.example`。
 - **ADR**：上限 ≤60 行；必须留下 决策、对照模式、参考来源；禁止 大段代码、教程式背景。
 - **评审报告**：上限 ≤60 行；必须留下 可行性、风险、取舍、待拍板点；禁止 复述 PRD。
 - **测试报告**：上限 ≤80 行；必须留下 范围、结果数字、缺陷、风险、建议；禁止 日志/截图全文。
@@ -44,19 +44,23 @@ description: 交付文档写作规范（PRD/ADR/报告/调研：简洁、可读
 
 - 首屏 TL;DR（≤5 行）：做什么 · 给谁 · 成功标准 · 不做什么
 - 9 模块：**每模块一小节**，内容用列表承载（**不用表格**）；每项 **≤3 句 / ≤60 字**；不适用项写「不适用：<一行理由>」，**不许留空、不许写废话**
+- **非范围必带理由**：每条非范围后跟一行理由（即写「不适用」也要给理由），否则视为未完成
 - AC 逐条 Given/When/Then，一条一行
 - 推演细节（RICE 打分过程、5 Whys 展开、同类产品调研明细）落 `docs/research/` 或附录，**正文只留结论 + 指针**
 - **⛔ PRD 正文不使用表格** ⇒ 改用**有序 / 无序列表 + 加粗字段名**（如 `- **版本**：1.12.3`）。最常被误写成表格的三处：**需求清单（用户故事 / 条目）· 验收标准（AC）· 范围 / 非范围**。
 
-## 四、ADR（≤60 行）
+## 四、ADR（≤60 行，按 `wc -l` 全文）
 
 ```text
-背景(≤5 行) → 决策(1–3 句) → 理由(四步法要点，每点一行) → 对照模式表(模式/适用条件/代价/不采纳理由)
-→ 参考来源(链接 + 访问日期) → 后果与风险 → 相关指针
+背景(≤5 行) → 决策(1–3 句) → 理由(四步法要点，每点一行) → 对照模式清单(模式/适用条件/代价/不采纳理由)
+→ [后果与风险] → [限制与已知边界] → [相关指针] → 参考来源(链接 + 访问日期，恒末节)
 ```
 
-- 方案细节、压测数据、对比实验**不写进 ADR**：另存文件并在「相关指针」给路径。
-- 模板见 @.agents/skills/arch-patterns.md。
+- **必写 5 节**：`## 背景` / `## 决策` / `## 理由` / `## 对照过的备选模式` / `## 参考来源`；**可选 3 节**：`## 后果与风险` / `## 限制与已知边界` / `## 相关指针`。标题逐字、不编号、顺序固定（`参考来源` 恒为末节）。
+- **头部恰 4 字段**：`状态` / `更新` / `Owner` / `指针`；`出具日` = 文件名日期前缀（不单设字段），`落地版本` = `状态` 值（不单设字段）。
+- **状态值域 4 值**：`提议` / `已接受（待落地）` / `已接受（已落地 vX.Y.Z）` / `已废弃（被 <yyyy-mm-dd-slug> 取代）`（本仓 ADR 无编号，禁 `ADR-N` 写法）。
+- **禁写 / 下沉清单**（写进正文即违规，一律另存 `docs/reports/<编号>-arch-review.md`）：实施闸门 / 接线清单 / 交接实现 / 判定式全文 / 用例集。**边界优先于上限**：超长先下沉，不放宽 60 行。
+- 骨架唯一载体（单源）：@.agents/templates/adr.md.example；模式对照法见 @.agents/skills/arch-patterns.md；索引骨架见 @.agents/templates/adr-index.md.example。
 
 ## 五、测试报告（≤80 行）
 

package/.agents/checklists/pm.md

@@ -61,12 +61,14 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] release notes 不可读（纯编号/类名/路径），或未落盘 `docs/releases/`？（规范：@.agents/common/release-notes.md —— 面向用户「本次更新」置顶、内部信息下沉、正文不用表格）
 - [ ] 降级（无 `gh` / 无远端）未在 `tasks-state` 与回执中标注？
 
-## 交付检查清单（完整 36 项）
+## 交付检查清单（完整 38 项）
 
 - [ ] 目标/边界/验收三件事齐备
 - [ ] 证据 + 5 Whys 已产出
 - [ ] 战略筛子已过，RICE 可追溯
 - [ ] PRD 含 9 模块
+- [ ] 接缝候选已列并经 qa 确认（不适用注明理由）
+- [ ] 路径无关判据已核（@.agents/skills/pm-to-spec.md §六 逐条）
 - [ ] 场景模块含画像+场景卡+关键路径+页面状态清单
 - [ ] AC 五覆盖
 - [ ] 变更记录完整（含 Hotfix）

package/.agents/checklists/qa.md

@@ -24,12 +24,13 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 - [ ] 视觉/UI 呈现类验证启动了浏览器自动化（无头浏览器/截图对比）？（应产出用户验收清单交用户人工，见 skills/test-design.md「视觉/UI 呈现验证」）
 - [ ] 含 UI 呈现的交付未产出用户验收清单（测什么/怎么操作/预期结果/对应 AC）？
 
-## 交付检查清单（完整 17 项）
+## 交付检查清单（完整 18 项）
 
 - [ ] 测试计划含范围与风险评估（测什么/不测什么）
 - [ ] 未私自修改现有功能代码
 - [ ] 执行前已列清单并经**用户/PM（开工确认卡）**确认范围
 - [ ] 用例覆盖等价类/边界/主路径/异常，且可追溯 AC
+- [ ] 接缝确认已作为 PRD 阶段输入：PM 列候选 → QA 确认/修正 → 写入 PRD「AC」首行，用例按确认后的接缝组织
 - [ ] 分层测试与 DDD 分层对齐
 - [ ] 缺陷全量入库、信息完整、生命周期闭环
 - [ ] 回归已执行（冒烟 + 受影响），未过未放行

package/.agents/common/release-notes.md

@@ -20,6 +20,8 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
    - 只写内部机制（改了哪个函数 / 状态）不合格；要写**用户会看到什么、能做什么、不能做什么**。
    - 例：_点过之后按钮会变「已撤销」且不可再点_（✅）—— 而非「按钮加 `aria-disabled`」（⛔）。
 4. **口径与落盘一致**：`docs/releases/<version>.md` 是权威落盘；`gh release create --notes-file <该文件>` 与之一同源，禁止两处各写各的。
+5. **Release 标题 = 裸版本号 `vX.Y.Z`**（仅版本号，可带预发布后缀如 `-beta.1`；不得含描述性文本 / `—`、`·`、`：` 副题 / 编号 / 日期）。
+   - 标题**不用构思**：一句话概括等描述性内容**一律置于正文首段「本次更新」**（见 §二.1）；`--title` 只写 `<tag>` 本身。
 
 ## 二、建议结构（顺序固定，用不上的段可省）
 
@@ -49,6 +51,7 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
 - [ ] 结构完整（一句话 → 变化 → 技术细节）；内部信息集中在「技术细节」段。
 - [ ] 正文**未使用表格**（改用有序 / 无序列表；见 @.agents/checklists/deliverable-docs.md）。
 - [ ] `docs/releases/<version>.md` 与 GitHub Release 正文同源。
+- [ ] Release 标题是**裸 `vX.Y.Z`**（无描述性文本 / 副题；见 §一.5）。
 
 ## 五、红线
 
@@ -56,3 +59,4 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
 - [ ] 正文里直接出现编号 / 哈希 / 类名 / 属性名 / 测试例数？
 - [ ] 没有面向用户的「本次更新」段，或它不在最前？
 - [ ] 盘上 release notes 与 Release 正文两处不一致？
+- [ ] Release 标题带了描述性文本 / 分隔副题（应为裸 `vX.Y.Z`）？

package/.agents/prompts/architecture-designer.md

@@ -1,8 +1,8 @@
 ---
 description: 资深系统架构师角色 Prompt（短常驻）——架构设计/技术选型/评审/ADR
 role: arch-designer
-version: 11
-updated: 2026-10-13
+version: 12
+updated: 2026-10-14
 ---
 
 # 架构设计师
@@ -85,8 +85,10 @@ PRD 摘要/路径、范围与非范围、NFR 基线（缺失必须索要）、
 ## 十一、归档（ADR）
 
 - 落盘 `docs/adr/YYYY-MM-DD-<简短主题>.md`（日期取评审终签日）。
+- 骨架唯一载体（单源）：@.agents/templates/adr.md.example（必写 5 节 + 可选 3 节，`参考来源` 恒为末节）；字段口径与禁写边界见 @.agents/checklists/deliverable-docs.md §四。
 - ADR 必含：`参考来源`（链接 + 访问日期）与 `对照过的备选模式`（含不采纳理由）；无外部来源则写「未检索到」。
-- 首次归档创建 `docs/adr/README.md` 索引（日期 | 主题 | 决策 | 状态）。
+- 实施类内容（闸门 / 清单 / 实现细节 / 用例集）下沉 `docs/reports/<编号>-arch-review.md`，ADR 正文不含。
+- 首次归档创建 `docs/adr/README.md` 索引：骨架见 @.agents/templates/adr-index.md.example（日期 | 主题 | 决策 | 状态，决策列 ≤20 字）。
 
 ## 十二、硬性红线
 

package/.agents/prompts/product-manager.md

@@ -1,8 +1,8 @@
 ---
 description: 产品经理角色 Prompt（短常驻）——需求分析/PRD/优先级/验收/多会话调度
 role: pm
-version: 23
-updated: 2026-10-13
+version: 25
+updated: 2026-10-14
 ---
 
 # 产品经理（PM）
@@ -10,6 +10,7 @@ updated: 2026-10-13
 > 通用规范见 @.agents/common/output-format.md 与 @.agents/common/intercom-protocol.md（常驻）。
 > 项目上下文：项目根 `AGENTS.md`（项目级属性/约束，PM 维护，pi 自动加载，见 §七）。
 > 按需技能：@.agents/skills/pm-rice.md（优先级）、@.agents/skills/pm-grill.md（澄清）。
+> @.agents/skills/pm-to-spec.md（成熟需求直出 PRD：验证接缝 + 对话综合；判定命中即跳过 grill）。
 > @.agents/skills/pm-routing.md（路由与派单纪律 + 技术调研边界；派发/调研前读取）。
 > @.agents/skills/pm-operations.md（调度细则 / 开工确认卡 / 会话生命周期 / AGENTS.md 治理 / 归档）。
 > @.agents/skills/codegraph.md（验收读码：node --file/--limit 行段读取，禁 cat 全文）。
@@ -31,6 +32,7 @@ updated: 2026-10-13
 
 9 模块：**问题证据｜目标指标｜范围/非范围｜用户场景｜业务规则｜NFRs｜AC｜上线闭环｜变更治理**。
 9 模块是验收闸门不得删；**正文用列表 + 加粗字段名承载，不用表格**（写法规格见 @.agents/checklists/deliverable-docs.md §三）。
+**入口分支**：需求成熟（命中 @.agents/skills/pm-to-spec.md 判定）→ 接缝 + 对话综合直接成稿；不成熟 → 先走 grill 五层追问。
 每模块内容与缺失后果速查（**写前参考，非正文格式**）：@.agents/checklists/pm.md（写 PRD 前读取）。
 
 ## 三、需求工作流（七阶段）
@@ -116,7 +118,7 @@ PM 负责 **Issue 立项与同步、PR 验收与评论、Tag Release、仓库治
 
 - **Issue（入口 + 摘要）**：**PRD 定稿后、开工确认卡前**建 Issue（TL;DR / AC 编号 / 优先级 / `docs/prds` 指针）——分支名需要 issue-id；**正文留 `docs/`**，Issue 不抄正文（避免双源）。同步时机仅 **5 个节点**：立项 / 派发 / 验收通过 / 合并 / 发布。
 - **PR**：PM 在 PR 评论核 AC；**验收通过 = 授权合并**；不点合并按钮。Reviewer 与 PR owner 在开工确认卡指定。
-- **发布（优先 `gh`）**：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 仍可用）→ `gh release create <tag> --title "<用户可读标题>" --notes-file docs/releases/<version>.md`；不可用降级 `git tag -a` + `git push origin <tag>`。**不自动 `gh auth login`**。
+- **发布（优先 `gh`）**：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 仍可用）→ `gh release create <tag> --title "vX.Y.Z" --notes-file docs/releases/<version>.md`（**标题口径（强约束）：@.agents/common/release-notes.md** —— 标题仅裸版本号，描述进正文首段）；不可用降级 `git tag -a` + `git push origin <tag>`。**不自动 `gh auth login`**。
 - **版本号**：SemVer（feat→MINOR / fix→PATCH / 破坏性→MAJOR）；tag 必须指向 **main 的合并提交**。
 - **仓库治理**：分支策略、`.github/` 模板（含 PR 模板）、README、`.gitignore` 属 PM；**不改源码/测试/构建配置**；冲突需改源码 → 转 worker。
 - **回滚**：已 push 的 tag 不删（改发下一个 PATCH），除非用户明确要求。

package/.agents/prompts/test-engineer.md

@@ -1,8 +1,8 @@
 ---
 description: 测试工程师角色 Prompt（短常驻）——策略/用例/缺陷/质量保障
 role: qa
-version: 13
-updated: 2026-10-13
+version: 14
+updated: 2026-10-14
 ---
 
 # 测试工程师（QA）
@@ -62,6 +62,7 @@ DDD 分层对齐（简）：
 - **AC = 测试用例**：Given/When/Then 直接转译；无 AC 需求先补齐再测。
 - **业务规则 → 领域测试**：状态流转、不变量对应 domain 单测；发现规则散落组件/Service 时提示研发收敛。
 - **评审参与**：需求评审确认可测性（数据口径/埋点/边界）。
+- **接缝确认 = QA 在 PRD 阶段的输入**：PM 列验证接缝候选（理想 1 个、优先复用、能高不高低）→ QA 确认或修正（可改为更高/更少）→ PM 写入 PRD「AC」首行；用例按确认后的接缝组织（流程见 @.agents/skills/pm-to-spec.md，用例设计见 @.agents/skills/test-design.md）。
 - **缺陷闭环联动**：指派明确、信息完整，避免"环境问题/数据问题"推诿。缺陷**全量入库**，落点见 @.agents/skills/test-design.md「缺陷管理」（`docs/reports/<编号>-defects.md` 或项目约定缺陷平台）。
 - **PR 验证**：在 PR 评论贴**全量门禁精确数字**（命令 + exit code + 文件数/例数/红数）与预览环境结论；**PM 验收通过前不得以"测试已过"为由催促合并**（合并由 RD 在 PM 授权后执行）。
 

package/.agents/skills/arch-patterns.md

@@ -41,21 +41,10 @@ graph TD
 
 ## ADR 模板
 
-```md
-# ADR-<编号>: <标题>
-- 日期：YYYY-MM-DD
-- 状态：提议 / 已接受 / 已废弃
-- 背景：<问题与约束>
-- 决策：<选择了什么>
-- 理由：<对照四步法分析>
-- 对照过的备选模式：<模式 → 不采纳原因（含"维持现状"基线）>
-- 参考来源：<[标题](链接) · 访问 YYYY-MM-DD；无则写"未检索到">
-- 备选方案：<列表 + 否决理由>
-- 后果：<正面 / 负面 / 风险>
-- 相关：<PRD / 关联 ADR / docs/research 路径>
-```
-
-> 长度上限 60 行、骨架与必写/可省/禁写见 @.agents/checklists/deliverable-docs.md §四。
+- **骨架唯一载体（单源）**：@.agents/templates/adr.md.example —— 复制后按「必写 5 节 + 可选 3 节」填空（标题逐字、顺序固定，`参考来源` 恒为末节）。
+- **模式对照法**：写入前先做上面对照四步法，把 ≥2 个候选的「不采纳理由」写进 `## 对照过的备选模式`（含「维持现状」基线）。
+- **字段口径与边界**：状态值域 4 值 / 头部 4 字段 / ≤60 行 / 禁写下沉清单，见 @.agents/checklists/deliverable-docs.md §四。
+- **索引登记**：每篇 ADR 在 `docs/adr/README.md` 追加一行（决策列 ≤20 字），索引骨架见 @.agents/templates/adr-index.md.example。
 
 ## 误区
 

package/.agents/skills/github-flow.md

@@ -53,7 +53,7 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 
 - 版本号：SemVer，PM 按批次范围定（feat→MINOR / fix→PATCH / 破坏性→MAJOR）；项目 `AGENTS.md` 有约定则从之。
 - 门禁：AC 全过 + 验收闭环 + main 门禁全绿 + 工作区干净 + PR 已合并。
-- **优先 `gh`**：`gh release create <tag> --title "<用户可读标题>" --notes-file docs/releases/<version>.md`。
+- **优先 `gh`**：`gh release create <tag> --title "vX.Y.Z" --notes-file docs/releases/<version>.md`（**标题口径（强约束）：@.agents/common/release-notes.md** —— 标题仅裸版本号，描述进正文首段）。
 - 探测：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 **仍可用**，可 `gh api user` 复核）；**不自动 `gh auth login`**（涉用户凭证）。
 - release notes 落盘 `docs/releases/<version>.md`（**写作规范（强约束）：@.agents/common/release-notes.md** —— 面向用户「本次更新」置顶、内部编号 / 文件名 / 属性名一律下沉「技术细节」、正文不用表格；骨架见 @.agents/templates/release-notes.md.example）。
 - 回滚：未 push → `git tag -d`；已 push → **不删远端 tag**，改发下一个 PATCH 修正（用户明确要求才删）。

package/.agents/skills/pm-grill.md

@@ -6,6 +6,10 @@ description: 按需技能——苏格拉底式澄清（grill-me）
 
 需求模糊时**必须**触发，逐层追问直至澄清，澄清前不得写 PRD。
 
+## 需求成熟度判定：命中则不触发
+
+先按 @.agents/skills/pm-to-spec.md §一 判成熟度（① 已有 grill 结论；② 已有原型/设计稿；③ 已有 ADR 或架构评审回执；④ 用户明示「讨论已充分」）。**任一命中 → 不触发本清单**，改走该技能的对话综合流程；一条都不命中才逐层追问。判定与综合入口口径以 `pm-to-spec.md` 为准，本文件不另设标准。
+
 ## 五层追问
 
 1. **目标用户**：谁？画像？规模？

package/.agents/skills/pm-to-spec.md

@@ -0,0 +1,83 @@
+---
+description: 按需技能——成熟需求的规格生产方式（验证接缝 + 对话综合，产出仍为 PRD）
+---
+
+# pm-to-spec（成熟需求直出 PRD）
+
+> 入口分支：需求**已成熟**（命中 §一 判定）时跳过 grill，走「接缝 → 综合 → 缺口检查 → 出稿」；不成熟仍走 @.agents/skills/pm-grill.md 五层追问。
+> 产出物一律叫 **PRD**（禁 `spec` 作并列术语）；格式 = 头部 + TL;DR + 9 模块（见 @.agents/checklists/deliverable-docs.md §三）。
+
+## 一、成熟度判定（4 条，任一命中即可走综合）
+
+1. **已有 grill 结论**：本需求已跑完五层追问并澄清。
+2. **已有原型 / 设计稿**：用户或 RD 已给出界面 / 交互稿。
+3. **已有 ADR 或架构评审回执**：`docs/adr/` 或 arch 回执已定关键取舍。
+4. **用户明示「讨论已充分」**：用户显式表示可直接成稿。
+
+- **一条都不命中 → 仍走 grill**，不得跳过；命中后也只在缺口处定点补产，不重复盘问。
+- 判定结论写入 PRD 头部指针（来源：grill 结论 / 原型 / ADR），供回执核对。
+
+## 二、接缝步骤（写 PRD 前先定可测接入点）
+
+- **PM 列候选 → QA 确认**：PM 只列 1–3 个候选接入点；最终以 QA 确认为准（QA 可改为更高 / 更少）。
+- **理想 1 个接缝**：接缝越少越好。
+- **优先复用已有接缝**：已有测试 / 调用入口优先于新建。
+- **能高不高低**：能在高层稳定接口测，就不下沉到实现细节。
+- 结论写入 PRD「七、AC」首行：`验证接缝：<接入点>（QA 已确认 YYYY-MM-DD）`；不适用写「不适用：<一行理由>」。
+- **一致性闸门（AC8）**：PRD 接缝与 QA 用例范围不一致 → PM 验收**打回**，对齐后重新验收（不得带不一致合入）。
+
+## 三、对话综合流程
+
+1. **判成熟度**（§一）：不命中 → 回 grill。
+2. **列接缝候选 → 请 QA 确认**（§二）。
+3. **综合上下文成稿**：按 §四 映射把已有讨论填进 9 模块；只综合已知，不重新盘问。
+4. **缺口检查**（§五）：缺口未清空不得出稿。
+5. **自核路径无关判据**（§六）→ 落 `docs/prds/` + 更新索引。
+
+## 四、上游 7 节 → 9 模块映射（列表，非表格）
+
+上游 `to-spec` 模板 7 节按下述归位；**实现决策 / 测试决策不落 PRD 正文**，只留指针：
+
+1. **问题证据** ← 上游「问题陈述」。
+2. **目标指标** ← 上游无对应：取 5 Whys + 北极星拆解；无依据即记缺口（§五）。
+3. **范围/非范围** ← 上游「用户故事」+「范围外」（非范围必带理由）。
+4. **用户场景** ← 上游「解决方案」（能力 / 关键路径视角）。
+5. **业务规则** ← 上游「解决方案」+「补充说明」中的状态 / 权限 / 边界 / 不变量。
+6. **NFRs** ← 上游「补充说明」的业务视角基线；无则写「不适用：<理由>」。
+7. **AC** ← 上游「用户故事」逐条转 Given/When/Then；首行为验证接缝（§二）。
+8. **上线闭环** ← 上游「补充说明」（灰度 / 监控 / 回滚）；缺则按项目默认并记缺口。
+9. **变更治理** ← 上游「补充说明」（正式流程 + 版本记录）。
+- **上游「实现决策」** → ⛔ 不写正文，指针 `docs/adr/`。
+- **上游「测试决策」** → ⛔ 不写正文，指针 QA 用例范围（`docs/reports/`）。
+
+## 五、缺口检查（缺口未清空不得出稿）
+
+逐条核对，缺一即列缺口并定点补产（补产靠 grill / 原型 / ADR / 用户拍板）：
+
+- 目标指标（北极星拆解 + 预期值）
+- NFRs（性能 / 安全 / 兼容性业务基线）
+- 上线闭环（灰度 / 监控 / 回滚）
+- 变更治理（正式流程 + 版本记录）
+
+处理顺序：先输出**缺口清单**（编号 + 缺口 + 影响）→ 定点补齐 → 复检清空 → 才可出稿。**不得**带着缺口直接成稿。
+
+## 六、路径无关判据清单（AC1，第三方逐条可核）
+
+- 头部齐（状态 / 更新 / Owner / 指针）
+- TL;DR ≤5 行（做什么 · 给谁 · 成功标准 · 不做什么）
+- 9 模块无空（不适用项写「不适用：<理由>」）
+- AC 逐条 Given/When/Then + 五覆盖（主路径 / 异常 / 边界 / 负向闭环 / 设计一致性）
+- 非范围含理由
+- 战略筛子 + RICE 结论在
+- 正文无表格
+- ≤150 行
+- 落 `docs/prds/` 且索引更新
+- Issue 只有摘要 + 指针（正文在 `docs/prds/`）
+
+> 判据与 @.agents/checklists/deliverable-docs.md §三、@.agents/checklists/pm.md 一致；模板见 @.agents/templates/prd.md.example。
+
+## 反模式
+
+- 不判成熟度就直接盘问（重复澄清轮次）。
+- 接缝由 PM 单方拍定、未经 QA 确认。
+- 带缺口出稿；写「实现决策 / 测试决策」正文；用 `spec` 作并列术语或替代 PRD 直发 tracker。

package/.agents/templates/adr-index.md.example

@@ -0,0 +1,11 @@
+<!-- ADR 索引骨架单源（T520）：复制为 docs/adr/README.md 后逐行追加；决策单元格 ≤20 字（短结论，细节留在各 ADR 正文）。 -->
+
+# ADR 索引（架构决策记录）
+
+> 约定见 @.agents/prompts/architecture-designer.md §十一：落盘 `docs/adr/YYYY-MM-DD-<简短主题>.md`（日期取评审终签日）；
+> 每篇必含 `参考来源`（链接 + 访问日期）与 `对照过的备选模式`（含不采纳理由）。
+> 本文件是**索引**，不是条款出处；机制条款以 `.agents/` 为准（单一事实来源）。
+
+| 日期 | 主题 | 决策 | 状态 |
+| :--- | :--- | :--- | :--- |
+| YYYY-MM-DD | [<简短主题>](YYYY-MM-DD-<slug>.md) | <≤20 字短结论> | <状态值域其一> |

package/.agents/templates/adr.md.example

@@ -0,0 +1,45 @@
+<!-- ADR 骨架单源（T520）：复制为 docs/adr/YYYY-MM-DD-<简短主题>.md 后逐节填空；日期取评审终签日。
+     规范口径 @.agents/checklists/deliverable-docs.md §四 · 模式对照 @.agents/skills/arch-patterns.md · 索引登记 @.agents/templates/adr-index.md.example。 -->
+
+<!-- 禁写下沉清单（一律另存）：实施闸门 · 接线清单 · 交接实现 · 判定式全文 · 用例集。 -->
+
+# ADR：<简短主题>
+
+- 状态：提议 / 已接受（待落地） / 已接受（已落地 vX.Y.Z） / 已废弃（被 <yyyy-mm-dd-slug> 取代）
+- 更新：YYYY-MM-DD
+- Owner：<角色>
+- 指针：<上游 PRD / 评审报告 / 关联 ADR 相对路径>
+
+## 背景
+
+- <问题、约束、触发原因；≤5 行>
+
+## 决策
+
+<选择了什么；1–3 句>
+
+## 理由
+
+1. <业务匹配 / 成熟度 / 团队能力 / 成本 四步法要点，每点一行>
+
+## 对照过的备选模式
+
+1. **<候选模式（含「维持现状」基线）>** —— 适用：<条件>；代价：<代价>；<采纳 / 不采纳理由>。
+
+<!-- 可选节：按需保留，顺序固定；参考来源恒为末节。 -->
+
+## 后果与风险
+
+- <正面 / 负面 / 风险>
+
+## 限制与已知边界
+
+- <适用范围边界 / 不覆盖项 / 不追溯项>
+
+## 相关指针
+
+- <骨架 / 规范 / 评审报告 / 关联文档路径>
+
+## 参考来源
+
+- [<标题>](<链接>) · 访问 YYYY-MM-DD · <一句话结论>；无外部来源则写「未检索到」。

package/.agents/templates/prd.md.example

@@ -0,0 +1,65 @@
+<!--
+  PRD 骨架 —— 复制为 docs/prds/YYYY-MM-DD-<slug>.md 后逐段填空。
+  权威写法：@.agents/checklists/deliverable-docs.md §三；生产方式：@.agents/skills/pm-to-spec.md
+  ⛔ 自查：正文无表格；每模块 ≤3 句；不适用项写「不适用：<理由>」；AC 一条一行；≤150 行。
+-->
+
+# PRD：<标题>
+
+- 状态：草稿 / 待确认 / 已定稿 · Owner：PM
+- 更新：YYYY-MM-DD
+- 指针：上游 <Issue / 讨论> · 关联 ADR / 调研 `docs/...md`
+- 优先级：<战略筛子结论 / RICE 高|中|低>
+
+## TL;DR（≤5 行）
+
+- **做什么**：<一句话>
+- **给谁**：<用户 / 角色>
+- **成功标准**：<可核指标>
+- **不做什么**：<边界>
+
+## 一、问题证据
+
+<数据 / 反馈 + 5 Whys 摘要（展开落 `docs/research/`）>
+
+## 二、目标指标
+
+<北极星拆解 + 预期提升值>
+
+## 三、范围 / 非范围
+
+- **范围**：<条目>
+- **非范围**：<条目 + 一行理由>
+
+## 四、用户场景
+
+<画像 + 场景卡 + 关键路径 + 页面状态清单（加载 / 空 / 错误 / 成功）>
+
+## 五、业务规则
+
+<状态流转 / 权限 / 边界 / 不变量>
+
+## 六、NFRs
+
+<性能 / 安全 / 兼容性业务基线；不适用：<理由>>
+
+## 七、AC
+
+- 验证接缝：<接入点>（QA 已确认 YYYY-MM-DD）
+- AC1（主路径）：Given <前置>，When <操作>，Then <预期>
+- AC2（异常）：Given <前置>，When <操作>，Then <预期>
+- AC3（边界）：Given <前置>，When <操作>，Then <预期>
+- AC4（负向闭环）：Given <前置>，When <操作>，Then <预期>
+- AC5（设计一致性）：Given <前置>，When <操作>，Then <预期>
+
+## 八、上线闭环
+
+<灰度 / 监控 / 回滚>
+
+## 九、变更治理
+
+<正式流程 + 版本记录（Hotfix 24h 补单）>
+
+## 附录：战略筛子 / RICE 结论
+
+<结论 + 指针；打分过程不展开>

package/.agents/templates/release-notes.md.example

@@ -2,6 +2,7 @@
   release notes 骨架 —— 复制为 docs/releases/<version>.md 后逐段填空。
   权威规范：@.agents/common/release-notes.md
   用法：把面向用户的「本次更新」放在最前；内部信息一律下沉「技术细节（可略过）」。
+  Release 标题 = 裸 `vX.Y.Z`（仅版本号，描述性概括进正文首段）—— 权威单处 @.agents/common/release-notes.md §一.5。
   ⛔ 自查：正文无编号 / 哈希 / 文件名 / 函数名 / 内部属性名 / 测试例数 / 守卫名 / 内部模块名；正文不要用表格。
 -->
 

package/README.md

@@ -24,7 +24,7 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
    ```bash
    cd 你的项目
-   pi install --local npm:@nathan33/nao-skill@0.16.2   # 声明 pin + 把机制包物化到项目内 .pi/npm
+   pi install --local npm:@nathan33/nao-skill@0.17.3   # 声明 pin + 把机制包物化到项目内 .pi/npm
    npx @nathan33/nao-skill init                        # 写入转发 shim + 生成 AGENTS.md
    ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathan33/nao-skill",
-  "version": "0.16.2",
+  "version": "0.17.3",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {