CS-10900: Add Claude Code plugin for boxel-cli

[FadhlanR]

Summary

Ships a first-class Claude Code plugin for @cardstack/boxel-cli, packaging the kind of guidance the standalone cardstack/boxel-cli repo carries in its .claude/CLAUDE.md so it's distributable via marketplace.

• Plugin lives at packages/boxel-cli/plugin/ with manifest .claude-plugin/plugin.json.
• Repo-root .claude-plugin/marketplace.json lists the plugin via relative path; external users /plugin marketplace add cardstack/boxel then /plugin install boxel-cli.
• Cardstack engineers: claude --plugin-dir packages/boxel-cli/plugin.
• 7 skills under the /boxel-cli: namespace:
  • boxel-development — .gts authoring (ported from standalone, ~90KB of evergreen Boxel patterns)
  • boxel-file-structure — file/directory naming + adoptsFrom rules (ported from standalone)
  • realm-sync, realm-history, file-ops, search, profile — new wrappers around the monorepo CLI's namespaced commands (incl. CS-10627 file touch)

How "generated from the code" works

scripts/build-plugin.ts walks the Commander tree and rewrites the <!-- generated:commands --> block inside each SKILL.md. The Commander tree is extracted into src/build-program.ts so both the runtime entry point (src/index.ts) and the generator share one source of truth. Curated narrative outside the markers is hand-authored.

Two CI gates in ci-lint.yaml:

1. Synopsis freshness — pnpm build:plugin && git diff --exit-code. Fails if commands changed without regenerating skills.
2. Synopsis-bump coupling — if any generated block is in the diff, plugin.json version must also be in the diff. Without a version bump, Claude's marketplace cache won't surface the update.

Versioning

Plugin and CLI version independently:

• Prose-only update → bump plugin.json only.
• CLI command added/changed → bump both (synopsis must regenerate; CI enforces).
• CLI internal refactor → bump package.json only.

The plugin is not npm-published. The marketplace clones it from cardstack/boxel directly. npm install -g @cardstack/boxel-cli remains the prerequisite for users — Pattern A in plugins-reference (matches how pyright-lsp and other npm-backed plugins work).

Test plan

• cd packages/boxel-cli && pnpm build:plugin → no diff (idempotent)
• pnpm lint in packages/boxel-cli passes (eslint + tsc)
• pnpm test:unit in packages/boxel-cli passes (158 tests)
• pnpm build in packages/boxel-cli produces a working dist/index.js
• claude --plugin-dir packages/boxel-cli/plugin from repo root: /help lists /boxel-cli:* skills
• Smoke-test one skill end-to-end (e.g., /boxel-cli:realm-sync against a local realm-server)
• Pin a fake CLI command change locally, re-run pnpm build:plugin, confirm git diff shows the synopsis update
• CI: synopsis-freshness gate fails on a PR that changes a Commander option without regenerating
• CI: version-bump-coupling gate fails on a PR that changes a generated block without bumping plugin.json

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e935183029

ℹ️ 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".

[habdelra]

are you just duplicating the skills that we already have? if so can you use sym links--otherwise we maintain 2 sources of truth and they will ultimately start to diverge

[Copilot]

Pull request overview

Adds a distributable Claude Code plugin for @cardstack/boxel-cli, including curated Boxel authoring guidance plus generated command synopses sourced from the CLI’s Commander program tree.

Changes:

• Refactors CLI program construction into a shared buildBoxelProgram() builder used by both runtime entrypoint and plugin synopsis generator.
• Introduces pnpm build:plugin generator to rewrite <!-- generated:commands --> blocks for selected skills from the Commander command tree.
• Adds plugin packaging/metadata (plugin manifest, marketplace entry) and CI checks to enforce synopsis freshness + version bump coupling.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/boxel-cli/src/index.ts	Switches runtime entrypoint to build and parse the shared Commander program tree.
packages/boxel-cli/src/build-program.ts	New shared builder for the full CLI Commander tree (single source of truth).
packages/boxel-cli/scripts/build-plugin.ts	New generator that derives skill command synopses from Commander and rewrites SKILL.md generated blocks.
packages/boxel-cli/plugin/skills/search/SKILL.md	New skill doc for federated search, including generated command synopsis block.
packages/boxel-cli/plugin/skills/realm-sync/SKILL.md	New realm sync skill doc with generated synopses for sync/push/pull/create/list.
packages/boxel-cli/plugin/skills/realm-history/SKILL.md	New realm history/indexing control skill doc with generated synopses.
packages/boxel-cli/plugin/skills/profile/SKILL.md	New profile management skill doc with generated synopsis for boxel profile.
packages/boxel-cli/plugin/skills/file-ops/SKILL.md	New single-file operations skill doc with generated synopses for boxel file *.
packages/boxel-cli/plugin/skills/boxel-file-structure/SKILL.md	New file layout/naming guidance skill doc (hand-authored prose).
packages/boxel-cli/plugin/skills/boxel-development/SKILL.md	New large Boxel authoring guide skill doc (hand-authored content).
packages/boxel-cli/plugin/README.md	Plugin install/usage/versioning/release documentation.
packages/boxel-cli/plugin/.claude-plugin/plugin.json	Plugin manifest for Claude Code marketplace distribution.
packages/boxel-cli/package.json	Adds build:plugin script to run the synopsis generator.
.github/workflows/ci-lint.yaml	Adds CI gates for synopsis freshness and plugin version bump coupling.
.claude-plugin/marketplace.json	Adds repository-level marketplace catalog pointing to the plugin directory.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[FadhlanR]

Good catch — fixed in db73171. We weren't going to symlink because boxel-skills lives in its own repo (cardstack/boxel-skills) and isn't checked out in this monorepo, plus the plugin needs the content physically present for marketplace distribution.

Instead, boxel-skills is now the single source of truth and the plugin mirrors it at build time:

• New pnpm build:skills (in packages/boxel-cli/scripts/build-skills.ts) shallow-clones cardstack/boxel-skills at a pinned tag (BOXEL_SKILLS_VERSION = 'v0.0.22') and regenerates plugin/skills/boxel-development/ (lean SKILL.md + 18 references/) and plugin/skills/boxel-design/ (single-file leaf).
• Two new CI gates in ci-lint.yaml mirror the existing build-plugin synopsis pattern:
  1. boxel-skills sync freshness — re-runs pnpm build:skills and fails if git diff shows hand edits to generated content.
  2. boxel-skills bump coupling — fails if generated content changed in the PR but plugin.json version didn't bump.

To pick up upstream changes: bump BOXEL_SKILLS_VERSION in scripts/build-skills.ts, run pnpm build:skills from packages/boxel-cli/, bump plugin.json. CI enforces no drift.