Verify release readiness and guide the release process. Part of the Plot workflow. Use on /plot-release.
Create a versioned release from delivered plans. This workflow can be run manually (using git and forge CLI), by an AI agent interpreting this skill, or via a workflow script (once available).
Input: $ARGUMENTS is optional. Can be:
rc — cut a release candidate tag and generate a verification checklist1.2.0) or bump type (major, minor, patch) — cut the final releaseExamples: /plot-release rc, /plot-release minor, /plot-release 1.2.0
Add a ## Plot Config section to the adopting project's CLAUDE.md:
## Plot Config
<!-- Optional: uncomment if using a GitHub Projects board -->
<!-- - **Project board:** owner/number (e.g. eins78/5) -->
- **Branch prefixes:** idea/, feature/, bug/, docs/, infra/
- **Plan directory:** docs/plans/
- **Active index:** docs/plans/active/
- **Delivered index:** docs/plans/delivered/
| Steps | Min. Tier | Notes |
|---|---|---|
| 1. Determine Version | Mid | Heuristic: plan types → bump suggestion |
| 2A. RC Path | Small | Git tag, template generation |
| 2B. Release Notes | Mid | Discovery logic, changelog collection |
| 3. Cross-check Notes | Frontier (orchestrator) + Small (subagents) | Orchestrator compares; small subagents can gather commit messages and plan changelogs in parallel |
| 4-6. Next Steps through Summary | Small | Template list, no-ops, formatting |
User interaction: Use
AskUserQuestion(Claude Code) /ask_question(Cursor) for all questions, proposals, and confirmations.
Check for the latest git tag:
git tag --sort=-v:refname | head -1
If $ARGUMENTS is rc:
git tag --list "v<version>-rc.*"rc.1; otherwise incrementIf $ARGUMENTS specifies a version (e.g., 1.2.0):
If $ARGUMENTS specifies a bump type (major, minor, patch):
If $ARGUMENTS is empty:
docs/releases/v*-checklist.md) with all items checkedminorpatchmajorSmaller models: Skip the automatic bump type suggestion. Instead, list the delivered plans with their types and ask the user: "What version should this release be? (major/minor/patch or exact version)" Let the human decide.
Tag the RC:
git tag -a v<version>-rc.<n> -m "Release candidate v<version>-rc.<n>"
git push origin v<version>-rc.<n>
Generate verification checklist:
Collect all delivered plans since the last release (via docs/plans/delivered/ — check the Delivered date in each plan's Status section against the last release tag date). For each delivered feature or bug plan, extract the ## Changelog section and create a checklist item. If a plan has a Sprint: <name> field, include the sprint name alongside the checklist item for context. Sprint completion is informational — it does not block the release.
mkdir -p docs/releases
Write docs/releases/v<version>-checklist.md:
# Release Checklist — v<version>
RC: v<version>-rc.<n> (YYYY-MM-DD)
## Verification
- [ ] <feature/bug slug> — <changelog summary>
- [ ] <feature/bug slug> — <changelog summary>
## Automated Tests
- [ ] CI passes on RC tag
## Sign-off
- [ ] All items verified by: ___
- [ ] Final release approved by: ___
git add docs/releases/v<version>-checklist.md
git commit -m "release: v<version>-rc.<n> checklist"
git push
Summary (RC):
v<version>-rc.<n>docs/releases/v<version>-checklist.md[ ] Draft > [ ] Approved > [x] Delivered > [*] Released (RC)bug/ branches, merge, then /plot-release rc for next RC/plot-release to cut the final releaseCheck for project-specific release note tooling, then either run it or fall back to manual collection.
Discover tooling — check in this order:
.changeset/config.json exist? If so, the project uses @changesets/cli.CLAUDE.md and AGENTS.md for release note instructions (e.g., custom scripts, specific commands).package.json for release-related scripts (e.g., release, version, changelog).If tooling is found: remind the user to run it (e.g., pnpm exec changeset version for changesets). Do not run release tooling automatically — the user controls when and how versions are bumped. Then proceed to step 3 (cross-check).
If no tooling is found: collect changelog entries from delivered plans and present them to the user:
# Get the date of the last release tag (exclude RC tags)
LAST_TAG=$(git tag --sort=-v:refname | grep -v '\-rc\.' | head -1)
if [ -n "$LAST_TAG" ]; then
LAST_RELEASE_DATE=$(git log -1 --format=%ai "$LAST_TAG" | cut -d' ' -f1)
else
LAST_RELEASE_DATE="1970-01-01"
fi
# Find delivered plans newer than the last release
ls docs/plans/delivered/ 2>/dev/null
For each delivered plan since the last release:
## Changelog section## Status section for the Type (feature/bug/docs/infra)Only include feature and bug plans in the release notes (docs/infra are live when merged — they don't need release).
Present the collected entries to the user and suggest they add them to CHANGELOG.md. Do not write to CHANGELOG.md directly.
Model tiers for this step:
- Frontier (e.g., Opus): Full cross-check — compare changelog entries against delivered plans and commit messages. Can delegate data gathering (reading plans, collecting commit messages) to small subagents. Flag significant gaps (missing features, phantom entries). Don't nitpick wording.
- Mid (e.g., Sonnet): Compare changelog entry count against delivered plan count. Can delegate plan reading to small subagents. Flag obvious mismatches (plan with no corresponding entry, entry with no corresponding plan). Skip semantic content comparison.
- Small (e.g., Haiku): Skip gap detection. Present the generated release notes and ask: "Do these release notes look complete?" Human review is the final gate.
Whether generated by tooling or manually constructed, compare the changelog against the actual work:
This cross-check is the primary value of /plot-release — verifying that release notes accurately reflect delivered work.
Present a numbered list of actions for the user to confirm:
CHANGELOG.md with the collected entries (if not already done by tooling)package.json (if applicable): pnpm version <version> --no-git-tag-versiongit commit -am "release: v<version>"git tag -a v<version> -m "Release v<version>"git push origin main && git push origin v<version>Offer to execute these steps only if the user confirms. Do not run them automatically.
If RC tags exist for this version, they remain in git history (don't delete them — they're part of the release record). The checklist file at docs/releases/v<version>-checklist.md stays committed as documentation of what was verified.
Print:
v<version><slug> — <type><slug> — <type>[ ] Draft > [ ] Approved > [ ] Delivered > [x] Released/plot to verify clean state/plot-idea or /plot-sprint