feat(plugin): distribute bundle from dist/claude-plugin via git-subdir#477
Merged
Conversation
Move the Claude Code plugin bundle from a tracked-on-main artifact to an orphan branch `dist/claude-plugin` rebuilt by CI on every push to main, so develop and main PR diffs stop carrying generated-bundle churn (closes #461) without breaking marketplace consumers. - Add ADR-0043 — choose orphan-branch + git-subdir over per-release tag, npm channel, linguist-generated, or auto-commit-on-merge. - Add `.github/workflows/publish-claude-plugin.yml` — builds the bundle from canonical `.claude/{agents,skills,commands}/` + `.mcp.json` sources on every push to main, force-pushes the staged tree to `dist/claude-plugin`. - Switch `.claude-plugin/marketplace.json` source from relative path to git-subdir pinned to `ref: dist/claude-plugin`. - Untrack `claude-plugin/specorator/{agents,skills,commands,.claude-plugin}/` and `claude-plugin/specorator/.mcp.json`; gitignore them. - Make `check-claude-plugin` generated-output checks (manifest, .mcp.json, agents/skills/commands dirs) conditional on the file being present, so a clean develop/main checkout passes without a prior local `build:claude-plugin`. Validate the new git-subdir marketplace shape. - Drop `build:claude-plugin --check` drift check from the verify gate — no committed bundle on develop/main to drift against. - Run `npm run build:claude-plugin` in `.github/workflows/release.yml` before the readiness gate so the npm tarball still ships the bundle. - Register `workflow:publish-claude-plugin` in the automation registry. - Refresh `docs/how-to/install-claude-plugin.md` and the plugin-bundle section of `docs/specorator-product/tech.md` for the orphan-branch model; document the contributor smoke-test prerequisite. Closes #474 Closes #461 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
zizmor on PR #477 flagged top-level `contents: write` as excessive + undocumented (security/code-scanning/76, /77). Top-level block is now read-only; the single `publish` job opts in to `contents: write` for the force-push to `dist/claude-plugin`. Both blocks carry explanatory comments matching the in-repo `release.yml` pattern. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
zizmor `undocumented-permissions` (security/code-scanning/78) flags the job-level `contents: write` line itself even with the block-level comment. Add an inline comment matching zizmor's expected shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1a9a95157d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Codex P1 on PR #477: `workflow_dispatch` accepts any ref from the UI, so a manual run from `develop` or a feature branch would force-push that ref's content to `dist/claude-plugin` and break marketplace installs. Add a job-level `if: github.ref == 'refs/heads/main'` guard so non-main dispatches are skipped silently. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Owner
Author
|
@codex review |
|
Codex Review: Didn't find any major issues. Chef's kiss. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
This was referenced May 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
dist/claude-plugin, rebuilt by CI on every push tomain. Marketplace consumers resolve viagit-subdirpinned to that ref (ADR-0043).claude-plugin/specorator/{agents,skills,commands,.claude-plugin}/+.mcp.jsonso develop/main PR diffs stop carrying generated-artifact churn (closes chore(plugin): gitignore claude-plugin bundle and build in CI instead #461).build:claude-plugin --checkdrift check from the verify gate — no committed bundle on develop/main to drift against. The release workflow rebuilds the bundle before the readiness gate so the npm tarball still ships it.Triage
track:specorator-improvement— template-self changeCompliance with ADR-0043
.github/workflows/publish-claude-plugin.yml— orphan-branch publish on push to main.claude-plugin/marketplace.json—git-subdirsource pinned todist/claude-plugin.gitignore— exclude generated bundle subdirs +.mcp.jsonscripts/check-claude-plugin.ts— structural-only on a clean checkout; validates new git-subdir shapepackage.json#scripts.check:claude-plugin— dropbuild:claude-plugin --check.github/workflows/release.yml— rebuild bundle before readiness gatetools/automation-registry.yml— registerworkflow:publish-claude-plugindocs/how-to/install-claude-plugin.md— refreshed for the orphan-branch flow + contributor smoke-test prereqdocs/specorator-product/tech.md#plugin-bundle— rewritten for the new modelTest plan
npm run verifygreen locally (run with--no-file-parallelismto sidestep a Windows-only parallel-pool flake ontests/scripts/cli.test.tsandtests/scripts/project-init.test.ts— both pass in isolation; tests pre-date this change).npm run check:claude-pluginpasses both with and without a locally-built bundle.claude-plugin.test.tscases — clean checkout (no bundle) and rejection of legacy relative-path source..github/workflows/publish-claude-plugin.ymlruns on the first push to main and creates the orphan branchdist/claude-plugin./plugin marketplace add Luis85/agentic-workflow+/plugin install specorator@specorator-marketplaceresolves the bundle fromdist/claude-pluginand produces a functional plugin.gh workflow run release.yml -f version=<X.Y.Z> -f dry_run=true— readiness gates pass with the freshly-built bundle.Transition note
Until the merge to develop → main → first publish-claude-plugin run completes, marketplace consumers will see a 404 on
dist/claude-plugin. This is the unavoidable bootstrap window. Existing installs that already cached the bundle stay functional until they run/plugin marketplace update.Closes #474
Closes #461
🤖 Resolved via /issue:tackle 474