opi-document

name

opi-document

description

Update opi documentation so it stays truthful to the shipped code and the English/Chinese mirrors stay in sync. Use this skill whenever the user mentions "update the docs/README", "refresh the README", "sync EN/ZH", "translate the README", "fix doc drift", "文档更新", "文档同步", "更新 README", "翻译 README", or asks to bring docs in line after a change. Also use at Phase 6 of the opi workflow (after implementation/remediation, before release), and whenever a version bump needs the doc version-strings resynced.

Opi Document

Keep opi documentation truthful — every claim matches the shipped source — and keep the English and Simplified-Chinese mirrors in lockstep, with the doc-guard tests green. This is Phase 6 of the opi workflow.

opi docs are not free prose. Eight guard-test suites read them from disk and assert specific tokens (provider lists, the opi-agent API-surface table, phase non-goal lists, exact tool-policy strings). Editing a doc without preserving those tokens breaks cargo test. This skill edits inside the guards, never around them.

Inputs

scope=<full | targeted | version-bump>   # default: targeted to changed surfaces
files=<path,...>                          # optional; explicit doc files
version=<X.Y.Z>                          # required for version-bump scope

If the user says "update the docs after the Phase 13 work" or "refresh the README", infer scope from what changed. A version bump requires version=.

Workflow

Phase A — Discover the doc delta

Identify what shipped since the docs were last touched: read CHANGELOG.md ([Unreleased] + recent releases), git log since the last doc-touching commit, and the current Cargo.toml workspace version.

Done when: you hold a list of (doc file → facts that may have drifted) and, if a version bump is in scope, the set of version-bearing lines (root README + AGENTS.md + CLAUDE.md + the four crate READMEs, EN + ZH).

Phase B — Audit current docs against source

For each affected doc, verify every checkable claim against authoritative source (Cargo.toml, crate src/, docs/opi-spec.md, CLAUDE.md). Dispatch parallel subagents for wide reads. Flag three classes:

• drift — wrong / outdated / unverifiable / missing-shipped claims (versions, provider ids, CLI flags, schema constants, limits, module lists).
• noise — internal milestone jargon a reader cannot act on ("Phase 11/12/13", "Workstream 10.x", spec-hash ledger references, "checkout may contain unreleased Phase N").
• gaps — what an adopter needs but is missing (one-line value prop, install line, runnable example).

Done when: every drift item cites the authoritative source that disproves it, and every noise/gap item is listed with file:line.

Phase C — Load the guard constraints

Read references/doc-guards.md. For each file you will touch, record the pinned tokens that must survive verbatim and the forbidden overclaim phrases that may appear only negated.

Done when: for every target file, the pinned-token set and the forbidden-phrase set that bound the edit are written down.

Phase D — Decide guard-safe scope

Produce a per-file change plan: fix every drift, remove noise only where it is unpinned, fill gaps. Never drop a pinned token; never introduce a forbidden positive claim. If a requested style (e.g. a pi-style rewrite) collides with guard-locked content, surface the conflict and pick the guard-safe option before editing.

Done when: the plan preserves every pinned token (named per file) and adds no forbidden phrase — stated explicitly, not assumed.

Phase E — Edit English docs

Apply the plan. Preserve section headings and tables that guards parse — notably the opi-agent ## API Surface Classification … ## Non-Goals block, which runtime_contract_docs.rs parses against the pub uses in crates/opi-agent/src/lib.rs (every crate-root re-export must stay a classified table row; only the Notes cell is free text).

Done when: every drift item is resolved; no pinned token removed; no forbidden phrase introduced outside a negation; version-bearing lines updated in lockstep when a version bump is in scope.

Phase F — Mirror to Chinese

Apply the same surgical edits to each *.zh.md, preserving every pinned ZH token verbatim (敏感, 脱敏, 任意流式 chunk, 会话费用汇总会被省略, OpenAI Chat 会从任何携带 \id` 的 chunk, 捕获 response ID, … — full list in [references/doc-guards.md](references/doc-guards.md)). For **net-new** English prose only, compose the baoyu-translateskill, which honors.baoyu-skills/baoyu-translate/EXTEND.md` (zh-CN, technical, glossary keeping Provider / Agent / crate / harness / 会话). Do not free-regenerate a ZH file — that desyncs the pinned tokens.

Done when: each ZH file mirrors its EN structurally and every pinned ZH token is still present.

Phase G — Verify

Run the guard suites (command in references/doc-guards.md), then grep -nE "Phase [0-9]|第 ?[0-9]+ ?阶段" across the edited docs to catch phase-jargon the guards do not enforce — they check token presence, not phase-label absence. If any edited doc is include_str!'d into rustdoc, also run cargo doc --workspace --no-deps and cargo test -p <crate> --doc.

Done when: every guard suite reports 0 failed, the grep is clean (or every remaining phase ref is intentional and noted), and — if docs/opi-spec.md was touched — the phase4 specification-hash ledger is re-synced.

What it does NOT do

• No code, Cargo.toml, or version changes — opi-release owns the version bump.
• No commits, pushes, PRs, or releases.
• No authoring of docs/opi-spec.md normative content (Phase 1, or an opi-implement doc task, owns that). It may edit opi-spec.md only as a doc-sync, and then it must re-sync the phase4 ledger (crates/opi-coding-agent/tests/phase4_ledger.rs) — any byte change there breaks that SHA256 guard.
• No weakening, disabling, or rewriting of guard-test files to "make docs cleaner". If a guard blocks a desired change, the guard wins; escalate.
• No free-regeneration of Chinese docs.

Artifacts

• Reads: the affected README*.md / docs/*.md, CHANGELOG.md, CLAUDE.md / AGENTS.md, crate src/, the guard-test files under crates/*/tests/, and .baoyu-skills/baoyu-translate/EXTEND.md.
• Writes: the affected docs (EN + ZH). On an opi-spec.md edit, also docs/snapshots/phase4/opi-impl-state.json and the repo-root .opi-impl-state.json spec-hash.

In the workflow

Phase 6 — after Phases 3–5 (implement / audit / remediate) pass and before opi-release (Phase 7). opi-implement Phase D does only per-task inline doc verification; opi-document owns the dedicated, guard-verified doc refresh and the EN/ZH sync. opi-release Phase 5 stages version files but defines no doc-sync step of its own — run opi-document first.