Ship Release
The Massing release discipline — how to ship a verified, CI-green version-numbered release direct to main. Invoke whenever finishing a shippable change (feature, fix, doc). Covers version bump (both files), CHANGELOG/roadmap notes, the ruff/lint CI gotchas, tag, push, and CI/CodeQL verification.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Ship Release when an AI agent needs a reusable SKILL.md workflow for this job: The Massing release discipline — how to ship a verified, CI-green version-numbered release direct to main. Invoke whenever finishing a shippable change (feature, fix, doc). Covers version bump (both files), CHANGELOG/roadmap notes, the ruff/lint CI gotchas, tag, push, and CI/CodeQL verification.
When not to use it
Skip Ship Release when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/ship-release # Save SKILL.md to ~/.claude/skills/ship-release/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/ship-release/SKILL.md. For a shared project, commit the folder at .claude/skills/ship-release/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Ship Release skill for this task: Use Ship Release when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 59/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Ship a Massing release
`main` is unprotected and ships version-numbered releases via **direct commits** (no PR gate). Each shippable change is its own release. Follow this exactly.
## 1. Verify before you ship - **Backend (services/api, services/data):** run the affected `test_*.py` (see the `backend-tests` skill) and **ruff exactly as CI does**: ``` cd services/api && python -m ruff check src/ ../data/src/ ``` A file-level `ruff check <file>` from elsewhere does NOT pick up `services/api/ruff.toml` (isort/I001) and gives false "passed". Prefer `ruff check --fix` to auto-sort imports; put third-party imports in their own group after stdlib. - **Web (apps/web):** `export PATH="/c/Program Files/nodejs:$PATH"` then `npm run typecheck && npm run lint && npm run build` (Node 20; Node 18 breaks the build). Run `npx vitest run <path>` if unit tests cover the change. - **Frontend UI:** the dev-preview geometry loader stalls at "preparing geometry", so verify rail UI via the `verify-frontend` skill (force `buildToolsPanel` by dispatching `aec:persona`), and flag any flow you couldn't exercise end-to-end.
## 2. Bump the version — BOTH files ``` git fetch origin --quiet # avoid the version race (a background release may have taken the next number) sed -i 's/"version": "0.3.X"/"version": "0.3.Y"/' apps/web/package.json apps/web/src-tauri/tauri.conf.json ``` Confirm `origin/main` is where you branched (`git log origin/main --oneline -1`). If it advanced, rebase and bump to the next free number.
## 3. CHANGELOG + roadmap - Prepend a `## vX.Y.Z — <title>` entry to `CHANGELOG.md` (newest at top). - Add a `✅ … SHIPPED vX.Y.Z` note to the relevant `docs/roadmap.md` item. - Keep competitor names OUT of shipped docs; interop names (Revit, Bonsai, Procore) are fine.
## 4. Commit, push, tag Commit with the trailer `Co-Authored-By: Claude Opus 4.8 <[email protected]>`. Then, guarding against a race: ``` if [ "$(git rev-parse origin/main)" = "$(git rev-parse HEAD~1)" ]; then git push origin HEAD:main && git tag vX.Y.Z && git push origin vX.Y.Z else echo "RACE — rebase + rebump"; fi ```
## 5. Verify CI + CodeQL - A "CI" workflow run showing `success` does NOT mean the **API test gate** ruff step passed, or that CodeQL is clean. Check both. - After each push run the `security-monitoring` skill's CodeQL check (open **alerts**, not run status). - The API test gate is slow (~15–20 min); each commit is independently verified locally, so keep shipping. Watch the first release carrying a new test file to confirm it's green in CI.
See memory: `main-fast-release-cadence`, `ruff-ci-config-gotcha`, `backend-test-runner`, `codeql-monitoring`, `web-build-needs-node-20`.
Intended uses
- Use Ship Release when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.