agentleFS
5kahoisaac5kahoisaac/pi-plugin-cc/.claude/skills/release/SKILL.md

release

Skill0 starsChanged 10 days agoApache-2.0View on GitHub

Prepare a change in this repo (pi-plugin-cc) for release. Picks the Semantic Versioning bump against the default branch, sets the version in package.json, package-lock.json, plugin.json, and marketplace.json with `npm run bump-version`, writes the CHANGELOG.md entry under that version, and updates the docs the change makes stale (README, COMPARISON, DEVELOPMENT, CLAUDE.md). Use when a change is ready for a pull request, after fixing a bug or adding or changing a command, flag, output, or setup step, or when asked to bump the version or cut a release. sync-upstream runs it after porting upstream codex-plugin-cc changes.

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-agent-adapter, changelog-style and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    create-agent-adapter

    Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.

    Also in 5 projects that use this

  • GrinvSkill

    changelog-style

    Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    component-release

    Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.

    Also in 4 projects that use this

  • GrinvSkill

    docs-consistency-check

    Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    documentation-consistency

    Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.

    Also in 8 projects that use this

  • parcadeiSkill

    agent-context-isolation

    Agent Context Isolation

    Also in 3 projects that use this

  • +3 more from Grinv

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 3 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run this skill once per pull request, after the code and tests are done.

    line 20
  2. Very specific:

    If another pull request takes your number first, rebasing conflicts in package.json and CHANGELOG.md.

    line 69
  3. Very specific:

    Write one bullet per change users can see, saying what they see.

    line 98
  4. Very specific:

    Leave the Synced upstream: codex-plugin-cc vX.Y.Z line alone unless you are syncing.

    line 101
  5. Distinctive:

    Update only the docs the table names.

    line 115
  6. Distinctive:

    All four must pass. CI runs the same checks.

    line 133
  7. Very specific:

    After the pull request merges, the user may tag v<version> for a GitHub release (upstream tags v1.0.6).

    line 144

“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Release a change

Users install this plugin from the repository's default branch (/plugin marketplace add 5kahoisaac/pi-plugin-cc), so every change merged to main that touches plugins/pi/ reaches them, but only once the version changes. Claude Code copies an installed plugin into ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ and keeps users there:

  • "Bump version on each release: users stay on their cached copy until the string changes."
  • plugin.json's version wins over the marketplace entry's. When both are set and differ, claude plugin validate reports the mismatch.

Both points come from the Claude Code docs, Host and maintain a marketplace, "Release a new version".

Run this skill once per pull request, after the code and tests are done. It never commits, tags, or pushes. Leave those to the user.

Preconditions

  • The change is complete and npm test passes. Release notes describe working behavior.
  • origin/main is current: git fetch origin.

Step 1 — Find the base version and whether the change ships

git cat-file -e origin/main:package.json \
  && git show origin/main:package.json | node -p 'JSON.parse(require("node:fs").readFileSync(0, "utf8")).version'
node -p 'require("./package.json").version'           # this branch's version
git diff --name-only origin/main...HEAD -- plugins/pi  # committed on this branch
git status --porcelain -- plugins/pi                   # not committed yet, including new files
  • Base version: the first command's output. If origin/main has no package.json, this branch introduces the first version, 0.1.0, and needs no bump.
  • Ships: either of the last two commands lists a file. Only plugins/pi/ is copied into the plugin cache, so a change there needs a version above the base.
  • Repo-only: nothing under plugins/pi/ changed (tests, CI, scripts/, the skills, README, contributor docs, the marketplace listing). It needs no bump. Skip to Step 5; add a CHANGELOG line only if this branch already carries a version above the base.

Step 2 — Choose the version

SemVer rule 4: "Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable." This project's own rule while it is on 0.y.z: breaking changes and new features bump the minor version, and everything else bumps the patch.

The public interface is what users and Claude touch: the slash commands with their flags, arguments, and accepted values; each command's rendered output and --json payload; the pi:pi-rescue subagent; the hooks' behavior; PI_COMPANION_* variables; and the supported Pi and Node.js versions.

ChangeOn 0.y.zFrom 1.0.0
Breaking: removes or renames a command or flag, rejects input that used to work, changes output or --json fields that commands parse, raises the minimum Pi or Node.js versionminormajor
Feature: new command, flag, accepted value, or output field that keeps old usage workingminorminor
Fix, prompt or wording change, docs under plugins/pi/, refactor, performancepatchpatch

Then compare this branch's version with the base:

  • Equal: bump from the base, e.g. a fix on 0.1.0 becomes 0.1.1.
  • Already above the base: this branch bumped earlier. Keep it, unless the change now needs a higher level (base 0.1.0, branch 0.1.1, and you add a feature: re-bump to 0.2.0).
  • If another pull request takes your number first, rebasing conflicts in package.json and CHANGELOG.md. Rebase onto main and run this skill again.

Going to 1.0.0 is the user's decision. Never make that bump on your own.

Step 3 — Set the version everywhere

npm run bump-version -- X.Y.Z

scripts/bump-version.mjs (upstream's script) writes all six fields: package.json version, package-lock.json version and packages[""].version, plugins/pi/.claude-plugin/plugin.json version, and .claude-plugin/marketplace.json metadata.version and plugins[pi].version. Like upstream, the version sits in both plugin.json and the marketplace entry, so the two must match. Never edit them by hand. npm run check-version confirms they agree, and npm test checks the same in CI.

Step 4 — Write the CHANGELOG entry

  • There is no [Unreleased] section. Every change sits under its version heading, ## [X.Y.Z] — YYYY-MM-DD, newest first. tests/commands.test.mjs fails unless the newest heading is package.json's version.
  • For a new version, add its heading above the newest one and date it today. For a re-bump (0.1.1 → 0.2.0), rename the existing heading. For a version this branch already added, add to its section.
  • Group bullets under Keep a Changelog's types and use only the ones that apply: Added, Changed, Deprecated, Removed, Fixed, Security. 0.1.0 has only Added, because there is no earlier version to compare it with.
  • Write one bullet per change users can see, saying what they see. For a fix, give the symptom and the fix ("/pi:status printed a literal <br>; each follow-up command now has its own line"), not just "fix status".
  • Leave the Synced upstream: codex-plugin-cc vX.Y.Z line alone unless you are syncing. sync-upstream reads the newest one, and a sync adds a new one to its version's section.

Step 5 — Update the docs the change makes stale

ChangeDoc
A command, flag, setup step, or output users seeREADME.md (keep upstream's structure)
Something done differently from upstream because Pi differsCOMPARISON.md: the summary row and the numbered section, with evidence (Pi docs, Observed, Upstream, Plugin)
Install, readiness, or sign-inREADME.md and COMPARISON.md §7
Repo layout, a convention, or a new trapCLAUDE.md (AGENTS.md is a symlink to it)
Loading, validation, debugging, or release workflowDEVELOPMENT.md
License or attributionNever weaken LICENSE or either NOTICE

Update only the docs the table names. README.md documents behavior, not internals.

Step 6 — Style gates

  • "Pi" is capitalized in prose. Lowercase pi only in literal commands, paths, and flags (pi -p, /pi:task, pi-companion.mjs).
  • State behavior. No marketing language, no TODOs or placeholders.
  • Escape | inside table cells as \|.

Step 7 — Verify

npm test
npm run check-version
claude plugin validate --strict ./plugins/pi
claude plugin validate --strict .

All four must pass. CI runs the same checks. Re-read each edited doc once, and confirm LICENSE and both NOTICE files are untouched.

Step 8 — Report

Tell the user:

  • the base version, the new version, and the table row that decided it;
  • the files the bump touched and the CHANGELOG section;
  • which docs you updated (one line why each) and which you left alone;
  • the verification results.

After the pull request merges, the user may tag v<version> for a GitHub release (upstream tags v1.0.6). Claude Code does not read tags.

Notes

  • Local testing needs no bump. A marketplace added from a local path (npm run dev:bind) loads the plugin in place, so edits apply at /reload-plugins (Plugin loading reference, "In-place and copied plugins").
  • Example: main is at 0.1.0 and a branch fixes render.mjs. Bump to 0.1.1 and add ## [0.1.1] — <today> with a ### Fixed bullet. If the same branch then adds --json to /pi:status, re-bump to 0.2.0, rename the heading, add an ### Added bullet, and update the README usage.
  • Example: a branch changes only tests/ and CI. No bump and no CHANGELOG entry.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.