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
In this repository21 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- adr-governanceSkill
- credential-operationsSkill
- documentation-experienceSkill
- engineering-loopSkill
- governance-doctorSkill
- homebrew-tap-mergeSkill
- jira-deliverySkill
- product-validationSkill
- public-release-reconcileSkill
- release-assuranceSkill
- release-docs-syncSkill
- release-evidence-finalizeSkill
- release-qa-gateSkill
- release-security-gateSkill
- release-validate-channelsSkill
- repo-bootstrapSkill
- repo-scaffoldSkill
- rust-developmentSkill
- shell-developmentSkill
- terraform-developmentSkill
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
- Very specific: line 96
After this skill ends (git push remote v<X>), agent-assembly's release.yml will publish the GitHub Release and fire two automation jobs:
- Very specific: line 125
Run from the main agent-assembly/ working tree, not a worktree — tags are pushed from the main checkout per project convention.
- Distinctive: line 133
All MUST hold before any step runs.
- Very specific: line 185
If it doesn't exist yet, stop and run /release-evidence-finalize <X> first, not inline here.
- Distinctive: line 209
After step 4, both MUST hold (full detail in REFERENCE.md → Post-conditions):
- Very specific: line 229
Use ticket-authoring's references/fix-versions.md for the exact REST create/release calls.
- Distinctive: line 240
MUST NOT replicate any of these by hand — see REFERENCE.md → What's auto-handled for the full list and rationale.
- Distinctive: line 251
Create or release Jira Fix Versions — it reminds the operator (see "advance the Jira Fix Version ladder").
≈ “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.
Files
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:
/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 underdocs/release/security-signoff/. The gate wraps the built-in/security-reviewscanner (and, at major tier, theanthropics/claude-code-security-reviewAction). A BLOCK verdict (or any unaddressed High/Critical) stops the release before this skill runs;scripts/release-readiness.shcheck 11 enforces it. Seerelease-security-gate/SKILL.md.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 momentgit push remote v<X>firesrelease.yml.- fan-out (automatic, owned by
release.yml) — the pushed tag triggers GitHub Release + cosign signing,cargo publishof the workspace,notify-downstreamrepository_dispatchto node-sdk + python-sdk, theupdate-{node,python,go}-sdk-ffi-pinauto-bump PRs, and theupdate-homebrew-tapbot PR. The operator runs none of these by hand. /release-validate-channels v<X>(read-only) — oncerelease.ymlis green, confirm every channel actually caught up. Emits a green/red matrix./homebrew-tap-merge <PR>(write, on the tap repo) — verify the bot's sha256s against the releaseSHA256SUMSand merge the tap PR sobrew install aasmserves 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 oncerelease.ymlfinishes.
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.3after0.0.1-beta.2; the same path served the earlier0.0.1-alpha.Ncuts). - The most recent CI run on
mainis 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
mainis up to date withremote/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-releasein the target SDK repo. Cutting anagent-assemblytag 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/-rcsuffix) — 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
mainis dirty, behindremote/main, or has a red CI run, stop and surface the gap to the operator. - No PASS security sign-off for
<X>— ifdocs/release/security-signoff/v<X>.mdis missing or its verdict is notPASS, 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>— ifdocs/release/qa-signoff/v<X>.mdis missing or its verdict is notPASS, stop. Run/release-qa-gate <X>inreleasedepth 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_dispatchso node-sdk and python-sdk knowaasm-*binaries are downloadable (AAASM-2336).update-{node|python|go}-sdk-ffi-pin— opens an auto-bump PR on each SDK that aligns theaa-sdk-clientgit-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:
- agent-assembly's
Releaseworkflow has reached thenotify-downstreamstep. - The auto-bump PR (
bot/aa-ffi-pin-v<X>) has been opened on each SDK repo. - 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. remoteis the configured remote pointing atai-agent-assembly/agent-assembly(project convention — notorigin).- 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.
- Working tree clean (
git status --porcelainempty). - On
main, in sync withremote/main(fetch first; zero ahead/behind). - Most recent CI run on main is green (
gh run list --branch main …). - Target version
<X>provided — the skill does not invent or bump it. - Security sign-off PASS for
<X>—docs/release/security-signoff/v<X>.mdexists and containsVerdict: PASS(stage 0,/release-security-gate <X>).scripts/release-readiness.shcheck 11 enforces this. - QA sign-off PASS for
<X>—docs/release/qa-signoff/v<X>.mdexists and containsVerdict: PASS(stage 0,/release-qa-gate <X>run inreleasedepth per RUNBOOK section 1.6).scripts/release-readiness.shcheck 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 notVerdict: PASS: the evidence checker exits 3 for it, so check 14,release-tag-guard.shandrelease.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.
- 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 tomainbefore 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. ConfirmCargo.tomlworkspace version is already<X>,CHANGELOG.mdalready has a## [<X>]section, anddocs/release/v<X>.mdalready 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 commitsremote/mainnever had, which made step 3's readiness check 3 — localmainmatchesremote/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.") - 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 commitsdocs/release/qa-signoff/v<X>.evidence.jsonfrom 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. - 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. - 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 againstHEADimmediately 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_shamay be an ancestor ofHEADonly 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. Seerelease-tag-guard.sh. This triggersrelease.yml.
Post-conditions
After step 4, both MUST hold (full detail in REFERENCE.md → Post-conditions):
- Tag exists on remote —
git ls-remote --tags remote "v<X>"returns one line. release.ymlrun isqueuedorin_progressforheadBranch=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):
- Mark the just-cut version released (
released:true+ release date). - Create the next Fix Version — for the
agent-assemblycore 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-*.ymlworkflows (RUNBOOK section 6). - Cut an
agent-assemblytag 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)
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.

