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

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 为空（每条分支都走过、无默认假设）即结束。
+
+## 硬规则
+
+- 在用户确认已达成共同理解之前，**不要动手实施**。
+- 绝不问用户你本可以自己查的事实。

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

@@ -0,0 +1,35 @@
+# 回退：tdd
+
+> 当需要调用 `tdd` 但环境未安装该 skill 时，按本文执行。
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 tdd（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+以测试先行的方式构建功能或修 bug：red → green 循环。
+
+## 步骤
+
+1. **先定 seam**：seam 是你据以测试的公共边界（无需伸手进内部即可观察行为）。写测试前先写下待测 seam 并与用户确认；**未确认的 seam 上不写测试**。
+2. **红**：写一个失败的测试。测试通过公共接口验证行为，读起来像规格（描述 WHAT 而非 HOW），每个测试一个逻辑断言。不要 mock 内部协作者，不要走旁路（绕过接口查数据库）。
+3. **绿**：只写刚好让这个测试通过的实现。不加预判未来测试的投机功能。
+4. **重复**：以**纵向切片**推进——一个测试 → 一个实现 → 重复，每个测试是回应上一轮所学的一发**曳光弹**。不要「先写完所有测试再写所有实现」。
+5. **重构**不属于 red → green 循环；它属于评审阶段。
+
+探索代码库时读 `CONTEXT.md`（若存在），让测试名匹配领域语言，并遵守相关 ADR。
+
+## 期望值
+
+期望值必须来自**独立真相源**：已知良好的字面量、算好的例子、规格。不要以代码的算法重算期望值（`expect(add(a, b)).toBe(a + b)`、手工按同样方式推出的快照）——那是同义反复，只会通过，永远无法与代码唱反调。
+
+## mock
+
+**只在系统边界 mock**：外部 API、数据库（有时——优先测试库）、时间/随机性、文件系统（有时）。**不要 mock** 你自己的类/模块、内部协作者、任何你控制得了的东西。
+
+便于 mock 的边界设计：用依赖注入把外部依赖传进来；优先 SDK 式接口（每个操作一个具体函数）而非带条件的通用 fetcher。
+
+## 反模式速查
+
+- 耦合实现：重构后行为未变测试却坏。
+- 同义反复：断言由构造保证为真。
+- 横切切片：批量测试验证想象的行为，测的是形状而非用户行为。
+
+当 seam 形状本身存疑（模块多深、seam 在哪、接口暴露什么）时，参考 `codebase-design` 的 module / interface / depth / seam / adapter / leverage / locality 词汇。

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

@@ -0,0 +1,51 @@
+# Issue tracker
+
+Default profile. Projects may override in their materialized `docs/agents/issues.md`; that copy governs runtime behavior.
+
+## Directory contract
+
+```
+docs/issues/
+├── bug/{human,agent}/        # defect fixes
+├── feature/{human,agent}/    # new features
+├── chore/{human,agent}/      # maintenance / refactor / misc
+├── suggestion/{human,agent}/ # improvement ideas (no history, no status; terminus ADR / PDR)
+└── <bug|feature|chore>/history/   # archived: filename suffixed -done / -drop
+```
+
+- `human/` and `agent/` = current responsible party. Transfer responsibility with `git mv` to the other directory.
+- Keep near-term work only (~1-week window). Whoever finishes or abandons an entry archives it; humans sweep periodically.
+- `history/` holds archived entries: suffix the filename `-done.md` (completed) or `-drop.md` (abandoned).
+- `suggestion` is special: no `history/`, no status.
+
+## Entry format
+
+- An issue is the workflow's work unit: one feature-level deliverable (bug / chore share the shape, simplified). See `workflow.md`.
+- Filename: short title in the project language, no number (e.g. `修复-波形首屏卡顿.md`). Archive by adding the status suffix.
+- Metadata line: `> Status: open|doing|blocked | 责任: human|agent | 创建: YYYY-MM-DD | 关联: ...` (关联 holds links such as `ADR-XXXX` or other entries).
+- Body: background and goal, as prose.
+- `## 完成判据` — completion criteria.
+- `## 结果（完成后填写，可选）` — outcome, filled in on completion (optional).
+- `## 步骤` — the five-step checklist from `workflow.md`; update it in place, and append a Log line on every step change. Materialized (Chinese) copies show:
+
+  ```
+  ## 步骤
+  - [ ] 规划（完成判据与方案已对齐）
+  - [ ] 骨架（最小可运行切片 + 证据；纯修复可跳过并注明理由）
+  - [ ] 细节（主路径实现与质量）
+  - [ ] 异常（失败路径、边界与稳定性）
+  - [ ] 回顾（收尾回顾：文档同步）
+  ```
+
+- `## Log` — dated lines appended in place; never rewrite history lines.
+- `Status` is updated in place.
+- Work that changes an ADR or PDR must sync those documents.
+- If the skill is installed, the skeleton lives at `~/.agents/skills/project-docs-workflow/assets/templates/entries/issue-entry.md`; otherwise create from the format above.
+
+## `suggestion` routing
+
+When a suggestion is resolved:
+
+- Accepted → land the conclusion in an ADR (or update the PDR), then remove the entry (`采纳 → 结论落 adr（或更新 pdr），随后删除本条目；`).
+- Rejected → delete it. Record a rejection ADR only if a human explicitly asks.
+- Actually a bug / feature / chore → move it to that directory.

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

@@ -0,0 +1,33 @@
+# PDR product specs
+
+PDR = target-state product spec ("产品规格书"): what the product should become, its modules, outward contracts, and mechanism design. Default profile; overridable in project copies.
+
+## Structure
+
+- Module directories numbered by reading order (e.g. `01-architecture/`, `02-ui/`). Root `00-README.md` = module index + reading order.
+- Each module:
+  - `00-README.md` — role / scope-boundary / dependencies / doc map.
+  - `01-spec.md` — functional requirements, each with an `FR-<MODULE>-NN` ID and 验收判据 (acceptance criteria). FR IDs are stable and never reused; numbering is continuous per module.
+  - `02-interfaces.md` — interface contracts. The providing module owns its outward interfaces; consumers reference them.
+  - `03-nfr.md` — non-functional requirements.
+  - `04-current.md` — current-state snapshot vs the spec; dated, ≤1 page, conclusions and gaps only. See "Goal / current & gap→issues".
+  - `design/` — optional mechanism-level design, **not numbered**.
+- Cross-module architecture and research material may live in module-external directories.
+
+## Goal / current & gap→issues
+
+- **The spec is the goal.** `NN/01-spec.md` is the target state; there are no separate goal files — the details of the end state live in the module specs, not in root docs.
+- **Root README carries two sections.** `docs/pdr/00-README.md` gains 「最终目标」(one-paragraph end state; details live in the module specs) and 「当前进展」(one line of status per module, each pointing to that module's `04-current.md`).
+- **Per-module `04-current.md`** is a current-state snapshot measured against the spec: dated, ≤1 page, conclusions and gaps only (never a log). Updated by the agent at issue completion, as part of the wrap-up review (see `workflow.md`).
+- **Scope & adoption.** Applies to numbered modules. Existing projects adopt it lazily — per module, when that module is next touched; init reports the diff and never overwrites.
+- **Gap → issue.** At the Plan step the agent reads goal (spec) plus current, derives gap candidates (module / FR, suggested type, slice, acceptance criteria), and the user picks. Accepted candidates land as entries in `docs/issues/` whose 关联 records the module / FR. No idle auto-creation of issues.
+
+## PDR ↔ ADR boundary
+
+- PDR = what the product should be (target state).
+- ADR = decisions with rationale and trade-offs.
+- A suggestion's acceptance routes into an ADR or the PDR (see `issues.md`).
+
+## Example (DA_AGENT) — not part of the general rules
+
+DA_AGENT is a concrete instance of this pattern: modules ui / agent / cpp-core / FPGA, plus architect and research as module-external areas; each module uses the spec layer `00-README / 01-spec / 02-interfaces / 03-nfr` with an unnumbered `design/` sub-area; FR prefixes read `FR-AGENT-NN`, `FR-UI-NN`, …; product scenarios sit in a separate `07-scenarios.md`. Source: DA_AGENT ADR-0026.

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

@@ -0,0 +1,21 @@
+# Domain terminology
+
+Two layers. Default profile; overridable in project copies.
+
+## 1. Primary glossary — `CONTEXT.md`
+
+- Per term: `**Term**：definition` followed by `_Avoid_: synonyms`.
+- Group terms under sections when clusters emerge; a flat list is fine for a single cohesive area.
+- Project-specific concepts only — zero implementation detail.
+
+## 2. Domain glossary — e.g. `docs/common/glossary.md`
+
+- Numbered index table (one line per term) + per-term sections + cross-links.
+
+## Usage rules
+
+- Read `CONTEXT.md` plus the relevant ADRs before exploring.
+- Use glossary vocabulary in every artifact (issue titles, refactor proposals, hypotheses, test names). Never drift to `_Avoid_` synonyms.
+- A novel concept is a signal: rethink whether you are inventing language the project does not use, or record the gap (hand it to `domain-modeling`, 未安装则按 `references/deps/domain-modeling.md` 执行).
+- If these files are missing, continue silently; creation happens when terms or decisions finalize, typically via `domain-modeling`（兜底 `references/deps/domain-modeling.md`）.
+- Flag ADR conflicts explicitly (`> _与 ADR-XXXX … 冲突，但…_`); never silently override.

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

@@ -0,0 +1,45 @@
+# Development workflow
+
+Default profile. Projects may override in their materialized `docs/agents/workflow.md`; that copy governs runtime behavior.
+
+The default shape for developing a single issue: align, build a thin slice, fill it in, harden it, then sync docs. The flow is a recommendation — projects may override any step — but while it is in use, its one hard rule is that alignment and planning come before implementation.
+
+## Work unit & granularity
+
+- The work unit is the **issue** (see `issues.md`): one feature-level deliverable. Bug / chore use the same shape, simplified.
+- **Granularity is a suggestion**, never forced: size a slice for a single reviewable push (heuristic ≈ 0.5 person-day), elastic per task.
+- **Stage slicing is agent-perceived** — which slice of the feature to take next never becomes directories or files; the only materialized tracking is the issue's own `## 步骤` checklist. An optional one-line note inside the issue can make the current stage explicit.
+
+## Alignment
+
+- **Align before building**: implementation starts only after the alignment is done and the plan / steps are written (align → plan & steps → build).
+- Alignment is **conversational and soft**: no freeze, no ceremonial "aligned" record. Re-align proactively when needs change (feature-requirement drift).
+- On an ambiguous direction, invoke `grilling`（未安装则按 `references/deps/grilling.md` 执行）; `grill-me` is only an entry alias; `grill-with-docs` = `grilling` + `domain-modeling`（兜底 `references/deps/grilling.md` + `references/deps/domain-modeling.md`）.
+- **Gap analysis** happens here, at Plan: read the goal (spec) plus current state, derive gap candidates (module / FR, suggested type, slice, acceptance criteria), and let the user pick. No idle auto-creation of issues.
+
+## The five steps
+
+1. **规划 / Plan** — refine acceptance criteria, set the step checklist status, and write a 1–2 sentence approach. Minimal output; no new sections. Gap analysis happens here.
+2. **骨架 / Skeleton** — a minimal runnable vertical slice (ignore output / formatting polish); leave one piece of run evidence and show it to the user — the first review point. Skippable for pure fixes (Log the reason); mandatory for features and structural work.
+3. **细节 / Details** — main-path implementation, detail completion, code quality. `tdd`（未安装则按 `references/deps/tdd.md` 执行）is an optional internal loop.
+4. **异常 / Exceptions** — failure paths, boundaries, and stability after the main path. Real development blockers are handled immediately and Logged, never queued for this step.
+5. **回顾 / Wrap-up review** (收尾回顾) — a lightweight docs-sync checklist at issue completion (pdr/current, adr, context, issues, agents); if nothing needs updating, one Log line. Doc sync only; session / agent retrospectives belong to `retro`（未安装则按 `references/deps/boundaries.md` 执行）.
+
+## Progress & resume
+
+- The issue entry carries a `## 步骤` checklist (the five steps); update it **in place**. Every step change appends a Log line.
+- **Sessions are soft.** A session is the user's attention window; the user controls pace (they may new / compact between issues). The agent must not absorb work beyond the aligned scope.
+- **On resume**, read the issue's 步骤 plus Log first, then confirm the continuation point with the user.
+
+## Docs sync hooks
+
+- **Plan**: gap → issue candidates land in `docs/issues`; the entry's 关联 records the module / FR.
+- **Wrap-up review**: update the module's `04-current.md` as part of completing the issue (see `pdr.md`); touch `adr` / `context` / `issues` / `agents` when the change warrants it.
+- **Archival**: archive the issue per `issues.md` when done / dropped.
+
+## Boundaries
+
+- Large or high-risk multi-phase work → `deepwork`（未安装则按 `references/deps/boundaries.md` 执行）; never stack it with this flow.
+- `tdd`（未安装则按 `references/deps/tdd.md` 执行）nests inside Details; seam confirmation folds into the Plan alignment (no second gate).
+- `retro`（未安装则按 `references/deps/boundaries.md` 执行）owns session / agent retrospectives; the fifth step is docs sync only.
+- See `coexistence.md` for how this profile sits beside these skills.

package/skills/retro/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: retro
+description: 对编码会话或 agent 表现做回顾，输出针对 agent 环境的改进建议。
+disable-model-invocation: true
+---
+
+# Retro（会话回顾）
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 retro（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+会话/agent 回顾的所有权属于本 skill；`project-docs-workflow` 第五步「回顾」只是文档同步，不做会话回顾。
+
+最小回顾至少覆盖三问：
+
+1. **发生了什么**：读指定会话的原始记录（未指定则默认当前会话），尽量取原始来源。
+2. **保留什么**：哪些做法或环境配置有效，值得延续。
+3. **改变什么**：给出针对 agent **环境**的改进候选（导航指针、自动化检查、编码规范、全局指令瘦身、工具经济性、多余指令、信息可达性），按严重程度排序呈现给用户。
+
+若环境未安装完整 skill，按 `project-docs-workflow/references/deps/boundaries.md` 的最小三问回顾执行。