hancrafted/markdown-harness / skills/release
release
UnverifiedCut and publish the next version of @hancrafted/markdown-harness. Releases are tag-driven — bump the version, push a vX.Y.Z tag, and GitHub Actions publishes to npm over trusted publishing (OIDC). This skill drafts release notes from the commit log and stops at a review gate for approval before anything publishes. Use when the user wants to release, publish a new version, ship, bump the version, or push a release tag.
A v* tag is the only thing that publishes. Merging to main publishes nothing.
The mechanics are a contract that must work with no skill installed:
docs/agents/release.md. This skill sits on top of that path — drafting notes,
judging the bump, holding a review gate — and never replaces it. When a step here disagrees with that page, that page
wins and this file is what needs fixing. Consult it whenever a step below surprises you.
Nothing publishes until the user approves a version and notes at the review gate (step 3). Work the steps in order; each ends on a criterion you check before moving on.
1. Pre-flight
Every gate below is a hard stop, not a warning:
- On an up-to-date trunk. Run
git worktree listfirst: this repo keeps several worktrees, and when one of them holdsmain,git checkout maindoes not switch — it fails with'main' is already used by worktree at .... Work from the checkout that holdsmainandgit pullthere, rather than switching to it. - Working tree clean:
git status --porcelainprints nothing. npm run verifyexits 0. Run the whole thing, in this order, not a subset —verifybuilds before it tests, andtsc --noEmitruns beforevitest, which never typechecks anything (docs/agents/verification.md, traps 8 and 9).- CI is green on
mainin the Actions tab. Publish re-runsverifyand the same Trivy gate, but catch it here.
Do not read a green archgate check inside step 3 as governance evidence. It is scoped to the files changed against
origin/main, so on an up-to-date trunk its scope is empty by construction and it passes over zero rules. It is in
verify because it belongs in verify; it tells you nothing at release time.
Done when: all four gates pass.
2. Draft the notes and propose a version
- Find the last release tag:
git describe --tags --abbrev=0. If the command fails there is no prior tag, and this is the first real release — that is aminor, because0.0.xmeans "not a release". - Gather every commit since it:
git log --no-merges <last-tag>..HEAD --pretty=format:'%h %s'. - Group them under the Keep a Changelog categories the commit bodies already use —
Added,Changed,Deprecated,Removed,Fixed,Security. - Propose
vX.Y.Z. The package stays in0.xuntil the command surface is deliberately declared stable, so most releases arepatchorminor. Anything that movesbin, an exit code, the response envelope or the supported Node range is breaking for an adopter whatever the number says — say so in the notes.
Never propose a prerelease. publish.yml passes no --tag, and npm refuses a prerelease version under the default
tag, so a v0.1.0-rc.1 tag fails the publish step outright. Release candidates are not a way to rehearse this pipeline;
enabling them means giving that step a --tag, deliberately, as its own change.
Done when: you have proposed a vX.Y.Z and grouped notes that account for every commit since the last tag.
3. Review gate — approve before releasing
Show the user the proposed vX.Y.Z and the full notes, then stop and wait. Advance to step 4 only once the user
explicitly approves both. If they change the bump or edit the notes, revise and show the updated version and notes
again.
Approving here authorises the push in step 4. That push is the irreversible act: published versions are immutable, and a tag that reaches the remote fires Publish.
Done when: the user has approved a specific version and specific notes.
4. Cut the release
npm version <patch|minor|major> --no-git-tag-version # bumps package.json + package-lock.json; no commit, no tag
# commit both files with the `commit` skill — see the second warning below
git tag -a vX.Y.Z -m "vX.Y.Z" # ANNOTATED — see the first warning below
git push --follow-tags # pushes the commit AND the tag, firing Publish
git ls-remote --tags origin | grep vX.Y.Z # prove the tag landed; no tag, no publish
Three ways this step fails, two of them silently:
git push --follow-tagspushes annotated tags only. A lightweight tag —git tag vX.Y.Z, no-a— is skipped without a word. The push printsmain -> main, exits0, and Publish never fires: the release looks finished and nothing reached npm. That is what the-aand thels-remoteline are for. Do not read a clean push as proof.- The commit-msg gate rejects a bare release commit. It requires a Keep a Changelog
### <category>section with at least one numbered item, plus aSource:trailer, sogit commit -m "chore(release): 0.2.0"is refused. Use thecommitskill, which writes a conforming message and runs the gate before committing. - A tag that disagrees with the manifest is refused, loudly.
publish.yml's first step comparesGITHUB_REF_NAMEagainstpackage.json's version and aborts beforenpm ci. This is a backstop for forgetting the bump, not a step to lean on — it costs a failed run and a re-tag.
Done when: git ls-remote --tags origin lists the vX.Y.Z tag.
5. Watch Publish
The Publish workflow fires on the tag: it re-runs npm run verify and the same HIGH/CRITICAL Trivy gate
security.yml applies, then publishes over OIDC with provenance attached. A red verify, a red scan or a failed build
aborts before anything reaches the registry.
A job-level success is not per-step evidence. If a step's outcome matters, read that step — a step skipped by an if:
also reports success.
Done when: the Publish run for the tag is green in the Actions tab.
6. Verify and record the notes
- The registry agrees:
npm view @hancrafted/markdown-harness versionreports the tag you cut. - The npm package page shows a provenance attestation. A manual publish cannot produce one, so its absence means the version did not come from the workflow.
- Publish the approved notes as a GitHub Release. Write them to a file first so multi-line markdown survives:
gh release create vX.Y.Z --title vX.Y.Z --notes-file <file>.
Done when: the registry reports the new version and its GitHub Release carries the approved notes.
If anything went wrong, never overwrite a published version — bump again and re-tag. Troubleshooting is in
docs/agents/release.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |