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

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@tanlinfeng/project-docs-workflow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "项目文档工作流 skill 包：提供 issue tracker / ADR / PDR / 术语表与工作流约定，自带轻量依赖 skill 与 ref 兜底，可独立分发。",
+  "license": "MIT",
+  "bin": {
+    "project-docs-workflow": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/deepwork/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: deepwork
+description: 高成本、多阶段、高风险深度工作会议的边界占位；与五步流程互斥，需要完整工作流时请另行安装。
+disable-model-invocation: true
+---
+
+# Deepwork（边界占位）
+
+本 skill 只界定边界，不含完整流程；需要完整的 deepwork 工作流时请单独安装。
+
+- **适用**：成本高、风险大、需跨多个阶段推进的整块工作。
+- **互斥**：与 `project-docs-workflow` 的五步流程（规划 / 骨架 / 细节 / 异常 / 回顾）互斥——同一个 effort 只能选一个，绝不叠加。
+- **无完整 deepwork 时**：退回一个最小的分阶段计划，每个阶段设评审闸门：计划 → 实现 → 评审，逐阶段推进。
+
+术语或 ADR 需求交给 `domain-modeling`。

package/skills/doc-opt/EXAMPLES.md

@@ -0,0 +1,77 @@
+# Doc Opt — Examples
+
+Behavioral anchors for the rules in `SKILL.md`. Each pair shows one rule applied.
+
+## Style — 中文
+
+**Before**
+
+> 其实呢，这个模块的性能问题，说白了主要就是每次请求都重新创建连接。值得注意的是，换成连接池之后，其实功能不会有太大影响，但是速度会快很多。
+
+**After**
+
+> 性能瓶颈来自每次请求重建连接。改用连接池，功能不变，延迟显著下降。
+
+Removed: 其实呢 / 说白了 / 主要就是 / 值得注意的是 / 其实 / "不会有太大影响"（模糊）→ 功能不变 / "会快很多"（模糊）→ 延迟显著下降。
+
+## Style — English
+
+**Before**
+
+> Basically, it's worth noting that the retry logic just retries forever, which is, of course, a problem. Simply add a cap and you're good to go.
+
+**After**
+
+> The retry logic loops forever. Cap the retry count.
+
+Removed: Basically / it's worth noting / just / of course / Simply / you're good to go.
+
+## Diagram — ASCII to mermaid
+
+**Before**
+
+```text
++--------+     +---------+     +---------+
+| Client | --> | Gateway | --> | Service |
++--------+     +---------+     +---------+
+```
+
+**After**
+
+```mermaid
+flowchart LR
+    client[Client] --> gateway[Gateway] --> service[Service]
+```
+
+The mapping is lossless: same nodes, same order, same direction. When an annotation has no mermaid equivalent, ask before converting.
+
+## Citations — rejected and accepted forms
+
+**Rejected (bare numbers)**
+
+> Batched requests cut per-call overhead in half [2]. The gateway supports HTTP/2 [1].
+
+**Accepted (jumpable)**
+
+> Batched requests cut per-call overhead in half ([MCP spec — Batching](https://modelcontextprotocol.io/specification/2025-06-18#batching)). The gateway supports HTTP/2 ([RFC 9113](https://www.rfc-editor.org/rfc/rfc9113)).
+
+**Accepted (self-contained, no stable target)**
+
+> Per the MCP specification, batching cuts per-call overhead.
+
+**Unknown source — move to the end**
+
+```markdown
+## 待补充来源
+
+- 吞吐提升数据（原文 [3]）：来源不明，待补。
+```
+
+## mermaid vs SVG
+
+| Situation | Use |
+| --- | --- |
+| Flow, sequence, state, class, ER, gantt, pie | mermaid |
+| Annotated architecture, custom positioning, layout mermaid misrepresents | svg |
+| Diagram too large or reused across documents | sibling `.svg` file, linked |
+| ASCII art or image explicitly requested by the user | keep as asked |

package/skills/doc-opt/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: doc-opt
+description: "Tersely professionalize documents: strip filler, use mermaid/SVG diagrams, make citations jumpable."
+disable-model-invocation: true
+argument-hint: "Files or paths to optimize"
+---
+
+# Doc Opt
+
+Optimize named markdown documents in place. Default targets: `.md` / `.mdx`. Other formats only when named.
+
+## Contract
+
+- Touch the named files; never sweep the repo.
+- Compression removes redundancy, never facts.
+- Code fences, frontmatter, commands, and quoted output stay byte-identical.
+- Structural moves (delete a section, reorder, merge diagrams) get a plan first, edits second.
+- End with a change report: files, change categories, `待补充来源`, self-check evidence.
+
+## Style (L2 by default)
+
+L1 strips filler only; L3 goes telegraphic. Move up or down only when the user names the level.
+
+- Delete words that carry no information: filler, hedging, throat-clearing.
+- Short declarative sentences. Active voice. Verbs over nominalizations.
+- Lists and tables when the content enumerates.
+- Keep technical terms exact; keep headings unless the heading is the problem.
+
+Filler to cut on sight:
+
+| ZH | EN |
+| --- | --- |
+| 其实、值得注意的是、让我们来看看、不得不说、说白了、众所周知 | basically, actually, of course, it's worth noting, let's dive in |
+
+`just` and `其实` get judged per sentence: they stay only when literal ("only") or when they mark a real contrast.
+
+## Diagrams
+
+Default: mermaid. Match the type to the relation: flowchart, sequence, state, class, ER, gantt, pie.
+
+SVG covers what mermaid cannot express or where layout needs control — annotated architecture, custom positioning. Inline SVG for small diagrams; a sibling `.svg` file plus a link for large or reused ones.
+
+ASCII art and image diagrams appear only when the user explicitly asks. Existing ASCII diagrams convert to mermaid/SVG when the mapping is lossless; ambiguous semantics get a question first. Screenshots stay: add a caption and a jumpable citation.
+
+## Citations
+
+A bare number (`[1]`) is not a citation. Every reference is jumpable or self-contained:
+
+| Target | Form |
+| --- | --- |
+| Section of the same document | `[label](#anchor)` |
+| File elsewhere in the repo | `[label](relative/path.md#anchor)` |
+| External source | `[label](https://full-url)` |
+
+Without a stable target, carry the source inside the sentence ("per the MCP spec, ..."). A source that cannot be identified goes into a `待补充来源` list at the document end and into the change report.
+
+## Workflow
+
+1. Read the targets whole. Mark frontmatter and code that must not move.
+2. Plan structural changes; wait for confirmation.
+3. Rewrite: style, then diagrams, then citations.
+4. Run the self-check.
+5. Report files, change categories, `待补充来源`, self-check evidence.
+
+## Self-check
+
+Run before reporting; put evidence in the report. Substitute the target paths for `<files>`; ignore hits inside code fences.
+
+```bash
+# filler survivors — expect no hits
+rg -n "其实|值得注意的是|让我们来看看|说白了|basically|actually|of course|worth noting" <files>
+
+# bare numeric citations — expect no hits
+rg -n '\[\d+\]' <files>
+
+# ASCII diagrams — expect no hits unless the user asked for them
+rg -n '[┌┐└┘├┤│─]|\+--' <files>
+
+# mermaid fences — count them; each needs a declaration line and a closing fence
+rg -n '^```mermaid' <files>
+```
+
+`EXAMPLES.md` holds before/after pairs: style (ZH/EN), ASCII→mermaid, citation forms, mermaid vs SVG selection.

package/skills/doc-opt/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Doc Opt"
+  short_description: "Terse professional docs with real diagrams"
+policy:
+  allow_implicit_invocation: false

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. <另一接口面>
+
+<职责与边界。>
+
+| 方法 / 接口 | 用途 |
+| :--- | :--- |
+| … | … |
+
+<!-- 只写对外契约，不写内部实现；接口一旦落地，实现变更不得改变此处语义。 -->