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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 project-docs-workflow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,52 @@
+NOTICE
+======
+
+project-docs-workflow
+Copyright (c) 2026 project-docs-workflow contributors
+Licensed under the MIT License (see LICENSE).
+
+Third-party attribution
+-----------------------
+
+Portions of the bundled skills in this package are trimmed / adapted from:
+
+  https://github.com/mattpocock/skills
+  MIT License
+  Copyright (c) 2026 Matt Pocock
+
+The following bundled skills contain material derived from the project above:
+
+  - skills/grilling
+  - skills/grill-me
+  - skills/grill-with-docs
+  - skills/domain-modeling
+  - skills/tdd
+  - skills/deepwork
+  - skills/retro
+  - skills/improve-codebase-architecture
+
+The MIT permission notice for the upstream material is reproduced below.
+
+------------------------------------------------------------------------
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @tanlinfeng/project-docs-workflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 项目文档工作流 skill 包：提供 issue tracker、ADR、PDR、术语表与协作工作流约定，自带轻量依赖 skill 与 ref 兜底，可独立分发。
+
+## 这是什么
+
+`project-docs-workflow` 是一套面向 AI agent 的「项目文档工作流」skill。它把项目中的几类关键文档沉淀为可复用的模板与约定：
+
+- **issue tracker**：任务 / 缺陷的登记与追踪约定
+- **ADR**（Architecture Decision Record）：架构决策记录
+- **PDR**（Product/Project Design Record）：设计与需求记录
+- **terminology**：领域术语表，统一团队与 agent 的词汇
+- **workflow**：上述文档之间的协作与更新流程
+
+skill 本身是自包含的：主 skill 内部带 `references/deps/*.md` 兜底材料，因此即使没有安装任何依赖 skill，也能独立工作。包内同时附带了若干**轻量依赖 skill**（来自 `mattpocock/skills` 的精简版本）以及一个**附赠的 `doc-opt` skill**。
+
+## 安装
+
+通过 npx 直接安装到默认的 skills 根目录（`~/.agents/skills`）：
+
+```bash
+npx @tanlinfeng/project-docs-workflow
+```
+
+常用选项：
+
+| 命令 | 说明 |
+| --- | --- |
+| `npx @tanlinfeng/project-docs-workflow` | 默认动作 `install`：安装主 skill 及所有依赖 skill |
+| `npx @tanlinfeng/project-docs-workflow --dir <path>` | 指定 skills 根目录（默认 `~/.agents/skills`） |
+| `npx @tanlinfeng/project-docs-workflow --force` | 覆盖已存在的 `project-docs-workflow`（**仅主 skill**；依赖 skill 仍不覆盖） |
+| `npx @tanlinfeng/project-docs-workflow --dry-run` | 只打印将执行的操作，不写入任何文件 |
+| `npx @tanlinfeng/project-docs-workflow check` | 检查依赖 skill 的解析状态，全部可解析时退出码为 0，否则为 1 |
+
+### 覆盖策略（安全优先）
+
+安装器**永不覆盖用户已存在的同名 skill**。若目标目录中已存在同名目录，会打印 `同名 skill 已存在，保留用户版本：<name>` 并跳过。只有对主 skill `project-docs-workflow` 使用 `--force` 时才会覆盖它；依赖 skill 即使加了 `--force` 也仍会跳过。
+
+## 直接复制（不使用 npm 安装器）
+
+也可以完全跳过安装器，手动把 `skills/` 下需要的内容复制进你的 skills 根目录：
+
+- 逐个复制 `skills/*` 中的目录；**遇到同名目录就跳过，绝不覆盖用户版本**。
+- 也可以**只复制 `skills/project-docs-workflow` 这一个目录**：它会通过内部的 ref 兜底（`references/deps/*.md`）独立工作，无需其他依赖 skill。
+
+## 两级解析协议
+
+skill 在引用依赖能力时，遵循两级解析：
+
+1. **按名解析**：如果 skills 根目录下存在同名 skill（`<target>/<name>/SKILL.md`），直接使用该已安装的 skill。
+2. **ref 兜底**：否则，回退到主 skill 内部自带的 `references/deps/<fallback>.md`。
+
+| 引用名 | 兜底文件 |
+| --- | --- |
+| `grilling` | `grilling.md` |
+| `grill-me` | `grilling.md` |
+| `grill-with-docs` | `grilling.md`、`domain-modeling.md` |
+| `domain-modeling` | `domain-modeling.md` |
+| `tdd` | `tdd.md` |
+| `deepwork` | `boundaries.md` |
+| `retro` | `boundaries.md` |
+| `doc-opt` | `doc-opt.md` |
+| `improve-codebase-architecture` | `boundaries.md` |
+
+`check` 子命令会对照上表逐个报告「按名可解析（skill 已安装）」或「ref 兜底可用」，只要每个名字能通过任一级解析即视为通过。
+
+## 内置 skill 与来源
+
+| skill | 说明 | 来源 |
+| --- | --- | --- |
+| `project-docs-workflow` | 主 skill：issue / ADR / PDR / 术语 / 工作流 | 本包 |
+| `grilling`、`grill-me`、`grill-with-docs` | 需求拷问相关 | `mattpocock/skills` 精简版（MIT，Matt Pocock） |
+| `domain-modeling` | 领域建模 | 同上 |
+| `tdd` | 测试驱动开发 | 同上 |
+| `deepwork`、`retro`、`improve-codebase-architecture` | 精简/占位版本 | 同上 |
+| `doc-opt` | 文档优化（附赠完整版） | 本包附赠 |
+
+部分内置 skill 内容摘自 <https://github.com/mattpocock/skills>（MIT License，Copyright (c) 2026 Matt Pocock），详见 [`NOTICE`](./NOTICE)。
+
+## 版本说明
+
+本包版本 `2.x` 与「模板生成 v2」对齐：模板结构与生成约定以 v2 为准。
+
+## License
+
+MIT，见 [`LICENSE`](./LICENSE)。
+
+---
+
+## English summary
+
+`project-docs-workflow` is an npm-packaged agent **skill bundle** for project documentation workflows: issue tracking, ADRs, PDRs, a terminology glossary, and the workflow that ties them together. The main skill is self-contained via internal `references/deps/*.md` fallbacks, and ships with lightweight dependency skills (trimmed from [mattpocock/skills](https://github.com/mattpocock/skills), MIT, Matt Pocock) plus a bundled `doc-opt` bonus skill.
+
+Install with `npx @tanlinfeng/project-docs-workflow` (defaults to `~/.agents/skills`; options: `--dir <path>`, `--force`, `--dry-run`, and the `check` subcommand). The installer **never overwrites** an existing skill of the same name — it skips it, preserving your version. `--force` overwrites only the main `project-docs-workflow` skill.
+
+You can also copy `skills/*` directly into your skills root (skip any existing directory name, never overwrite); copying just `skills/project-docs-workflow` works standalone thanks to the internal ref fallbacks.
+
+Resolution is two-level: use an installed skill by name if present, otherwise follow `references/deps/*.md` inside the skill. Version `2.x` aligns with template generation v2. Licensed MIT (see `LICENSE` and `NOTICE`).

package/bin/install.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const PKG_ROOT = path.join(__dirname, "..");
+const SKILLS_DIR = path.join(PKG_ROOT, "skills");
+const MAIN_SKILL = "project-docs-workflow";
+const DEFAULT_TARGET = path.join(os.homedir(), ".agents", "skills");
+
+// 依赖 skill 的按名解析与 ref 兜底映射。
+// 顺序：先按名解析 <target>/<name>/SKILL.md，其次尝试 ref 兜底文件。
+// grill-with-docs 的兜底包含 grilling.md 与 domain-modeling.md 两个文件。
+const REF_FALLBACKS = {
+  grilling: ["grilling.md"],
+  "grill-me": ["grilling.md"],
+  "grill-with-docs": ["grilling.md", "domain-modeling.md"],
+  "domain-modeling": ["domain-modeling.md"],
+  tdd: ["tdd.md"],
+  deepwork: ["boundaries.md"],
+  retro: ["boundaries.md"],
+  "doc-opt": ["doc-opt.md"],
+  "improve-codebase-architecture": ["boundaries.md"],
+};
+
+const REF_NAMES = Object.keys(REF_FALLBACKS);
+const DEPS_DIR = path.join(SKILLS_DIR, MAIN_SKILL, "references", "deps");
+
+function usage() {
+  console.log(
+    [
+      "project-docs-workflow 安装器",
+      "",
+      "用法：",
+      "  project-docs-workflow [install] [选项]   安装 skill 到目标目录（默认动作）",
+      "  project-docs-workflow check   [选项]     检查依赖 skill 的解析状态",
+      "",
+      "选项：",
+      "  --dir <path>   指定目标 skills 根目录（默认 ~/.agents/skills）",
+      "  --force        覆盖已存在的 project-docs-workflow（仅主 skill；依赖仍不覆盖）",
+      "  --dry-run      仅打印将执行的操作，不实际写入",
+      "  -h, --help     显示本帮助",
+    ].join("\n")
+  );
+}
+
+function parseArgs(argv) {
+  const opts = { command: "install", target: DEFAULT_TARGET, force: false, dryRun: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "install" || arg === "check") {
+      opts.command = arg;
+    } else if (arg === "--force") {
+      opts.force = true;
+    } else if (arg === "--dry-run") {
+      opts.dryRun = true;
+    } else if (arg === "--dir") {
+      const value = argv[++i];
+      if (!value) {
+        fail("--dir 需要一个路径参数");
+      }
+      opts.target = path.resolve(value);
+    } else if (arg.startsWith("--dir=")) {
+      opts.target = path.resolve(arg.slice("--dir=".length));
+    } else if (arg === "-h" || arg === "--help") {
+      usage();
+      process.exit(0);
+    } else if (arg.startsWith("-")) {
+      fail("未知选项：" + arg);
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length > 0) {
+    fail("未知参数：" + positional.join(" "));
+  }
+  return opts;
+}
+
+function fail(message) {
+  console.error("错误：" + message);
+  process.exit(1);
+}
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch (e) {
+    return false;
+  }
+}
+
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+// 列出 skills/ 下的所有子目录名；缺失时返回空数组（由调用方给出提示）。
+function listSkillDirs() {
+  if (!isDir(SKILLS_DIR)) {
+    return null;
+  }
+  return fs
+    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function copySkill(name, dest, dryRun) {
+  const src = path.join(SKILLS_DIR, name);
+  if (dryRun) {
+    console.log("  [dry-run] 将复制 " + name + " → " + dest);
+    return;
+  }
+  fs.cpSync(src, dest, { recursive: true });
+  console.log("  ✓ 已安装 " + name + " → " + dest);
+}
+
+function runInstall(opts) {
+  const dirs = listSkillDirs();
+  if (dirs === null || dirs.length === 0) {
+    fail(
+      "找不到 skills 目录（" +
+        SKILLS_DIR +
+        "）。请确认已在完整的 npm 包内运行（不要单独复制 bin/）。"
+    );
+  }
+  if (dirs.indexOf(MAIN_SKILL) === -1) {
+    fail("缺少主 skill 目录：skills/" + MAIN_SKILL);
+  }
+
+  const target = opts.target;
+  console.log("目标目录：" + target + (opts.dryRun ? "（dry-run，不会写入）" : ""));
+  if (!opts.dryRun) {
+    fs.mkdirSync(target, { recursive: true });
+  }
+
+  // 主 skill：仅在 --force 时覆盖已存在的版本，否则同样保护用户版本。
+  const mainDest = path.join(target, MAIN_SKILL);
+  const mainExists = isDir(mainDest) || isFile(mainDest);
+  console.log("主 skill：" + MAIN_SKILL);
+  if (mainExists && !opts.force) {
+    console.log("  同名 skill 已存在，保留用户版本：" + MAIN_SKILL + "（如需覆盖请加 --force）");
+  } else if (mainExists && opts.force) {
+    if (opts.dryRun) {
+      console.log("  [dry-run] 将覆盖 " + MAIN_SKILL + " → " + mainDest);
+    } else {
+      fs.rmSync(mainDest, { recursive: true, force: true });
+      copySkill(MAIN_SKILL, mainDest, false);
+    }
+  } else {
+    copySkill(MAIN_SKILL, mainDest, opts.dryRun);
+  }
+
+  // 其他依赖 skill：永不覆盖。
+  console.log("依赖 skill：");
+  const others = dirs.filter((name) => name !== MAIN_SKILL);
+  if (others.length === 0) {
+    console.log("  （未发现其他目录）");
+  }
+  for (const name of others) {
+    const dest = path.join(target, name);
+    if (isDir(dest) || isFile(dest)) {
+      console.log("  同名 skill 已存在，保留用户版本：" + name);
+      continue;
+    }
+    copySkill(name, dest, opts.dryRun);
+  }
+
+  if (opts.dryRun) {
+    console.log("dry-run 完成，未写入任何文件。");
+  } else {
+    console.log("安装完成。");
+  }
+}
+
+function runCheck(opts) {
+  const target = opts.target;
+  console.log("检查依赖 skill 解析状态（目标目录：" + target + "）：");
+
+  let ok = true;
+  for (const name of REF_NAMES) {
+    const installed = isFile(path.join(target, name, "SKILL.md"));
+    if (installed) {
+      console.log("  " + name + "：按名可解析（skill 已安装）");
+      continue;
+    }
+    const fallbacks = REF_FALLBACKS[name] || [];
+    const hit = fallbacks.find((file) => isFile(path.join(DEPS_DIR, file)));
+    if (hit) {
+      console.log("  " + name + "：ref 兜底可用（references/deps/" + hit + "）");
+      continue;
+    }
+    ok = false;
+    console.log(
+      "  " + name + "：无法解析（未安装，且缺少 ref 兜底：" +
+        fallbacks.map((f) => "references/deps/" + f).join("、") +
+        "）"
+    );
+  }
+
+  if (ok) {
+    console.log("全部依赖 skill 均已解析。");
+    process.exit(0);
+  } else {
+    console.log("存在无法解析的依赖 skill。");
+    process.exit(1);
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.command === "check") {
+    runCheck(opts);
+  } else {
+    runInstall(opts);
+  }
+}
+
+main();

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.0.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