@tanlinfeng/project-docs-workflow 0.0.0-stage → 2.0.0

package/skills/domain-modeling/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: domain-modeling
+description: 构建并打磨项目的领域模型与术语。当讨论代码库术语、编写或修改 CONTEXT.md、或记录/编辑 ADR 时使用。
+---
+
+# Domain Modeling（领域建模）
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 domain-modeling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+在设计的同时**主动**构建并打磨项目的领域模型。这是主动的纪律：质疑术语、构造边界场景、在术语和决策成型的那一刻就把它们写下来。（只是为查词而读 `CONTEXT.md` 不算本 skill——那是任何 skill 都能做的一行习惯；本 skill 用于**修改**模型，而不只是消费它。）
+
+## 文件结构
+
+多数仓库只有一个上下文：
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+若根目录存在 `CONTEXT-MAP.md`，说明仓库有多个上下文，由它指向每个上下文的位置。
+
+**惰性创建**：只在有内容可写时才建文件。没有 `CONTEXT.md`，就在第一个术语确定时创建；没有 `docs/adr/`，就在需要第一条 ADR 时创建。
+
+## 会话中的动作
+
+- **对照词汇表质疑**：用户用词与 `CONTEXT.md` 冲突时立刻指出。「你的词汇表把 cancellation 定义为 X，但你说的似乎是 Y，到底是哪个？」
+- **锐化模糊表达**：用户用含糊或一词多义的词时，提出精确的规范术语。「你说的 account 是指 Customer 还是 User？这是两回事。」
+- **讨论具体场景**：讨论领域关系时用具体场景压力测试，逼用户把概念边界说清楚。
+- **与代码交叉验证**：用户描述某处如何工作时，核对代码是否一致；矛盾要当面提出。「你的代码取消整个 Order，但你刚说可以部分取消，哪个对？」
+- **立即更新 CONTEXT.md**：术语一确定就当场写入，不要攒批。
+
+`CONTEXT.md` 必须完全不含实现细节：它是词汇表，不是 spec、草稿本或实现决策仓库。
+
+## CONTEXT.md 格式
+
+```md
+# {上下文名称}
+
+{一两句话说明这是什么上下文、为什么存在。}
+
+## Language
+
+**Order**：
+{一或两句话的术语描述}
+_Avoid_: Purchase, transaction
+```
+
+规则：
+
+- **有主见**：同一概念有多个词时，选最好的一个，其余列入 `_Avoid_`。
+- **定义紧致**：最多一两句，定义它**是什么**，不是**做什么**。
+- **只收本项目特有概念**：通用编程概念（超时、错误类型、工具模式）不进，哪怕项目大量使用它们。
+- **自然成簇时可分子标题**；单一内聚领域用平铺列表即可。
+
+## ADR
+
+ADRs 放在 `docs/adr/`，顺序编号：`0001-slug.md`、`0002-slug.md`。编号时扫描现有文件取最大号加一。
+
+**模板极简**（一条 ADR 可以只有一段）：
+
+```md
+# {决策的简短标题}
+
+{1-3 句：背景是什么、决定了什么、为什么。}
+```
+
+价值在于记录**做过这个决策**及其**原因**，而非填满小节。可选小节仅在确有价值时加：`Status` frontmatter（`proposed | accepted | deprecated | superseded by ADR-NNNN`）、Considered Options、Consequences。
+
+**仅当以下三条同时成立才提议写 ADR**：
+
+1. **难以逆转**：以后改主意的代价可观。
+2. **无背景会令人意外**：未来的读者会想「当初为什么这么做？」
+3. **是真实取舍的结果**：确有替代方案，且有特定理由选中这一个。
+
+缺任何一条就跳过——容易反悔的将来直接反悔即可；不意外的没人会问；没有替代方案的记下来也只是「我们做了显而易见的事」。
+
+典型合格情形：架构形态；上下文间的集成模式；带锁定的技术选型（数据库、消息总线、认证、部署目标）；边界与范围决策（显式的「不做」同样有价值）；刻意偏离常规路径的做法；代码里看不见的约束；拒绝理由非显然的替代方案。

package/skills/domain-modeling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Domain Modeling"
+  short_description: "Build and sharpen a domain model"

package/skills/grill-me/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: grill-me
+description: 追问式访谈（grilling）的入口别名，用于把计划或设计压到没有含糊之处。
+disable-model-invocation: true
+---
+
+# Grill Me
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 grill-me（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+`grill-me` 只是 `grilling` 的入口别名，本身不含流程。
+
+请改调用 `grilling` skill；若环境未安装，按 `project-docs-workflow/references/deps/grilling.md` 执行。

package/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: grill-with-docs
+description: 追问式访谈的同时产出文档（ADR 与术语表）。
+disable-model-invocation: true
+---
+
+# Grill with Docs
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 grill-with-docs（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+`grill-with-docs` 是一个包装器：把 `grilling` 与 `domain-modeling` 一起跑。
+
+- 用 `grilling` 推进设计树、逐轮追问，直到达成共同理解。
+- 同时用 `domain-modeling`：术语确定时当场写入 `CONTEXT.md`；决策满足「难以逆转 / 无背景会意外 / 真实取舍」三条时记录 ADR。
+
+两个流程交织进行：每轮追问中浮现的术语与决策，立刻落成文档。
+
+若环境未安装，按 `project-docs-workflow/references/deps/grilling.md` 与 `project-docs-workflow/references/deps/domain-modeling.md` 执行。

package/skills/grilling/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: grilling
+description: 追问式访谈，把计划、决策或想法压到没有含糊之处。当用户想压力测试自己的思路、或说出任何 "grill" 触发短语时使用。
+---
+
+# Grilling（追问式访谈）
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 grilling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+持续追问用户，直到双方对方案达成共同理解。把这次访谈建模成一棵**设计树（design tree）**：每个决策都会分叉出依赖它的子决策。
+
+## 按轮次推进
+
+**frontier（前沿）** = 所有前置条件已确定的决策：也就是你现在就能问、不必臆测尚未听到的答案的问题。
+
+1. 一轮处理当前 frontier：把 frontier 上的问题**一次性全部提出**。
+2. 每个问题**编号**，并给出**你推荐的答案**。
+3. 等用户回答后，再进入下一轮。
+
+轮次格式：
+
+```
+❓ **Q1** - **<问题标题>**：<问题正文，可多段，可含多选项>
+
+➡️ <你推荐的答案>
+
+---
+
+❓ **Q2** - **<问题标题>**：<问题正文>
+
+➡️ <你推荐的答案>
+```
+
+用户每一轮的回答会重塑整棵树：已确定的决策把 frontier 向外推，解锁依赖它们的问题。每轮结束都**重新计算 frontier**，再问下一轮。若某问题的答案依赖本轮尚未解决的另一个问题，它属于**后面的轮次**，不属于本轮。
+
+## 事实 vs 决策
+
+- **事实是 agent 的活，永远不要问用户。** 当某个 frontier 问题需要环境中的事实（文件系统、工具、外部文档等），派子 agent 去查，不要问用户你本可以自己查的东西。
+- **不要因此阻塞**：一个还在跑的探查本身就是一个未确定的前置条件，所以只有它下游的问题需要等子 agent 回报；frontier 上其余问题现在就问。
+- **决策是用户的活。** 每个决策都摆到用户面前并等待回答，绝不替用户拍板。
+
+## 完成条件
+
+当 frontier 为空——设计树每个分支都走过、没有任何东西被默默假设——本次访谈结束。
+
+**在用户确认你们达成了共同理解之前，不要动手实施。**

package/skills/grilling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Grilling"
+  short_description: "Stress-test thinking a round of questions at a time"

package/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: improve-codebase-architecture
+description: 代码库架构改进路线的占位；需要术语或 ADR 支持时转 domain-modeling。
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture（路径占位）
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 improve-codebase-architecture（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+本 skill 只标出代码库架构改进的路线，不含完整流程。
+
+- **目标**：找出「深化模块」的机会（把浅模块变深），提升可测试性与 AI 可导航性。
+- **基础**：建立在领域模型与共享架构词汇（module / interface / depth / seam / adapter / leverage / locality）之上；领域术语来自 `CONTEXT.md`，决策记录在 `docs/adr/`。
+- **无完整流程时**：本技能包不提供扫描与 HTML 报告流程。若环境未安装完整 skill，而你需要术语或 ADR 支持，转 `domain-modeling`（未安装则见 `project-docs-workflow/references/deps/domain-modeling.md`）。

package/skills/project-docs-workflow/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: project-docs-workflow
+description: Initialize or align a project's documentation workflow — issue tracker, ADRs, PDR product specs (goal/current), recommended five-step development workflow, and domain terminology. Run manually once per project (idempotent); creates missing files and reports alignment without overwriting.
+disable-model-invocation: true
+---
+
+# Project Docs Workflow
+
+Scaffold and align a project's documentation system: issue tracker, ADRs, PDR product specs, domain terminology, and a recommended five-step development workflow. The skill is the canonical source; init materializes the rules into the target project so agents read them at runtime.
+
+Run it manually, once per project — on adoption, or again after the skill's templates evolve to check alignment. Re-runs are idempotent: they create what is missing and report drift, never rewrite existing content.
+
+## Ownership model
+
+- **Canonical**: this skill holds the rules (`references/`) and templates (`assets/templates/`).
+- **Materialized**: init copies rules into the target project. Those copies are the runtime source agents read; the skill does not auto-load.
+- **Overrides are legitimate**: projects edit their copies to fit local reality. Init reports the diff, it does not enforce or revert.
+- **Language**: templates default to Chinese; for non-Chinese projects, translate the materialized copies — overrides are legitimate.
+- **Never overwrite**: existing content is compared, never rewritten (one additive exception: the missing `AGENTS.md` block — see checklist).
+
+## 依赖解析（两级）
+
+External skill references resolve in two levels:
+
+1. **Invoke the skill by name** — the user has the full version installed, or the bundled lite version ships with the package (canonical names: `grilling`, `domain-modeling`, `tdd`, `deepwork`, `retro`, `doc-opt`, `improve-codebase-architecture`; the full version wins when present).
+2. **Fallback** — if that skill is absent, follow `references/deps/<name>.md`; `deepwork` / `retro` / `improve-codebase-architecture` share `references/deps/boundaries.md`.
+
+Canonical wording (templates use the same line with the deps path parameterized): 调用 `<skill>`（未安装则按 `<deps 路径>/<file>.md` 执行）— skill-internal docs use `references/deps/<file>.md`, materialized project files use `docs/agents/deps/<file>.md`.
+
+## Init procedure
+
+Run from the target project root (`cwd`).
+
+1. **Inventory** every artifact in the checklist below. Classify each as *missing* or *existing*. Done when every row has a classification.
+2. **Create missing** files from their template, and create the issue directory tree.
+2b. **Fill placeholders**: fill only obvious, determinable *fill-in* placeholders (e.g. project name from the repo/directory name); list every remaining fill-in placeholder under `Next:` in the report. Format notation such as `<标题>` is documentation, not a placeholder — skip it.
+3. **Compare existing** files against their template: classify *aligned*, or *diff* with the specific differences listed.
+4. **Report** using the format below.
+
+### Artifact checklist
+
+| Artifact | Template |
+| :--- | :--- |
+| `AGENTS.md` → `## Agent skills` block | `assets/templates/project/agents-block.md` |
+| `docs/agents/issues.md` | `assets/templates/project/agents-issues.md` |
+| `docs/agents/domain.md` | `assets/templates/project/agents-domain.md` |
+| `docs/agents/workflow.md` | `assets/templates/project/agents-workflow.md` |
+| `docs/agents/deps/` | `references/deps/*`（整目录复制，不改内容） |
+| `docs/issues/` directory tree | none — create dirs (below) |
+| `docs/adr/README.md` | `assets/templates/project/adr-readme.md` |
+| `docs/pdr/00-README.md` | `assets/templates/project/pdr-00-readme.md` |
+| `CONTEXT.md` | `assets/templates/project/context.md` |
+
+- Create `AGENTS.md` only if missing — its whole content is this block; a file containing only this section is intentional (projects add their own guidance around it). If `AGENTS.md` exists: heading `## Agent skills` present → compare the block in place (never edit); absent → append the block at end of file, separated by one blank line. Only `AGENTS.md` is touched, never `CLAUDE.md`.
+- The provenance line sits immediately under the `## Agent skills` heading and is intentional — keep it (it identifies materialized files and their generation).
+- Issue tree: `bug/{human,agent,history}`, `feature/{human,agent,history}`, `chore/{human,agent,history}`, `suggestion/{human,agent}`; add a `.gitkeep` to each leaf directory (one containing no files). Do not run `git init`.
+- Dep fallbacks: init copies `references/deps/*` into the project's `docs/agents/deps/` as a whole-directory copy (content unchanged), so target projects are self-sufficient even without this skill installed.
+- Domain glossaries (e.g. `docs/common/glossary.md`) are **not** scaffolded; the rules cover them and projects create them on demand.
+
+### Alignment comparison (existing files)
+
+Compare **rules, not bytes**. An existing file is **aligned** when every required rule/section below is present in recognizable form — wording, language, ordering, formatting and filled-in project content may all differ. Project additions are always fine, never a diff.
+
+**diff** = a required rule/section is missing, or a default rule is contradicted. Diffs are informational; init never auto-fixes. One bullet per file: `- <file>: <missing or contradicted rule>`.
+
+Ignore in every comparison: the provenance line; filled placeholders; index/table rows; module/term/entry names; language; extra content.
+
+Required elements per artifact:
+
+- `AGENTS.md` block: `## Agent skills` heading + three subsections (`### Issue tracker`, `### Domain docs`, `### Development workflow`).
+- `docs/agents/issues.md`: directory contract; human/agent responsibility; entry format (`Status:` line, `## 完成判据`, `## 步骤`, `## Log`; the `## 结果` section itself is optional); archiving suffixes (`-done`/`-drop`); suggestion routing.
+- `docs/agents/domain.md`: read CONTEXT.md + docs/adr before exploring; silently continue if missing; glossary vocabulary rule; ADR-conflict flagging.
+- `docs/agents/workflow.md`: recommended five-step flow (规划 / 骨架 / 细节 / 异常 / 回顾 with 回顾 = docs-sync wrap-up); align-before-build ordering; conversational alignment (no freeze); elastic granularity suggestion (≈0.5 人天 heuristic); issue `## 步骤` tracking + resume anchor; PDR goal/current gap→issue derivation; boundaries (deepwork / tdd / retro / grilling 调用 + 兜底指针).
+- `docs/adr/README.md`: lifecycle rules (edit+Log, delete→tombstone stub, no renumber); catalog table present.
+- `docs/pdr/00-README.md`: purpose; 最终目标 / 当前进展 overview sections; module index; reading order.
+- `CONTEXT.md`: glossary structure (term blocks with `_Avoid_`).
+- `docs/issues/` tree: leaf directories exist (`.gitkeep` may be checked); extras informational only.
+- `docs/agents/deps/`: leaf files exist (`grilling.md`, `domain-modeling.md`, `tdd.md`, `doc-opt.md`, `boundaries.md`); extras informational only.
+
+### Report format
+
+Write the report in the project's documentation language (default: Chinese, matching the templates).
+
+```
+## Init report
+- Created: …
+- Aligned: …
+- Diff: one bullet per file: `- <file>: <missing or contradicted rule>`（仅供参考，不自动改；multi-file → multiple bullets）
+- Next: remaining placeholders plus a one-line "do this first".
+```
+
+## References
+
+Rules carry the detail; read the one you need.
+
+- `references/issues.md` — issue tracker directory contract, entry format, `suggestion` routing.
+- `references/adr.md` — ADR lifecycle (edit + Log, delete → tombstone stub, reference sweep, catalog index), body shape.
+- `references/pdr.md` — PDR product-spec structure (`00-README` / `01-spec` / `02-interfaces` / `03-nfr` / `04-current` + `design/`), the goal/current & gap→issues layer, PDR↔ADR boundary.
+- `references/terminology.md` — `CONTEXT.md` primary glossary, domain glossary, usage rules.
+- `references/workflow.md` — recommended single-issue development flow (five steps, alignment, granularity, tracking, docs-sync hooks, skill boundaries).
+- `references/coexistence.md` — how this profile sits beside `domain-modeling`, `grilling`, `deepwork`, `tdd`, `retro`, and the bundled `doc-opt`; and how its docs/issues conventions supersede older `.scratch`-style trackers.
+- `references/deps/` — fallback procedures for the two-level resolution: `grilling` / `domain-modeling` / `tdd` / `doc-opt` / `boundaries` (`deepwork` / `retro` / `improve-codebase-architecture` share `boundaries.md`).
+
+## Templates
+
+- `assets/templates/project/*` — the files init materializes (Chinese). They carry the provenance marker (current generation: `v2`; in `agents-block.md` it sits just under the `## Agent skills` heading) — keep it; future generations update the marker so stale copies are detectable.
+- `references/deps/*` — fallback procedures when an external skill is absent. init copies the whole directory as-is into the project's `docs/agents/deps/`; they are not materialized templates and carry no provenance marker.
+- `assets/templates/entries/*` — day-to-day authoring aids used when this skill is at hand (copy the skeleton when creating a new entry). NOT materialized by init; the rule docs are self-sufficient without them; materialized docs may reference their path opportunistically.

package/skills/project-docs-workflow/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Project Docs Workflow"
+  short_description: "Initialize or align a project's docs workflow"
+policy:
+  allow_implicit_invocation: false

package/skills/project-docs-workflow/assets/templates/entries/adr-entry.md

@@ -0,0 +1,27 @@
+<!-- 文件名：NNNN-slug.md（4 位零填充，编号永不复用；标题写在下方 H1）。语义修改就地改并在 ## Log 追加一行；删除 = 墓碑桩化。见 docs/adr/README.md。 -->
+
+# <决策短标题>
+
+<!-- 活跃条目无状态标注。失效时在 H1 之后仅用下列既定集合的标注行，每个退役事件一行、可叠加（不允许自由文本注记；示例，按需替换 XXXX / 日期 / 原因）：
+> 已被 ADR-XXXX 取代（2026-10-08）：原因
+> 经 ADR-XXXX 修订（2026-10-08）：说明
+> 已废弃（2026-10-08）：原因
+> 已删除（2026-10-08）：原因
+-->
+
+<1–3 句：背景是什么、决定了什么、为什么。>
+
+代价：<这次选择付出了什么、放弃了什么；若只是自然选择可省略。>
+
+## Log
+
+- YYYY-MM-DD <一句话原因>
+
+<!-- 仅语义修改时追加一行；非语义修改（错字 / 格式 / 链接）直接改、无需 Log。无记录可删除本节。 -->
+
+<!-- 以下小节仅在有真实价值时保留。 -->
+
+## Considered Options
+
+- **<备选 A>**：<为何未选>
+- **<备选 B>**：<为何未选>

package/skills/project-docs-workflow/assets/templates/entries/issue-entry.md

@@ -0,0 +1,28 @@
+<!-- 文件名：<项目语言短标题>.md，无编号。归档时改为 …-done.md（完成）/ …-drop.md（放弃）。步骤见 docs/agents/workflow.md。 -->
+
+# <短标题>
+
+> Status: open｜doing｜blocked ｜ 责任: human｜agent ｜ 创建: YYYY-MM-DD ｜ 关联: ADR-XXXX / 其他条目
+
+<背景与目标：问题是什么、为什么要做、预期结果。>
+
+## 完成判据
+
+- <可判定的完成条件 1>
+- <可判定的完成条件 2>
+
+## 步骤
+
+- [ ] 规划（完成判据与方案已对齐）
+- [ ] 骨架（最小可运行切片 + 证据；纯修复可跳过并注明理由）
+- [ ] 细节（主路径实现与质量）
+- [ ] 异常（失败路径、边界与稳定性）
+- [ ] 回顾（收尾回顾：文档同步）
+
+## 结果（完成后填写，可选）
+
+<完成后填写：做了什么、结论、遗留。未完成时可删本节。>
+
+## Log
+
+- YYYY-MM-DD <动作 / 进展 / 决定>

package/skills/project-docs-workflow/assets/templates/entries/pdr-current.md

@@ -0,0 +1,19 @@
+<!-- 文件名：04-current.md，位于模块根；现状快照（对照 01-spec.md 目标），收尾回顾时更新；≤1 页，只记结论与差距，不写流水账。 -->
+
+# <模块> 现状（Current）
+
+> 更新：YYYY-MM-DD ｜ 对照：01-spec.md
+
+## 进展概览
+
+- 已实现：<FR 或功能块，只记结论>
+- 部分实现：<…>
+- 未实现：<…>
+
+## 与目标的差距
+
+- <差距要点（对应 FR-<模块>-NN）>
+
+## 关键结论与已知问题
+
+- <结论 / 遗留；指向相关 issue / ADR>

package/skills/project-docs-workflow/assets/templates/entries/pdr-interfaces.md

@@ -0,0 +1,28 @@
+<!-- 本模块是这些接口的提供方；消费方引用本文件，不复制定义。权威定义（接口定义文件 / schema / 源）在此登记指针。 -->
+
+# <模块> 接口面
+
+> 定位：<模块> 对外提供的接口与契约。
+
+## 1. <接口面 / 服务分组>
+
+<一句话说明该接口面的职责与边界。>
+
+| 方法 / 接口 | 用途 |
+| :--- | :--- |
+| `<Name>` | <用途> |
+| `<Name>` | <用途> |
+
+- 关键契约：<幂等、版本、错误语义、鉴权等。>
+- 权威定义：<接口定义文件 / schema / 代码路径>。
+- 待决：<尚未定的点，建议转 issues。>
+
+## 2. <另一接口面>
+
+<职责与边界。>
+
+| 方法 / 接口 | 用途 |
+| :--- | :--- |
+| … | … |
+
+<!-- 只写对外契约，不写内部实现；接口一旦落地，实现变更不得改变此处语义。 -->

package/skills/project-docs-workflow/assets/templates/entries/pdr-module-readme.md

@@ -0,0 +1,34 @@
+<!-- 模块目录名：`NN-<模块>/`，编号即阅读顺序；本文件位于模块根，命名为 00-README.md。 -->
+
+# <模块> 模块
+
+> 定位：<一句话——该模块在产品中的角色与核心价值。>
+
+## 形态
+
+<可选：该模块的形态 / 运行方式 / 与其他模块的关系。无内容可删本节。>
+
+## 范围与边界
+
+| 交付（范围内） | 边界（不做） |
+| :--- | :--- |
+| <本模块负责什么> | <明确不做什么，防止职责蔓延> |
+
+## 依赖
+
+| 依赖 | 用途 | 契约入口 |
+| :--- | :--- | :--- |
+| <依赖方 / 模块> | <用途> | [02-interfaces.md](02-interfaces.md) §… |
+
+（无依赖则删行；契约入口只保留将真实存在的文件链接。）
+
+## 文档地图
+
+| 文件 | 内容 |
+| :--- | :--- |
+| [01-spec.md](01-spec.md) | 功能规格（FR-<模块>-NN + 验收判据） |
+| [02-interfaces.md](02-interfaces.md) | 对外接口与契约 |
+| [03-nfr.md](03-nfr.md) | 非功能约束 |
+| [design/](design/) | 机制级设计（可选，不参与编号；无则删行） |
+
+（表中只保留实际存在的文件；`design/` 等可选部分（无则删行）。）

package/skills/project-docs-workflow/assets/templates/entries/pdr-nfr.md

@@ -0,0 +1,22 @@
+<!-- 非功能规格：与功能无关、但约束产品形态的横切要求（性能 / 可观测 / 安全 / 可复现 / 隔离等）。 -->
+
+# <模块> 非功能规格
+
+> 定位：<模块> 的非功能约束。
+
+## 1. <维度，如 可复现性>
+
+- <约束 / 字段 / 阈值。>
+- 判据：<如何判定满足。>
+
+## 2. <维度，如 可观测性>
+
+- <约束。>
+- 判据：<…>
+
+## 3. <维度，如 安全 / fail-safe>
+
+- <约束。>
+- 判据：<…>
+
+<!-- 每条约束尽量落到可检查的判据；无判据的条目说明尚未定案，标注「待决」。 -->

package/skills/project-docs-workflow/assets/templates/entries/pdr-spec.md

@@ -0,0 +1,20 @@
+<!-- FR 编号：`FR-<模块>-NN`，模块用大写短名；同一模块内编号连续、不复用。 -->
+
+# <模块> 功能规格
+
+> 定位：<模块> 目标态功能规格（FR-<模块>-NN，逐条给验收判据）。依据见 [design/](design/)（无 design/ 目录则删去该链接）与相关 ADR。
+
+## 1. <功能分组>
+
+| FR | 功能 | 验收判据 |
+| :--- | :--- | :--- |
+| FR-<模块>-01 | <功能一句话> | <可判定、可验证的条件> |
+| FR-<模块>-02 | <功能> | <判据> |
+
+## 2. <另一分组>
+
+| FR | 功能 | 验收判据 |
+| :--- | :--- | :--- |
+| FR-<模块>-NN | <功能> | <判据> |
+
+<!-- 验收判据要能被检查（阈值 / 区间 / 状态谓词），不写「体验良好」这类不可判定的描述。 -->

package/skills/project-docs-workflow/assets/templates/entries/term-entry.md

@@ -0,0 +1,22 @@
+<!-- 术语条目：按落点二选一。 -->
+
+## 用于 CONTEXT.md（主术语表）
+
+**<术语>**：
+<一到两句定义，说明概念「是什么」，不写实现细节。>
+_Avoid_: <应回避的同义词 / 近义词>
+
+<!-- 只收项目特定概念；同义词归入 _Avoid_，不并存。 -->
+
+## 用于领域术语表（编号索引式，如 docs/common/glossary.md）
+
+先在术语索引表追加一行：
+
+| <# > | <术语> | <一句话> |
+| :--- | :--- | :--- |
+
+再补词条小节：
+
+## <#>. <术语>
+
+<定义与口径；需要时附交叉链接与外部来源。>

package/skills/project-docs-workflow/assets/templates/project/adr-readme.md

@@ -0,0 +1,31 @@
+> 模板来源：project-docs-workflow v2（模板演进后可重跑幂等 init 对齐；本文件可按项目实际修改）
+
+# ADR 规则与目录
+
+## 规则
+
+- 文件名：`NNNN-精炼 slug.md`（4 位零填充；**编号永不复用**：新增 = 当前最大编号 + 1，墓碑桩计入）；slug（文件名）不可变，墓碑桩化只清空内容、不改文件名；标题写在文件内 H1。
+- 维护范围：**未删除**的条目（含已失效标注者）均在册；允许修改与删除，完整历史由 git 兜底。
+- **语义修改**（结论 / 约束 / 范围变化）就地修改，并在条目 `## Log` 追加一行 `- YYYY-MM-DD <一句话原因>`。
+- **非语义修改**（错字、格式、补链接）直接改，无需 Log。
+- 默认就地改；仅当变更是"方向性 / 值得长期单独引用"时才新增条目，旧条目加注记。新增时若编号已被占用（并发写入），顺延 +1 并 sweep 更新引用。
+- **删除**优先用 `> 已废弃（日期）：原因` 标注（内容保留）；仅当项目**人类 owner**（或经其明确授权）判定"无借鉴价值 / 纯噪音"时才删除，agent 不得自行判定。
+- 删除 = **墓碑桩化**：文件内容清空为两行 `# <原标题>` + `> 已删除（YYYY-MM-DD）：原因`，**保留编号与文件名**；墓碑桩不再删除（编号永久退役）。
+- 删除顺序：①墓碑桩化（改写文件）→ ②目录移除该行 → ③全仓库 sweep；重试 / 重跑前先核对，避免重复 Log 或注记。
+- 失效标注（H1 之后，活跃条目无标注；**每个退役事件一行、可叠加**；只允许下列既定集合，不允许自由文本注记）：
+  - `> 已被 ADR-XXXX 取代（日期）：一句话`
+  - `> 经 ADR-XXXX 修订（日期）：一句话`
+  - `> 已废弃（日期）：原因`
+  - `> 已删除（日期）：原因`（墓碑桩）
+- **删除或语义修改**触发引用核查：优先派 subagent，无则自行 grep `ADR-\d{4}`（范围 = 全仓库；`docs/` 必改，代码注释逐一判定：保留 / 更新 / 就地注释；逐一处理后再收尾）。引用优先改指替代 ADR 编号；无替代则删去该句或就地注明「（ADR-XXXX 已删除）」。
+
+## 目录
+
+| 编号 | 标题 | 一句话 |
+| --- | --- | --- |
+
+新增 ADR 后在此登记一行。
+
+只列**未删除**的条目（含已失效标注者）；删除则移除该行；编号空缺 = 已删除（见对应墓碑桩文件 / git）。可在「一句话」列为已失效条目注明状态（如「已被 ADR-XXXX 取代」）。
+
+新增条目骨架（若已安装 project-docs-workflow）：~/.agents/skills/project-docs-workflow/assets/templates/entries/adr-entry.md。

package/skills/project-docs-workflow/assets/templates/project/agents-block.md

@@ -0,0 +1,15 @@
+## Agent skills
+
+> 模板来源：project-docs-workflow v2（模板演进后可重跑幂等 init 对齐；本文件可按项目实际修改）
+
+### Issue tracker
+
+工作条目位于 `docs/issues/<类型>/{human,agent}/`（类型：bug / feature / chore / suggestion）。任何工作开始前，先在对应子目录创建或更新条目，明确任务与责任，再动手；约定见 `docs/agents/issues.md`。
+
+### Domain docs
+
+单 context：仓库根目录 `CONTEXT.md`，ADR 位于 `docs/adr/`。约定见 `docs/agents/domain.md`。
+
+### Development workflow
+
+推荐五步流程：规划 / 骨架 / 细节 / 异常 / 回顾。开工前先读 PDR 目标与现状（各模块 `04-current.md`），与用户对齐本次范围与粒度；步骤记录在 issue 的 `## 步骤`。约定见 `docs/agents/workflow.md`。

package/skills/project-docs-workflow/assets/templates/project/agents-domain.md

@@ -0,0 +1,44 @@
+> 模板来源：project-docs-workflow v2（模板演进后可重跑幂等 init 对齐；本文件可按项目实际修改）
+
+# Domain Docs
+
+工程类技能在探索本代码库时应如何消费本仓库的领域文档。
+
+本模板覆盖单 context 布局；多 context（CONTEXT-MAP.md）暂未纳入。
+
+## Before exploring, read these
+
+- 根目录的 **`CONTEXT.md`**。
+- **`docs/adr/`**：读取与将要改动的领域相关的 ADR；规则与目录见 `docs/adr/README.md`。
+
+如果这些文件不存在，**静默继续**：不要提示缺失，也不要主动建议创建它们。`/domain-modeling`（未安装则按 `docs/agents/deps/domain-modeling.md` 执行；经 `/grill-with-docs` 与 `/improve-codebase-architecture` 到达，后者未安装则按 `docs/agents/deps/boundaries.md` 执行）会在词条或决策真正定案时按需创建。
+
+外部技能未安装时的兜底流程物化在 `docs/agents/deps/`。
+
+## File structure
+
+按项目实际结构填写（单 context 仓库的典型布局如下，据实替换）：
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   ├── adr/
+│   ├── agents/
+│   ├── common/
+│   ├── issues/
+│   └── pdr/
+└── <源码目录…>
+```
+
+## Use the glossary's vocabulary
+
+当你的产出提到某个领域概念（issue 标题、重构提案、假设、测试名）时，使用 `CONTEXT.md` 中定义的术语。不要漂移到术语表明确回避的同义词。
+
+如果你需要的概念还不在术语表里，这本身是一个信号：要么你在发明项目不使用的语言（重新考虑），要么存在真实缺口（记下来，交给 `/domain-modeling`；未安装则按 `docs/agents/deps/domain-modeling.md` 执行）。
+
+## Flag ADR conflicts
+
+如果你的产出与既有 ADR 冲突，显式指出，不要默默覆盖：
+
+> _与 ADR-XXXX（<决策短标题>）冲突，但值得重新讨论，因为……_