agentic-kit: Skill for Claude Code

Release a version

A tag push publishes to npm and cannot be undone, so each outward step below needs its own yes.

When to use

The maintainer wants a new @pacphi/agentic-kit version published. The contents must already be merged to main. This skill does not merge feature PRs (use ak-ship).

Preflight

1. Work in a checkout you own with git branch --show-current, git status --porcelain and git worktree list. Never switch branches in a checkout another session uses; if main is held elsewhere, use a worktree you create. Stop and report if the tree is dirty.
2. git fetch origin and confirm the release base equals origin/main. Stop if it is behind, or if the contents the maintainer expects are not merged.
3. Read the current version: node -p "require('./package.json').version". Read docs/maintainer.md sections 6 and 7 again if unsure. Section 7's checklist pushes main directly; the pull request path in step 4 is current practice.
4. gh run list --workflow=release.yml --limit 3 and npm view @pacphi/agentic-kit dist-tags to see what shipped last.

Steps

1. Choose the version with the maintainer, by SemVer and the bump rules in docs/maintainer.md section 6. Ask whether the next step is an alpha, a beta or an rc (-alpha.N and -rc.N go to next, -beta.N to the project-scoped beta line, a stable version to latest); never infer it. Confirm with node scripts/release-dist-tag.mjs <version> and show the result.
2. Run the suite: node scripts/run-tests.mjs unit (the pnpm test script; never pnpm in a worktree). Stop if red.
3. Bump version in package.json, the only place it lives. Check node bin/agentic-kit.mjs --version prints it.
4. Release commit release: v<version>. Recent releases landed through a pull request because main requires one: push a release branch and open the PR only after a yes, then hand the merge to ak-ship (a release PR needs a fresh yes there). Pushing main directly needs its own yes that names this commit and this branch; a general "direct pushes are allowed" is not that yes. A rejected push is reported, never worked around. ak-ship's cleanup may remove the release branch's worktree: run step 5 onward from a checkout ak-ship is not removing.
5. Verify the commit before tagging, and again right before the tag-push approval: git fetch origin, then git rev-parse HEAD must equal git rev-parse origin/main (or tag origin/main explicitly, as on the pull request path, where HEAD is the release branch). Read the version from the commit being tagged, not the working tree: git show origin/main:package.json | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).version" must print <version>, and git log -1 --format=%s origin/main must be release: v<version> or release: v<version> (#<N>), where <N> is the release PR a squash merge appends. If any differs, stop and report. Never git checkout main in a worktree where it is held elsewhere.
6. Create the annotated tag on the verified commit, matching exactly: git tag -a v<version> -m "v<version>" origin/main. Show git show v<version> --stat and the dist-tag.
7. Tag push, separate approval: name the tag, the commit and the dist-tag, repeat the step 5 checks, then run git push origin v<version> only after that yes. This starts the publish (release.yml runs pnpm publish; you never publish).
8. Watch the publish, separate approval (cheap to give, it only reads): gh run list --workflow=release.yml --limit 5 --json databaseId,headBranch,event,status. Pick the run whose headBranch is v<version> and event is push, not an earlier run or a workflow_dispatch dry run; if none appears yet, wait and list again. Then gh run watch <run-id> --exit-status. A failure on the tag-version guard or tests published nothing; report it and the fix options in docs/maintainer.md section 7, and do not move or delete the tag without a yes for that exact action.
9. npm check, separate approval (also read-only and cheap): npm view @pacphi/agentic-kit dist-tags and npm view @pacphi/agentic-kit@<version> version dist.tarball. Allow about eight minutes after the workflow reports success; a 404 on the tarball inside that window is registry lag, not a failed publish, so wait and re-check.
10. gh release view v<version> --json tagName,isPrerelease (the workflow creates it; do not run gh release create). Prereleases must show isPrerelease true.
11. Close the release epic and its items in the GitHub Project after a yes per target, with gh issue close <N> --comment "Released in v<version>"; list the numbers first.
12. Remind the maintainer that the global ak is the published npm copy, not the repo: run npm i -g @pacphi/agentic-kit@<dist-tag>, then ak sync. Do not run it unasked.