docs: establish WaveBench documentation workflow

.agents/skills/wavebench-docs/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: wavebench-docs
+description: >-
+  Develop and maintain the WaveBench repository documentation system. Use only
+  for active documentation development: audits, information-architecture
+  migrations, writing or rewriting project docs, generated references, and
+  documentation-focused diff reviews. Documentation must be a primary requested
+  deliverable; do not use for incidental doc edits during ordinary code changes,
+  merely reading docs, instrument operation, or unrelated Chinese copyediting.
+license: MIT
+metadata:
+  author: "WaveBench maintainers"
+  version: "1.0.0"
+  project: "wavebench"
+---
+
+# WaveBench documentation development
+
+## Boundary
+
+Use this skill only while developing or reviewing documentation owned by the
+WaveBench repository. It governs information architecture, page responsibility,
+canonical sources, migrations, navigation, examples, and documentation CI.
+
+Do not use it for:
+
+- normal WaveBench operation, diagnosis, measurement, or hardware control;
+- answering a question by reading existing docs without changing or auditing them;
+- ordinary code changes with only an incidental one-line documentation update;
+- generic Markdown editing or Chinese copyediting outside WaveBench.
+
+Hardware access is never part of a documentation audit. Runtime commands used to
+verify help or schema must be offline. If a documentation example requires real
+hardware, validate it statically unless the user separately authorizes the live
+operation under the `wavebench` safety workflow.
+
+## Start from repository facts
+
+1. Work from the Git repository root and inspect `git status --short --branch`.
+2. Read `README.md`, `pyproject.toml`, `CHANGELOG.md`, the relevant documentation
+   indexes, and the pages directly in scope.
+3. Resolve changing claims from implementation, executable help/schema, tests,
+   descriptors, and release tags. Existing prose is evidence to audit, not proof
+   of current behavior.
+4. Classify each page by audience, reader goal, type, canonical facts, and related
+   pages before editing it.
+5. Preserve unrelated changes and do not move or rewrite broad document sets
+   without an accepted audit and migration slice.
+
+Read [文档宪法](references/information-architecture.md) when deciding taxonomy,
+page contracts, sources of truth, Core/plugin ownership, README scope, status,
+lifecycle, or user journeys. This is the single normative source for those rules.
+
+## Choose one mode
+
+| Mode | Use when | Load |
+| --- | --- | --- |
+| `audit` | Assess a documentation set without broad edits | [audit.md](references/audit.md) |
+| `migrate` | Apply an accepted audit in small, traceable slices | [migrate.md](references/migrate.md) |
+| `write` | Add or substantially rewrite a specific page | [write.md](references/write.md) |
+| `review` | Review a documentation PR or diff | [review.md](references/review.md) |
+
+Load only the selected mode plus `information-architecture.md` when that mode
+needs constitutional rules. Do not turn every review into a repository-wide audit.
+
+## Invariants
+
+- Follow the document constitution for one-fact/one-source, status labels,
+  Core/plugin ownership and lifecycle actions.
+- Structure and facts come before prose polish. For Chinese writing or review,
+  apply `tech-doc-style-chinese` only after page responsibility and sources are
+  settled. Do not assume that skill's unrelated `Project-Overrides.md` applies to
+  WaveBench.
+- Apply the [协作输出卫生](references/information-architecture.md#协作输出卫生)
+  rule to reader-facing content created or reviewed in this workflow. It is a
+  contextual write/review judgment, not a hook, text filter, or CI gate.
+- Prefer generated Reference when stable code or schema can produce it. Generated
+  output must name its source and have a drift check before it becomes canonical.
+
+## Mechanical audit
+
+In `audit` mode, run the dependency-free checker for the full requested scope:
+
+```bash
+python .agents/skills/wavebench-docs/scripts/audit_docs.py
+```
+
+For `write` or `review`, pass the changed page and its direct navigation entry as
+paths; use a full audit only for an approved migration or a demonstrated systemic
+problem.
+
+The script checks deterministic breakage and reports judgment-heavy concerns as
+warnings. It does not decide page type, migration action, user-journey quality, or
+whether content belongs in a Guide, Reference, or Concept.
+
+For trigger-boundary maintenance, read [eval-prompts.md](references/eval-prompts.md).
+
+## Handoff
+
+Treat the handoff as an execution and safety record under the
+[协作输出卫生](references/information-architecture.md#协作输出卫生) rule. Report the
+documentation scope, canonical sources checked, files changed, audit errors and
+warnings, commands or examples verified, content intentionally deferred, and whether
+any live hardware, local configuration, generated data, or virtual environment was
+touched. Omit feedback back-and-forth and discarded alternatives unless they affect
+a remaining decision or risk.

.agents/skills/wavebench-docs/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "WaveBench Docs"
+  short_description: "审计、迁移、编写与评审 WaveBench 仓库文档"
+  default_prompt: "使用 $wavebench-docs 审计本次 WaveBench 文档改动，并核对事实源、导航和验证结果。"
+policy:
+  allow_implicit_invocation: true

.agents/skills/wavebench-docs/references/audit.md

@@ -0,0 +1,48 @@
+# Audit 模式
+
+> 加载时机：评估整个文档系统、一个目录或一组相关页面，且当前阶段不进行广泛迁移时加载。
+
+## 范围
+
+全仓 audit 至少盘点 `README.md`、`docs/`、`plans/README.md`、`CHANGELOG.md`、相关 CLI/schema/config/artifact/capability/safety 源码入口，以及 `.agents/skills/`。局部 audit 只扩展到修改页的导航入口、直接相关页面和 canonical source。
+
+先运行：
+
+```bash
+python .agents/skills/wavebench-docs/scripts/audit_docs.py
+```
+
+机械结果只是审计输入。不要把「链接没坏」写成「文档结构合理」。
+
+## Inventory
+
+每篇页面先按[文档宪法](information-architecture.md)确定主类别、读者目标、canonical
+source 和一个主要动作：
+
+| File | Type | Audience | Reader Goal | Canonical? | Problems | Action |
+| --- | --- | --- | --- | --- | --- | --- |
+
+`Canonical?` 说明页面是否为该事实的权威来源；若不是，写出实际来源。`Problems`
+优先记录职责混合、重复事实、过时风险、旅程断点、Core/plugin 越界和
+Current/RFC 混杂，不以措辞偏好充数。生命周期动作的定义只以文档宪法为准。
+
+## 系统级输出
+
+除 inventory 外，列出并排序：
+
+- 最严重的 10 个系统问题；
+- 八条用户旅程的断点；
+- 重复维护的易变事实；
+- 孤儿页面和失效导航；
+- 超长 mixed-purpose 页面；
+- Core/plugin 边界违规；
+- Current、Experimental、RFC 和历史记录的混杂；
+- 目标信息架构、事实源表和小步迁移顺序。
+
+结论必须引用 `file:line`、符号名、命令输出或 tag。若只是推断，要明确标注，不把旧文档互相引用当作事实核验。
+
+审计报告属于需要追溯的内容。为 Action 保留必要证据、影响、目标页或替代入口和验证结果；不记录讨论时间线或与结论无关的备选方案。
+
+## 当前基线
+
+首轮仓库审计见 [WaveBench 文档系统审计与迁移提案](../../../../docs/project/design/WaveBench_文档系统审计与迁移提案.md)。后续 audit 应重新扫描当前树，不得把这份日期快照当永久事实源。

.agents/skills/wavebench-docs/references/eval-prompts.md

@@ -0,0 +1,35 @@
+# 触发与模式回归用例
+
+> 加载时机：维护 `wavebench-docs` 的 description、隐式触发边界或 reference 路由时加载。
+
+## 应触发
+
+| 请求 | Mode | 预期加载 |
+| --- | --- | --- |
+| 「审计 WaveBench 的 README、docs 与事实源，给迁移表」 | `audit` | 入口、`audit.md`、`information-architecture.md` |
+| 「按已批准的文档审计拆分 run plan 指南」 | `migrate` | 入口、`migrate.md`、`information-architecture.md` |
+| 「为新的 run step 编写 WaveBench Reference」 | `write` | 入口、`write.md`、`information-architecture.md` |
+| 「评审这个只改文档的 PR」 | `review` | 入口、`review.md`，按需加载信息架构 |
+
+## 不应触发
+
+| 请求 | 正确处理 |
+| --- | --- |
+| 「执行这个 WaveBench run plan」 | 使用 `wavebench` 的 run/safety 工作流 |
+| 「采集示波器 CH1 并生成报告」 | 使用 `wavebench`，先过硬件写入门禁 |
+| 「README 里怎么安装？」 | 直接读取并回答，不进入文档开发 workflow |
+| 「修复 config parser 的 bug，顺手更新一句报错说明」 | 普通 WaveBench 代码开发；附带的一行说明不触发完整文档工作流 |
+| 「把这段中文写自然一点」 | 使用 `tech-doc-style-chinese`，除非明确是 WaveBench 文档开发 |
+| 「解释 Diátaxis」 | 直接解释方法，不审计 WaveBench 仓库 |
+| 「解释傅里叶变换」 | 普通知识任务 |
+
+## 行为检查
+
+用全新上下文逐条测试，确认：
+
+1. 普通使用和只读问答不会加载本 Skill；
+2. 文档开发能自动选择正确 mode；
+3. `review` 不默认扩大为全仓 audit；
+4. `write` 在结构和事实确定前不会先做措辞润色；
+5. 文档任务不会自行连接仪器或执行实时 plan；
+6. 中文写作层按需交给 `tech-doc-style-chinese`，且不套用无关项目覆盖规则。