Instructions

the scheme

MAJOR.MINOR.PATCH, stored in the repo and moved by a person:

• main is the integration trunk and reaches no user, because the marketplace ref is production
• a merge to production is the release, and the bumped version is what fires /plugin update
• PATCH is the default, since most releases here are fixes to skills that already shipped
• MINOR is new work a user would notice, and MAJOR is a break in how a skill is invoked
• the commit count is no longer a version field; git log answers that question better

the four files

one version said four times, and every one of them ships inside the same install:

• plugins/operator/.claude-plugin/plugin.json
• plugins/gitgud/.claude-plugin/plugin.json
• plugins/retardify/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json, its own top-level field, never a per-plugin entry

plugin.json outranks a marketplace entry's version, so a drifted pair resolves silently to the manifest. A value read only when it agrees is worse than an absent one, which is why no entry carries the field. The install a user gets is one directory, so all four move together or none do.

the branches

production has to stay a fast-forward of the trunk, and the sidecar refuses when it is not:

• a commit landing on production directly ends every later merge --ff-only
• a trunk rule requiring a pull request rejects the bump push, so the sidecar reads that rule first
• under that rule the bump branches before it commits, and the tag waits for the merged sha
• so the bump is authored on the trunk, before the promotion, never by a workflow reacting to it
• nothing is deployed by the push; users pull, so the promotion IS the release
• the release notes generate from the commits, which is why no CHANGELOG is written here

the run

• --check is the read-only gate: the four files agree and every value parses as semver
• --quick is that same gate under the name every other ci sidecar answers to
• --strict promotes the warning tier to a failure; a plugin the marketplace never lists is one
• IF --quick, STOP after the inline report; audit_file: none confirms it, and nothing is appended
• ci runs that flag and nothing else, since it is pure, reaches no network, and writes nothing
• a bare run means --patch; --minor and --major differ only in the number they compute
• the write is a sed on the version line, so every hand-formatted object survives it
• the commit, the tag, both pushes, the ff-merge and the release call are emitted, never run
• trunk gate in the telemetry says which sequence you got: direct or pull request required

the artifact

append one entry to [audit_file], in the shape under ## the entry below:

• the heading reads ## Release Audit #[next_audit]: [timestamp], both taken from the telemetry
• state is the repo, the branches, the version move and the trunk gate, one clause each
• files is the FILE/WAS/NOW table the sidecar printed, as a markdown table
• handover is the emitted sequence, fenced as bash and copied verbatim from the terminal
• copy the handover rather than retyping it, since a retyped step is a step that can drift
• CREATE the file first if it does not exist, with # <audit_file> as its only line
• --check returns before the telemetry, so that mode names no artifact and writes none

the entry

the artifact this skill appends to; /gitgud:audit grades the shape on its next run

.construct/maintainer/push-release/YYYY-MM-DD.md

one file per day, appended to by every bump:

• an entry captures one bump at a moment in time, so it is never edited after the fact
• lines are hyphen bullets holding a single clause, capped at 100 characters

Release Audit #1: YYYY-MM-DD HH:MM

state

the repo, the trunk and production branches, the release type, the version move, the trunk gate

example:

• repo: owner/name, trunk: main, production: production
• release type: patch, version: 0.12.0 -> 0.12.1
• trunk gate: pull request required, promoting 4 commit(s)

files

the four version files, with the value each held before and after

handover

the emitted sequence, fenced as bash, exactly as the terminal printed it

Verify

not part of the tool; these run after a bump or before any release claim

• RUN bash .claude/skills/export-readme/export-readme.sh --check FIRST; a release ships the plugin copies, so a drifted one reaches users as the version that fixed nothing
• RUN bash .claude/skills/push-release/push-release.sh --check before claiming a version
• READ the preflight aborts rather than working around one; each names a way a release half-lands
• CONFIRM the telemetry table in chat before pasting, since the four files are already written
• STAGE only those four; a release commit carrying other work buries what the bump was for
• PASTE the handover in order, since the tag has to reach origin before the release call resolves

Help

IF the invocation carries --help or -h, this section is the whole turn:

SKILL: /plugin:name
DESCRIPTION: <the `description` frontmatter, verbatim>
POSTURE: <the readme index's keyword for this skill>
FLAGS:
- --flag: <what it changes, in the telemetry bullet's own words>
ARGUMENTS:
- <arg>: <what it names>
ARTIFACT: <the `metadata.artifact` path, or none>
OUTPUT: <what lands in the turn: an audit entry, a handover block, an inline report>
SPEC: <this doc's own path>

• every field prints, in this order; one with nothing to say prints none
• every value is COPIED from the source named beside it, never composed fresh
• ask what they are actually trying to do, and what they have already tried
• name the flag or the sibling skill that fits their answer, then STOP
• run no step, write no file, and never fall through to step 1