bump
Skill161 starsChanged 11 days agoMITView on GitHub
Release Pneuma Skills when the user requests a version bump or release. Updates versions and release notes, validates, pushes main, and verifies publishing.
- Commits and pushes
11 other projects use a version of this.
Adopted by
Most recently taken up by
- zanellig/skillstheir own version, first seen Oct 29, 2026
- PrimeIntellect-ai/verifierstheir own version, first seen Oct 17, 2026
- jwilger/agent-skillstheir own version, first seen Oct 11, 2026
- poco-ai/Agenterotheir own version, first seen Oct 8, 2026
- av1155/houndarrtheir own version, first seen Oct 8, 2026
- PinW/whisper-key-localtheir own version, first seen Oct 8, 2026
Used with
Projects with it also use release.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillrelease
Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).
Also in 3 projects that use this
Other versions11 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 11
- PrimeIntellect-ai/verifiers★ 4.8ksame name
- poco-ai/Agentero★ 2.5ksame name
- av1155/houndarr★ 312same name
- PinW/whisper-key-local★ 203same name
- GeoloeG-IsT/agents-reverse-engineer★ 20same name
- maxwellsdm1867/wheeler★ 12same name
- atournayre/claude-marketplace★ 9same name
- soderlind/skills★ 5same name
- jwilger/agent-skills★ 4same name
- zanellig/skills★ 1same name
1 more not listed
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 repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- create-adrSkill
- create-modeSkill
- dev-workflowSkill
- showcaseSkill
- create-modeSkill
- dev-workflowSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 6 are distinctive, and 8 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Read references/release-process.md before executing the steps.
- Very specific: line 31
Read the current version from package.json.
- Very specific: line 35
Read CHANGELOG.md and the git log since the last version bump commit.
- Very specific: line 55
Do NOT include chore/CI/version-bump commits
- Distinctive: line 74
Do NOT bloat these files — keep them concise and accurate.
- Very specific: line 81
Add a key under changelog matching the new version (e.g.
- Very specific: line 83
Keep at most ~6 bullets per version.
- Distinctive: line 84
Don't backfill old versions you didn't ship — only annotate the version you're releasing now (and leave any pre-existing entries untouched).
- Distinctive: line 99
Update all four files in a single commit:
- Distinctive: line 114
Before pushing, run the same checks as CI:
- Very specific: line 130
Do not substitute HEAD^ or the previous push: the final commit may contain only the version bump while earlier unpublished commits contain …
- Very specific: line 138
Use bun run test:release --dry-run to inspect the choice, --base <ref> for an explicit verified baseline, and --full to request every tier.
- Distinctive: line 190
Do NOT create or push tags — CI handles that automatically.
- Distinctive: line 248
Verify the workflow for the pushed commit, npm version, and expected desktop assets.
“Common” is measured: kept by at least 6 in 10 of the 8 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
/bump — Version Bump & Release
Perform a full version bump: sync main, write changelog, refresh top-level docs, bump version, and push.
Read references/release-process.md before executing the steps; it owns the detailed release checklist and recovery notes. Paths in this procedure are repository-relative unless marked as skill-relative.
Steps
1. Sync main
Inspect the branch, status, and diff first. Preserve unrelated work. Include the
current task's authorized changes in the release; do not ask the user to resolve
your own pending edits. Fetch origin and compare the intended release with
origin/main. Fast-forward when possible; use an isolated checkout if unrelated
edits prevent a safe update. Resolve routine integration issues within scope and
ask only when including or changing unrelated work requires a decision.
2. Determine version bump
Review all commits since the last version tag to decide the bump level per Semantic Versioning:
- patch (x.y.Z): bug fixes, minor improvements, doc updates
- minor (x.Y.0): new features, new modes, new API endpoints, new viewer capabilities
- major (X.0.0): breaking changes to contracts, CLI interface, or manifest format
Read the current version from package.json. Compute the new version. If unsure, ask the user.
3. Write CHANGELOG entry
Read CHANGELOG.md and the git log since the last version bump commit. Write a new version section at the top following the existing format:
## [X.Y.Z] - YYYY-MM-DD
### Added
- ...
### Fixed
- ...
### Improved
- ...Rules:
- Group changes by category (Added / Fixed / Improved / Changed / Removed)
- Each bullet should be a concise, user-facing description — not a commit message copy
- Bold the feature name, then describe what it does
- Omit categories with no entries
- Do NOT include chore/CI/version-bump commits
4. Refresh top-level docs
Review README.md, README.zh.md, AGENTS.md, and docs/reference/project-guide.md against the current codebase state. Fix any contradictions, outdated info, or missing features. This is a holistic review, not just appending — trim stale content, update tables, fix version numbers.
AGENTS.mdis the single source of agent instructions;CLAUDE.mdis a one-line@AGENTS.mdimport — never write content into it.
Specifically check:
AGENTS.md**Version:**line → update to new versionAGENTS.mdmode-catalog link → resolves to the maintained README catalog; public entries match registered manifests and hidden modes stay outdocs/reference/project-guide.mdtech stack table → matchespackage.jsondependenciesdocs/reference/project-guide.mdproject structure tree → reflects any new/moved directoriesdocs/reference/project-guide.mdserver API reference → includes any new endpoints.claude/rules/*.md→ keep current constraints and topic routing concise; place longer evidence in linked references and correct or retire stale guidanceREADME.mdmode table → matches manifest descriptionsREADME.mdCLI help section → matches actual CLI outputREADME.mdfeature list / roadmap → reflects current state
Do NOT bloat these files — keep them concise and accurate. Remove outdated entries rather than accumulating.
4b. Update mode changelog for any mode whose skill version moved
If this release bumps any mode's manifest.ts version field, you MUST also update that manifest's changelog map with a matching entry — the launcher's skill-update prompt extracts these bullets to tell the user what changed in the skill they're about to reinstall. Skip this step when no mode skill version changed.
For each touched mode:
- Add a key under
changelogmatching the newversion(e.g."1.3.0": [ ... ]). - Each bullet is a one-line user-visible summary, no markdown, no trailing period — they render as
· bulletin a small UI surface. - Keep at most ~6 bullets per version. The full prose lives in the project
CHANGELOG.md. - Don't backfill old versions you didn't ship — only annotate the version you're releasing now (and leave any pre-existing entries untouched).
Also grep for the old literal before bumping, in case a test hardcodes it. Tests under server/__tests__/ and the backends/*/[__tests__]/ lifecycle harnesses sometimes pin webcraftManifest.version, slideManifest.version, etc. with a string equality. Before the commit:
# e.g. webcraft going 1.3.0 → 1.4.0
rg -n '"1\.3\.0"' core server backends modes --glob '*.ts' --glob '*.tsx'Any test hit needs the new string. A miss here is silent locally but fails CI's Release > Test, Build & Release step on push and forces a follow-up commit.
The desktop auto-updater also surfaces highlights in its "Update Available" / "Update Ready" dialogs, but it parses them straight from the project CHANGELOG.md you wrote in step 3 — so a well-formed - **Bold headline** — description bullet there is enough; no extra wiring needed.
5. Bump version
Update all four files in a single commit:
package.json—"version": "X.Y.Z"desktop/package.json— the same versionAGENTS.md—**Version:** X.Y.ZCHANGELOG.md— new version section (from step 3)
Plus any doc changes from step 4.
Commit message format:
chore: bump version to X.Y.Z — <brief milestone description>5b. Pre-push sanity — run the release checks
Before pushing, run the same checks as CI:
bun install --frozen-lockfile
bun install --frozen-lockfile --cwd cloud/collaboration
bun run check:guidance
bun run typecheck
bun run --cwd cloud/collaboration typecheck
bun run test:release
bun run buildtest:release compares the entire release against the nearest reachable stable
release tag older than the target version, including local staged, unstaged and
untracked work. It prints the baseline, changed files, selected modes, expensive
tiers and any fallback reason before running common checks and affected modes.
Do not substitute HEAD^ or the previous push: the final commit may contain only
the version bump while earlier unpublished commits contain the implementation.
The selector enables media pipelines and live backend checks when relevant, and falls back to the full suite if the baseline or impact is unknown. It uses a 60-second per-test deadline in both local and CI runs. Typecheck, production build and catalog verification remain required regardless of test selection.
Use bun run test:release --dry-run to inspect the choice, --base <ref> for an
explicit verified baseline, and --full to request every tier. The standalone
full command remains bun run test:all --timeout 60000; do not run it again
merely because a scoped release selection passed. The deterministic policy and
recovery behavior live in release-process.md;
.claude/rules/testing.md owns tier authoring and focused development commands.
A non-zero test exit means stop and fix before pushing. A skipped opt-in tier is not evidence that it passed: report what ran. Missing optional binaries may produce expected skips; a missing baseline must produce a full selection, never an empty successful run. When a version assertion fails, check the old literals from step 4b in external test directories as well as in the mode itself.
5c. Publish the catalog modes for this version
Before the push, and after the version in package.json is the new one.
Catalog modes — every modes/<name>/ that modes/distribution.json does not
list under bundled — do not travel inside the package. They are downloaded
from the CDN from URLs pinned in a generated modes/catalog.json, and a
prebuilt viewer bundle only runs on the core that built it. So every release
republishes every catalog mode from this commit:
bun run publish:modes --version X.Y.Z --dry-run # sizes first, uploads nothing
bun run publish:modes --version X.Y.Z # build, pack, uploadNeeds ~/.pneuma/r2.json (the credentials snapshot publishing already uses).
CI holds no R2 credentials and uploads nothing — its Verify mode catalog step
downloads official/vX.Y.Z/catalog.json and HEAD-checks every archive before
the tag and before npm, so a release whose archives never went up stops there.
Pushing before this runs is what makes that step fail.
Rules worth knowing before you re-run it:
- A key that already holds the same bytes is skipped.
- A key whose bytes differ is overwritten only while
pneuma-skills@X.Y.Zis not yet on npm — the "failed gate → fix commit → same version" path. - Once that version is on npm the script refuses: its users resolve those exact URLs. Bump the version instead.
- Re-run the whole script, not
--only: every archive in a release comes from one commit.
references/release-process.md has the recovery notes.
6. Push
git push origin mainDo NOT create or push tags — CI handles that automatically.
6b. Deploy the online player when the release touched it
Automatic — do this on every release whose diff touches the player, without
being asked. CI never deploys the player; it only tags, releases and
publishes to npm. The hosted player at pneuma.deepaste.ai is a separate
Cloudflare Pages surface, and viewers are compiled into its bundle at build
time — so "the mode is in the whitelist" is not the same as "the online
player can play it", and a viewer fix that shipped in npm is still absent from
every shared link until this runs.
Decide by looking at what actually changed since the previous tag:
PREV=$(git describe --tags --abbrev=0 HEAD^)
git diff --name-only "$PREV"...HEAD -- \
core/player-support.ts 'src/player/**' web/ 'modes/*/viewer/**' 'modes/*/domain.ts' 'modes/*/pneuma-mode.ts' \
player.html src/index.css src/fonts.css 'public/fonts/**' scripts/deploy-player.shAny output at all means deploy. (domain.ts and pneuma-mode.ts are on the
list because a mode's viewer bundle imports them, so a change there reaches the
player even when no viewer/ file moved. player.html is the player's own
entry, and it imports the same src/index.css as the app — which is where the
bundled fonts in public/fonts/ are declared — so those reach the player too.
scripts/deploy-player.sh stages an explicit file list, not all of
dist-player/; a change to it only takes effect by running it.)
bash scripts/deploy-player.shNeeds wrangler already logged in on this machine (npx wrangler whoami); if it
is not, say so and hand the command to the user rather than skipping in
silence. The script builds dist-player/, then deploys it plus the landing
page to the pneuma-landing Pages project on the production branch. Success
ends with Deployment complete! and a *.pages.dev preview URL; the custom
domain pneuma.deepaste.ai follows.
Two failure shapes worth knowing:
- A whitelisted mode with no viewer in the deployed bundle is a hard error,
not a degradation. The exporter stamps a package
supported: truefrom the whitelist in the repo, and the live player'sloadMode()throws on a mode it was not built with — the user sees "This shared link could not be loaded". - A stale viewer degrades quietly instead. The mode loads, but renders with the old build — a new construct comes out as raw markdown, which reads as broken without saying so.
7. Report
Print a summary:
- Previous version → new version
- Bump type (patch/minor/major)
- Key changes included
- How many catalog modes were published and how many bytes of archives
- Whether the online player was redeployed, and why or why not
- Verify the workflow for the pushed commit, npm version, and expected desktop assets; distinguish a published release from a still-running or failed job
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.

