Cut a Release
The release lane belongs to your project, not only to codeArbiter maintainers. It reads
.codearbiter/release-targets.md for target names, tag prefixes, version policy, manifests,
changelog, payload and optional qualification/build declarations. It does not contain an
implicit list of codeArbiter plugins that every consumer must use.
| Host | Example explicit entry |
|---|---|
Claude Code | /ca:release --dry-run app |
Codex | $ca-release --dry-run app |
Pi | /ca-release --dry-run app |
app is an illustrative target name. Use your declaration’s actual name. You can also describe
the release intent naturally; the same target and authorization requirements apply.
Trace the release workflow from entry to its actual endpoint
Follow the work, not a catalog
Prepare a release through a reviewed PR
Real release path, not --dry-run. Preparation stops at a release PR. Tag composition belongs to a qualified hosted publisher after merge and exact-head CI, never the interactive checkout.
Rows identify roles. Gold commands enter or define a procedure; blue skills coordinate work; green agents perform bounded roles. Arrows cross rows in execution order. A dashed arrow reuses a procedure rather than calling its entry again. Dashed nodes are conditional roles selected for the work.
Chapter 1 / 4
Resolve and derive
Which target and version are actually eligible?
Link to this chapter- command
/ca:release: select the declared target
Use the sole declared target or name the intended one. An unknown or ambiguous selection stops rather than choosing a familiar plugin or version.
Result: One explicit target and the real versus dry-run mode.
declared owner → The command routes to the reusable release skill.
Source for step 1 - skill
release: pre-flight and target resolution
Resolve project and shell context, the declared row, clean non-default branch, current verification and relevant questions. A missing declaration uses confirmed back-fill, not a guessed row.
Result: A target with its preconditions and verification scope.
target scoped → Sibling target history must not bump this target.
Source for step 2 - skill
release: version derivation
Classify only the target’s payload window. Derive through its declared policy using compatible tags and manifests; required changelog notes come from actual commit evidence.
Result: The derived version, rationale and target-scoped notes.
Source for step 3
Before continuing: A resolved target, target-scoped history and a derived identity. Missing declarations or required notes are explicit stops or governed back-fill.
Continuations, returns and repeat paths
- real run only. Dry run stops before modifying surfaces. Next: release: declared manifests and changelog. Owning contract
Chapter 2 / 4
Prepare the release PR
What is reviewed before a tag can exist?
Link to this chapter- skill
release: declared manifests and changelog
Update only declared surfaces and run the post-bump pre-tag checks. Report exact asset names and the hosted qualification path without executing release-build locally.
Result: The intended diff and declaration, not a local publication payload.
gated persistence → Commit release edits through the existing gate.
Source for step 4 - skill
commit-gate: release changes
Commit the release edits through the existing permission, selected-file and evidence gate. A tag names a commit, never outstanding working-tree changes.
Result: Committed release changes and current gate results.
mandatory PR → The release branch must use the PR route and stop this invocation.
Source for step 5 - command
Ordinary PR procedure
Route the committed branch through the ordinary PR path. The release skill stops here instead of composing a tag on this branch.
Result: A reviewable release request with the publisher and intended cohort disclosed.
review before merge → Apply the ordinary PR reviewer and merge requirements.
Source for step 6 - agent
Applicable PR review and owner decision
Run the path-selected review and current-head checks. The owner decides whether to merge. The PR’s own head is not the later hosted publication identity.
Result: A reviewed release PR; merge remains explicit.
Source for step 7
Before continuing: The release PR describes committed surfaces, exact declared asset names and their reviewed hosted qualification path. Stop this invocation: no tag composition before merge.
Continuations, returns and repeat paths
- after owner merge. Only the actual merged, green default-branch candidate may enter the qualifying hosted publisher. Next: release: bind the hosted candidate. Owning contract
Chapter 3 / 4
Qualify the merged candidate
Which environment can compose the tag?
Link to this chapter- skill
release: bind the hosted candidate
After the release PR merges, a fresh hosted checkout must equal the fetched default branch and satisfy exact-head checks. Bind the current release section and every declared manifest.
Result: The merged candidate identity, not the earlier PR head.
qualified cohort → The exact merged candidate owns the package evidence.
Source for step 8 - skill
release: exact hosted inventory
The reviewed publisher either builds the declared assets or verifies a retained exact-head CI cohort. Local scratch files do not cross the PR boundary as publication input.
Result: The declared inventory and candidate-bound evidence, when assets are declared.
before publication → The qualifying hosted publisher owns tag composition; the interactive agent does not run it locally.
Source for step 9 - skill
release: hosted annotated tag
Classify the observed tag/release state, compose only when appropriate, and verify the stored tag message. An already-published identity is not replaced.
Result: An annotated tag in the isolated hosted checkout and a report; nothing yet pushed.
Source for step 10
Before continuing: A qualified hosted publisher identifies the exact fetched default-branch commit and green evidence. Missing capability, stale surfaces or asset mismatch stops publication.
Continuations, returns and repeat paths
- one-cohort authority. Consume explicit publisher authorization, including the narrowly defined prior release-PR merge instruction where applicable. Next: release: consume explicit authorization. Owning contract
Chapter 4 / 4
Authorize, publish and retain proof
What is public, and what still needs a record?
Link to this chapter- skill
release: consume explicit authorization
Only the declared publisher consumes the applicable one-cohort permission. An explicit merge instruction after the release-PR report can supply it for that protected publisher; CI success alone cannot.
Result: An authorized push and release creation for the identified cohort.
verify the remote → A successful command alone is not proof of the remote inventory.
Source for step 11 - skill
release: inspect remote identities and assets
Read back the annotated tag, dereferenced commit, non-draft release and exact asset names. Preserve partial failure evidence instead of recreating published identities.
Result: The observed publication result, not merely an upload attempt.
retain original evidence → Capture the original publication identity before disposing of positively identified scratch state.
Source for step 12 - skill
release: retain the original receipt
If declared, capture the original remote provenance and hand off a non-default-branch receipt PR. Closeout remains pending until that PR merges. With no declared manifest, say explicitly that this step is skipped.
Result: Published release plus an explicit completed or pending provenance boundary.
Source for step 13
Before continuing: Read back exact publication before cleanup. When a provenance manifest is declared, close its receipt through a separate PR rather than editing the hosted default branch.
Continuations, returns and repeat paths
An exact published tag and declared asset inventory after authorization and read-back. When provenance is declared, retain the original receipt and merge its separate closeout PR; publication alone does not finish that record.
Open the full three-row diagram.
Where the targets come from
Section titled “Where the targets come from”A single-application repository might have this declaration, only when these files and this payload really describe that repository:
<!-- release-targets -->[app]prefix: vmanifest: package.jsonchangelog: CHANGELOG.mdpayload: .latest-eligible: true<!-- /release-targets -->Do not paste the example into a different package manager or monorepo. Context creation can derive a declaration from sufficient source evidence. If no declaration exists, the release lane’s back-fill proposes one and waits for explicit confirmation before writing. Ambiguity is a question, not a guessed row. Greenfield decomposition records release intent before manifests exist; it does not invent a release-target row in advance.
With exactly one target, a bare release selects that target. With multiple targets, name one.
An unknown or ambiguous target stops rather than selecting ca or the nearest Git tag.
Current release-note version grammar
Section titled “Current release-note version grammar”The release-note helpers accept plain final MAJOR.MINOR.PATCH versions under the default
semver policy. A declared numeric-sequence policy accepts canonical dotted numeric versions
with the component count set by initial-version. Release headings must use ## [VERSION] ...
or ## vVERSION .... Prerelease and build-metadata headings are refused, never prefix-matched
as a final version. This is not full SemVer heading support.
At most one Unreleased section may precede the released sections. Duplicate target headings,
malformed version-shaped headings and an Unreleased section after a release stop extraction.
Publication reconstructs notes from the tagged commit’s regular-file changelog blob; a dirty
working copy cannot replace those bytes.
Full prerelease and build-metadata heading support remains deferred follow-up work. Documenting the current strict behavior does not satisfy that requirement.
Prerequisites
Section titled “Prerequisites”Confirm the current repository root, non-default branch and clean working tree. Inspect the
selected target’s payload changes since its own last compatible release, current verification,
unresolved questions and required CHANGELOG: footers. Use the declared version policy rather
than assigning a desired version by hand. Publication additionally needs the relevant remote
permissions, a reviewed qualifying hosted publisher and explicit authorization. The release
preparation must merge through a PR before tag composition. Missing publisher capability is a
stop to address in a separate reviewed change, not permission for a local tag fallback.
Do not change commit history merely to silence a footer or version error. Preserve the failure and correct it through the project’s governed development procedure.
1. Target-scoped pre-flight
Section titled “1. Target-scoped pre-flight”Start with a read-only preview:
/ca:release --dry-run appThe dry run performs only the read-only, locally evaluable pre-flight and version derivation:
target resolution, current local history, classification and required footer checks. It reports
the selected row, derived version, rationale and locally detectable blockers. It does not run
git fetch, commit-gate, the declared suite, artifact rebuilds or post-bump pre-tag checks.
It does not edit manifests or changelog, create assets, compose a tag or publish. Declared commands
are listed, not executed. Remote freshness and the unexecuted checks remain unverified.
A clean dry run is not proof that the later build or publication will succeed.
Review the report: is the target correct, does the payload exclude siblings, and does the version
change follow the declared policy? For example, a feat change in a SemVer target can justify a
minor increment; this illustrative classification is not a version to force onto your project.
2. Derive the version and changelog
Section titled “2. Derive the version and changelog”When the preview and prerequisites are satisfactory, invoke the same target without --dry-run:
/ca:release appThis is a mutating lane. It derives the version from the target’s declared policy, compatible tags, manifest values and scoped commit history. It updates the declared manifests and changelog and runs the declared pre-tag checks at the appropriate post-update state. Required release notes must come from actual commit evidence; missing footers are not invented.
Inspect the resulting diff and checks. Changes pass through the normal commit gate. The absence of a sibling’s change from this target’s changelog is deliberate when that sibling is outside the selected payload.
Report the exact declared asset names and their reviewed hosted build or retained-cohort path. Do not turn a local build into publication input. Route the committed changes through the ordinary PR procedure, report the intended publisher and STOP this invocation. The release PR must merge before the hosted tag phase can begin.
3. Compose the local tag
Section titled “3. Compose the local tag”“Local” here means inside the qualifying hosted publisher’s isolated checkout, not your interactive repository. This phase starts only after the release PR merges. The hosted checkout must equal the fetched default-branch revision, carry the current release-surface changes, and have green exact-head evidence before the publisher’s write job can proceed. The PR head and a previous green commit are not substitutes for that merged identity.
The publisher qualifies declared assets through its reviewed build path or a retained exact-head cohort with provenance-bound packages. It confirms declared filenames, candidate source and manifest versions before composing the annotated tag in the selected namespace. Arbitrary build failures, changed tracked files, mismatched provenance and unexpected inventory are stops.
A tag in that checkout is still not publication. A matching tag whose publication is incomplete can be a resume case; do not invent another identity or re-create a published tag merely because a session or job ended.
4. Review and authorize publication
Section titled “4. Review and authorize publication”Read the selected target, derived version, tag identity, exact changelog section, verified asset inventory and intended destination. Publication needs explicit, cohort-specific authority. For a declared protected automatic post-CI publisher, an explicit instruction to merge or complete the already-reported release PR, given after its report and before merge, supplies that one cohort’s publication permission. Do not require the same approval a second time. This exception does not authorize a later cohort, a rebuilt candidate or publication merely because CI is green. In other paths, follow the explicit publication handoff. Requirements approval or sprint autonomy is not blanket release permission.
After publication, inspect the remote tag and dereferenced commit, non-draft release metadata,
asset names and available provenance. Require the published inventory to match the declared,
qualified inventory. The target’s latest-eligible policy controls eligibility for the
repository-wide Latest label; do not infer it from which tag was created most recently.
When the target declares a provenance manifest, retain the original remote tag receipt and hand it off in a separate receipt PR from a non-default branch. Publication can be live while that closeout remains pending; a branch-local ledger append does not finish it. Do not write into the hosted default-branch checkout or recapture a new identity to replace a missing original receipt. When no manifest is declared, report that this step is skipped. Preserve scratch evidence on partial failure; clean up only positively identified run-owned files after the required read-back.
Common stops
Section titled “Common stops”| Stop | What to inspect | Next safe action |
|---|---|---|
Unknown or ambiguous target | Your declared target rows | Select the exact intended row or complete the confirmed back-fill |
No version-earning change | The selected payload window and declared policy | Do not manufacture a release just to obtain a tag |
Version or footer mismatch | Actual manifests, compatible tags and commit evidence | Correct the source through the governed path, then rerun the preview |
Qualification or inventory mismatch | Exact-head build/provenance and declared names | Preserve the failure; do not upload an arbitrary local substitute |
Partial publication | Existing local/remote tag, release and assets | Read back exact state and resume the missing step without replacing published identities |
Recover from a bad published release
Section titled “Recover from a bad published release”Preserve published tag identity. Fix the defect through a new reviewed change and publish the next policy-derived version. Explain which release supersedes the bad one through the normal release metadata process. Never move, retarget or delete a published tag to make old evidence describe new bytes.
codeArbiter’s own declared targets
Section titled “codeArbiter’s own declared targets”codeArbiter itself is a multi-target example. Its declared target file is maintainer configuration, not a universal target list. Keep consumer guidance separate from those plugin-specific packaging and publication recipes.
The exact release command and release skill own the detailed contract. Confirm that your installed adapter supports the documented source capability before relying on it.