Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / plugin-release-automation

Plugin release automation

Plugin release automation turns each merge to main into a compatible plugin package release without making contributors edit shared version fields. It selects a release size from merged pull-request labels, updates the package metadata as one unit, and blocks publication unless all supported plugin hosts still resolve the same package.

Release lifecycle

The release model separates product changes from release numbering. Pull requests carry the product and metadata changes that need review, while a post-merge workflow owns the version update on main.

Pull request version contract

Pull requests must leave the version field unchanged in .claude-plugin/plugin.json, .codex-plugin/plugin.json, .factory-plugin/plugin.json, and .qoder-plugin/plugin.json. This avoids merge conflicts between open branches and lets the release workflow assign one version to all changes that reach main together; CI enforces the rule with the no-bump validation mode. (docs/…/0009-versions-are-bumped-on-main-after-merge.md, plugin-manifest-validation)

When a change needs more than a patch release, maintainers apply release:minor or release:major to the merged pull request. Without either label, the workflow uses a patch release.

References: .github/…/ci.yml• L49-66 scripts/verify-plugin-package.py• L156-214 docs/…/0009-versions-are-bumped-on-main-after-merge.md• L5-13

Main-branch bump flow

After a push to main, the Auto Version Bump workflow determines whether the synchronized version fields changed in the new tip. It skips a tip that already contains a version change, then examines all unversioned merges since the previous bump so several rapid merges produce one release with the strongest label in that range. Bump runs are serialized without cancellation, so a newer queued run can include work that arrived while an earlier run was preparing its release.

The workflow prepares the bump without its protected-main token. A publisher applies the prepared change only if main is still at the same source commit; otherwise it abandons the prepared result and lets the newer queued run calculate a fresh one. The publisher checks the prepared artifact again before it creates the release commit and before it pushes that commit.

This diagram shows how merged work becomes a versioned package on main.

flowchart TD
    A[Pull requests merge without version edits] --> B[Push to main]
    B --> C{Tip already has a version bump?}
    C -->|Yes| D[Skip]
    C -->|No| E[Read labels since previous bump]
    E --> F[Choose major, minor, or patch]
    F --> G[Prepare synchronized metadata change]
    G --> H{Main still matches source commit?}
    H -->|No| I[Discard prepared change]
    H -->|Yes| J[Revalidate and commit bump]
    J --> K{Main still matches before push?}
    K -->|No| I
    K -->|Yes| L[Push release commit to main]

References: .github/…/auto-bump.yml• L1-18 .github/…/auto-bump.yml• L50-113 .github/…/auto-bump.yml• L114-159 .github/…/auto-bump.yml• L160-198 .github/…/auto-bump.yml• L199-368 docs/…/0009-versions-are-bumped-on-main-after-merge.md• L9-13

Release metadata

The release is a metadata change shared by four native host packages and one skill declaration. The goal is to keep host identity and package compatibility aligned while preserving one shared plugin root.

Synchronized manifest versions

The Claude, Codex, Factory, and Qoder manifests use strict MAJOR.MINOR.PATCH versions. The bump operation reads their current versions as one set, rejects drift, and applies the selected major, minor, or patch step to all four manifests.

The manifests also share identity metadata such as the plugin name, description, author, repository, license, and keywords. A release is compatible only when those shared values remain equal across hosts; the host-specific fields may describe how that host locates or presents the package.

References: .claude-plugin/plugin.json• L1-24 .codex-plugin/plugin.json• L1-47 .factory-plugin/plugin.json• L1-24 .qoder-plugin/plugin.json• L1-27 scripts/bump-plugin-version.py• L13-20 scripts/bump-plugin-version.py• L45-76 scripts/verify-plugin-package.py• L26-47 scripts/verify-plugin-package.py• L216-233

Skill metadata version

skills/…/SKILL.md carries a metadata.version value for the skill package. The release operation updates it to the new manifest MAJOR.MINOR, not to the full patch version, and the verifier rejects a missing, malformed, or stale value.

This second version is part of the release contract because a skill can appear current while its package manifests have moved ahead. Keeping both values in the same release change prevents that silent mismatch.

References: scripts/bump-plugin-version.py• L19-20 scripts/bump-plugin-version.py• L72-123 scripts/verify-plugin-package.py• L339-459 skills/…/SKILL.md• L1-7

Marketplace package identity

Marketplace metadata tells Claude, Codex, and Factory where to find the package. Each marketplace must identify exactly one diagram-design plugin and resolve it to the same repository root, so the hosts share the same skill and command surfaces rather than receiving copied variants.

The package gate also checks that each host-specific manifest exists at its marketplace target. Codex metadata must retain its local-source and installation policy contract, while all marketplace paths must stay inside the repository package root.

References: scripts/verify-plugin-package.py• L26-35 scripts/verify-plugin-package.py• L236-299 docs/…/0008-native-host-manifests-share-one-plugin-root.md• L9-17

Release gates

The release path uses separate checks for contributor changes, the prepared bump, and the resulting main tree. Each gate protects a different boundary: no premature version edit, valid package metadata, and a safe exact change before a privileged push.

Preparation and publication checks

The preparation job runs the package verifier against the pre-bump commit and creates an allowlisted change containing the four manifest files and, when present in the package contract, the skill metadata file. The publisher independently checks the artifact paths, applies it with whitespace validation, confirms the exact expected version step, and verifies that no other content or file mode changed.

Only the final push receives the protected-main token. The token is introduced for that command instead of being available to merged repository code or third-party actions. If the token is absent or main changes during the process, publication fails or is skipped instead of pushing an old release over newer work.

References: .github/…/auto-bump.yml• L115-159 .github/…/auto-bump.yml• L176-231 .github/…/auto-bump.yml• L233-328 .github/…/auto-bump.yml• L330-368

Current-tree package validation

CI validates the current tree on pushes to main and checks that versions are synchronized, host identity is stable, marketplace paths are safe, the shared skill is packaged, and commands are present. Before that version check, the package job runs the package-tooling, maintainer-policy, and OpenAI package checks. Pull requests use the same package rules but require no version bump relative to the merge base represented by the pull request merge commit. The package gate then performs a strict Claude marketplace validation before the workflow accepts the tree.

The regression suite covers the version helper and package gate as a combined contract. It ensures that valid synchronized changes pass and that version drift, unsafe marketplace targets, missing package surfaces, and skill metadata drift fail before they can become release state.

References: .github/…/ci.yml• L43-72 scripts/verify-plugin-package.py• L462-527 scripts/test-plugin-package.py• L169-475 scripts/test-plugin-package.py• L476-535

This page explains when release metadata changes and how main publishes them. For the broader host package layout, see Plugin distribution; for the rules that validate manifest identity and package paths, see Plugin manifest validation; for the wider CI workflow and page automation, see CI and Pages automation.

Change checklist

When these files or sections are changed, remember to consider these:

  • If a new plugin host is added, extend the synchronized version set, shared identity checks, marketplace checks, and the release allowlist together.
  • If the skill directory or manifest version contract changes, update both the bump helper and the verifier so the full version and MAJOR.MINOR relationship remain explicit.
  • If release labels or merge grouping changes, keep the strongest-label rule aligned with the workflow's search range since one bump can represent several merges.
  • If protected-branch rules change, review the separation between the unprivileged preparation job and the token-bearing final push.
  • If the CI package gate changes, keep its pull-request no-bump check, main current-tree check, package-tooling checks, maintainer-policy check, OpenAI package checks, and strict Claude marketplace validation aligned with the release contract.

Important failure modes

TriggerConsequenceGuard
A pull request changes a plugin manifest versionThe pull request fails the version gate and cannot follow the normal merge flowCI runs verify-plugin-package.py --require-no-bump against the merge base represented by HEAD^1
The four manifest versions differThe package cannot represent one compatible releaseThe bump helper and verifier reject unsynchronized versions
SKILL.md has no valid matching metadata.versionThe skill metadata can drift from the package releaseThe bump helper fails closed and the verifier compares it with manifest MAJOR.MINOR
main advances after preparationAn old prepared release is not pushedThe publisher rechecks the source commit before applying and before pushing
A marketplace target leaves the repository root or points to a different rootA host may install the wrong package surfaceMarketplace path and shared-root validation rejects the package
The package passes local checks but fails strict Claude marketplace validationThe package is not accepted by the Claude marketplace gateCI runs claude plugin validate . --strict after the package checks

Key files

FileWhy to read it
.github/…/auto-bump.ymlDefines the post-merge release lifecycle, label selection, serialized runs, artifact checks, and protected push
scripts/bump-plugin-version.pyDefines the synchronized version change and the skill metadata update
scripts/verify-plugin-package.pyDefines the package compatibility and release integrity rules
.github/…/ci.ymlShows the pull-request no-bump gate, the main package gate, package-tooling checks, maintainer-policy check, OpenAI package checks, and strict Claude marketplace validation
scripts/test-plugin-package.pyShows the release contract through focused regression coverage
.claude-plugin/plugin.jsonShows the Claude host manifest and its shared release metadata
.codex-plugin/plugin.jsonShows the Codex host manifest and its host-specific package interface
.factory-plugin/plugin.jsonShows the Factory host manifest and its shared release metadata
.qoder-plugin/plugin.jsonShows the Qoder host manifest and its shared release metadata
docs/…/0009-versions-are-bumped-on-main-after-merge.mdRecords why release numbering belongs to post-merge automation
docs/…/0008-native-host-manifests-share-one-plugin-root.mdExplains why host packages share one plugin root