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:

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

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

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:

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

Then spawn docs-roadmap-qa:

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.