agentleFS
mediajunkiemediajunkie/piper-morgan-product/.claude/skills/cut-release/SKILL.md

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

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.
  • layer5ioSkill

    quota-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

  • SentrySkill

    iterate-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

  • layer5ioSkill

    gh-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

  • kunchenguidSkill

    chrome-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

  • kunchenguidSkill

    lavish

    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

  • ThisIsSadeghiSkill

    verify-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

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
  1. Distinctive:

    When PM says "cut a release", "cut v0.8.X", or "do a release".

    line 18
  2. Distinctive:

    If any of these are unclear, ask PM before starting.

    line 28
  3. Very specific:

    ⭐ #1413 CONTENT-PARITY GATE (added 2026-08-04): run scripts/check-release-parity.sh FIRST.

    line 34
  4. Distinctive:

    Stop and surface to PM if: cut commit is ambiguous, tests are broken, P0 is open.

    line 55
  5. Distinctive:

    Write it fresh — do not copy-paste the previous release notes.

    line 74
  6. Very specific:

    Verification: after editing, grep -n "0\.8\." docs/ALPHA_QUICKSTART.md — all version references should be NEW_VERSION.

    line 105
  7. Distinctive:

    Don't bump it. It's scoped to the self-install alpha (banner at the top) and doesn't describe hosted Piper.

    line 123
  8. Distinctive:

    Read each of these sections and confirm they describe THIS release, not the previous one:

    line 224
  9. Distinctive:

    If any section still describes old functionality: fix it now, before the release is done.

    line 235

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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: empty

Stop 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 OK

Create 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.md instead, with no issue number (the number goes in the d-known-limits notes of docs/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 sets last_verified only 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; run python3 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 \
  --latest

Phase 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:

DocSection to readWhat to verify
ALPHA_QUICKSTARTWhat's NewFeatures are from THIS release
ALPHA_QUICKSTARTWhat's WorkingCapabilities list is current
ALPHA_QUICKSTARTTesting FocusReflects what's newly shipped
ALPHA_TESTING_GUIDEWhat's NewSame check
ALPHA_KNOWN_ISSUESKnown IssuesFixed issues removed; new issues added
known-limitsevery rowFixed 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 + sha

Anti-patterns

Don'tWhy
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 releaseTesters 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 auditThe grep catches version strings; the audit catches stale prose. Both required.
Call the release done without a GitHub ReleaseThe 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): production branch 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 — production is retiring, deploys come from origin/main; Phase 7's deployment block is the actual fly deploy from a detached clean worktree with the sha build-arg and the /health READ, 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.