cut-release
Skill8 starsChanged 11 days agoApache-2.0View on GitHub
Execute a Piper Morgan release end-to-end — pre-flight, version bump, doc updates (version strings AND prose body as separate explicit tasks), git ops, GitHub release, production branch, post-release audit. Invoke instead of reading the runbook directly.
- Deletes or force-pushes
- Commits and pushes
36 other projects use a version of this.
Adopted by
Most recently taken up by
- ItalyPaleAle/skillstheir own version, first seen Nov 16, 2026
- ToolJet/ToolJettheir own version, first seen Nov 12, 2026
- fim-ai/fim-onetheir own version, first seen Nov 11, 2026
- GLinnik21/plx-nativetheir own version, first seen Nov 8, 2026
- delexw/motion-graphics-agenttheir own version, first seen Nov 8, 2026
- tansu-io/tansutheir own version, first seen Nov 1, 2026
Used with
Projects with it also use quota-axi, iterate-pr and 6 more.
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.
layer5ioSkillquota-axi
Report local Claude, Codex, Cursor, GitHub Copilot, and Grok quota windows via the quota-axi CLI - remaining percentages, reset times, and provider status read from local auth sources, with no routing, recommendation, or provider mutation. Use before deciding whether it is safe to keep spending a provider's quota, when the user asks about usage, rate limits, or remaining quota, or when comparing local provider headroom.
Also in 4 projects that use this
SentrySkilliterate-pr
Iterate on a PR until actionable CI passes and high/medium review feedback is addressed. Use for PR CI failures, review feedback, or green-check loops; do not wait for human approval, draft status, or merge gates.
Also in 4 projects that use this
layer5ioSkillgh-axi
Operate GitHub through the gh-axi CLI - issues, pull requests, workflow runs, workflows, releases, repositories, labels, Projects (v2), Actions secrets and variables, search, and raw API access. Use whenever a task touches GitHub: listing or filing issues, reviewing or merging PRs, checking CI runs, triggering workflows, cutting releases, managing Projects boards, or managing Actions secrets/variables.
Also in 4 projects that use this
kunchenguidSkillchrome-devtools-axi
Control a Chrome browser session through the chrome-devtools-axi CLI - navigate, snapshot, click, fill forms, run JavaScript, inspect console and network, take screenshots, audit performance. Use whenever a task needs a real browser: opening or testing a web page, clicking through a flow, extracting page content, or debugging a website.
Also in 4 projects that use this
kunchenguidSkilllavish
Turn complex or visual agent responses into rich, reviewable HTML artifacts (HTML files) the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.
Also in 4 projects that use this
ThisIsSadeghiSkillverify-ui
Verify UI implementation against Stitch design via a token audit (HTML ↔ Code, with X-component default-render checks) and an X-components compliance check.
Also in 3 projects that use this
Other versions36 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 36
- ToolJet/ToolJet★ 41ksame name
- meshery/meshery★ 12ksame name
- danielmeppiel/apm★ 4.4ksame name
- microsoft/apm★ 4.4ksame name
- Screenly/Anthias★ 3.7ksame name
- Netflix/bpftop★ 2.7ksame name
- tansu-io/tansu★ 1.9ksame name
- fim-ai/fim-agent★ 1.6ksame name
- fim-ai/fim-one★ 1.6ksame name
- libredb/libredb-studio★ 1.3ksame name
26 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 repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/architecture-patterns.mdcCursor rule
- .cursor/rules/completion-discipline.mdCursor rule
- .cursor/rules/github-tracking.mdcCursor rule
- .cursor/rules/programmer-briefing.mdcCursor rule
- .cursor/rules/verification-first.mdcCursor rule
- ab-a-isolationSkill
- assign-sprint-safelySkill
- audit-cascadeSkill
- brief-coding-agentSkill
- check-mailboxSkill
- cleanup-dev-activeSkill
- close-issue-properlySkill
- cohort-attention-rollupSkill
- compost-reviewSkill
- continue-narrativeSkill
- create-omnibusSkill
- create-session-logSkill
- delete-module-safelySkill
- deliver-mailSkill
- discovered-work-captureSkill
- doc-sync-sweepSkill
- draft-blog-postSkill
- draft-weekly-shipSkill
- duty-cycle-tickSkill
- narrative-verificationSkill
- piper-draft-issueSkill
- piper-draft-specSkill
- piper-sprint-planSkill
- piper-stakeholder-updateSkill
- piper-synthesize-feedbackSkill
- propose-featureSkill
- publish-to-blogSkill
- query-github-boardSkill
- template-auditSkill
- trust-checkSkill
- update-calendarSkill
- update-current-stateSkill
- update-piperSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 7 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 36 edited versions we read keep these.
7
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
- Distinctive: line 18
When PM says "cut a release", "cut v0.8.X", or "do a release".
- Distinctive: line 28
If any of these are unclear, ask PM before starting.
- Very specific: line 34
⭐ #1413 CONTENT-PARITY GATE (added 2026-08-04): run scripts/check-release-parity.sh FIRST.
- Distinctive: line 55
Stop and surface to PM if: cut commit is ambiguous, tests are broken, P0 is open.
- Distinctive: line 74
Write it fresh — do not copy-paste the previous release notes.
- Very specific: line 105
Verification: after editing, grep -n "0\.8\." docs/ALPHA_QUICKSTART.md — all version references should be NEW_VERSION.
- Distinctive: line 123
Don't bump it. It's scoped to the self-install alpha (banner at the top) and doesn't describe hosted Piper.
- Distinctive: line 224
Read each of these sections and confirm they describe THIS release, not the previous one:
- Distinctive: line 235
If any section still describes old functionality: fix it now, before the release is done.
“Common” is measured: kept by at least 6 in 10 of the 36 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
cut-release
Execute a Piper Morgan release. Companion skill to docs/internal/operations/release-runbook.md — the runbook is the reference; this skill is the executable procedure that makes doc-body updates non-skippable.
Primary failure mode this skill prevents: bumping the version header without updating the prose body (What's New, Testing Focus, What's Working). These are distinct tasks; the skill treats them as such.
When to Use
When PM says "cut a release", "cut v0.8.X", or "do a release". Always invoke this skill — do not work from memory.
Inputs You Need Before Starting
- NEW_VERSION — e.g.
0.8.8 - PREV_VERSION — e.g.
0.8.6(the version currently in the files) - CUT_COMMIT — the git commit hash the release is cut from
- MILESTONE — what sprint/milestone this covers, e.g. "D1/RECONNECT"
- PREV_TAG — the previous git tag, for commit log range
If any of these are unclear, ask PM before starting. A release cut on the wrong commit or wrong version is hard to undo.
Phase 1 — Pre-flight (do not skip)
⭐ #1413 CONTENT-PARITY GATE (added 2026-08-04): run scripts/check-release-parity.sh
FIRST. A "full-parity" claim is a statement about a moment (the 7/16 incident: the claim
aged 48 minutes and silently dropped a live login fix → two-day latent login regression).
The script refuses on any unexplained content gap between the release ref and origin/main;
intentional exclusions go in release-exclusions.txt AND the release notes verbatim —
empty diff or explained lines, never silent gaps.
# 1. Confirm cut commit
git log --oneline {PREV_TAG}..HEAD | head -20
# Identify the commit that closes the milestone gate
# 2. Confirm tests
python -m pytest tests/ --collect-only -q 2>/dev/null | tail -3
# Record: N tests collected
# 3. No open P0 blockers
gh issue list --label P0 --state open --repo mediajunkie/piper-morgan-product
# Expected: emptyStop and surface to PM if: cut commit is ambiguous, tests are broken, P0 is open.
Phase 2 — Version bump + release notes
pyproject.toml AND the repo-root VERSION file (both, always)
# Change: version = "{PREV_VERSION}" → version = "{NEW_VERSION}" in pyproject.toml
# Change: the repo-root VERSION file → {NEW_VERSION} ← #1839's /health reads THIS file
# Verify BOTH with the existing checker (added to this skill 2026-09-21 after the
# v0.8.13.0 cut shipped with VERSION stale — the deployed /health would have reported
# the previous version):
python scripts/check-version-consistency.py # must print OKCreate release notes
File: docs/releases/RELEASE-NOTES-v{NEW_VERSION}.md
Write it fresh — do not copy-paste the previous release notes. Required sections:
- Summary (2-3 sentences: what milestone, quality posture, test count)
- What's New (organized by theme, each item links to its issue)
- Known limitations (honest — what's still rough for alpha testers)
- Version mechanics (cut commit, tag, pyproject note if applicable)
- Upgrade instructions
Phase 3 — Documentation updates (THE HIGH-FAILURE ZONE)
Work through this list in order. For each file: read it first, then make the specified changes. Do not treat "update version" as sufficient for any file that has body content.
3a. docs/releases/README.md
- "Current Version" line → NEW_VERSION
- Add row to Release History table (version, date, type, highlights)
- Update "Last updated" date
3b. docs/ALPHA_QUICKSTART.md
Two separate tasks — do not conflate:
Task 1 — version strings (grep-able):
- Header
**Version**: X.Y.Z→ NEW_VERSION - Footer "This is alpha software (X.Y.Z)" → NEW_VERSION
- "Last Updated" date → today
Task 2 — prose body (requires rewriting, not just find/replace):
- "What's New" section: rewrite entirely. Describe the features that shipped in THIS release, in plain language a developer-tester will understand. Do not leave the previous version's feature descriptions. Each bullet should describe a real user-facing change.
- "Testing Focus" section: rewrite entirely. What should testers pay attention to in THIS release? What's newly shipped and needs eyes?
- "What's Working" section: update to reflect current capabilities. Remove features that have been superseded; add what's genuinely stable in THIS release.
Verification: after editing, grep -n "0\.8\." docs/ALPHA_QUICKSTART.md — all version references should be NEW_VERSION. Read the What's New section and ask: does this describe what THIS release ships, or the previous one?
3c. docs/ALPHA_TESTING_GUIDE.md
- Header version + Last Updated
- "What's New" section: rewrite for THIS release (same discipline as Quickstart)
- "Testing Focus": update for what's new to test
- Footer version
3d. docs/ALPHA_KNOWN_ISSUES.md
- Header version, title line
(vX.Y.Z), Last Updated - Check GitHub for open bugs:
gh issue list --label bug --state open - Move any fixed issues OUT of Known Issues (the tester page may say "Fixed in": it describes a release)
- Add any newly discovered issues. A limit that meets PPM's three-part rule (a limit of something offered, can cost a person time, data or a wrong belief, safe to say before the fix is live) goes in
docs/known-limits.mdinstead, with no issue number (the number goes in thed-known-limitsnotes ofdocs/internal/design/tier1-corpus-manifest.csv). The tester page links to it and keeps only tester-only items. docs/known-limits.md: a fixed limit is DELETED from it, never marked fixed, in a commit that has the fix as an ancestor (Arch, 11-13). PPM passes membership on every added or removed row, CXO passes the words, Docs re-verifies each row on the served build and setslast_verifiedonly for rows actually read. See #2355 part (d).- Update "Needs Testing" for this release
- Keep under 200 lines (if longer, content is misplaced)
3e. docs/ALPHA_AGREEMENT_v2.md — retired from releases (2026-10-16)
Don't bump it. It's scoped to the self-install alpha (banner at the top) and doesn't describe hosted Piper; version bumps made it look current. xian's OK via Exec, 10-16. Hosted Terms are being written separately (Terms option 2, CXO owns the plan).
3f. docs/briefing/BRIEFING-CURRENT-STATE.md (short "Now" page since 2026-10-08)
- Overwrite the Version line (tag, date, your attestation) and the Alpha (live) line once deployed
- Bump front-matter
last_updated; runpython3 scripts/check-current-state.py - (No Version History table or Recent Progress any more: release history lives in the release notes and the omnibus.)
3g. docs/operations/alpha-onboarding/email-template.md
- Version in header
- Version in body text (may appear multiple times)
- Footer version / "Last Updated"
3h. docs/versioning.md (if it exists)
ls docs/versioning.md docs/VERSION_NUMBERING.md 2>/dev/null- "Current Version" at top → NEW_VERSION
- Add row to Version History table
- Footer date
3i. docs/README.md
- Release notes quick link (line ~18) → new version
Phase 4 — Git ops
# Fix newlines
./scripts/fix-newlines.sh
# Stage with explicit paths (never git add -A)
git add pyproject.toml \
docs/releases/RELEASE-NOTES-v{NEW_VERSION}.md \
docs/releases/README.md \
docs/ALPHA_QUICKSTART.md \
docs/ALPHA_TESTING_GUIDE.md \
docs/ALPHA_KNOWN_ISSUES.md \
docs/known-limits.md \
docs/briefing/BRIEFING-CURRENT-STATE.md \
docs/operations/alpha-onboarding/email-template.md \
docs/versioning.md \
docs/README.md
git diff --cached --name-only # Verify: only expected files
git commit -m "release: v{NEW_VERSION} — {MILESTONE}"
# Tag at cut commit (not HEAD if different)
git tag -a v{NEW_VERSION} {CUT_COMMIT} -m "Release v{NEW_VERSION} — {MILESTONE}"
# If cutting at HEAD:
git tag -a v{NEW_VERSION} HEAD -m "Release v{NEW_VERSION} — {MILESTONE}"
git push origin HEAD:main
git push origin v{NEW_VERSION}Phase 5 — Deploy source (origin/main; the production branch was retired 2026-09-29)
Deploys come from origin/main. The production branch retired with the droplet at cutover
step 11 (2026-09-29, PM-ruled); there is no second lineage to advance. PM's original intent for that
branch — a stable cut for testers while main moves — is being rebuilt as a mechanism by the
deployment-pipeline plan §4e (CI deploys main to piper-morgan-staging; promotion to alpha is a
deliberate act), Pard building. Until §4e lands, the release IS the deploy: tag the commit, then
deploy that exact commit.
⭐ #1413 DEPLOY-SOURCE RULE, restated for the Fly era: an environment must never be NEWER
than its release lineage. The lineage is origin/main, so: deploy the tag's commit or a LATER
origin/main tip from a detached throwaway worktree, never a feature branch or a dirty checkout —
fly deploy -a piper-morgan --remote-only --build-arg PIPER_GIT_SHA=$(git rev-parse HEAD) — and
run the parity gate against what you deploy: scripts/check-release-parity.sh <ref> must say
PARITY OK. Verify /health's git_sha equals the deployed commit afterwards; a deploy is not done
on an exit code.
Phase 6 — GitHub Release
gh release create v{NEW_VERSION} \
--title "v{NEW_VERSION} — {MILESTONE}" \
--notes-file docs/releases/RELEASE-NOTES-v{NEW_VERSION}.md \
--latestPhase 7 — Post-release audit (do not skip)
Version string audit
# Scan for any docs still referencing PREV_VERSION (excluding historical release notes)
grep -r "{PREV_VERSION}" docs/ --include="*.md" | grep -v "docs/releases/"Any hits are stale. Update them.
Content accuracy audit
Read each of these sections and confirm they describe THIS release, not the previous one:
| Doc | Section to read | What to verify |
| ALPHA_QUICKSTART | What's New | Features are from THIS release |
| ALPHA_QUICKSTART | What's Working | Capabilities list is current |
| ALPHA_QUICKSTART | Testing Focus | Reflects what's newly shipped |
| ALPHA_TESTING_GUIDE | What's New | Same check |
| ALPHA_KNOWN_ISSUES | Known Issues | Fixed issues removed; new issues added |
| known-limits | every row | Fixed limits deleted, new ones meet PPM's rule, no issue numbers |
If any section still describes old functionality: fix it now, before the release is done.
Deployment
# Deploys run from ANY seat PM directs (measured 2026-09-24: Lead's seat deployed v121–v126),
# from a DETACHED, CLEAN worktree at origin/main — never PM's checkout, never a feature branch.
rm -rf /tmp/deploy-wt && git worktree add --detach /tmp/deploy-wt origin/main && cd /tmp/deploy-wt
fly deploy -a piper-morgan --remote-only --build-arg PIPER_GIT_SHA="$(git rev-parse HEAD)"
# PIPER_GIT_SHA is what /health's git_sha reads; without it /health says "unknown" (#1839/#1849).
# The release_command runs `alembic upgrade head` before the new machine takes traffic.
cd - && git worktree remove --force /tmp/deploy-wt
# READ, never an exit code: the NEW version + the sha you just built.
curl -s https://alpha.pipermorgan.ai/health | head -c 320
fly releases -a piper-morgan | head -3 # newest vN "complete"
# This is the check that caught the unmounted-router gap on 09-21 and the dangling import on 09-23.
# Until the §4e CI deploy path lands (Pard), this is the whole deploy. PM's local checkout is
# never the source: `scripts/sync-pm-local.sh` fast-forwards it AFTER, for PM's reading.Completion matrix
Paste this into your session log when done:
## Release v{NEW_VERSION} Completion Matrix
Phase 1 — Pre-flight
- [ ] Cut commit identified: {CUT_COMMIT}
- [ ] Tests passing: N collected
- [ ] No open P0s
Phase 2 — Version bump
- [ ] pyproject.toml bumped
- [ ] Release notes written (not copy-pasted)
Phase 3 — Documentation
- [ ] docs/releases/README.md
- [ ] docs/ALPHA_QUICKSTART.md — version strings AND prose body
- [ ] docs/ALPHA_TESTING_GUIDE.md — version strings AND prose body
- [ ] docs/ALPHA_KNOWN_ISSUES.md
- [ ] docs/known-limits.md
- [ ] docs/briefing/BRIEFING-CURRENT-STATE.md
- [ ] docs/operations/alpha-onboarding/email-template.md
- [ ] docs/versioning.md
- [ ] docs/README.md
Phase 4 — Git ops
- [ ] Committed with explicit paths
- [ ] Tag created at cut commit
- [ ] Pushed to main + tag
Phase 5 — Deploy source
- [ ] deployed from the tag's commit; parity gate PARITY OK against the deployed ref; /health git_sha verified
Phase 6 — GitHub Release
- [ ] gh release create v{NEW_VERSION} published
Phase 7 — Audit
- [ ] Version string grep: no stale hits
- [ ] Content accuracy: What's New sections describe THIS release
- [ ] Deployed from a detached clean worktree at origin/main (or surfaced to PM if the seat can't); /health attests version + shaAnti-patterns
| Don't | Why |
| Bump version string only, skip prose | "Update version" means TWO tasks: number + body. The body is the one that rots. |
| Copy-paste release notes from last release | Testers read these. Stale notes erode trust. |
git add -A or git add docs/ | Sweeps stale untracked files into the commit. Explicit paths only. |
| Skip the content accuracy audit | The grep catches version strings; the audit catches stale prose. Both required. |
| Call the release done without a GitHub Release | The tag is internal; the GitHub Release is what testers see. |
Changelog
- v1.4 (2026-11-13, Docs): Step 3d now routes limits that meet PPM's rule to
docs/known-limits.md(the Tier 1 corpus file, no issue numbers, fixed limits deleted not marked fixed) and lists it in the staging and completion checks. Arch's ruling 01M7APG3SB, PPM 01M7AP6MM5, CXO's go 01M7AQHDM7. The tester page keeps its issue numbers and "Fixed in". - v1.3 (2026-09-29, Lead):
productionbranch DELETED at cutover step 11 (PM-ruled); Phase 5 is now the single-lineage rule, pointing at pipeline plan §4e for the stable-cut-for-testers mechanism. - v1.2 (2026-09-24, Lead): Phase 5 rewritten for the Fly era —
productionis retiring, deploys come fromorigin/main; Phase 7's deployment block is the actualfly deployfrom a detached clean worktree with the sha build-arg and the/healthREAD, replacing the droplet instructions. Completion matrix updated to match. - v1.1 (2026-09-21, Lead): Phase 2 now bumps the repo-root VERSION file alongside
pyproject and runs
scripts/check-version-consistency.py(the v0.8.13.0 cut shipped with VERSION stale — the file #1839's /health reads; caught by the same-session docs audit). Phase 7's deployment note gains the PIPER_GIT_SHA build-arg + the live /health identity check. - v1.0 (2026-06-20, PA): Initial skill. Created after ALPHA_QUICKSTART was discovered with stale body content post-v0.8.8 release — version header bumped but "What's New", "Testing Focus", and "What's Working" sections still described v0.8.6 features. Root cause: runbook listed "Update Version and 'What's New' section" as one checkbox item; under time pressure it read as one action (bump the number). This skill splits them explicitly and makes prose rewrites non-skippable.
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.

