| name | release-orchestration |
| description | Top-level orchestrator for a release. Sequences three phases — source-stabilization → version-bump → npm-otp-publish — maintains the release control-plane state artifact across them, and routes on each phase's outcome (advance / repeat / return to an earlier phase / terminate). It holds NO release policy: every command name, gate definition, required field, and prohibition is owned by the project's publish rule and is pointed at, never restated. Use when running a release, a release-level merge, a version bump, or a publish. |
Release Orchestration — pipeline only
The state machine for a release. This skill owns ordering and routing between phases and nothing else.
It does not define what a gate is, what the state artifact must contain, which publish command is allowed,
or when to stop — those are invariants owned by the rules below, and restating them here would create a
second copy that drifts.
Where the procedure needs a concrete command, script, artifact path, or branch name, it points at the
rule that owns it. The only names used literally are the pipeline's own structure: the phase skills and
the agents it dispatches.
Rule Anchor
AGENTS.md > "Rules and Skills Boundary" — skills are procedure; rules win on conflict.- publish.md — the release runbook's invariants: "Release Control Plane"
(required state fields), "Release-Run Artifact" (the state artifact and its entry points),
"Release State Machine" (phase order and its per-step constraints), "CI Failure Triage" (the triage-note
contract), "Long-Running Gates", "Dist Artifact Invariant", "Publish Boundary", "Stop Conditions".
- git-branch.md — branch policy, merge approval, merge landing verification.
- enforcement-architecture.md — orchestrator / worker / guardian.
Preconditions (refuse to start otherwise)
- The release target is explicit: a source branch, a target version, and the user's intent to release.
- The working tree is clean of anything unrelated to this release (a Stop Condition in the rule).
- The release-run state artifact exists for the target version, created through the entry point the rule
names, and reflects the current SHA and branch.
If any precondition fails → terminate and report which one. Do not open the pipeline "provisionally":
the rule forbids beginning gate-sensitive work while the release state is unclear.
State-artifact duty (runs at every transition, not as a step)
Before entering a phase, when a phase's gate status changes, and immediately after any terminate edge
fires, update the release-run artifact so it names the active gate, the next action, and the stop
condition for the phase now running. This is a continuous duty of this orchestrator, not a numbered step
any phase owns. The artifact's required fields and its update entry points belong to
publish.md — read them there.
Phases and routing
| # | Phase | Advance when | On failure |
|---|
| 1 | source-stabilization | the source branch has landed on the release target, verified as landed | route per the phase's own edges; it escalates to here |
| 2 | version-bump | the bump has landed on the release target, verified as landed | route per the phase's own edges |
| 3 | npm-otp-publish | every in-scope package is published at the target version | route per the phase's own edges |
Each phase returns one of four outcomes. This orchestrator routes on the outcome and forms no verdict of
its own:
| Phase outcome | Route |
|---|
COMPLETE | Advance to the next phase. After phase 3, go to Close-out. |
RETRY | Re-run the same phase. Bounded: at most 2 re-runs of any one phase per release. On the third, terminate and hand to the user with the phase's own report. |
REGRESSED | Return to phase 1. A later phase discovering the source is no longer green (a new merge landed, the base diverged) invalidates stabilization; do not patch forward from inside a later phase. |
HALT | Terminate. Report the release state, the failing gate, and the stop condition that fired. Do not continue to a later phase, and never skip a phase to recover. |
Additional edges that belong to this level:
- A Stop Condition in publish.md becomes true at any point →
HALT
immediately, whichever phase is running. Each condition listed there is a terminate edge of this
pipeline; they are not restated here.
- The user interrupts the turn → terminate any observation loop a phase left running (the rule's
watcher-cleanup invariant), record the interrupted state in the artifact, and stop.
- A process defect is discovered mid-release → do not fold the fix into the release. Record it and
continue, unless it directly blocks the currently active gate — in which case treat it as that phase's
failure and take the phase's own edge.
Close-out
After phase 3 reports COMPLETE:
- Update the artifact to its terminal state and clear any watcher it recorded.
- Generate the final release report through the entry point publish.md names.
Its required contents are that rule's contract — do not compose an ad-hoc summary instead.
- Report the outcome to the user. The pipeline ends here; it does not start another release.
What This Skill Does NOT Do
| Not this skill's job | Owner |
|---|
| Decide why a check is red | ci-failure-triager (agent) |
| Decide whether a merge truly landed | merge-verifier (agent) |
| Sequence the steps inside a phase | that phase's own skill |
| Define gates, required fields, allowed commands | publish.md |
| Choose the version or author changesets | version-management |
| Merge the release target | the user (release-level merge needs explicit approval) |
If you find yourself judging a failure, defining a gate, or running a phase's internal steps here, stop —
route to the owner instead.
