[robzolkos]

Why

The basecamp-cli entry, and its basecamp alias, install whatever is on basecamp-cli's main (marketplace.json L10–L24 @ 663bcac). The plugin's skills run the basecamp command, which people install from releases. So between releases, a fresh install can get skills that call commands no released CLI has. 4, 5 and 8 commits touched basecamp-cli's skills/ in the last three release cycles.

What

• Both Basecamp entries get "ref": "stable". bin/check-marketplace requires the alias to share basecamp-cli's source, so they change together.
• basecamp-cli's release workflow fast-forwards stable to each stable release once it has published (basecamp/basecamp-cli#925). After that, a release changes nothing in this repo.
• The README says why the ref is there, and its basecamp-cli link points at stable.

HEY, Fizzy and the house-skills plugins are unchanged. HEY and Fizzy could do the same once their release workflows promote a stable branch.

This replaces #12, which pinned commit shas with an hourly workflow here. With a stable branch, nothing lags a release by up to an hour, and nobody has to merge a PR here for each release.

Ready to merge

stable is at basecamp-cli's latest release, v0.17.0 (e2d5b2a5), moved by hand on 2026-10-23 from v0.14.0, where it had stopped because basecamp/basecamp-cli#925 had not merged yet. #925 merges first, so stable keeps moving with each release. Plugin versions here change only when the stamped version does, so merging this gives existing 0.17.0 installs nothing new, and fresh installs get v0.17.0 instead of whatever is on main. Why the order matters: landing order.

Verified locally

• Validation: bin/check-marketplace passes, and so does claude plugin validate .. Its only warning, a missing marketplace description, is already on main.
• Claude Code, in a fresh CLAUDE_CONFIG_DIR with this branch as the marketplace: basecamp-cli and basecamp both installed 0.14.0 at 2dbca87a.
• Codex 0.163.0, in a fresh CODEX_HOME: basecamp-cli installed 0.14.0, and its basecamp-connect/SKILL.md is byte-identical to v0.14.0's.
• The ref is really followed. Since stable and main are the same commit today, I also pointed a scratch copy of this marketplace at v0.13.2. Claude Code installed 0.13.2 at d742884a, and Codex installed 0.13.2 with v0.13.2's basecamp-connect skill.
• stable only moves forward. On the new branch, setting it to the commit it already points at succeeds, which is what a re-run of the release job does. Setting it back to v0.13.2 with force=false was refused with Update is not a fast forward (HTTP 422), and stable stayed at v0.14.0.

Companion: basecamp/basecamp-cli#925. Card: https://app.basecamp.com/2914079/buckets/48521764/card_tables/cards/10423396016

[Copilot]

🟢 Approved

Both entries consistently select stable, the documentation matches, and no blocking issues were identified.

No open issues 🎉

What changed in this PR

Aligns Basecamp plugin skills with released CLI versions by installing from stable instead of main.

Changes:

• Sets ref: stable for both basecamp-cli and its basecamp alias.
• Updates the README link and explains release-driven branch promotion.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

File	Description
README.md	Documents stable-branch installation and updates the plugin link.
.claude-plugin/​marketplace.json	Selects stable for both Basecamp entries.

_{Review effort: Balanced}

[robzolkos]

Decision: don't merge this until stable is at the latest release

The "Ready to merge" section is out of date. stable is still at v0.14.0 (2dbca87a), but basecamp-cli has since released v0.15.1, v0.16.0 and v0.17.0 (e2d5b2a5). Its stable job, basecamp/basecamp-cli#925, hasn't merged, so nothing has moved the branch.

Merging this now would most likely push installs back to 0.14.0, not just leave them where they are. Claude Code detects an update by comparing version strings for difference, not order:

"Users get a new copy only when the plugin's computed version differs from the one they have."
— Versions and updates

"A version string, not checked against semver"
— plugin manifest version

Codex's loader also reinstalls on any version-string difference. That comes from reading its source; the docs don't say. Neither documents what happens when the marketplace offers a lower version. Under the "differs" rule, an auto-updating user on 0.17.0 would get 0.14.0, and a fresh install would get 0.14.0 skills.

Order to land:

1. Merge Promote a stable branch to each release for the plugin to install from basecamp-cli#925 (the promote-stable job).
2. Fast-forward stable to v0.17.0 (e2d5b2a5) once by hand. The job only runs at the next release. 2dbca87a is an ancestor of e2d5b2a5, so the force=false refs API call the job uses will accept it.
3. Merge this, after updating the "Ready to merge" section.

Each of those three steps waits on a person's word.

Why stable is the right shape

This is the norm, not something we made up. All 262 external entries in Anthropic's own marketplace pin a sha, and a nightly bot bumps them (bump-plugin-shas.yml). 14 plugins are enrolled in releases-only (bump-tracking.json), which moves forward only to the latest published release; the enrolling commit is titled "enroll 8 constant-bumpers in releases-only". A stable branch fast-forwarded by our release workflow does the same thing without the bot, and without a PR here for each release.

The docs' release-channel recipe carries one condition, which we already meet:

"Updates are detected by comparing versions, so a ref that moves without a version change leaves users on the cached copy"
— Run release channels

basecamp-cli stamps .claude-plugin/plugin.json and .codex-plugin/plugin.json with each release's version, so every move of stable comes with a new version string.

What this doesn't fix, and where that's handled

Pinning keeps fresh installs on a release. It doesn't help anyone who already has an old plugin or an old binary. Auto-update is off by default for a third-party marketplace, and marketplace.json has no field to turn it on:

"off for every other marketplace"
— Which marketplaces and plugins auto-update

There's also no manifest field for "requires basecamp ≥ X". The closest prior art is a check run on the user's machine: Vercel's plugin compares vercel --version with the latest at SessionStart (session-start-profiler.mjs). Railway's skill says an unrecognized command means the CLI may be out of date (SKILL.md).

basecamp-cli takes that route in basecamp/basecamp-cli#949:

• The plugin's existing SessionStart hook, which runs the installed binary, tells the user once per version pairing which side to update.
• The skill says that an unknown command means "run basecamp upgrade".

Not doing, for now: a command plugin source (reference), in which the installed binary prints its own plugin directory. That would keep plugin and binary in step by construction, but:

• it needs Claude Code v2.1.229+ and the user's acceptance;
• Codex has no equivalent;
• none of the 315 entries in the official marketplace uses it.

Worth revisiting if the hook notice turns out not to be enough.

[robzolkos]

Step 2 of the landing order is done: basecamp-cli's stable is at v0.17.0 (e2d5b2a5), the latest release, so merging this no longer moves anyone backwards. Still open: basecamp/basecamp-cli#925 (step 1, so stable keeps moving), and the "Ready to merge" section above, which still says v0.14.0.