document-release

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. Improve repository onboarding and keep documentation aligned with what users can obtain.

For a repository creation, substantial README/setup or open-source onboarding request, use Step 2 and its reference as the acceptance standard before drafting. For a release, analyze its changes and sync the affected documentation. A README task does not require a release or authorize one.

---

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

For release synchronization, resolve the release from the request and history; ask only if it remains ambiguous. An onboarding request already supplies scope.

---

Step 0b: --dry-run

When invoked with --dry-run, run Steps 1-6 as ANALYSIS ONLY: make no Edit call and never reach the committer in Step 7. Emit the Step 7 report block with every line prefixed would update:. The flag was advertised in the argument-hint and read by nothing, so a run asking to preview rewrote and committed the docs.

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 references/repository-entrypoints.md before auditing. Inventory root, localized and independently distributed package READMEs, with their setup and support destinations. A README is the first product visit: discovery → understanding → credible proof → first successful use. Text edits alone do not establish a usable entry point.

Check each section:

Section	What to verify
First screen	Can a new reader identify the audience, outcome, maturity and next action?
Product evidence	Does a real screenshot, terminal/demo, input/output comparison or diagram explain the product? Logos/badges alone do not count. Are fixtures and illustrations labeled?
Presentation	Do images load and remain legible on phone/desktop and light/dark? Is there useful hierarchy rather than a wall of text?
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?
Repository and help map	Are real responsibilities, architecture/docs, support and contribution paths easy to find and reachable?
Distribution	Do commands, claims and images match the source preview, package or release readers are directed to?
Participation	Can the intended audience use the help/report/contribution routes? Are advertised starter tasks concrete and available?

For each stale section:

• Fix factual errors and outdated counts immediately (no permission needed)
• Implement reversible documentation and presentation fixes within the user's authorized scope. Ask only for missing material facts, genuine conflicting directions or an action that needs separate authority.

For a new or substantially revised entry point, inspect relevant projects in the same category, including their actual rendered media and navigation. Do not copy one layout across unrelated products or treat stars as usability evidence. Run the first-use path in an isolated context, inspect the rendered README, and repair findings. Record source, rendered and runtime evidence separately; unavailable checks stay unverified. Use frontend-design for visual changes.

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, follow its existing convention. For onboarding work, describe user-visible changes under Unreleased where that section is used; do not invent a release version or date.

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: Task-list 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"

Update the project's existing task-list file under the appropriate section; do not create a second TODO/TODOS spelling.

---

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 — required facts, access, or authority are unavailable. Create missing documentation within the authorized scope; do not ask the user to write it merely because it does not exist.
• ❓ NEEDS_CONTEXT — the requested scope or release remains ambiguous after inspection.

---

What NOT to do

• Rewrite or reorganize docs beyond the requested onboarding or release scope
• Delete existing CHANGELOG entries
• Update unrelated docs
• Split release-related docs into a separate "cleanup" PR; keep them with that release. Standalone onboarding work is its own reviewable change.

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.