cut-a-release
Skill1 starsChanged 3 days agoMITView on GitHub
Cut a doctrina-cli release with consistent version stamps, a Changelog entry, and every gate green. Use when: The task is to release/publish a new version of doctrina-cli, or to reconcile drifted version stamps.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- henit-chobisa/decktheir own version, first seen Oct 19, 2026
- royalpinto007/ship-skillstheir own version, first seen Oct 13, 2026
- takealook97/vattheir own version, first seen Aug 28, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- henit-chobisa/deck★ 33same name
- royalpinto007/ship-skills★ 1same name
- takealook97/vat★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/00-doctrina.mdcCursor rule
- add-cli-commandSkill
- check-the-line-ending-before-patchingSkill
- keep-docs-en-pt-paritySkill
- ledger-abandoned-entries-are-ledger-onlySkill
- read-the-grammar-through-the-document-modelSkill
- split-an-oversized-specSkill
- stage-a-change-backlogSkill
- triage-holds-work-on-the-machinerySkill
- write-acceptance-evidenceSkill
- add-cli-commandSkill
- check-the-line-ending-before-patchingSkill
- cut-a-releaseSkill
- keep-docs-en-pt-paritySkill
- ledger-abandoned-entries-are-ledger-onlySkill
- read-the-grammar-through-the-document-modelSkill
- split-an-oversized-specSkill
- stage-a-change-backlogSkill
- triage-holds-work-on-the-machinerySkill
- write-acceptance-evidenceSkill
- doctrina-contextSkill
- doctrina-nextSkill
- doctrina-onboardSkill
- doctrina-statusSkill
- doctrina-whySkill
- doctrina-workSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Write the changelog. Everything since the last release sits under ## [Unreleased] in CHANGELOG.md (Keep a Changelog format.
- Very specific: line 24
Write the agent-facing changelog by hand: doctrina status --view agent-changelog proposes one candidate bullet per archived change that …
- Distinctive: line 51
Check the run's warnings. npm may hold the version staged until a maintainer approves it with 2FA (a token that bypasses 2FA is staged, and …
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- doctrina:skill-export — generated from .doctrina/skills/cut-a-release.md by `doctrina index rebuild`; edit that file, not this one. -->Skill — cut-a-release
When to use this skill
- Publishing
doctrina-clito npm (any semver bump). - Reconciling version stamps after they drifted.
Procedure
The canonical version lives in ONE place:
packages/doctrina-cli/package.json. Everything else quotes it, and
scripts/release.mjs writes every quote.
- Write the changelog. Everything since the last release sits under
## [Unreleased]inCHANGELOG.md(Keep a Changelog format; pre-1.0 minor bumps may change CLI surface and artifact shapes). Add an### Upgrading from <previous>note when a user has something to run. - Write the agent-facing changelog by hand:
doctrina status --view agent-changelogproposes one candidate bullet per archived change that touched a documented surface, newest first, capped at the block's five bullets and windowed since the last tag. Paste the block intoAGENT_CHANGELOGinsrc/lib/commands.jsunder the new version and REWRITE each line into what an agent must now DO — the draft only knows which surface moved. Bullets that do not change an agent's behaviour belong inCHANGELOG.md, not here; if more than five survive, choose, do not raise the cap (it is AGENTS.md's line budget). - Open the release as a chore (
doctrina work --chore "release X.Y.Z"), then stamp:node scripts/release.mjs X.Y.Z. It moves the Unreleased content under## [X.Y.Z] — <today>, bumpspackage.jsonand the lockfile, regenerates AGENTS.md's blocks, and writes the status line of the three READMEs, the supported minor inSECURITY.md, and theframework_versionof the root index and of everyexamples/*/index. It refuses while step 2 is missing.node scripts/release.mjs --checksays which stamp still disagrees; the suite and the Release workflow both run it. npm pack --dry-runinsidepackages/doctrina-cli/— the tarball must list onlysrc/,templates/,README.md,package.json(theprepackscript copies.doctrina/templates/in).- Close the change (
doctrina close <id>runs every gate), commit, open the pull request and merge it. Do not tag. The Release workflow runs when a push tomainchangespackages/doctrina-cli/package.json: if npm does not have that version yet it runs the gates, publishes, and tags the published commitvX.Y.Zitself. A version npm already has ends the run at the first step with a notice. - Check the run's warnings. npm may hold the version staged until a
maintainer approves it with 2FA (a token that bypasses 2FA is staged, and
from 2027 cannot publish directly): the run says "not public after two
minutes". Approve it on npmjs.com (account → Staged Packages) or with
npm stage list doctrina-clithennpm stage approve <stage-id>. Never re-run the publish for it: npm refuses a version it holds (E409). Trusted publishing configured on npmjs.com forrelease.ymlremoves the step.
Anti-patterns
- Bumping package.json and leaving AGENTS.md/READMEs on the old version: the audit behind v0.10.0 found the hub declaring v0.4.0 while the CLI shipped 0.9.0 — agents reading the hub never discovered six commands.
- Publishing with
coverage --strictred "because it's only docs". The gates are the product; a release that fails its own gates argues against itself. - Tagging by hand. Both failed releases of November 2026 were a tag on
the wrong commit: v0.20.0 on a merge made after 0.20.0 was on npm (a 403
after every gate passed), v0.21.0 on a commit whose examples were still
stamped 0.20.0. A version bump merged into
mainIS the release. - Bumping the version in a pull request that is not the release: the merge publishes it.
- Pushing or creating a
v*tag by hand, or a GitHub Release that creates one: the job writes the tag, and a tag starts nothing.
Related material
CHANGELOG.md— versioning policy section.- ADR 0008 (honest gates); ADR 0009 (validate as the drift truth).
- The
write-acceptance-evidenceskill for getting coverage green honestly.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

