Release-management skill family

Scope — organization: ASF · 🪶 ASF-specific. This family encodes Apache Software Foundation processes (the 14-step release lifecycle) and assumes an ASF adopter profile by default. Non-ASF projects can still adopt it through the adapter/config layer, but it carries ASF assumptions the generic families do not.

End-to-end automation for an ASF project’s release lifecycle, from the planning issue and version bump through to [ANNOUNCE] on announce@apache.org, archive sweep, and the per-release audit log. Ten skills that compose into the canonical 14-step process documented in process.md.

Why a framework skill family? Every ASF project runs essentially the same release process: version bump, KEYS reconciliation, RC signed with the Release Manager’s key, staged to dist/apache.org/repos/dist/dev/<project>/, voted on dev@ per release-policy.html § release approval, promoted to dist/release/<project>/, announced on announce@apache.org per release-policy.html § announcements, and archived past retention per release-distribution. The procedural shape is foundation-wide; the project-specific content (release-train identity, build invocation, KEYS file path, vote-window length, retention rule, audit-log location) plugs in through <project-config>/ just like the security family.

Non-ASF adopters are first-class adopters of this family, not a follow-up case. The 14-step lifecycle is described in ASF terminology because the framework’s first pilot is an ASF PMC, but every step that touches an ASF-specific surface is implemented as a backend call the adopter selects in release-management-config.md. Three dimensions parametrise the lifecycle, with no ASF assumption baked into the install path:

Distribution backend (release_dist_backend): svnpubsub (ASF), github-releases, s3, self-hosted.
Approval mechanism (release_approval_mechanism): dev-list-vote (ASF), github-discussion, pr-approval, maintainer-roster.
Announcement backend (release_announce_backend): announce-list (ASF), github-release-notes, site-post, discord-channel.

The 14 steps stay identical across backends; only the command set the agent emits changes. The state-change boundaries (Agentic Drafting vs Agentic Triage; agent never holds the signing key; agent never publishes) stay identical too. See process.md § Adopter backends for the full backend table and per-step mapping.

Install & first runs

Install just this family — one plugin, 10 skills. The 14-step ASF release lifecycle. The agent never holds your signing key.

Once you have added the marketplace:

/plugin install magpie-release-management@apache-magpie

New to Magpie? The quick start walks the whole path in one place — install, the first /magpie-setup run, and a recording of it happening — plus the other agents and the secure-isolation setup to run next.

Before the first run

An animated /magpie-setup config run for the release-management family: the check failing, the values derived from the repository, one question for the rest, and gitignored files written

Illustrative — the real run derives more and asks better. What is true is the shape: it runs itself, it writes only gitignored files, and it stages nothing.

Every skill here resolves project-specific values from the adopter’s <project-config>/ directory — which is .apache-magpie-local/ (gitignored, yours) first, then .apache-magpie-overrides/ (committed, the project’s).

For yourself: /magpie-setup config scaffolds and fills these locally. Nothing is staged, nothing is committed, and it works on a repository that has never adopted Magpie.

For the project: /magpie-setup adopt commits them for every contributor, either scaffolded directly or promoted from what you configured locally.

Required. Without these a skill would act on a guess, so it stops and says which file is missing.

File	What it carries	Read by
`pmc-roster.md`	Who is binding. Read wherever a vote is counted or a PMC-only action is gated.	`promote`, `vote-tally`
`release-build.md`	How this project builds and signs artefacts: reproducible source-archive recipe (`git archive` + `.gitattributes`), build command, the project’s optional convenience artefacts (each with its own build, staging, reproducibility mode, vote scope and publish channel), artefact names, checksum algorithm, optional reproducibility checks.	`rc-cut`, `verify-rc`
`release-management-config.md`	Vote window and pass rule, distribution backend and paths, announce/vote list addresses, retention rule.	`announce-draft`, `archive-sweep`, `audit-report`, `keys-sync`, `prepare`, `promote`, `rc-cut`, `verify-rc`, `vote-draft`, `vote-tally`
`release-trains.md`	Active release branches, release-manager attribution per cut, rotation rosters, security-team roster.	`archive-sweep`, `prepare`

Optional. Each has a documented fallback; absent, the skill still runs.

File	What it carries	Read by
`canned-responses.md`	Reusable reporter-facing reply templates.	`announce-draft`, `vote-draft`

Try these first

Illustrative shapes, not real transcripts — your output will differ. Nothing below sends, merges, or posts anything without you confirming it.

Open the release plan.

/magpie-release-management:prepare

A prepare run that drafted a planning issue and a version-bump PR for 1.4.0 and filed neither

Check an RC before you vote.

/magpie-release-management:verify-rc

A verify-rc run: five green checks across signatures, checksums, licence headers, NOTICE and prohibited binaries, one warning about a stale version string, and a PASS WITH WARNINGS verdict

Tally the vote thread.

/magpie-release-management:vote-tally

A vote-tally run counting three binding +1s and no -1s, and drafting the RESULT email without sending it

Status

Experimental — all 10 skills shipped. The family is feature-complete; every skill landed as experimental with an eval suite:

Skill	PR	Step(s)
`release-prepare`	#540	1, 2, 14
`release-keys-sync`	#541	3
`release-rc-cut`	#543	4, 5
`release-verify-rc`	#537	6
`release-vote-draft`	#582	7
`release-vote-tally`	#533	9
`release-promote`	#544	10
`release-announce-draft`	#512	11
`release-archive-sweep`	#551	12
`release-audit-report`	#552	13

Every skill is flagged experimental and tracked in docs/modes.md.

The family landed as docs first (this README, the 14-step process.md, the per-skill spec.md, and the adopter scaffold projects/_template/release-management-config.md) so the lifecycle, the state-change boundaries, and the adopter contract are reviewable independently from runtime behaviour. This pattern matches Mentoring.

Promotion of any skill in this family from experimental to default-on, or from Agentic Drafting to a state-changing lane, requires evidence sourced from Release Managers and binding voters that the project’s release process is healthier (fewer stalled RCs, shorter time-to-[ANNOUNCE], fewer reverted promotions), not throughput numbers alone. The evidence window is set by adopter governance, not by this family.

See MISSION.md § Initial Goals for the commitment to cut a first Apache release through the standard process within 3 months of resolution adoption; this family operationalises it.

Skills

The skill table below names each release-* skill, its mode, and the lifecycle step(s) it owns. Read spec.md for the per-skill state-change boundary; read process.md for the step it executes against.

Skill	Mode	Steps owned	Status	Purpose
`release-prepare`	Agentic Drafting	1, 2, 14	experimental	Open the planning issue, draft the version-bump + changelog + NOTICE/LICENSE PR, then draft the post-release `-SNAPSHOT` bump.
`release-keys-sync`	Agentic Drafting	3	experimental	Draft the `KEYS` diff for a Release Manager cutting their first release for the project. Agent never holds the private key.
`release-rc-cut`	Agentic Drafting	4, 5	experimental	Emit the paste-ready command sequence, signed tag, build, detached signatures, checksums, `svn` import to `dist/dev/<project>/`. Agent never signs and never imports.
`release-verify-rc`	Agentic Triage / Agentic Pairing	6	experimental	Read-only pre-flight: signatures against the project’s `KEYS`, checksums, license headers (Apache RAT), NOTICE/LICENSE presence, no prohibited binaries, version-string consistency. Voters can run it in their own dev loop before posting `+1`.
`release-vote-draft`	Agentic Drafting	7	experimental	Draft the `[VOTE]` email body to `dev@<project>`. Agent never sends.
`release-vote-tally`	Agentic Triage	9	experimental	Parse the vote thread, classify each reply (+1 / 0 / -1) binding vs non-binding against the PMC roster, propose `[RESULT] [VOTE]`. Conservative on ambiguous votes, refuses to count, flags `AMBIGUOUS, needs RM call`.
`release-promote`	Agentic Drafting	10	experimental	Emit the paste-ready `svn mv dist/dev → dist/release` command set plus commit message. Agent never moves; the human commit is the act of release.
`release-announce-draft`	Agentic Drafting	11	experimental	Draft the `[ANNOUNCE]` email body to `announce@apache.org` and the site-bump PR (download page, release notes, version banner). Agent never sends mail and never merges the site PR.
`release-archive-sweep`	Agentic Triage	12	experimental	Scan the distribution area, identify releases past retention, propose the backend-shaped archival step — the `svn mv` sequence under `svnpubsub`, or archiving in ATR (which removes the files from `dist/release` itself) under `atr`. Agent never archives.
`release-audit-report`	Agentic Triage (dashboard)	13	experimental	Read-only structured report per release, RM, voters with binding flags, artefacts with sigs and checksums, promotion revision, `[ANNOUNCE]` archive URL. Output appended to the project’s audit log.

Two non-negotiable boundaries cross every Agentic Drafting skill above:

The agent never holds, invokes, or proxies the Release Manager’s private signing key. Steps 3, 4, 10 emit paste-ready recipes; the RM runs every signing or svn commit operation as themselves. This mirrors security-cve-allocate (Vulnogram URL + paste-ready JSON, human submits) and satisfies RFC-AI-0004 Principle 1.
The agent never publishes the release. Steps 10 (svn mv dist/dev → dist/release) and 11 ([ANNOUNCE] send, site bump merge) are the moments of release; the agent drafts artefacts, the RM and the PMC execute and merge.

Deep documentation

process.md, the 14-step lifecycle with Mermaid flowchart + per-step description; the label-lifecycle state diagram + label reference table. The authoritative process reference.
spec.md, per-skill scope, state-change boundary, hand-off protocol, adopter knobs. The contract the future skill implementations must satisfy.
svn-release-runbook.md, the hands-on copy-paste command sequence for the svnpubsub backend: package a tagged revision as a signed source .zip with SHA-512 and stage it to dist/dev/ (lifecycle Steps 4–5). The longhand companion to release-rc-cut.
atr-release-runbook.md, the counterpart runbook for the atr (Apache Trusted Releases) backend: compose a signed candidate in ATR, let the platform run the policy checks and drive the [VOTE], then finish to publish and announce. Same 14-step lifecycle and same skills as the svnpubsub runbook; ATR replaces the mechanics of Steps 5–11. ATR is in beta and is Magpie’s release backend — start here.
manual-release-process.md, the concrete as-executed record of the 0.1.0 release on the now-retired hybrid backend (release_dist_backend = svnpubsub + release_vote_backend = atr): the exact command sequence run, the real URLs, and the rc1/rc2 rough edges. Kept as history — the hybrid was retired in #1182 — not as the procedure to follow.

Two documents that do not ship in this family but are referenced from it:

<project-config>/release-trains.md , release-train identity (already present in the adopter scaffold for security use; release-management reuses it).
<project-config>/release-management-config.md , the family’s adopter contract (new in this PR).

Mode mapping

Release-management is a family, not a mode. The lifecycle spans the existing Agentic Triage and Agentic Drafting modes; no new mode is introduced. See docs/modes.md for the family-by-mode breakdown; release-* skills appear under the Agentic Triage and Agentic Drafting subsections (all ten skills are now experimental; the family is feature-complete).

The family’s read-only dashboard skill (release-audit-report) sits in Agentic Triage because it classifies and reports against existing state, not because it routes inbound work. The docs/modes.md § Meta section is reserved for framework infrastructure (setup-*, issue-reassess-stats, isolation tooling) and the audit skill does not belong there, it is project-facing maintainership work.

Cross-references

process.md, spec.md, within this family.
MISSION.md § Initial Goals, the standard-release commitment this family operationalises.
docs/modes.md, the mode taxonomy each skill in this family inhabits.
docs/security/README.md, the precedent for a multi-skill ASF-process family with shared state-change-boundary discipline.
docs/mentoring/README.md, the precedent for spec-before-code on a proposed family.
ASF release policy, ASF release distribution, ASF release signing, ASF licensing-howto, Apache RAT, the canonical foundation references the lifecycle is anchored to.