agentleFS
ai-agent-assemblyai-agent-assembly/agent-assembly/.claude/skills/release-tag-cut/SKILL.md

release-tag-cut

Skill4 starsChanged 3 months agoApache-2.0View on GitHub

Cut a coordinated agent-assembly release tag on an already-bumped main: verify the version/CHANGELOG/release-notes bump PR landed, run the release-readiness gate (security/QA sign-off + evidence binding), then create and push the annotated tag to trigger release.yml. Use when an operator is ready to cut a new pre-release agent-assembly tag (the current cadence is the 0.0.1-beta.N series; earlier cuts were 0.0.1-alpha.N) on a green main, with the bump PR merged and gates PASS, and wants the readiness check, tag, and downstream fan-out handled in the correct order.

  • Installs packages
  • Commits and pushes

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After this skill ends (git push remote v<X>), agent-assembly's release.yml will publish the GitHub Release and fire two automation jobs:

    line 96
  2. Very specific:

    Run from the main agent-assembly/ working tree, not a worktree — tags are pushed from the main checkout per project convention.

    line 125
  3. Distinctive:

    All MUST hold before any step runs.

    line 133
  4. Very specific:

    If it doesn't exist yet, stop and run /release-evidence-finalize <X> first, not inline here.

    line 185
  5. Distinctive:

    After step 4, both MUST hold (full detail in REFERENCE.md → Post-conditions):

    line 209
  6. Very specific:

    Use ticket-authoring's references/fix-versions.md for the exact REST create/release calls.

    line 229
  7. Distinctive:

    MUST NOT replicate any of these by hand — see REFERENCE.md → What's auto-handled for the full list and rationale.

    line 240
  8. Distinctive:

    Create or release Jira Fix Versions — it reminds the operator (see "advance the Jira Fix Version ladder").

    line 251

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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

release-tag-cut

Executable contract for cutting an agent-assembly release tag from a clean main. This SKILL.md is a lean overview; the per-step detail lives in REFERENCE.md and a concrete walk-through in EXAMPLES.md. The canonical prose, recovery procedure, manual gates, and downstream channel matrix live in docs/release/RUNBOOK.md.

Release-flow index (cut → fan-out → validate → tap-merge)

A full release is a relay across sibling skills. WHY this is split: each stage has a different write-authority and a different owner, so collapsing them invites an LLM to "fix" downstream channels from inside the cut. Run them in order:

  1. /release-security-gate <X> (stage 0, pre-cut gate) — run the release-gate security review scaled by release type and commit the PASS sign-off artifact under docs/release/security-signoff/. The gate wraps the built-in /security-review scanner (and, at major tier, the anthropics/claude-code-security-review Action). A BLOCK verdict (or any unaddressed High/Critical) stops the release before this skill runs; scripts/release-readiness.sh check 11 enforces it. See release-security-gate/SKILL.md.
  2. release-tag-cut (this skill, write) — verify the bump PR (RUNBOOK section 1) already landed, run the release-readiness gate, tag, push the tag. Ends the moment git push remote v<X> fires release.yml.
  3. fan-out (automatic, owned by release.yml) — the pushed tag triggers GitHub Release + cosign signing, cargo publish of the workspace, notify-downstream repository_dispatch to node-sdk + python-sdk, the update-{node,python,go}-sdk-ffi-pin auto-bump PRs, and the update-homebrew-tap bot PR. The operator runs none of these by hand.
  4. /release-validate-channels v<X> (read-only) — once release.yml is green, confirm every channel actually caught up. Emits a green/red matrix.
  5. /homebrew-tap-merge <PR> (write, on the tap repo) — verify the bot's sha256s against the release SHA256SUMS and merge the tap PR so brew install aasm serves the new version.

The cadence is currently the 0.0.1-beta.N pre-release series (the latest cut is v0.0.1-beta.2); the same relay served the earlier 0.0.1-alpha.N cuts and is version-string-agnostic — the operator always supplies the exact literal.

This skill ends at git push remote v<X>. The post-tag verification loop (Homebrew tap PR merge, crates.io / PyPI / npm propagation, ghcr.io image push) is owned by /release-validate-channels, invoked by the operator once release.yml finishes.

When to use

Pick this skill when all of the following hold:

  • The operator has decided agent-assembly is ready for a new pre-release tag (current cadence: the beta series, e.g. cutting 0.0.1-beta.3 after 0.0.1-beta.2; the same path served the earlier 0.0.1-alpha.N cuts).
  • The most recent CI run on main is green.
  • The bump PR (RUNBOOK section 1: version/CHANGELOG/release notes) is already merged to main — step 1 verifies this and refuses if not; this skill does not write release notes itself.
  • The working tree is clean and main is up to date with remote/main.

The triggering operator phrasing is typically:

"Cut beta-N+1", "Tag v0.0.1-beta.3", "Release the next beta".

When NOT to use

This skill is pre-release-series, agent-assembly-monorepo, full-fanout specific. Pick a different path in any of the following cases:

  • SDK-only release — use /sdk-only-release in the target SDK repo. Cutting an agent-assembly tag for an SDK-only change wastes a full crates.io publish cycle.
  • GA or non-pre-release tag (v1.0.0, v0.1.0, etc. — any tag with no -alpha/-beta/-rc suffix) — this skill is intentionally scoped to the pre-release cadence; a GA cut needs the release-readiness checklist + manual review, not this autopilot path.
  • Hotfix to an already-tagged release — use the SDK-only path or a follow-up patch tag coordinated via the RUNBOOK; do not re-cut the same tag.
  • Pre-conditions not met — if main is dirty, behind remote/main, or has a red CI run, stop and surface the gap to the operator.
  • No PASS security sign-off for <X> — if docs/release/security-signoff/v<X>.md is missing or its verdict is not PASS, stop. Run /release-security-gate <X> (stage 0) first; do not cut a tag past an unaddressed High/Critical finding.
  • No PASS QA sign-off for <X> — if docs/release/qa-signoff/v<X>.md is missing or its verdict is not PASS, stop. Run /release-qa-gate <X> in release depth first; a security PASS never substitutes for a missing/ non-PASS QA sign-off.

Downstream SDK coordination

After this skill ends (git push remote v<X>), agent-assembly's release.yml will publish the GitHub Release and fire two automation jobs:

  • notify-downstream — repository_dispatch so node-sdk and python-sdk know aasm-* binaries are downloadable (AAASM-2336).
  • update-{node|python|go}-sdk-ffi-pin — opens an auto-bump PR on each SDK that aligns the aa-sdk-client git-SHA pin on main with this tag's commit (AAASM-2883 + AAASM-3006).

Operator rule for the SDK side (codified in each SDK's sdk-only-release skill — AAASM-3007)

Until all three of the following are true for this tag, operators MUST NOT dispatch the SDK release workflows (release-node.yml or release-python.yml) for the matching version:

  1. agent-assembly's Release workflow has reached the notify-downstream step.
  2. The auto-bump PR (bot/aa-ffi-pin-v<X>) has been opened on each SDK repo.
  3. The auto-bump PR has been reviewed and merged.

Pre-dispatching the SDK release with npm_version=<X> / pypi_version=<X> against the previous agent-assembly release content burns the version slot on npm + PyPI and ships stale content to users. See AAASM-3007 for the 2026-06-15 incident that motivated this SOP.

How to use

Invocation:

/release-tag-cut <X>

where <X> is the target version literal exactly as it appears in Cargo.toml and in the git tag (e.g. 0.0.1-alpha.10, NOT v0.0.1-alpha.10 — the leading v is added only at tag time).

Required context:

  • Run from the main agent-assembly/ working tree, not a worktree — tags are pushed from the main checkout per project convention.
  • remote is the configured remote pointing at ai-agent-assembly/agent-assembly (project convention — not origin).
  • The operator supplies <X>; the skill never invents a version number.

Pre-conditions

All MUST hold before any step runs; if any fails, stop and report — do not remediate from inside this skill. Full detail in REFERENCE.md → Pre-conditions.

  1. Working tree clean (git status --porcelain empty).
  2. On main, in sync with remote/main (fetch first; zero ahead/behind).
  3. Most recent CI run on main is green (gh run list --branch main …).
  4. Target version <X> provided — the skill does not invent or bump it.
  5. Security sign-off PASS for <X> — docs/release/security-signoff/v<X>.md exists and contains Verdict: PASS (stage 0, /release-security-gate <X>). scripts/release-readiness.sh check 11 enforces this.
  6. QA sign-off PASS for <X> — docs/release/qa-signoff/v<X>.md exists and contains Verdict: PASS (stage 0, /release-qa-gate <X> run in release depth per RUNBOOK section 1.6). scripts/release-readiness.sh check 12 enforces this independently of check 5/11 above — a security PASS never substitutes for a missing/non-PASS QA sign-off, in either direction. Verdict: CANDIDATE_VERIFIED (AAASM-6419) is not Verdict: PASS: the evidence checker exits 3 for it, so check 14, release-tag-guard.sh and release.yml's evidence gate all refuse. Stop and report the pending obligations; a SHA-specific owner approval is a separate decision this skill cannot grant.

Executable plan

Runs inside the main agent-assembly/ checkout. Substitute the operator-supplied <X> throughout. Per-step commands, edge-cases, and the no-op guard rationale are in REFERENCE.md → Executable plan.

  1. Verify the bump PR already landed on remote/main — per RUNBOOK section 1, the version/CHANGELOG/release-notes bump is its own separate, reviewed PR merged to main before this skill is invoked, so that when the QA/ security gates below capture their evidence, they capture it against the exact commit that will be tagged — not a commit this skill is still about to create. Confirm Cargo.toml workspace version is already <X>, CHANGELOG.md already has a ## [<X>] section, and docs/release/v<X>.md already exists. If any is missing, stop and point the operator at RUNBOOK section 1 — do not bump inline. (A prior version of this step bumped version/lockfile/notes as local commits inside this skill itself; that created commits remote/main never had, which made step 3's readiness check 3 — local main matches remote/main — fail by construction, and step 4's candidate-binding re-verification (AAASM-5998) would have nothing legitimate to bind against either. Removed for that reason: those checks require nothing to change locally between "bump merged" and "tag pushed.")
  2. Confirm the security and QA sign-offs are for this exact <X>, and that evidence has been finalized against that same commit — pre-conditions 5/6 above are the RUNBOOK section 1.5/1.6 gate; /release-evidence-finalize <X> (RUNBOOK section 1.7, AAASM-6001) is the separate step that generates and commits docs/release/qa-signoff/v<X>.evidence.json from those two sign-offs — this skill only ever reads that file, it never generates it. If it doesn't exist yet, stop and run /release-evidence-finalize <X> first, not inline here.
  3. Run the release gate — bash scripts/release-readiness.sh <X> from this exact commit. All 14 checks (mechanical version/CHANGELOG/notes state, secrets, stale tap PRs, security sign-off PASS, QA sign-off PASS, and release-evidence binding to HEAD) must report ✓. Any ✗ stops the run here — do not proceed to step 4, and do not skip a check to get to green.
  4. Create and push the annotated tag — bash scripts/release-tag-guard.sh <X>. This is the only sanctioned way this skill creates/pushes the tag: the guard re-verifies remote identity, clean tree, re-runs step 3's readiness gate, re-verifies candidate binding fresh against HEAD immediately before tagging (AAASM-5998 — the same R1/R1b rules the readiness gate's check 14 already ran, re-run as TOCTOU defense-in-depth), then additionally runs a narrower, version-scoped candidate/tag binding check (AAASM-6001 Option 4, Core ADR 0037 — --strict-tag-binding): candidate_sha may be an ancestor of HEAD only through commits that touch exclusively this version's own sign-off/evidence artifacts, nothing else. Refuses if the tag already exists, and has no skip flag. See release-tag-guard.sh. This triggers release.yml.

Post-conditions

After step 4, both MUST hold (full detail in REFERENCE.md → Post-conditions):

  1. Tag exists on remote — git ls-remote --tags remote "v<X>" returns one line.
  2. release.yml run is queued or in_progress for headBranch=v<X>.

Surface both confirmations, then point the operator at /release-validate-channels v<X> for the downstream channel matrix.

Reminder — advance the Jira Fix Version ladder

Cutting v<X> ships everything targeted at that version, so the next dev work needs a target. The release skills do not manage Jira versions, so after the cut remind the operator to, in Jira (project AAASM):

  1. Mark the just-cut version released (released:true + release date).
  2. Create the next Fix Version — for the agent-assembly core train and each affected repo/component train (python-sdk / node-sdk / go-sdk) that participates in this coordinated release — so their tickets have a target.

Use ticket-authoring's references/fix-versions.md for the exact REST create/release calls. This is a manual reminder: the Atlassian MCP has no version tool and version writes need a manage-versions token, so the operator (or a credentialed release job) does it. Automating this in release.yml is a separate follow-up, blocked on a CI manage-versions token.

What's auto-handled (do NOT manually run)

Once the tag is pushed, release.yml auto-runs GitHub Release creation, cargo publish for every crate, the Homebrew tap bump PR, the downstream SDK repository_dispatch fanout, and the FFI source-pin bump PRs. The operator MUST NOT replicate any of these by hand — see REFERENCE.md → What's auto-handled for the full list and rationale.

What this skill explicitly does not do

  • Open the bump PR (operator's job, per RUNBOOK section 1).
  • Merge the Homebrew tap PR (RUNBOOK section 4, operator-gated).
  • Re-trigger failed release-*.yml workflows (RUNBOOK section 6).
  • Cut an agent-assembly tag for an SDK-only hotfix (RUNBOOK section 7).
  • Touch repos other than ai-agent-assembly/agent-assembly.
  • Create or release Jira Fix Versions — it reminds the operator (see "advance the Jira Fix Version ladder"); the operator (or a credentialed release job) creates/releases them. The Atlassian MCP has no version tool.

Detailed references

One level deep from this SKILL.md:

  • Worked example (concrete alpha-10 walk-through) → EXAMPLES.md
  • Step-by-step detail (per-step commands, edge-cases, pre/post-conditions, auto-handled rationale) → REFERENCE.md
  • Bump-PR helper script (the version-bump + lockfile regenerator, for the separate RUNBOOK section 1 bump PR — no longer invoked by this skill's own executable plan, AAASM-5879) → scripts/release-tag-cut.sh (bundled inside this skill dir)
  • Release gate → scripts/release-readiness.sh (executable plan step 3)
  • Tag guard (the only sanctioned tag-create/push path) → scripts/release-tag-guard.sh (executable plan step 4)

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.