| name | update-docs |
| description | Keep repository documentation accurate by auditing docs against source code, configs, READMEs, and external references. Use when updating docs, checking architecture docs, reviewing README drift, or maintaining files under docs/. |
Update Docs
Use this workflow to keep docs grounded in the current codebase. Prefer source-of-truth files over memory, and update only claims that are stale, missing, or misleading.
Quick Start
- List docs under
docs/ and identify the requested target docs.
- Read the target doc before searching broadly.
- Build a source-of-truth map for each major claim: code, config, package metadata, README, tests, or external docs.
- Compare architecture diagrams, commands, examples, exported APIs, dependency descriptions, and invariants against those sources.
- Edit the doc in the existing voice and structure. Preserve accurate content; avoid unrelated rewrites.
- Validate links, paths, code snippets, diagrams, and commands that changed.
Generic Review Loop
For every doc update:
- Check repository topology first: root package/config files, workspace references, package manifests, and build/test scripts.
- Check nearby implementation files for behavioral claims. Do not treat README prose as stronger evidence than code.
- Check package READMEs for public-facing wording that should stay consistent with the doc.
- Check tests when the doc describes regression coverage, CLI behavior, or expected outputs.
- Check external citations when the doc describes provider APIs or dated vendor features.
- Note the files that mattered most, then fold those notes into this skill if they are reusable.
Editing Rules
- Keep docs concise and reader-oriented.
- Preserve intentional design goals and invariants even when implementation details move.
- Update diagrams when package ownership, dependencies, or runtime flow changes.
- Keep examples executable-looking: current commands, current package names, current model IDs.
- Do not add speculative roadmap content unless the doc already has an explicit out-of-scope or future-work section.
- Prefer local file paths over vague references like "the adapter" when naming a source of truth.
docs/architecture.md Workflow
Start with these source-of-truth checks:
- Package topology:
package.json, tsconfig.json, and packages/*/package.json.
- Design invariants:
@onkernel/cua-ai owns provider-specific policy (catalog, tool schemas, payload transforms); @onkernel/cua-agent is provider-neutral runtime glue around pi-agent-core (no provider names in packages/agent/src); provider differences reach the agent as compiled CuaToolCatalog data; @onkernel/cua-cli composes both for orchestration.
- Model layer:
packages/ai/src/index.ts, cua.ts, tool-catalog.ts, getCuaModel/listCuaModels/parseCuaModelRef, provider adapters, and api-keys.ts.
- Execution layer:
packages/agent/src/index.ts, CuaAgent and CuaAgentHarness wiring, and the canonical CUA tool executors against @onkernel/sdk.
- CLI runtime flow:
packages/cli/src/cli.ts, cli-harness.ts, harness.ts, harness-browser.ts, harness-models.ts, harness-sessions.ts, harness-named-sessions.ts, harness-skills.ts, print.ts, output/harness-jsonl.ts, action/, and tui/.
- TUI test infrastructure:
packages/ptywright/package.json, src/index.ts, src/session.ts, src/terminal.ts, and README.md.
- External drift: provider computer-use docs,
@earendil-works/pi-* versions, and @onkernel/sdk versions in package manifests.
Questions architecture.md should answer after each update:
- What owns the canonical action vocabulary and the model catalog?
- Where is the cua-ai vs cua-agent ownership boundary, and how do provider differences reach the agent without provider conditionals in
packages/agent/src?
- Where does Kernel SDK browser execution happen?
- What does the CLI compose at runtime via
buildCuaHarness?
- Which package is dev/test infrastructure only?
Validation
- Re-read the changed doc and verify every new claim has a source.
- Check Markdown links and relative paths touched by the edit.
- For Mermaid changes, ensure node IDs have no spaces, labels with punctuation are quoted, and no explicit styling is used.
- For command changes, prefer a lightweight dry-run or help command when available.
- For docs-only changes, do not run the full build unless the edited examples or generated docs depend on build output.
