document-release

name	document-release
description	Post-ship documentation sync — updates README, CHANGELOG, AGENTS.md, ARCHITECTURE, and TODOS after a release. Ensures docs never drift from code. Run after /commit or /ship before closing a PR.

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Plugin skills are namespaced. Invoke this workflow explicitly as $clade:document-release; a bare $name does not select the installed Clade plugin.
• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $clade:skill-name plugin skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

You are the Document Release skill. You sync project documentation after a code release.

Run this after /commit or merging a PR — before closing the sprint.

---

Step 0: Pre-flight

git branch --show-current
git log --oneline -5
git diff --stat origin/main..HEAD 2>/dev/null || git diff --stat HEAD~3..HEAD

If on the base branch (main/master) with no recent changes: ask the user which release to document.

---

Step 1: Diff analysis

Classify changes into categories:

• New features — new functionality users can use
• Changed behavior — existing features that work differently
• Removed — deleted functionality or deprecated APIs
• Infrastructure — internal changes, no user-visible effect

This classification determines which docs need updating.

---

Step 2: README audit

Read README.md (and variants like README.zh-CN.md if they exist).

Check each section:

Section	What to verify
Feature list	Does it reflect new/removed features?
Numeric counts	"N skills", "M hooks" — do the numbers match reality?
Architecture diagram	Still accurate after structural changes?
Install instructions	Still work? Any new steps needed?
Quick start / examples	Still valid? New examples needed?
Configuration	New env vars or config options documented?

For each stale section:

• Fix factual errors and outdated counts immediately (no permission needed)
• For significant rewrites, show the proposed change and ask first

Numeric count rule: If README mentions counts (e.g., "28 skills"), re-count the actual files:

ls configs/skills/ | wc -l       # skill count
ls configs/hooks/*.sh | wc -l    # hook count
ls configs/scripts/*.sh | wc -l  # script count

Update every README variant to match.

---

Step 3: CHANGELOG update

If the project has a CHANGELOG.md or CHANGES.md:

Voice rules:

• User-facing language: "You can now..." not "We implemented..."
• Past tense for fixes: "Fixed a bug where..." not "Fix bug in..."
• Omit internal refactors unless they affect public API

CHANGELOG polish (not rewrite):

• Add an entry for this release if one doesn't exist
• Format: ## [version] — YYYY-MM-DD followed by ### Added / Fixed / Changed / Removed
• Group related changes into one line (don't list every commit)
• NEVER delete or rewrite existing entries
• Use file-editing tools, never Write — preserve what's already there

## [1.4.0] — 2026-03-30

### Added
- `/investigate` skill — root cause analysis with Iron Law and structured debug reports
- `/cso` skill — OWASP + STRIDE security audit
- `/retro` skill — data-driven engineering retrospective from git history
- `/document-release` skill — post-ship documentation sync

### Fixed
- Guardian hook no longer false-positives on variable assignment strings containing migration patterns

---

Step 4: AGENTS.md sync

Read the project AGENTS.md. Check if any of these need updating:

• Architecture section — new modules, changed import DAG, new files
• Key commands — new scripts or changed verify commands
• File map table — new files not yet listed
• Code rules — new patterns established in this release

Update only what changed — don't add commentary or restructure.

---

Step 5: TODOS.md cleanup

cat TODO.md 2>/dev/null || echo "No TODO.md"

For each - [ ] item: check if it was completed in this release (Glob/Grep for the implementation).

• Mark completed items as - [x] with the completion date in a comment if helpful
• Flag stale items (referenced code no longer exists)

Also scan changed files for inline TODO/FIXME/HACK comments added in this release:

git diff HEAD~5..HEAD | grep "^+" | grep -E "TODO|FIXME|HACK|XXX"

Add them to TODOS.md under the appropriate section.

---

Step 6: Cross-doc consistency check

Quick scan to verify docs agree with each other:

• README feature list vs AGENTS.md architecture — same modules?
• Version in README vs package.json/VERSION file — same?
• Every doc reachable from README or AGENTS.md? (orphan docs are invisible)

---

Step 7: Commit doc changes

If any docs were updated:

committer "docs: sync documentation after [release description]" \
  README.md CHANGELOG.md AGENTS.md TODO.md
# (only include files that actually changed)

Report what was updated:

Documentation sync complete:
  ✓ README.md — updated skill count (24 → 28), added new skills to feature list
  ✓ CHANGELOG.md — added v1.4.0 entry
  ✓ AGENTS.md — updated Key File Map with 4 new skill dirs
  ✓ TODO.md — marked 6 items complete, added 2 new FIXMEs from code scan
  ✓ Committed: docs: sync documentation after skills v1.4.0 release

---

Completion Status

• ✅ DONE — all docs updated and committed
• ⚠ DONE_WITH_CONCERNS — docs updated but some sections couldn't be auto-verified (e.g., diagram accuracy)
• ❌ BLOCKED — key docs are missing (no README, no AGENTS.md) — ask user to create them first
• ❓ NEEDS_CONTEXT — which release is this for? (asked if context is unclear)

---

What NOT to do

• Rewrite or reorganize docs beyond what the release requires
• Delete existing CHANGELOG entries
• Update docs that weren't affected by this release
• Commit doc changes in a separate "cleanup" PR — include them with the release

Delivery completion

If this workflow changes files or external state:

• Inspect the real final state before responding, including git status for a repository task.
• Never report DONE while task-owned changes are uncommitted. Use or continue $clade:delivery and create a repository-compliant checkpoint or preserve the work when committing is unavailable.
• When the user request or trusted repository policy makes publication, deployment, or live verification part of the task, do not silently downgrade the result to local-only work.
• If a required delivery transition lacks authority, credentials, a destination, or reachable external state, report BLOCKED or NEEDS_CONTEXT rather than appending a "not committed/pushed/deployed" caveat after DONE.