feat(plugin-dev): unify plugin creation across runtimes with multi-format (#252)

* feat(plugin-dev): add multi-format command and unify plugin creation across runtimes

- add /plugin-dev:multi-format command wrapping the Codex/Antigravity/Cursor manifest generator
- add plugin-authoring skill teaching the author-once → multi-format workflow
- chain /plugin-dev:scaffold into the multi-format generator so a new plugin loads in all four runtimes
- bump plugin-dev to 1.1.0 and regenerate Codex/Cursor manifests

* chore(plugin-dev): apply AI code review suggestions

* chore: update agent memory

Author: amondnet

.claude/agent-memory/review-review-cubic-reviewer/MEMORY.md

@@ -8,3 +8,4 @@
 - [Graphite please-config opt-in review (PR #181)](pr181-graphite-please-config-opt-in.md) — cubic clean pass (0 issues); AWK YAML parser tightened to match `enabled: true` only at direct-child indent level of `graphite:`
 - [PortOne plugin review (PR #184)](pr184-portone-plugin.md) — initial pass: P1 misleading `express.raw()` note, P2 false positive on named import; follow-up uncommitted edit (Express 4 `next(e)` fix) → cubic clean (0 issues)
 - [Graphite awk state-reset fix (PR #189)](pr189-graphite-awk-state-reset.md) — cubic clean pass (0 issues); state-leakage fix in graphite-context.sh awk parser
+- [plugin-dev docs review (PR #252)](pr252-plugin-dev-docs.md) — cubic clean pass (0 issues); reviewed uncommitted changes with plain `-j`, overriding default `-b` per task context

.claude/agent-memory/review-review-cubic-reviewer/pr252-plugin-dev-docs.md

@@ -0,0 +1,20 @@
+---
+name: pr252-plugin-dev-docs
+description: cubic review of PR #252 docs-only changes to plugin-dev plugin (scaffold.md, multi-format.md, SKILL.md)
+metadata:
+  type: project
+---
+
+PR #252 applied AI review suggestions to 3 markdown files in `plugins/plugin-dev/`
+(`commands/scaffold.md`, `commands/multi-format.md`, `skills/plugin-authoring/SKILL.md`).
+Reviewed via `cubic review -j` against uncommitted working-tree changes (not `-b`),
+since the task explicitly requested reviewing local uncommitted changes rather than a
+full base-branch diff. Result: 0 issues (clean pass).
+
+**Why:** Confirms cubic can be pointed at uncommitted changes even when
+`REVIEW_CUBIC_DEFAULT_FLAGS` defaults to `-b`; when the invoking context explicitly says
+"review local uncommitted changes," override the configured default and drop `-b`.
+
+**How to apply:** For future docs-only or small doc-tweak PRs in this repo, prefer
+plain `cubic review -j` (uncommitted diff) when the task description says so, even if
+`.please/config.yml` sets `-b` as the default flag.

plugins/plugin-dev/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-dev",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Best practices, guidelines, and validation tools for Claude Code plugin development",
   "author": {
     "name": "Passion Factory",

plugins/plugin-dev/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "plugin-dev",
   "displayName": "Plugin Dev",
   "description": "Best practices, guidelines, and validation tools for Claude Code plugin development",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "Passion Factory"
   },

plugins/plugin-dev/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to the plugin-dev plugin will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-07-07
+
+### Added
+- `/plugin-dev:multi-format` command — generate Codex, Antigravity, and Cursor manifests from the Claude Code source of truth
+- `plugin-authoring` skill — teaches the author-once → multi-format workflow so the plugin is self-contained across runtimes
+
+### Changed
+- `/plugin-dev:scaffold` now chains into the multi-format generator so a new plugin loads in all four runtimes in one flow
+
 ## [1.0.0] - 2025-10-17
 
 ### Added

plugins/plugin-dev/README.md

@@ -11,6 +11,7 @@ Best practices, guidelines, and validation tools for Claude Code plugin developm
 - 🎯 **Best Practices Guidance** - Expert advice on plugin development
 - ✅ **Plugin Validation** - Automated manifest and structure validation
 - 🏗️ **Plugin Scaffolding** - Quick-start templates for new plugins
+- 🌐 **Multi-Runtime Manifests** - Author once in Claude Code format, generate Codex, Antigravity, and Cursor manifests
 - 🔄 **Gemini Migration** - Tools to migrate Gemini CLI extensions
 - 🔍 **Real-time Validation** - Automatic validation when editing plugin files
 
@@ -84,6 +85,27 @@ Generate a new plugin with proper structure and best practices baked in.
 I need a new plugin called "api-tools" that provides commands for API testing
 ```
 
+### `/plugin-dev:multi-format`
+
+Generate the Codex, Antigravity, and Cursor manifests for the marketplace's local plugins from the
+Claude Code source of truth. The Claude manifest is the only file you author by hand — this command
+keeps every runtime in sync.
+
+**Generates (per local plugin):**
+- `.codex-plugin/plugin.json` (+ `.mcp.json` when MCP is present)
+- root `plugin.json` + `mcp_config.json` + `hooks.json` (Antigravity)
+- `.cursor-plugin/plugin.json`
+- `.agents/plugins/marketplace.json` and `.cursor-plugin/marketplace.json`
+
+**Example:**
+```
+/plugin-dev:multi-format
+
+I just edited plugins/api-tools — regenerate its Codex and Cursor manifests
+```
+
+> The generator rewrites all local plugins; scope your commit to the plugin(s) you changed.
+
 ### `/plugin-dev:migrate-gemini`
 
 Migrate existing Gemini CLI extensions to Claude Code plugins.
@@ -182,24 +204,29 @@ plugin-name/
    - Create agents in `agents/`
    - Configure hooks in `hooks/`
 
-3. **Validate continuously**
+3. **Generate multi-runtime manifests**
+   ```bash
+   /plugin-dev:multi-format
+   ```
+
+4. **Validate continuously**
    ```bash
    /plugin-dev:validate
    ```
 
-4. **Test locally**
+5. **Test locally**
    ```bash
    claude --debug
    /plugin list
    /your-plugin:command
    ```
 
-5. **Version and document**
+6. **Version and document**
    - Update version in plugin.json
    - Document changes in CHANGELOG.md
    - Update README with new features
 
-6. **Publish**
+7. **Publish**
    - Add to marketplace
    - Tag release in git
    - Share with community

plugins/plugin-dev/commands/multi-format.md

@@ -0,0 +1,82 @@
+# Generate Multi-Runtime Manifests
+
+You are a multi-runtime plugin packaging expert. Generate the Codex, Antigravity, and Cursor
+manifests for the marketplace's local plugins from the Claude Code source of truth, keeping every
+runtime in sync.
+
+## Background
+
+This repository ships the **same plugin set across four runtimes**. The Claude Code manifest is the
+**single source of truth**; the others are **generated** and must never be hand-edited.
+
+| Runtime      | Manifest path                          | Companion files                       |
+|--------------|----------------------------------------|---------------------------------------|
+| Claude Code  | `.claude-plugin/plugin.json` (or root `plugin.json`) | `hooks/hooks.json`, inline `mcpServers` |
+| Codex        | `.codex-plugin/plugin.json`            | `.mcp.json` (when MCP present)        |
+| Antigravity  | `plugin.json` (root)                   | `mcp_config.json`, root `hooks.json`  |
+| Cursor       | `.cursor-plugin/plugin.json`           | none — components auto-discovered     |
+
+Shared assets (`commands/`, `agents/`, `skills/`, `hooks/`) live once at the plugin root and are
+referenced by every manifest. Only manifest-level fields differ per runtime.
+
+## Your Task
+
+### 1. Run the generator
+
+> **New plugin? Wire its `.claude-plugin/marketplace.json` entry first.** The generator resolves
+> each plugin's metadata (notably `category`) from the marketplace entry. A plugin dir not yet
+> listed there is generated with no entry — its Codex manifest falls back to the default category
+> and it is omitted from the emitted Codex/Cursor marketplace files. Add the entry, then run:
+
+```bash
+bun scripts/cli.ts multi-format
+```
+
+For every local plugin (`source: "./plugins/..."` in `.claude-plugin/marketplace.json`) this emits:
+
+- `plugins/<name>/.codex-plugin/plugin.json` (+ `.mcp.json` when the plugin defines `mcpServers`)
+- `plugins/<name>/plugin.json` + `mcp_config.json` + root `hooks.json` (Antigravity)
+- `plugins/<name>/.cursor-plugin/plugin.json`
+- `.agents/plugins/marketplace.json` (Codex marketplace, local plugins only)
+- `.cursor-plugin/marketplace.json` (Cursor marketplace, local plugins only)
+
+The generator only writes files whose content actually changed, and prints per-plugin status
+(`wrote N file(s)` / `up to date` / `skipped`).
+
+### 2. Scope the diff to your change
+
+⚠️ **`multi-format` rewrites all local plugins, not just the one you touched.** If the committed
+artifacts had pre-existing drift, the command produces a large unrelated diff. Keep the change
+atomic:
+
+```bash
+git status --short
+# Revert churn from plugins you did NOT intend to change:
+git restore plugins/<other-plugin>/...
+```
+
+Commit only the files for the plugin(s) you actually changed.
+
+### 3. Claude-only fields do not propagate
+
+Fields that exist only in the Claude runtime — notably `relevance` (plugin suggestion signals) — are
+intentionally **not** copied to the Codex/Cursor marketplaces. Author them only in
+`.claude-plugin/marketplace.json`.
+
+### 4. Verify
+
+```bash
+claude plugin validate .claude-plugin/marketplace.json
+claude plugin validate plugins/<name>
+```
+
+## When to Run
+
+- After scaffolding a new plugin (`/plugin-dev:scaffold`)
+- After editing any plugin's Claude manifest (name, version, description, `mcpServers`, hooks)
+- After adding, removing, or reordering a plugin entry in `.claude-plugin/marketplace.json`
+
+Do **not** hand-edit `.codex-plugin/`, `.cursor-plugin/`, root Antigravity `plugin.json`, or the
+generated marketplaces — re-run this command instead.
+
+Now, run the generator, scope the diff to the intended plugin(s), and report what changed.

plugins/plugin-dev/commands/scaffold.md

@@ -1,10 +1,16 @@
 # Scaffold New Plugin
 
-You are a plugin scaffolding expert. Help users create a new Claude Code plugin with proper structure and best practices.
+You are a plugin scaffolding expert. Help users create a new plugin with proper structure and best practices.
+
+Author the plugin **once in Claude Code format** (the source of truth), then generate the
+Codex / Antigravity / Cursor manifests from it in a single step. One directory, four runtimes —
+you never hand-write the other manifests.
 
 ## Your Task
 
-Create a complete plugin structure based on user requirements. Ask clarifying questions if needed, then generate all necessary files.
+Create a complete plugin structure based on user requirements. Ask clarifying questions if needed,
+generate all necessary files in Claude Code format, then run the multi-format generator so the same
+directory loads in Codex, Antigravity, and Cursor too.
 
 ## Scaffolding Process
 
@@ -192,6 +198,44 @@ All notable changes to this project will be documented in this file.
 - Feature 2
 ```
 
+### 10. Wire the Marketplace Entry, Then Generate Multi-Runtime Manifests
+
+The plugin is authored in Claude Code format (`.claude-plugin/plugin.json`, or a root-level
+`plugin.json` for plugins that also serve as the Antigravity manifest). This is the **source of
+truth** — never hand-write the other runtimes' manifests; generate them instead.
+
+**Order matters — wire the marketplace entry _first_.** The generator resolves each plugin's
+metadata (notably `category`) from `.claude-plugin/marketplace.json`. A plugin dir that is not yet
+listed there is generated with no entry, so its Codex manifest falls back to the default category
+and it is omitted from the emitted Codex/Cursor marketplace files. So for a brand-new plugin, wire
+the companion files described in `.claude/rules/marketplace-sync.md` **before** running the
+generator:
+
+1. Add the marketplace entry to `.claude-plugin/marketplace.json` (source of truth).
+2. If the plugin is release-managed, add a `plugins/<name>` entry to `release-please-config.json`
+   + `.release-please-manifest.json` covering every version-bearing manifest the plugin ships.
+
+Then generate the other runtimes' manifests in a single pass:
+
+```bash
+bun scripts/cli.ts multi-format
+```
+
+This reads the Claude manifest + the marketplace entry and emits, for every local plugin
+(`source: "./plugins/..."`):
+
+- `plugins/<name>/.codex-plugin/plugin.json` (+ `.mcp.json` when the plugin defines `mcpServers`)
+- `plugins/<name>/plugin.json` + `mcp_config.json` + root `hooks.json` (Antigravity)
+- `plugins/<name>/.cursor-plugin/plugin.json`
+- `.agents/plugins/marketplace.json` (Codex marketplace) and `.cursor-plugin/marketplace.json` (Cursor marketplace)
+
+Shared assets (`commands/`, `agents/`, `skills/`, `hooks/`) live **once** at the plugin root and
+are referenced by every manifest — only manifest-level fields differ per runtime.
+
+> **This command rewrites all local plugins, not just the new one.** If unrelated plugins show up
+> in the diff (pre-existing drift), `git restore` those files and commit only the new plugin's
+> artifacts so the change stays atomic. See `/plugin-dev:multi-format` for the dedicated wrapper.
+
 ## After Scaffolding
 
 1. **Validate structure** using `/plugin-dev:validate`

plugins/plugin-dev/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-dev",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Best practices, guidelines, and validation tools for Claude Code plugin development",
   "author": {
     "name": "Passion Factory",

plugins/plugin-dev/skills/plugin-authoring/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: Authoring Plugins (Multi-Runtime)
+description: Author a plugin once in Claude Code format, then generate Codex, Antigravity, and Cursor manifests from it so one directory loads in all four runtimes. Use when creating, scaffolding, or editing a plugin in this marketplace, wiring a marketplace entry, running the multi-format generator, or when the user mentions "plugin.json", ".claude-plugin", ".codex-plugin", ".cursor-plugin", "multi-format", "marketplace.json", or "Codex/Cursor/Antigravity plugin".
+---
+
+# Plugin Authoring — Multi-Runtime
+
+This marketplace ships the **same plugin directory across four runtimes**. You author **once** in
+Claude Code format (the source of truth) and **generate** the rest. Never hand-write the Codex,
+Antigravity, or Cursor manifests.
+
+## The one rule: edit Claude → generate the rest
+
+```
+.claude-plugin/plugin.json  (or root plugin.json)   ← author here, source of truth
+        │
+        │  bun scripts/cli.ts multi-format
+        ▼
+.codex-plugin/plugin.json + .mcp.json               ← generated
+plugin.json (root) + mcp_config.json + hooks.json   ← generated (Antigravity)
+.cursor-plugin/plugin.json                           ← generated
+.agents/plugins/marketplace.json                     ← generated (Codex marketplace)
+.cursor-plugin/marketplace.json                      ← generated (Cursor marketplace)
+```
+
+Shared assets (`commands/`, `agents/`, `skills/`, `hooks/`) live **once** at the plugin root and are
+referenced by every manifest. Only manifest-level fields differ per runtime.
+
+## Workflow
+
+1. **Scaffold / edit** the plugin in Claude Code format — run `/plugin-dev:scaffold` for a new one.
+   Components go at the plugin **root**, never inside `.claude-plugin/`:
+   ```
+   plugins/<name>/
+   ├── .claude-plugin/plugin.json   # manifest only (or root plugin.json — see below)
+   ├── commands/                     # at root
+   ├── agents/                       # at root
+   ├── skills/                       # at root
+   └── hooks/hooks.json              # at root
+   ```
+2. **Register** in the source-of-truth marketplace `.claude-plugin/marketplace.json`
+   (`source: "./plugins/<name>"`). Claude-only fields like `relevance` live **only** here.
+3. **Generate** the other runtimes: `/plugin-dev:multi-format` (or `bun scripts/cli.ts multi-format`).
+4. **Scope the diff** — the generator rewrites *all* local plugins; `git restore` any unrelated
+   churn so the commit stays atomic.
+5. **Validate**: `/plugin-dev:validate`, then `claude plugin validate plugins/<name>`.
+
+## Root-level `plugin.json` plugins
+
+A few plugins (e.g. `plugin-dev`, `bun`) use a **root** `plugin.json` that serves as *both* the
+Claude Code manifest *and* the Antigravity manifest. Edit that root file as the source of truth;
+`multi-format` still regenerates `.codex-plugin/` and `.cursor-plugin/` from it.
+
+## Companion files for a NEW plugin
+
+Wire these in the same change (see `.claude/rules/marketplace-sync.md`):
+
+- `.claude-plugin/marketplace.json` — add the plugin entry (source of truth).
+- `release-please-config.json` + `.release-please-manifest.json` — add a `plugins/<name>` entry
+  covering **every** version-bearing manifest the plugin ships (`.claude-plugin/plugin.json` and,
+  when multi-format generates them, `.codex-plugin/plugin.json` + root `plugin.json` +
+  `.cursor-plugin/plugin.json`). *Only if the plugin is release-managed.*
+- `README.md` — add the plugin under **Built-in Plugins**.
+
+## What NOT to do
+
+- ❌ Hand-edit `.codex-plugin/`, `.cursor-plugin/`, generated root Antigravity `plugin.json`, or the
+  Codex/Cursor `marketplace.json` — re-run `multi-format`.
+- ❌ Put `relevance` (or other Claude-only fields) in the Codex/Cursor marketplaces — the generator
+  intentionally drops them.
+- ❌ Nest `commands/` / `agents/` / `skills/` inside `.claude-plugin/` — they won't load.
+
+## Related
+
+- Deep Claude Code component reference (commands, agents, skills, hooks, MCP, Gemini migration):
+  the `claude-code-plugin-builder` skill.
+- Codex-native creation (inside Codex): the `plugin-creator` skill.
+- Cursor-native creation (inside Cursor): the `create-plugin-scaffold` skill.
+- Commands: `/plugin-dev:scaffold`, `/plugin-dev:multi-format`, `/plugin-dev:validate`,
+  `/plugin-dev:migrate-gemini`, `/plugin-dev:best-practices`.