tdmcp-docs-roadmap-update

Files (1)

• SKILL.md

SKILL.md (first lines)

# tdmcp-docs-roadmap-update

Updates the repo's documentation surfaces after feature waves or releases:
`docs/ROADMAP.md`, high-level docs named by the audit, EN/PT prompt cookbooks,
and generated reference docs.

**Execution mode:** sub-agents. This environment does not use `TeamCreate`;
spawn the role agents defined in `.Codex/agents/` and coordinate them from the
main session.

## Phase 0: Context Check

Before spawning agents:

1. Inspect `git status --short`.
2. Check whether `_workspace/docs_release_audit.md`,
   `_workspace/roadmap_docs_update.md`, `_workspace/cookbook_sync_update.md`, or
   `_workspace/docs_roadmap_qa.md` already exist.
3. Decide execution mode:
   - no prior workspace files -> full run;
   - prior files + user says update/re-run/continue -> refresh only affected
     phases;
   - prior files + new release/tag/feature input -> refresh audit first, then
     re-run writers.

Preserve unrelated local changes. Do not reset or revert user edits.

## Phase 1: Release And Feature Audit

Spawn `docs-release-auditor`:

```text
Read .Codex/agents/docs-release-auditor.md and execute it.
Audit current local package, CHANGELOG, ROADMAP, README, cookbook docs,
CLI/resource surfaces, generated docs, npm package version, GitHub releases, and
tags. Write _workspace/docs_release_audit.md.
```

The audit is mandatory whenever release wording, tool counts, or "latest"
features are involved.

## Phase 2: Docs Writing

After `_workspace/docs_release_audit.md` exists, spawn these agents in parallel
when their write sets are both needed:

**Roadmap/docs editor**

```text
Read .Codex/agents/roadmap-docs-editor.md and execute it.
Use _workspace/docs_release_audit.md. Update docs/ROADMAP.md and any high-level
docs named by the audit. Do not edit generated docs or cookbook files. Write
_workspace/roadmap_docs_update.md.
```

**Cookbook sync**

```text
Read .Codex/agents/docs-cookbook-sync.md and execute it.
Use _workspace/docs_release_audit.md and _workspace/roadmap_docs_update.md if it
exists. Update docs/guide/prompt-cookbook.md and docs/pt/guide/prompt-cookbook.md
for docs-worthy new features, keeping locales in parity. Write
_workspace/cookbook_sync_update.md.
```

If only roadmap docs or only cookbook docs are affected, run only the relevant
writer.

## Phase 3: Generated Docs And QA

Run the docs generation/build gate from the main session:

```bash
npm run docs:build
npm run validate:recipes
git diff --check
```

Then spawn `docs-roadmap-qa`:

```text
Read .Codex/agents/docs-roadmap-qa.md and execute it.
Use the release audit and writer summaries. Verify release claims, EN/PT parity,
generated docs behavior, VitePress media embeds, and command outcomes. Write
_workspace/docs_roadmap_qa.md.
```

If QA finds narrow issues, fix them in the main session or re-run only the
responsible writer.

## Data Flow

- Auditor writes `_workspace/docs_release_audit.md`.
- Roadmap editor writes `_workspace/roadmap_docs_update.md`.
- Cookbook sync writes `_workspace/cookbook_sync_update.md`.
- QA writes `_workspace/docs_roadmap_qa.md`.
- Final docs edits remain in normal repo files.

## Quality Rules

- Verify live release state before claiming a public version is current.
- Keep public release, local `HEAD`, and planned backlog distinct.
- Never hand-edit generated `docs/reference/tools.md`.
- Keep EN/PT cookbook examples in parity.
- Use `withBase('/examples/...')` for VitePress video embeds.
- Treat missing media assets as description-only or explicit follow-up, not as
  silent broken links.

## Test Scenarios

**Normal flow:** a new release lands. Audit confirms package/npm/GitHub agree,
roadmap is updated with shipped and remaining work, cookbook gets matching EN/PT
entries, `npm run docs:build`, `npm run validate:recipes`, and
`git diff --check` pass.

**Error flow:** npm or GitHub release checks fail. Auditor marks release state
unverified; writers avoid definitive public-release claims; QA records residual
risk and asks for a retry or human release confirmation.

From hybridlabor-api/aos, Apache-2.0.

More from hybridlabor-api/aos