القائمة
Worktrunk release workflow. Use when user asks to "do a release", "release a new version", "cut a release", or wants to publish a new version to crates.io and GitHub.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | release |
| description | Worktrunk release workflow. Use when user asks to "do a release", "release a new version", "cut a release", or wants to publish a new version to crates.io and GitHub. |
| metadata | {"internal":true} |
Run tests: cargo run -- hook pre-merge --yes
Check current version: Read version in Cargo.toml
Review commits: Check commits since last release to understand scope of changes
Check library API compatibility: Run cargo semver-checks check-release -p worktrunk (install with cargo install cargo-semver-checks --locked if missing). If it reports breaking changes, the bump must be minor (pre-1.0) or major (post-1.0). See "Library API Compatibility" below.
Credit contributors: Check for external PR authors and issue reporters (see "Credit External Contributors" and "Credit Issue Reporters" below)
Confirm release type with user: Present changes summary (including semver-checks result) and ask user to confirm patch/minor/major (see below)
Bump version (must run on a clean tree — before editing CHANGELOG):
cargo release X.Y.Z -p worktrunk -x --no-publish --no-push --no-tag --no-verify --no-confirm && cargo check
This bumps Cargo.toml, Cargo.lock, and applies pre-release-replacements (e.g., SKILL.md's version: line), then auto-commits. We'll reset this commit in step 9 to fold in the CHANGELOG.
Then sync the SHA-256 digest of SKILL.md in docs/static/.well-known/agent-skills/index.json — cargo-release doesn't know that file derives from SKILL.md, so it stays stale until the docs-sync test rewrites it:
cargo test --test integration test_docs_are_in_sync || cargo test --test integration test_docs_are_in_sync
The first run rewrites the digest and exits non-zero; the second confirms sync. The regenerated index.json is then picked up by git add -A in step 9.
Update CHANGELOG: Add ## X.Y.Z section at top with changes (see MANDATORY verification below)
Commit: Reset the auto-commit from step 7, stage everything, and create the final release commit:
git reset --soft HEAD~1 && git add -A && git commit -m "Release vX.Y.Z"
Merge to main: wt merge --no-remove (rebases onto main, pushes, keeps worktree)
Tag and push: git tag vX.Y.Z && git push origin vX.Y.Z
Wait for release workflow: Poll with gh pr checks --required or gh run view <run-id> every 60 seconds until complete (avoid gh run watch — it can hang). Non-required checks are ignored
The tag push triggers the release workflow which builds binaries and publishes to crates.io, Homebrew, and winget automatically.
Check commits since last release for missing entries:
git log v<last-version>..HEAD --oneline
IMPORTANT: Don't trust commit messages. Commit messages often undersell or misdescribe changes. For any commit that might be user-facing:
git show <commit> --stat to see what files changedCommon patterns where commit messages mislead:
Notable changes to document:
Section order: Improved, Fixed, Documentation, Internal. Documentation is for help text, web docs, and terminology improvements. Internal is for selected notable internal changes (not everything).
Within each section, order by impact:
Breaking changes: Note inline with the entry, not as a separate section:
- **Feature name**: Description. (Breaking: old behavior no longer supported)
Skip: internal refactors, test additions (unless user-facing like shell completion tests).
For any changelog entry where an external contributor (not the repo owner) authored the commit, add credit with their GitHub username:
- **Feature name**: Description. ([#123](https://github.com/user/repo/pull/123), thanks @contributor)
Find external contributors:
git log v<last-version>..HEAD --format="%an <%ae>" | sort -u
Then for each external contributor's commit, find their GitHub username from the commit (usually in the email or PR).
When a fix or feature addresses a user-reported issue in this repo, thank the reporter — not just the PR author. Users who take time to report bugs, request features, or provide reproduction steps deserve recognition. (Don't credit reporters from upstream/external repos — only issues filed here.)
- **Feature name**: Description. ([#456](https://github.com/user/repo/pull/456), thanks @reporter for reporting)
For fixes that reference issues:
- **Bug fix**: Description. Fixes [#123](https://github.com/user/repo/issues/123). (thanks @reporter)
Finding reporters — do ALL three steps:
Issues may have been filed months before the fix. Bug reports also appear as PR comments, not just issues. These steps are complementary; each catches things the others miss.
Extract every issue/PR reference from every commit (PRIMARY):
git log v<last-version>..HEAD --format="%B" | grep -oE '#[0-9]+' | sort -un
For each referenced number: run gh issue view N --json title,author,state. This catches issues filed months ago — the most commonly missed credits.
Check PR comments for bug reports (catches reports that never became issues): For feature PRs referenced in commits, check comment threads for users reporting problems:
gh pr view NNN --json comments --jq '.comments[] | "\(.author.login): \(.body[:150])"'
Survey every issue opened or closed since last release (catches unreferenced matches):
git log -1 --format=%cs v<last-version>
gh issue list --state all --search "created:>=<date>" --json number,title,author --limit 100
gh issue list --state closed --search "closed:>=<date>" --json number,title,author --limit 100
Cross-reference every title against changes in this release.
When to credit:
Skip credit for: issues opened by the repo owner, trivial reports, or issues that were substantially different from what was implemented.
For major features with dedicated documentation, include a docs link. Use full URLs so links work from GitHub releases:
- **Hook system**: Shell commands that run at key points in worktree lifecycle. [Docs](https://worktrunk.dev/hook/) ([#234](https://github.com/user/repo/pull/234), thanks @contributor for the suggestion)
Link when there's substantial documentation the user would benefit from reading — new commands, feature pages, or Tips & Patterns sections. Skip for minor improvements.
After drafting changelog entries, you MUST spawn a subagent to verify each bullet point is accurate. This is non-negotiable — changelog mistakes are a recurring problem.
The subagent should:
Subagent prompt template:
Verify these changelog entries for version X.Y.Z are accurate.
Previous version: [e.g., v0.1.9]
Commits to check: git log v<previous>..HEAD
Entries to verify:
[paste drafted entries]
For EACH entry:
1. Find the relevant commit(s) using git log and git show
2. Read the actual diff, not just the commit message
3. Confirm the entry accurately describes the user-facing change
4. Flag if the entry overstates, understates, or misdescribes the change
Also check:
- Are there user-facing changes NOT covered by these entries?
- Verify each "thanks @..." attribution (right person, right role — author vs reporter)
Report format:
- Entry: [entry text]
Status: ✅ Accurate / ⚠️ Needs revision / ❌ Incorrect
Evidence: [what you found in the diff]
Suggested fix: [if needed]
Do not finalize the changelog until the subagent confirms all entries are accurate.
If verification finds problems: Escalate to the user. Show them the subagent's findings and ask how to proceed. Don't attempt to resolve ambiguous changelog entries autonomously — the user knows the intent behind their changes better than you do.
Before proceeding with changelog and version bump, confirm the release type with the user.
After reviewing commits, present:
0.2.0)Use AskUserQuestion to get explicit confirmation. Example:
Current version: 0.2.0
Changes since v0.2.0:
- Added `state clear` command (new feature)
- Added `previous-branch` state key (new feature)
- No breaking changes
Recommendation: Minor release (0.3.0) — new features, no breaking changes
Do not proceed until user confirms the release type. The user may have context about upcoming changes or preferences that affect versioning.
Current project status: early release, breaking changes acceptable, optimize for best solution over compatibility.
Worktrunk is primarily a CLI, but it also publishes a library crate ([lib] in Cargo.toml) that downstream crates depend on. cargo-semver-checks compares the current public API against the last version published to crates.io and flags semver violations.
cargo semver-checks check-release -p worktrunk
Interpreting results:
cargo semver-checks check-release -p worktrunk --baseline-version <last-published>.This check validates the chosen bump — it doesn't distinguish patch vs. minor when no breakage exists. Continue using the commit review to decide between patch (fixes only) and minor (new features).
If the workflow fails (e.g., cargo publish error), fix the issue, then recreate the tag:
gh release delete vX.Y.Z --yes # Delete GitHub release
git push origin :refs/tags/vX.Y.Z # Delete remote tag
git tag -d vX.Y.Z # Delete local tag
git tag vX.Y.Z && git push origin vX.Y.Z # Recreate and push
The new tag will trigger a fresh workflow run with the fixed code.
Worktrunk-specific guidance for tend CI workflows. Adds codecov polling, Rust test commands, labels, and review criteria on top of the generic tend-* skills. Use when operating in CI.
Guidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.
CLI output formatting standards for worktrunk. Use when writing user-facing messages, error handling, progress output, hints, warnings, or working with the output system.