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

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（<决策短标题>）冲突，但值得重新讨论，因为……_

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

@@ -0,0 +1,65 @@
+> 模板来源：project-docs-workflow v2（模板演进后可重跑幂等 init 对齐；本文件可按项目实际修改）
+
+# Issue 体系（仓库内工作跟踪）
+
+工作条目的存放与流转规范。**任何工作（人 / agent）开始前，先在对应子目录创建或更新条目，明确任务与责任，再动手。**
+
+## 目录结构
+
+```
+docs/issues/
+├── bug/{human,agent}/        # 缺陷修复
+├── feature/{human,agent}/    # 新功能
+├── chore/{human,agent}/      # 维护 / 重构 / 杂务
+├── suggestion/{human,agent}/ # 改进建议（无 history、无状态；归宿 adr / pdr）
+└── <bug|feature|chore>/history/   # 归档：文件名尾部带 -done（完成）/ -drop（放弃）
+```
+
+- `human/` 与 `agent/` = 当前责任方；责任移交时把文件 `git mv` 到对方目录。
+- 仅保留近期待办（约一周窗口）；完成或放弃的条目由完成者随手归档，人定期巡检。
+- `suggestion` 特殊：处理完成后——采纳 → 结论落 adr（或更新 pdr），随后删除本条目；不采纳 → 仅当 human 明确要求时才落否决 ADR，否则直接删除；本质是 bug / feature / chore 的 → 挪到对应目录。
+
+## 条目格式
+
+文件名：项目语言短标题，无编号（例：`修复-首屏加载卡顿.md`）。归档时在末尾加状态后缀：`…-done.md` / `…-drop.md`。
+
+```md
+# <标题>
+> Status: open｜doing｜blocked ｜ 责任: human｜agent ｜ 创建: YYYY-MM-DD ｜ 关联: ADR-XXXX / 其他条目
+
+<背景与目标>
+
+## 完成判据
+- …
+
+## 步骤
+- [ ] 规划（完成判据与方案已对齐）
+- [ ] 骨架（最小可运行切片 + 证据；纯修复可跳过并注明理由）
+- [ ] 细节（主路径实现与质量）
+- [ ] 异常（失败路径、边界与稳定性）
+- [ ] 回顾（收尾回顾：文档同步）
+
+## 结果（完成后填写，可选）
+- …
+
+## Log
+- YYYY-MM-DD ……
+```
+
+（若本机安装了 project-docs-workflow：条目骨架 ~/.agents/skills/project-docs-workflow/assets/templates/entries/issue-entry.md；未安装则按本文格式创建。）
+
+- `Status` 就地更新；`## Log` 追加式记录，不改历史行。
+- 涉及 adr / pdr 的改动，须同步更新对应文档。
+- 推进流程见 `workflow.md`（推荐五步：规划 / 骨架 / 细节 / 异常 / 回顾）；步骤状态就地更新，变更记 Log。
+
+## 与开发流程的衔接
+
+- 开工前与用户对齐本次范围与粒度（差距候选来自 PDR 目标与现状）。
+- 步骤按 `docs/agents/workflow.md` 推荐流程推进，状态就地更新，变更记 Log。
+- 收尾回顾时更新受影响模块的 `04-current.md`。
+
+## 相关
+
+- ADR 规则与目录：`../adr/README.md`
+- 域文档约定：`domain.md`
+- 开发流程（推荐）：`workflow.md`

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

@@ -0,0 +1,61 @@
+> 模板来源：project-docs-workflow v2（模板演进后可重跑幂等 init 对齐；本文件可按项目实际修改）
+
+# 开发流程（推荐）
+
+本文件是推荐的单 issue 开发流程；项目可按实际覆盖。核心：小步推进、随时可 review、与用户对齐后再动手。
+
+## 工作单元
+
+一条 issue = 一个可独立交付的工作单元（通常 feature 级；bug / chore 同构，形态相应简化）。
+
+粒度建议（非强制）：切到「可单次 review 的推进单元」，≈0.5 人天仅启发式参考，按任务弹性调整。工作如何切分由 agent 自行感知，阶段不落盘（必要时可在当前 issue 内记一句）。
+
+## 开工前对齐
+
+读 PDR 目标与现状（`docs/pdr/` 的 `01-spec` 与各模块 `04-current.md`），列出差距候选（模块 / FR、类型、切片、完成判据），与用户确认要做哪条并落 issue。
+
+- 对话确认即可：不冻结、不设仪式行。
+- 需求变化时主动重对齐，并更新 issue 内的计划与完成判据。
+- 方向有歧义 → 调用 `grilling`（未安装则按 `docs/agents/deps/grilling.md` 执行）；`grill-me` 仅入口别名。
+- 不要吞并超出对齐范围的工作。
+
+## 五步流程（规划 / 骨架 / 细节 / 异常 / 回顾）
+
+### 规划
+
+细化完成判据与步骤状态，给出 1–2 句方案。产出最小，不新开章节。PDR 的目标 / 现状差距分析在此完成（候选带模块 / FR、类型、切片、完成判据；用户挑选后才落 issue）。
+
+### 骨架
+
+实现最小可运行的垂直切片（忽略输出 / 格式细节），留下一条运行证据，并把证据展示给用户（首个 review 点）。纯修复可跳过（在 Log 注明理由）；feature / 结构性改动必做。
+
+### 细节
+
+主路径实现、细节打磨与代码质量。`tdd` 可作内部循环（可选；未安装则按 `docs/agents/deps/tdd.md` 执行）。
+
+### 异常
+
+两点含义：作为流程步骤，主路径完成后再处理失败路径、边界与稳定性；作为开发现实，真实的开发阻塞立即处理并记 Log，不排队到本步。
+
+### 回顾（收尾回顾）
+
+issue 完成时做一次轻量的文档同步清单（`pdr/current`、`adr`、`context`、`issues`、`agents` 是否有需更新）；若无，一行 Log 即可。仅做文档同步；会话复盘属于 `retro`（未安装则按 `docs/agents/deps/boundaries.md` 执行）。
+
+## 进度与续接
+
+- 步骤记录在 issue 的 `## 步骤` 清单（就地更新）；步骤变更追加一行 Log。
+- session 为软约束：session = 用户注意力窗口，节奏由用户掌握；agent 不得吞并超出对齐范围的工作。
+- 恢复时先读 issue 的 `## 步骤` 与 `## Log`，与用户确认续点后再继续。
+- issue 收尾时更新受影响模块的 `04-current.md`，并按 `issues.md` 归档。
+
+## 边界
+
+- 高风险 / 大规模多阶段 → `deepwork`（未安装则按 `docs/agents/deps/boundaries.md` 执行），不叠加。
+- `tdd` 可作细节内循环（seam 确认并入规划对齐；未安装则按 `docs/agents/deps/tdd.md` 执行）。
+- `grilling` 为对齐访谈（`grill-me` 仅入口别名；未安装则按 `docs/agents/deps/grilling.md` 执行）。
+
+## 相关
+
+- Issue 体系：`issues.md`
+- PDR 文档集：`../pdr/00-README.md`
+- 依赖兜底文档（外部技能未安装时）：`docs/agents/deps/`

package/skills/project-docs-workflow/assets/templates/project/context.md

@@ -0,0 +1,21 @@
+> 模板来源：project-docs-workflow v2（模板演进后可重跑幂等 init 对齐；本文件可按项目实际修改）
+
+# <项目名> 上下文
+
+<一两句话说明本 context 是什么、为什么存在。项目特定概念与词汇的单一事实源，不含实现细节。>
+
+## Language
+
+<按自然聚类分组；无聚类时可扁平列出。只收项目特定概念，不收通用编程概念（超时、错误类型、工具函数等不进本表）。定义说明概念「是什么」，不写「怎么做」，一到两句。>
+
+### <分组示例>
+
+**<术语>**：
+<一到两句定义。>
+_Avoid_: <应回避的同义词 / 近义词>
+
+**<另一术语>**：
+<定义。>
+_Avoid_: <…>
+
+<新增术语时照此追加；同义词归入 `_Avoid_`，措辞有歧义时优先消歧而不是并存。>

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

@@ -0,0 +1,36 @@
+> 模板来源：project-docs-workflow v2（模板演进后可重跑幂等 init 对齐；本文件可按项目实际修改）
+
+# PDR 文档集
+
+PDR（Product Design Requirements）= 产品最终功能与形态规格书（目标态）：描述产品最终要长成什么样、由哪些模块构成、各模块对外契约与机制设计。
+
+## 最终目标
+
+<一段话描述产品的最终形态；各模块的细化目标见其 `01-spec.md`。>
+
+## 当前进展
+
+<每个模块一行概览，并指向该模块的 `04-current.md`；只记状态与差距，不写流水账。>
+
+## 模块索引
+
+| 区 / 模块 | 定位 | 入口 |
+| :--- | :--- | :--- |
+
+<!-- 示例（新增模块时替换并删除本行）：| <区 / 模块名> | <一句话定位> | <目录>/00-README.md | -->
+
+## 组织约定
+
+- 编号即阅读顺序：每模块 = 规格层（`00-README` / `01-spec` / `02-interfaces` / `03-nfr`）+ 现状快照（`04-current.md`，与目标的差距用于派生 issue）+ 设计子区（`design/`，机制级设计，不参与编号）。
+- 模块外区：架构总纲、调研等跨模块材料按需单列，不占模块编号。
+
+## 阅读顺序
+
+<先读什么建立整体基线与公共契约，再按模块读规格层，最后看调研 / 场景等附加材料。>
+
+## 新增模块
+
+- 在 `docs/pdr/` 下建编号目录（编号沿用阅读顺序，不插号）；
+- 补齐规格层四件套（`00-README` / `01-spec` / `02-interfaces` / `03-nfr`）与现状快照 `04-current.md`，机制细节进 `design/`；
+- 在上方模块索引与阅读顺序中登记入口，明确对外接口的提供方归属；
+- 涉及产品形态的决策，同步落 ADR。

package/skills/project-docs-workflow/references/adr.md

@@ -0,0 +1,53 @@
+# ADR conventions
+
+Default profile. Projects may override in their materialized `docs/adr/README.md`; that copy governs runtime behavior.
+
+## Files
+
+- Filename `NNNN-slug.md`: 4-digit zero-padded. **Numbers are never reused** — a new entry takes the current maximum number + 1 (tombstone stubs count). H1 title in the project language.
+- The slug (filename) is **immutable**: tombstoning clears the body only, it never renames the file.
+- Numbering race: when adding, if the number is already taken (concurrent write), shift +1 and sweep references (see Reference sweep).
+
+## Lifecycle
+
+The ADR set keeps current entries plus retired marker lines; editing and deleting are both allowed. Full history is held by git.
+
+- **Semantic change** (conclusion / constraint / scope): edit in place and append one line to `## Log` — `- YYYY-MM-DD <one-line reason>` (canonical format: the date then the reason, no prefix label).
+- **Non-semantic change** (typos, format, links): edit directly, no Log.
+- Default is in-place editing. Write a **new** ADR only when the change is direction-defining or worth citing on its own long-term; then annotate the old entry (see Annotations).
+
+## Deletion
+
+- Prefer an annotation first: `> 已废弃（日期）：原因` keeps the content. Delete only when the project's **human owner** (or someone explicitly authorized by them) judges the entry has no reference value / is pure noise — agents must not decide deletion on their own.
+- Deletion = **tombstone stub**: clear the file body to two lines — `# <original title>` and `> 已删除（YYYY-MM-DD）：原因` — keeping the number and filename (existing path links stay valid).
+- **Tombstones are final**: a tombstone stub is never deleted; the number retires permanently.
+- Deletion order: ① tombstone-stub the file (rewrite the body) → ② remove the row from the catalog → ③ run the whole-repo reference sweep. On retry / re-run, check first to avoid duplicate Log lines or annotations.
+
+## Annotations
+
+Status block on the first lines after the H1. Active entries carry none. Retired entries carry **only marker lines from this fixed set** — one line per retirement event, stackable; no free-form notes:
+
+| Marker | Meaning |
+| --- | --- |
+| `> 已被 ADR-XXXX 取代（日期）：原因` | superseded by a newer ADR (a new entry was written) |
+| `> 经 ADR-XXXX 修订（日期）：说明` | amended in place by a newer ADR |
+| `> 已废弃（日期）：原因` | deprecated; content retained |
+| `> 已删除（日期）：原因` | deleted; tombstone stub |
+
+## Reference sweep
+
+`ADR-XXXX` (4-digit zero-padded) is the only reference notation. Whenever an entry is **deleted or semantically edited**, the executor must sweep references: prefer a subagent; without one, grep directly. Pattern `ADR-\d{4}`; scope = the whole repository (`docs/` must be updated; code comments judged one by one: keep / update / annotate in place). Handle every hit before finishing. When a reference points at a deleted entry, prefer retargeting it to the replacing ADR number; with no replacement, drop the sentence or annotate it in place `(ADR-XXXX deleted)`.
+
+## Index (README)
+
+`docs/adr/README.md` is a **catalog**, not a status authority: table `| 编号 | 标题 | 一句话 |`. It lists every **not-deleted** entry — including entries carrying a retired marker; deleting removes the row, and a gap in the numbering means deleted (see the matching tombstone stub / git). The one-line column may note a retired entry's status (e.g. "superseded by ADR-XXXX"). Its rules section states this v2 lifecycle. After adding an entry, register a row in the catalog.
+
+## Body shape
+
+H1 title → decision + rationale + trade-off (`代价：…`) → optional `## Log` (appended on every semantic change) → optional `## Considered Options`.
+
+An ADR can be a single paragraph; the value is recording *that* a decision was made and *why*.
+
+## Relationship to domain-modeling
+
+The base ADR format is compatible with the `domain-modeling` skill's ADR-FORMAT (未安装则按 `references/deps/domain-modeling.md` 执行). That skill forbids neither edits nor deletes and carries its own `proposed | accepted | deprecated | superseded` status words; this profile is a superset (reference sweep, tombstone stubs, catalog-style README), and the two coexist. See `coexistence.md`.

package/skills/project-docs-workflow/references/coexistence.md

@@ -0,0 +1,49 @@
+# Coexistence with other skills
+
+## Scope
+
+Single-context layouts. Multi-context (`CONTEXT-MAP.md`) is not covered by this profile.
+
+## `domain-modeling`
+
+Active model-sharpening conversations. The base CONTEXT and ADR formats are compatible. Where both apply, **this profile's materialized rules govern project docs** — it is a superset of the base formats (ADR lifecycle v2 (in-place edit + Log, delete→tombstone stub, reference sweep, catalog-style README); issue routing). Do not fork or redefine the base formats beyond this house variant.
+
+Bundled lite version ships with the package; fallback doc `references/deps/domain-modeling.md`.
+
+## `grill-with-docs`
+
+A wrapper: `grilling` + `domain-modeling`. Unaffected. `grill-me` is only an entry alias of `grilling`.
+
+Bundled lite `grilling` ships with the package; fallback doc `references/deps/grilling.md` (and `references/deps/domain-modeling.md`).
+
+## `deepwork`
+
+Large or high-risk multi-phase efforts run under `deepwork`. This profile's `workflow.md` is for routine single-issue development; the two are never stacked — pick one per effort.
+
+Bundled lite version ships with the package; fallback doc `references/deps/boundaries.md`.
+
+## `tdd`
+
+Nests inside the Details step of `workflow.md` (red → green loop). Seam confirmation is folded into the Plan alignment — no second gate.
+
+Bundled lite version ships with the package; fallback doc `references/deps/tdd.md`.
+
+## `retro`
+
+The workflow's fifth step 收尾回顾 is documentation sync only. Session / agent retrospectives belong to `retro`, not here.
+
+Bundled lite version ships with the package; fallback doc `references/deps/boundaries.md`.
+
+## `doc-opt`
+
+Post-hoc prose polishing of named files. Ships with the package as a full bonus skill (`skills/doc-opt`), plus the fallback doc `references/deps/doc-opt.md`. Chain it after authoring if desired; explicit invocation only.
+
+## Older `.scratch`-style trackers
+
+Not used for issue tracking in these projects (DA_AGENT precedent: ADR-0012, refined by ADR-0026). This skill's `docs/issues` conventions supersede older `.scratch`-style tracking conventions.
+
+A generic scaffolder writing the same surfaces (`docs/agents/domain.md`, an `## Agent skills` block, `CLAUDE.md` preference) is not used for scaffolding in projects on this profile; if one ran before, review its leftovers against this profile's rules (init reports diffs; never overwrites).
+
+## Invocation
+
+This skill is manual-invocation only. Runtime compliance for agents comes from the project's materialized files (`AGENTS.md` + `docs/agents/*`), not from auto-loading this skill.

package/skills/project-docs-workflow/references/deps/boundaries.md

@@ -0,0 +1,29 @@
+# 回退：边界类 skill（deepwork / retro / improve-codebase-architecture）
+
+> 当某个边界类 skill 被引用但环境未安装时，按对应小节执行。
+
+## deepwork
+
+用于成本高、风险大、需跨多个阶段推进的整块工作。与 `project-docs-workflow` 的五步流程（规划 / 骨架 / 细节 / 异常 / 回顾）**互斥**：同一个 effort 只能选一个，绝不叠加。
+
+**无完整 deepwork 时**：退回到一个最小的分阶段计划，每个阶段设评审闸门——**计划 → 实现 → 评审**，逐阶段推进。把每个阶段当作一次可评审的推送，评审通过才进入下一阶段。
+
+## retro
+
+会话/agent 回顾的所有权。第五步「回顾」只是文档同步，不在此列。
+
+**最小三问回顾**：
+
+1. **发生了什么**：读指定会话的原始记录（未指定则默认当前会话）。
+2. **保留什么**：哪些做法或环境配置有效。
+3. **改变什么**：给出针对 agent 环境的改进候选，按严重程度排序。
+
+## improve-codebase-architecture
+
+代码库架构改进的路线（找出「深化模块」的机会，把浅模块变深，提升可测试性与 AI 可导航性），建立在领域模型与架构词汇之上。
+
+**无完整流程时**：本技能包不提供扫描与 HTML 报告流程；需要术语或 ADR 支持时，**转 `domain-modeling`**（未安装则见同目录 `domain-modeling.md`）。
+
+## doc-opt
+
+`doc-opt` 随包附带于 `skills/doc-opt`（完整版）；环境未安装时可参考同目录 `doc-opt.md` 的最小回退。

package/skills/project-docs-workflow/references/deps/doc-opt.md

@@ -0,0 +1,17 @@
+# 回退：doc-opt
+
+> 当需要调用 `doc-opt` 但环境未安装该 skill 时，按本文执行。
+
+> doc-opt 随包附带于 `skills/doc-opt`（完整版）。
+
+对**指定的** markdown 文档做后置润色：读整篇文档，在不改变原意的前提下提升清晰度与结构；只改被点名的文件，绝不扫全仓。
+
+## 步骤
+
+1. **读整篇**：标出 frontmatter 与代码块——它们必须逐字节不变。
+2. **计划结构改动**（删小节、重排、合并图）：先出计划，等确认再动手。
+3. **改写**：按「风格 → 图 → 引用」的顺序。删无信息的冗词（其实、值得注意的是、说白了、basically、actually 等）；短句、主动语态、动词优于名词化；枚举内容用列表/表格；术语保持精确。
+4. **自检**：确认无冗词残留、无裸数字引用（`[1]`）、无遗留 ASCII 图；每个 mermaid 块有声明行与闭合围栏。
+5. **报告**：文件、改动类别、`待补充来源`、自检证据。
+
+引用必须可跳转（同文档 `#anchor`、仓库内相对路径、或完整 URL），否则把来源写进句内。

package/skills/project-docs-workflow/references/deps/domain-modeling.md

@@ -0,0 +1,51 @@
+# 回退：domain-modeling
+
+> 当需要调用 `domain-modeling` 但环境未安装该 skill 时，按本文执行。
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 domain-modeling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+主动构建并打磨项目的领域模型：挑战术语、构造边界场景、在术语与决策成型时立刻写下。**修改**模型才算本流程；只是为查词而读 `CONTEXT.md` 不算。
+
+## 步骤
+
+1. **定位文件**：根目录有 `CONTEXT-MAP.md` → 多上下文，按它找到相关 `CONTEXT.md`；只有根 `CONTEXT.md` → 单上下文；都没有 → 在第一个术语确定时惰性创建。
+2. **质疑与锐化**：
+   - 用词与 `CONTEXT.md` 冲突 → 立刻指出，问「到底是哪个」。
+   - 用词含糊或一词多义 → 提出精确的规范术语。
+   - 讨论领域关系 → 用具体场景压力测试，逼清概念边界。
+   - 用户描述行为 → 与代码交叉核对，矛盾当面提出。
+3. **当场更新 `CONTEXT.md`**（不要攒批），沿用下方格式。
+4. **按需记录 ADR**，沿用下方规则与格式。
+
+## CONTEXT.md 格式
+
+```md
+# {上下文名称}
+
+{一两句话说明这是什么上下文、为什么存在。}
+
+## Language
+
+**Order**：
+{一或两句话的术语描述}
+_Avoid_: Purchase, transaction
+```
+
+- 有主见：多词指同一概念时选最好的一个，其余列入 `_Avoid_`。
+- 定义紧致：最多一两句，说它**是什么**，不是**做什么**。
+- 只收本项目特有概念；通用编程概念不进。
+- 完全不含实现细节：它是词汇表，不是 spec。
+
+## ADR 格式
+
+位置 `docs/adr/`，顺序编号 `0001-slug.md`，取现有最大号加一。
+
+```md
+# {决策的简短标题}
+
+{1-3 句：背景是什么、决定了什么、为什么。}
+```
+
+可选小节仅在确有价值时加：`Status`（`proposed | accepted | deprecated | superseded by ADR-NNNN`）、Considered Options、Consequences。
+
+**仅当三条同时成立才写 ADR**：难以逆转；无背景会令人意外；是真实取舍的结果。缺一即跳过。

package/skills/project-docs-workflow/references/deps/grilling.md

@@ -0,0 +1,31 @@
+# 回退：grilling
+
+> 当需要调用 `grilling` 但环境未安装该 skill 时，按本文执行。
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 grilling（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+持续追问用户，直到对方案达成共同理解。把它建模成一棵**设计树**：每个决策分叉出依赖它的子决策。用**轮次**遍历这棵树。
+
+## 步骤
+
+1. **算 frontier**：frontier = 前置条件已确定、现在就能问的问题（不必臆测尚未听到的答案）。答案依赖本轮其他未决问题者，属于后续轮次。
+2. **整轮提问**：把当前 frontier 一次性全部提出；每个问题编号，并给出**你推荐的答案**。
+   ```
+   ❓ **Q1** - **<问题标题>**：<正文，可多段、可含多选项>
+
+   ➡️ <推荐答案>
+
+   ---
+
+   ❓ **Q2** - **<问题标题>**：<正文>
+
+   ➡️ <推荐答案>
+   ```
+3. **等用户回答**，然后回到第 1 步重算 frontier：已确定的决策把 frontier 向外推，解锁下游问题。
+4. **拆事实与决策**：环境中的事实（文件系统、工具、文档）由**你**派子 agent 去查，绝不问用户；只有依赖该探查的下游问题需要等回报，frontier 其余问题现在就问。决策一律摆到用户面前并等待，不替用户拍板。
+5. **收尾**：frontier 为空（每条分支都走过、无默认假设）即结束。
+
+## 硬规则
+
+- 在用户确认已达成共同理解之前，**不要动手实施**。
+- 绝不问用户你本可以自己查的事实。