diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 3bc3460..13bbf6e 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -9,10 +9,12 @@ "homepage": "https://github.com/hiivmind/plugin-portability", "repository": "https://github.com/hiivmind/plugin-portability", "license": "MIT", - "keywords": [ "cross-platform", - "multi-platform", - "plugin-portability", - "plugins", - "skills", - "portability" + "keywords": [ + "cross-platform", + "multi-platform", + "plugin-portability", + "plugins", + "skills", + "portability" + ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d74ddee..c6cb534 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,12 +17,7 @@ This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). Please read ## Adding a New Platform -1. Create a platform documentation file in `docs/platforms/` -2. Add a manifest template in `lib/templates/manifests/` -3. Add install doc templates in `lib/templates/install-docs/` -4. Add a platform rubric in `lib/rubrics/` -5. Update the portability skill (`skills/plugin-portability/SKILL.md`) to handle the new platform -6. Update the assessment rubric (`docs/assessment-rubric.md`) with scoring criteria +See [lib/principles/adding-a-platform.md](lib/principles/adding-a-platform.md) for the full guide — architecture overview, phased checklist, and verification gates. ## Authoring Skills diff --git a/INSTALL.md b/INSTALL.md index feb8159..50c6ae2 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,5 +1,7 @@ # Installation +How to install **Plugin Portability** on each supported platform. + ## Important: Whole-repo install required This plugin uses shared hooks, context files, and platform manifests that live outside @@ -10,25 +12,24 @@ Every install path below clones or references the full repo. See [docs/ecosystem-landscape.md](docs/ecosystem-landscape.md) for background on why this is necessary across today's agent platforms. -## Fresh Install +## Claude Code -### Claude Code +### Install from GitHub -#### Marketplace install +Register the plugin's marketplace, then install: ```bash -claude plugin install plugin-portability@plugin-portability-marketplace +/plugin marketplace add hiivmind/plugin-portability +/plugin install plugin-portability@plugin-portability-marketplace ``` -#### Local development +### Install from local clone ```bash -claude --plugin-dir ./path-toplugin-portability +claude --plugin-dir /path/to/plugin-portability ``` -#### Project install - -Add to `.claude/settings.json`: +Or add to `.claude/settings.json` for persistent access: ```json { @@ -43,7 +44,7 @@ Add to `.claude/settings.json`: } ``` -#### Verify +### Verify ```bash claude plugin list @@ -51,282 +52,200 @@ claude plugin list Look for `plugin-portability` in the output. -#### Using the skills - -In Claude Code, invoke skills by describing what you want in natural language: - -``` -Assess the portability of /path/to/my-plugin -``` - -``` -Use the plugin-portability skill on /path/to/my-plugin -``` - -### Cursor +## Cursor -#### Install from GitHub +### Install from registry -In Cursor's Agent chat: +Search for **plugin-portability** in the Cursor marketplace panel, visit `cursor.com/marketplace`, or run in Agent chat: ``` /add-plugin hiivmind/plugin-portability ``` -#### Local development - -Symlink or copy the plugin directory to `~/.cursor/plugins/local/plugin-portability/` and restart Cursor (Developer: Reload Window). - -#### Verify - -Open Cursor and check that skills from Plugin Portability appear when typing `/` in chat. - -#### Using the skills - -In Cursor's chat, invoke skills with the `/` prefix: +### Install from GitHub ``` -/plugin-portability +/add-plugin hiivmind/plugin-portability ``` -### Gemini CLI +### Install from local clone -#### Install from GitHub +Symlink or copy the plugin directory and restart Cursor (Developer: Reload Window): ```bash -gemini extensions install https://github.com/hiivmind/plugin-portability +ln -s /path/to/plugin-portability ~/.cursor/plugins/local/plugin-portability ``` -#### Install from local path - -```bash -gemini extensions link /path/to/plugin-portability -``` +### Verify -#### Verify +Open Cursor and check that skills from plugin-portability appear when typing `/` in chat. Rules should appear in Cursor Settings > Rules with the plugin name prefix. -```bash -gemini extensions list -``` +## Gemini CLI -Look for `plugin-portability` in the output. Restart Gemini CLI if it was running during install. +### Install from registry -#### Using the skills - -Gemini CLI activates skills automatically when it determines they are relevant. You can also mention a skill by name: - -``` -Assess the portability of /path/to/my-plugin using plugin-portability -``` - -List available skills with `/skills list`. - -### Antigravity - -#### Skill-only install - -Copy skills to the Antigravity skills directory: +Browse the gallery at [geminicli.com/extensions](https://geminicli.com/extensions/) and search for **plugin-portability**, or install directly: ```bash -cp -r skills/ .agents/skills/ +gemini extensions install hiivmind/plugin-portability ``` -Or for global install: +With version pin: ```bash -cp -r skills/ ~/.gemini/antigravity/skills/ +gemini extensions install hiivmind/plugin-portability --ref ``` -#### Extension install +### Install from GitHub ```bash -antigravity --install-extension hiivmind/plugin-portability +gemini extensions install hiivmind/plugin-portability ``` -#### Using the skills - -Antigravity discovers skills automatically. Mention a skill by name and the agent will activate it: - -``` -Run plugin-portability on /path/to/my-plugin -``` - -### OpenClaw - -#### ClawHub install - -```bash -openclaw plugins install plugin-portability -``` - -#### npm install +### Install from local clone ```bash -npm install plugin-portability +gemini extensions link /path/to/plugin-portability ``` -#### Local install +Changes are reflected immediately without reinstalling. -Add the plugin path to `openclaw.json`: +### Verify -```json -{ - "plugins.load.paths": ["/path/to/plugin-portability"] -} +```bash +gemini extensions list ``` -#### Using the skills +Look for `plugin-portability` in the output. -OpenClaw discovers skills automatically. Mention a skill by name and the agent will activate it: +## Codex -``` -Run plugin-portability on /path/to/my-plugin -``` +### Install from registry -### Codex +Open `/plugins` in Codex, search for **plugin-portability**, and install it. -#### GitHub marketplace install +### Install from GitHub -Register the repo as a Codex marketplace: +Register the repo as a marketplace source: ```bash -codex marketplace add hiivmind/plugin-portability +codex plugin marketplace add hiivmind/plugin-portability ``` -This adds a marketplace entry to `~/.codex/config.toml`. - Then open `/plugins` in Codex and install `plugin-portability`. -Codex persists the plugin enablement as a separate config entry: - -```toml -[plugins."plugin-portability@plugin-portability-marketplace"] -enabled = true -``` - -#### Local development install - -Use this only when you are intentionally testing a local checkout rather than installing from GitHub. +### Install from local clone ```bash -codex marketplace add /path/to/plugin-portability +codex plugin marketplace add /path/to/plugin-portability ``` Then open `/plugins` in Codex and install `plugin-portability`. -#### Skill-discovery fallback +### Platform notes -If you only want the raw skills and do not need Codex plugin packaging, clone the repo and expose the skills directory: +**Context file:** Codex uses `AGENTS.md` as its primary context file. -```bash -git clone https://github.com/hiivmind/plugin-portability -ln -s $(pwd)/plugin-portability/skills ~/.agents/skills/plugin-portability +**Hooks:** If this plugin includes hooks, enable the Codex hooks feature flag: + +```toml +# ~/.codex/config.toml +[features] +codex_hooks = true ``` -Use this as a fallback path, not the default install story for this repo. +Without this flag, hooks are silently ignored. -#### Context file +**Multi-agent:** If this plugin's skills use subagent dispatch, confirm multi-agent mode is enabled: -Codex uses `AGENTS.md` as its primary context file. +```toml +# ~/.codex/config.toml +[features] +multi_agent = true +``` -#### Verify +### Verify Start a new Codex session and check one of: - `/plugins` shows `plugin-portability` as installed - `~/.codex/config.toml` contains both the marketplace entry and the enabled plugin entry -- `$plugin-portability` resolves in a fresh session +- the relevant `$` skill resolves in a fresh session -#### Using the skills +## Antigravity -In Codex, invoke skills with the `$` prefix: +### Install from GitHub +```bash +git clone hiivmind/plugin-portability +cp -R plugin-portability/.agents/skills/plugin-portability .agents/skills/ ``` -$plugin-portability -$plugin-portability -``` - -## Adding Another Platform -Already have the repo cloned for one platform? Add others by pointing them at the same checkout. - -### Claude Code - -Point Claude Code at your existing checkout: +Or for global scope: ```bash -claude --plugin-dir /path/to/existing/plugin-portability +cp -R plugin-portability/.agents/skills/plugin-portability ~/.gemini/antigravity/skills/ ``` -Or add to `.claude/settings.json` for persistent access: +### Install from local clone -```json -{ - "extraKnownMarketplaces": { - "plugin-portability-marketplace": { - "source": { - "source": "github", - "repo": "hiivmind/plugin-portability" - } - } - } -} +```bash +cp -R /path/to/plugin-portability/.agents/skills/plugin-portability .agents/skills/ ``` -### Cursor - -Symlink your existing checkout into Cursor's plugin directory: +Or for global scope: ```bash -ln -s /path/to/existing/plugin-portability ~/.cursor/plugins/local/plugin-portability +cp -R /path/to/plugin-portability/.agents/skills/plugin-portability ~/.gemini/antigravity/skills/ ``` -Restart Cursor (Developer: Reload Window). +### Verify + +Start a new Antigravity session and check that skills from Plugin Portability appear in the skill listing at conversation start. -### Gemini CLI +## OpenClaw -Link Gemini to your existing checkout: +### Install from registry + +Install from ClawHub: ```bash -gemini extensions link /path/to/existing/plugin-portability +openclaw plugins install clawhub:plugin-portability ``` -### Antigravity - -Copy skills from your existing checkout: +Or from npm: ```bash -cp -r /path/to/existing/plugin-portability/skills/ .agents/skills/ +openclaw plugins install @org/plugin-portability ``` -Or install as an extension: +### Install from GitHub + +Clone the repo and install locally: ```bash -antigravity --install-extension /path/to/existing/plugin-portability +git clone hiivmind/plugin-portability +openclaw plugins install -l ./plugin-portability ``` -### OpenClaw +### Install from local clone -Add the checkout path to `openclaw.json`: +Add to `plugins.load.paths` in `~/.openclaw/openclaw.json`: ```json { - "plugins.load.paths": ["/path/to/existing/plugin-portability"] + "plugins": { + "load": { + "paths": ["/path/to/plugin-portability"] + } + } } ``` -### Codex - -For local development against an existing checkout, register the checkout itself as a marketplace: +### Verify ```bash -codex marketplace add /path/to/existing/plugin-portability +openclaw plugins list ``` -Then open `/plugins` in Codex and install `plugin-portability`. - -If you only want skill discovery, symlink the skills directory from your existing checkout: - -```bash -ln -s /path/to/existing/plugin-portability/skills ~/.agents/skills/plugin-portability -``` +Skills from Plugin Portability should appear in the plugin listing. diff --git a/PUBLISHING.md b/PUBLISHING.md index 0718eee..9a49b7f 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -1,25 +1,18 @@ # Publishing & Discoverability -How to get **Plugin Portability** discovered and installed on each platform. +How to get **Plugin Portability** listed and distributed on each platform. See [INSTALL.md](INSTALL.md) for end-user installation instructions. ## Claude Code -No public marketplace — distribution is via Git repositories. +### Prerequisites -### Publishing +Create `.claude-plugin/marketplace.json` listing the plugins the repo contains. No submission or review process — any Git repo with a valid marketplace manifest can be consumed. -Create a `.claude-plugin/marketplace.json` in your repo. No submission or review process — any Git repo with a valid marketplace manifest can be consumed. +### Team / org distribution -### How users find and install Plugin Portability - -1. Register the marketplace: `/plugin marketplace add hiivmind/plugin-portability` -2. Install: `/plugin install plugin-portability@plugin-portability-marketplace` - -### Team distribution - -Teams can auto-register the marketplace by adding to their project `.claude/settings.json`: +Add to the team's project `.claude/settings.json` so teammates get the marketplace automatically: ```json { @@ -34,125 +27,81 @@ Teams can auto-register the marketplace by adding to their project `.claude/sett } ``` -## Cursor +Auto-enable plugins via `"enabledPlugins"` in the same settings file. -Public marketplace at `cursor.com/marketplace` (curated, manually reviewed). +## Cursor -### Publishing +### Prerequisites -1. Ensure the plugin is open-source in a Git repository -2. `.cursor-plugin/plugin.json` manifest must be present -3. Submit at `cursor.com/marketplace/publish` -4. Every plugin and update is manually reviewed +- Plugin must be open-source in a Git repository +- `.cursor-plugin/plugin.json` manifest required (minimum: `name` field) -### How users find and install Plugin Portability +### Submit to registry -- Browse the marketplace at `cursor.com/marketplace` -- In Agent chat: `/add-plugin hiivmind/plugin-portability` +1. Go to `cursor.com/marketplace/publish` +2. Submit the plugin for review +3. Every plugin and update is manually reviewed before listing -### Team distribution +### Team / org distribution -Cursor 2.6+ (Teams/Enterprise): admins import GitHub repos as team marketplaces via Dashboard Settings. +Cursor 2.6+ (Teams/Enterprise): admins import GitHub repos as team marketplaces via Dashboard Settings. Admins set plugins as required or optional. ## Gemini CLI -Extensions gallery at [geminicli.com/extensions](https://geminicli.com/extensions/). +### Prerequisites -### Publishing +Include `gemini-extension.json` at the repo root with `name`, `version`, and `description` fields. The repo must be public on GitHub. -Publish as a GitHub repository with a `gemini-extension.json` manifest (requires `name`, `version`, `description`). Extensions are not vetted by Google. +### Submit to registry -### How users find and install Plugin Portability +No manual submission process. To get listed in the gallery: -```bash -gemini extensions install hiivmind/plugin-portability -``` +1. Add the `gemini-cli-extension` topic to the repository's About section on GitHub +2. The gallery crawler indexes tagged repos daily; listing appears within ~1 week -Users can browse the gallery or install directly from the GitHub URL. +Browse existing extensions at [geminicli.com/extensions](https://geminicli.com/extensions/). -## Antigravity - -Published to the [OpenVSX](https://open-vsx.org/) registry. +## Codex -### Publishing +### Prerequisites -Package the plugin as a VSIX extension and publish to OpenVSX: +- `.codex-plugin/plugin.json` manifest +- `.agents/plugins/marketplace.json` listing the plugin with source path, description, version +- For a single-plugin GitHub repo, the marketplace entry should point at the repo root with `source.path: "./"` -```bash -antigravity publish -``` +Self-serve publishing to the official Plugin Directory is coming soon. In the meantime, plugins are distributed via Git repos with marketplace manifests. -Extensions are reviewed by the OpenVSX team before listing. +## Antigravity -### How users find and install Plugin Portability +### Prerequisites -```bash -antigravity --install-extension hiivmind.plugin-portability -``` +- `.agents/skills/plugin-portability/SKILL.md` with standard frontmatter (`name`, `description`) +- Optional: `AGENTS.md` context file -Users can also browse and install from the OpenVSX web registry. +Antigravity auto-discovers skills from `.agents/skills/` directories — no platform-specific manifest or registry submission required. Share the Git repository URL to distribute. ## OpenClaw -Published to [ClawHub](https://clawhub.dev/) and via npm. - -### Publishing - -Publish as an npm package and register on ClawHub: - -```bash -npm publish -``` - -Then submit to ClawHub for listing. No formal review process. +### Prerequisites -### How users find and install Plugin Portability +- `openclaw/openclaw.plugin.json` manifest with `id` and `configSchema` (required for native plugins) +- `package.json` with `openclaw.extensions` and `openclaw.compat` (required for npm distribution) +- Optional: `AGENTS.md` context file, `skills/*/SKILL.md` for skill-bearing plugins -**npm:** - -```bash -npm install -g @hiivmind/plugin-portability -``` +### Submit to registry **ClawHub:** -Browse [clawhub.dev](https://clawhub.dev/) and install directly from the listing. - -## Codex - -Two publishing paths — choose based on what you're distributing. - -### Skill discovery (lightweight) - -For repos that are mostly instructions with no plugin UI metadata: - -- Submit a PR to `github.com/openai/skills` for inclusion in the curated catalog -- Or publish as a standalone GitHub repo — users install through Codex skill discovery -- Only recommend `$skill-installer install hiivmind/plugin-portability` when the distributed artifact is truly a skill-only repo and does not depend on root-level plugin manifests, hooks, or shared context files - -### Plugin packaging (full) - -For first-class plugin packages with marketplace metadata: - -- Create `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` -- For a single-plugin GitHub repo, the marketplace entry should point at the repo root with `source.path: "./"` -- Users register via `codex marketplace add hiivmind/plugin-portability` -- Users then enable the plugin from `/plugins` -- Public self-serve plugin publishing is coming soon per OpenAI docs - -### How users find and install Plugin Portability - -**Skill-only repo:** - ```bash -git clone hiivmind/plugin-portability -ln -s $(pwd)/plugin-portability/skills ~/.agents/skills/plugin-portability +npm i -g clawhub +clawhub login +clawhub package publish your-org/plugin-portability ``` -**Plugin repo:** +**npm (alternative):** ```bash -codex marketplace add hiivmind/plugin-portability +npm publish --access public ``` -Then enable `plugin-portability` from `/plugins`. +Users can install from either registry. Bare names check ClawHub first, then npm. diff --git a/README.md b/README.md index c022b4f..ae3f25f 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ gemini extensions install https://github.com/hiivmind/plugin-portability **Codex:** ```bash -codex marketplace add hiivmind/plugin-portability +codex plugin marketplace add hiivmind/plugin-portability ``` Then open `/plugins` in Codex and install `plugin-portability`. @@ -93,7 +93,8 @@ Then open `/plugins` in Codex and install `plugin-portability`. **Antigravity:** ```bash -antigravity --install-extension hiivmind/plugin-portability +git clone https://github.com/hiivmind/plugin-portability +cp -R plugin-portability/.agents/skills/plugin-portability .agents/skills/ ``` **OpenClaw:** diff --git a/docs/reconciliation-matrix.md b/docs/reconciliation-matrix.md index 1a410b3..3132fcc 100644 --- a/docs/reconciliation-matrix.md +++ b/docs/reconciliation-matrix.md @@ -204,14 +204,15 @@ Track every platform-specific claim in the plugin against researched facts in |-------|---------|---------------|--------| | Claude Code publishing | Git repos, marketplace, team distribution | Confirmed: marketplace add, extraKnownMarketplaces | Correct | | Cursor publishing | cursor.com/marketplace, /add-plugin | Confirmed: marketplace submission, /add-plugin install | Correct | -| Gemini CLI publishing | geminicli.com/extensions, extensions install | Confirmed: gallery, extensions install command | Correct | -| Codex skills publishing | $skill-installer, GitHub repos | Confirmed: $skill-installer, standard skill paths | Fixed (removed unverifiable .curated/.experimental claims) | -| Codex plugins publishing | marketplace add, not yet public | Confirmed: codex plugin marketplace add | Correct | -| Antigravity publishing | Claimed antigravity.dev/plugins marketplace | No official marketplace exists; distribution via git repos and npm installers | Fixed (rewrote section) | -| Antigravity install commands | Claimed `antigravity plugin add` | No such CLI command; install by copying to .agents/skills/ | Fixed (rewrote section) | -| OpenClaw registry | Claimed openclaw.dev/registry | Registry is ClawHub at clawhub.ai | Fixed (corrected URL and name) | -| OpenClaw install commands | Claimed `openclaw install ` | Actual: `openclaw plugins install clawhub:` or `openclaw skills install ` | Fixed (corrected syntax) | -| OpenClaw manifest requirement | Claimed "no manifest required" | `openclaw.plugin.json` with id and configSchema IS required for native plugins | Fixed (added requirement) | +| Gemini CLI publishing | Auto-indexed via `gemini-cli-extension` GitHub topic, 908+ extensions | Confirmed: daily crawler, no manual submission | Fixed (added auto-discovery mechanism, updated count from 897) | +| Gemini CLI local dev | `link` reflects changes immediately | Confirmed: no restart needed | Fixed (previously said restart required) | +| Codex skills install | `$skill-installer ` or manual copy/symlink | Confirmed: no `install` subcommand or `search` subcommand verified | Fixed (removed fabricated `$skill-installer install ` and `search`) | +| Codex plugins publishing | marketplace add, official directory coming soon | Confirmed: codex plugin marketplace add, /plugins browser | Correct | +| Antigravity publishing | Git repos, manual copy to .agents/skills/ | No official marketplace; no npm installer recommended | Fixed (removed antigravity-awesome-skills prominence, VS Code extensions section) | +| OpenClaw registry | ClawHub at clawhub.ai | Confirmed: clawhub CLI, npm secondary | Correct | +| OpenClaw install commands | `openclaw plugins install clawhub:` | Confirmed | Correct | +| OpenClaw manifest requirement | `openclaw.plugin.json` with id and configSchema required | Confirmed for native plugins | Correct | +| Template structure | Three overlapping sets (install, adding-platform, publishing) | Two audience-based sets (`install/`, `publish/`) with journey structure | Fixed (restructured per 2026-04-28 spec) | ### injection-checks.md diff --git a/docs/superpowers/plans/2026-04-28-adding-a-platform-guide.md b/docs/superpowers/plans/2026-04-28-adding-a-platform-guide.md new file mode 100644 index 0000000..78bec8f --- /dev/null +++ b/docs/superpowers/plans/2026-04-28-adding-a-platform-guide.md @@ -0,0 +1,388 @@ +# Adding a Platform Guide Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Create the end-to-end guide for adding a new platform to plugin-portability, and trim CONTRIBUTING.md to point to it. + +**Architecture:** One new document at `lib/principles/adding-a-platform.md` (architecture overview + 7 phased checklists + cross-cutting updates + final verification). One edit to `CONTRIBUTING.md` replacing the 6-line section with a one-liner. + +**Tech Stack:** Markdown + +--- + +### Task 1: Create the adding-a-platform guide + +**Files:** +- Create: `lib/principles/adding-a-platform.md` + +- [ ] **Step 1: Write the guide** + +Write to `lib/principles/adding-a-platform.md`: + +````markdown +# Adding a New Platform + +End-to-end guide for adding a new platform to plugin-portability. Covers the architecture, what to create in what order, and how to verify each step. + +Audience: human contributors and coding agents. Every phase ends with a verification gate — concrete checks that can be evaluated mechanically or by inspection. + +--- + +## Architecture + +A platform is represented by 7 artifact types. They have a strict dependency order: + +``` +Research doc (docs/platforms/.md) + ↓ sourced facts with citations +Platform spec (lib/references/platforms/.md) + ↓ structured PlatformSpec dictionary + ├→ Rubric (lib/rubrics/.yaml) + │ conditions reference spec fields + ├→ Manifest templates (lib/templates/manifests//) + │ field names from spec + ├→ Install/publish templates (lib/templates/install-docs/) + │ commands from spec + ├→ Pattern updates (lib/patterns/) + │ hook events, publishing mechanisms + └→ Skill pseudocode (skills/plugin-portability/SKILL.md) + platform in selection list and ELSE fallback +``` + +### Key principles + +**Research is the source of truth.** Every platform-specific claim in any file traces back to a cited fact in the research doc. When research and other files disagree, research wins. + +**The platform spec is the single structured representation.** Rubrics, templates, and patterns all derive from the spec — they don't independently describe platform behavior. The spec conforms to the `PlatformSpec` type defined in `lib/references/platform-api.md`. + +**Rubric conditions are scored, not prose.** Each condition has an ID, a type (`checkable` or `judgement`), points, and pseudocode. The schema is defined in `lib/rubrics/rubric-framework.md`. + +**Templates use `{{mustache}}` variables.** They're resolved at generation time for a specific target plugin. Variables fall into three categories: +- **Core:** `{{name}}`, `{{displayName}}`, `{{version}}`, `{{description}}`, `{{repository}}`, `{{marketplaceName}}` +- **Package metadata:** `{{author.name}}`, `{{author.email}}`, `{{license}}`, `{{keywords}}`, `{{homepage}}` +- **Generated:** `{{skillsList}}` and any platform-specific values produced by builder-mode templates + +### Existing files to read first + +| File | What it tells you | +|------|-------------------| +| `lib/references/platform-api.md` | PlatformSpec type definition and lookup functions | +| `lib/rubrics/rubric-framework.md` | Condition schema (id, type, component, critical, points, check) | +| `lib/principles/pseudocode-principles.md` | How to write pseudocode, registries, and LOAD_AND_VERIFY gates | +| `lib/references/templates/registry.md` | Template registry (schema, platform, mode, paths) | +| An existing platform's full set of artifacts | Structural reference for every phase | + +--- + +## Phase 1: Research + +**Create:** `docs/platforms/.md` + +**Inputs:** +- Platform's official documentation, GitHub repos, release announcements +- An existing research doc (e.g., `docs/platforms/cursor.md`) as structural reference + +**What goes in this file:** + +Sourced documentation organized into the 9 standard sections. Every factual claim must have an inline `[source](url)` citation. + +The 9 sections are: + +1. Plugin Structure +2. Manifest +3. Skills +4. Context Files +5. Hooks +6. Tool Mapping +7. Install and Distribution +8. Runtime Components +9. Sources + +Follow the heading format of existing research docs (`## 1. Plugin Structure`, etc.). + +**Verification gate:** +- [ ] File exists at `docs/platforms/.md` +- [ ] All 9 standard sections present +- [ ] Every factual claim has a `[source](url)` citation +- [ ] No claims copied from another platform's research doc without independent verification + +--- + +## Phase 2: Platform spec + +**Create:** `lib/references/platforms/.md` + +**Inputs:** +- Research doc from Phase 1 +- `lib/references/platform-api.md` (PlatformSpec type definition) +- An existing spec (e.g., `lib/references/platforms/cursor.md`) as structural reference + +**What goes in this file:** + +A `REGISTRY[""]` block conforming to the PlatformSpec type. Every field must be populated — use `null` for capabilities the platform doesn't support. Key sections: + +- **tools** — map canonical operations (`file.read`, `shell.execute`, etc.) to the platform's native tool names +- **hooks** — event names, config path, naming convention (PascalCase/camelCase/snake_case), structure +- **context** — primary context file, secondary files, priority rules +- **skills** — path, frontmatter fields, discovery mechanism +- **marketplace** — marketplace path or `null` + +**Verification gate:** +- [ ] File exists at `lib/references/platforms/.md` +- [ ] Contains `REGISTRY[""] = {` +- [ ] Every field in PlatformSpec type has a value (`null` is valid, missing is not) +- [ ] Tool entries reference actual platform tool names from the research doc +- [ ] Hook events match the platform's actual event names and casing convention +- [ ] No fields copy-pasted from another platform without verification against research + +--- + +## Phase 3: Rubric + +**Create:** `lib/rubrics/.yaml` + +**Inputs:** +- Platform spec from Phase 2 +- `lib/rubrics/rubric-framework.md` (condition schema) +- `lib/principles/pseudocode-principles.md` (pseudocode patterns) +- An existing rubric (e.g., `lib/rubrics/cursor.yaml`) as structural reference + +**What goes in this file:** + +YAML file with a header block and a `categories` map. The header declares the platform, manifest path, context files, and hooks path. Categories group conditions by concern. + +Each condition has: + +```yaml +- id: ._.. + type: checkable | judgement + component: + critical: true | false + points: 1 + check: | + pseudocode (checkable) or prose description (judgement) + template: optional — path to template that fixes this condition +``` + +Standard categories: `1_manifest`, `2_skills`, `3_context`, `4_hooks`, `5_toolmap`, `6_install`. + +Pseudocode in `check` fields should use LOAD_AND_VERIFY / GLOB_AND_VERIFY patterns from `lib/principles/pseudocode-principles.md`. + +**Verification gate:** +- [ ] File exists at `lib/rubrics/.yaml` +- [ ] Every condition has all required fields (`id`, `type`, `component`, `critical`, `points`, `check`) +- [ ] Condition IDs follow the format `._..` +- [ ] `type` is either `checkable` or `judgement` +- [ ] `check` pseudocode for `checkable` conditions references concrete file paths or spec fields +- [ ] YAML parses without errors: `python3 -c "import yaml; yaml.safe_load(open('lib/rubrics/.yaml'))"` + +--- + +## Phase 4: Manifest templates + +**Create:** `lib/templates/manifests//` with one `.tmpl` file per manifest the platform requires. + +**Inputs:** +- Platform spec from Phase 2 (manifest fields) +- Research doc (manifest format and required fields) +- `lib/references/templates/registry.md` (template registry) +- An existing manifest template directory (e.g., `lib/templates/manifests/cursor-plugin/`) as structural reference + +**What goes in these files:** + +JSON or TOML template files using `{{mustache}}` variables. Each template should have a `{{! fixes: }}` comment at the top linking it to the rubric condition it satisfies. + +Fields must match what the platform actually requires per the research doc. + +**Verification gate:** +- [ ] Directory exists at `lib/templates/manifests//` +- [ ] At least one `.tmpl` file present +- [ ] Template files are valid JSON/TOML (ignoring `{{mustache}}` placeholders) +- [ ] Required fields from the platform spec are present in the template +- [ ] Every `{{variable}}` is either a core variable, a package metadata variable, or documented in the template registry +- [ ] New template entry added to `lib/references/templates/registry.md` with correct `schema`, `platform`, `mode`, `template_path`, `target_path` + +--- + +## Phase 5: Install and publish templates + +**Create:** +- `lib/templates/install-docs/install/.md` +- `lib/templates/install-docs/publish/.md` + +**Inputs:** +- Platform spec from Phase 2 (install commands, marketplace info) +- Research doc (install and distribution section) +- `lib/patterns/publishing-and-discoverability.md` +- Existing install/publish templates as structural reference + +**Install template structure:** + +Follow the journey-structured format. Sections are conditional — omit when they don't apply: + +1. **Install from registry** — only if the platform has a registry +2. **Install from GitHub** — always present +3. **Install from local clone** — always present +4. **Verify** — always present + +Use `{{mustache}}` variables throughout. + +**Publish template structure:** + +Author-facing only. No install commands: + +1. **Prerequisites** — always present (required manifests/metadata) +2. **Submit to registry** — only if the platform has a submission process +3. **Team / org distribution** — only if the platform has a mechanism + +**Verification gate:** +- [ ] Both files exist at the expected paths +- [ ] Install template has "Install from GitHub", "Install from local clone", and "Verify" sections +- [ ] Install template has "Install from registry" only if the platform has a registry +- [ ] Publish template has "Prerequisites" section +- [ ] Publish template contains zero install commands (`grep -c "install\|clone\|cp " ` returns 0 or only false positives) +- [ ] Both templates use `{{mustache}}` variables, not hardcoded values + +--- + +## Phase 6: Pattern updates + +**Modify:** Files in `lib/patterns/` + +**Inputs:** +- Research doc from Phase 1 +- Platform spec from Phase 2 + +**What to update:** + +- `lib/patterns/publishing-and-discoverability.md` — add platform to the quick reference table and add a dedicated platform section +- `lib/patterns/hook-merging.md` — add the platform's hook format if it supports hooks +- Other pattern files as needed based on platform capabilities + +**Verification gate:** +- [ ] `grep "" lib/patterns/publishing-and-discoverability.md` returns hits +- [ ] If the platform has hooks: `grep "" lib/patterns/hook-merging.md` returns hits +- [ ] All platform-specific claims in pattern files are consistent with the research doc + +--- + +## Phase 7: Skill integration + +**Modify:** `skills/plugin-portability/SKILL.md` + +**Inputs:** All artifacts from Phases 1–6. + +**What to update:** + +Three locations in the skill's intent-gathering pseudocode: + +1. **The `options` array** in the "Select target platforms" question — add a new entry with `label` and `description` +2. **The `ELSE` fallback list** — the `platforms = ["claude-code", "cursor", ...]` line that defines the "All platforms" default +3. **The "All platforms" option description** — if it enumerates platform names, add the new one + +**Verification gate:** +- [ ] Platform appears in the `options` array with `label` and `description` +- [ ] `description` accurately summarizes the platform (no fabricated features) +- [ ] Platform appears in the `ELSE` fallback list: `grep 'platforms = \[' skills/plugin-portability/SKILL.md` shows the new platform +- [ ] "All platforms" option description includes the new platform +- [ ] Template file count increased: `find lib/templates/install-docs -name "*.md" | wc -l` is 2 more than before + +--- + +## Cross-cutting updates + +Files that need a mention of the new platform but don't have their own phase: + +| File | What to update | +|------|----------------| +| `docs/reconciliation-matrix.md` | Add a new section for the platform tracking claim verification status | +| `README.md` | Add platform to the "What it does" artifacts table | +| `CHANGELOG.md` | Add an entry for the new platform | + +--- + +## Final verification checklist + +Run these end-to-end checks after all phases and cross-cutting updates are complete: + +- [ ] `find lib/references/platforms -name "*.md" | wc -l` matches expected platform count +- [ ] `find lib/rubrics -name "*.yaml" | wc -l` matches expected platform count +- [ ] `find lib/templates/install-docs/install -name "*.md" | wc -l` matches expected platform count +- [ ] `find lib/templates/install-docs/publish -name "*.md" | wc -l` matches expected platform count +- [ ] Platform appears in the skill's platform selection options and ELSE fallback list +- [ ] Platform appears in `lib/patterns/publishing-and-discoverability.md` quick reference table +- [ ] Phase 7 glob `lib/templates/install-docs/**/*.md` matches all template files +- [ ] No hardcoded platform counts in README or CONTRIBUTING that are now stale +- [ ] `INSTALL.md` and `PUBLISHING.md` are regenerated from the new templates (or noted as needing regeneration for a specific target plugin) +```` + +- [ ] **Step 2: Verify the file was written correctly** + +Run: `grep -c "^## Phase\|^## Architecture\|^## Cross-cutting\|^## Final verification" lib/principles/adding-a-platform.md` + +Expected: `4` (Architecture, Cross-cutting updates, Final verification checklist — note that "## Phase" won't match because phases use `##` not `## Phase` literally; the actual check is for the 4 top-level sections). + +Corrected run: `grep -c "^## " lib/principles/adding-a-platform.md` + +Expected: `11` (Architecture + Phase 1–7 + Cross-cutting updates + Final verification checklist = 11 `## ` headings). + +- [ ] **Step 3: Verify no placeholders** + +Run: `grep -in "TBD\|TODO\|FIXME\|placeholder\|fill in" lib/principles/adding-a-platform.md` + +Expected: no output. + +- [ ] **Step 4: Commit** + +```bash +git add lib/principles/adding-a-platform.md +git commit -m "docs: add end-to-end guide for adding a new platform" +``` + +--- + +### Task 2: Trim CONTRIBUTING.md + +**Files:** +- Modify: `CONTRIBUTING.md:18-26` + +- [ ] **Step 1: Replace the "Adding a New Platform" section** + +In `CONTRIBUTING.md`, replace lines 18–26 (the current "Adding a New Platform" section): + +```markdown +## Adding a New Platform + +1. Create a platform documentation file in `docs/platforms/` +2. Add a manifest template in `lib/templates/manifests/` +3. Add install doc templates in `lib/templates/install-docs/` +4. Add a platform rubric in `lib/rubrics/` +5. Update the portability skill (`skills/plugin-portability/SKILL.md`) to handle the new platform +6. Update the assessment rubric (`docs/assessment-rubric.md`) with scoring criteria +``` + +With: + +```markdown +## Adding a New Platform + +See [lib/principles/adding-a-platform.md](lib/principles/adding-a-platform.md) for the full guide — architecture overview, phased checklist, and verification gates. +``` + +- [ ] **Step 2: Verify the change** + +Run: `grep -A1 "## Adding a New Platform" CONTRIBUTING.md` + +Expected output: +``` +## Adding a New Platform + +See [lib/principles/adding-a-platform.md](lib/principles/adding-a-platform.md) for the full guide — architecture overview, phased checklist, and verification gates. +``` + +- [ ] **Step 3: Commit** + +```bash +git add CONTRIBUTING.md +git commit -m "docs: point CONTRIBUTING.md to the full adding-a-platform guide" +``` diff --git a/docs/superpowers/plans/2026-04-28-install-publish-template-restructure.md b/docs/superpowers/plans/2026-04-28-install-publish-template-restructure.md new file mode 100644 index 0000000..0c5f49b --- /dev/null +++ b/docs/superpowers/plans/2026-04-28-install-publish-template-restructure.md @@ -0,0 +1,1064 @@ +# Install & Publish Template Restructure Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace three overlapping template sets (install, adding-platform, publishing) with two journey-structured sets (install, publish) serving two distinct audiences (plugin user, plugin author). + +**Architecture:** Delete 19 old template files across 3 directories. Create 16 new files across 2 directories plus 2 headers. Regenerate INSTALL.md and PUBLISHING.md from the new templates. Update reconciliation matrix. + +**Tech Stack:** Markdown templates with `{{mustache}}` variables (`{{name}}`, `{{displayName}}`, `{{repository}}`, `{{marketplaceName}}`) + +--- + +### Task 1: Create install/ templates (Claude Code, Cursor, Gemini CLI) + +**Files:** +- Create: `lib/templates/install-docs/install/claude-code.md` +- Create: `lib/templates/install-docs/install/cursor.md` +- Create: `lib/templates/install-docs/install/gemini-cli.md` + +- [ ] **Step 1: Create the install/ directory** + +Run: `mkdir -p lib/templates/install-docs/install` + +- [ ] **Step 2: Write claude-code.md install template** + +Write to `lib/templates/install-docs/install/claude-code.md`: + +```markdown +## Claude Code + +### Install from GitHub + +Register the plugin's marketplace, then install: + +```bash +/plugin marketplace add {{repository}} +/plugin install {{name}}@{{marketplaceName}} +``` + +### Install from local clone + +```bash +claude --plugin-dir /path/to/{{name}} +``` + +Or add to `.claude/settings.json` for persistent access: + +```json +{ + "extraKnownMarketplaces": { + "{{marketplaceName}}": { + "source": { + "source": "github", + "repo": "{{repository}}" + } + } + } +} +``` + +### Verify + +```bash +claude plugin list +``` + +Look for `{{name}}` in the output. +``` + +- [ ] **Step 3: Write cursor.md install template** + +Write to `lib/templates/install-docs/install/cursor.md`: + +```markdown +## Cursor + +### Install from registry + +Search for **{{name}}** in the Cursor marketplace panel, visit `cursor.com/marketplace`, or run in Agent chat: + +``` +/add-plugin {{repository}} +``` + +### Install from GitHub + +``` +/add-plugin {{repository}} +``` + +### Install from local clone + +Symlink or copy the plugin directory and restart Cursor (Developer: Reload Window): + +```bash +ln -s /path/to/{{name}} ~/.cursor/plugins/local/{{name}} +``` + +### Verify + +Open Cursor and check that skills from {{name}} appear when typing `/` in chat. Rules should appear in Cursor Settings > Rules with the plugin name prefix. +``` + +- [ ] **Step 4: Write gemini-cli.md install template** + +Write to `lib/templates/install-docs/install/gemini-cli.md`: + +```markdown +## Gemini CLI + +### Install from registry + +Browse the gallery at [geminicli.com/extensions](https://geminicli.com/extensions/) and search for **{{name}}**, or install directly: + +```bash +gemini extensions install {{repository}} +``` + +With version pin: + +```bash +gemini extensions install {{repository}} --ref +``` + +### Install from GitHub + +```bash +gemini extensions install {{repository}} +``` + +### Install from local clone + +```bash +gemini extensions link /path/to/{{name}} +``` + +Changes are reflected immediately without reinstalling. + +### Verify + +```bash +gemini extensions list +``` + +Look for `{{name}}` in the output. +``` + +- [ ] **Step 5: Commit** + +```bash +git add lib/templates/install-docs/install/claude-code.md lib/templates/install-docs/install/cursor.md lib/templates/install-docs/install/gemini-cli.md +git commit -m "feat: add journey-structured install templates for Claude Code, Cursor, Gemini CLI" +``` + +--- + +### Task 2: Create install/ templates (Codex, Antigravity, OpenClaw) + +**Files:** +- Create: `lib/templates/install-docs/install/codex.md` +- Create: `lib/templates/install-docs/install/antigravity.md` +- Create: `lib/templates/install-docs/install/openclaw.md` + +- [ ] **Step 1: Write codex.md install template** + +Write to `lib/templates/install-docs/install/codex.md`: + +```markdown +## Codex + +### Install from registry + +Open `/plugins` in Codex, search for **{{name}}**, and install it. + +### Install from GitHub + +Register the repo as a marketplace source: + +```bash +codex plugin marketplace add {{repository}} +``` + +Then open `/plugins` in Codex and install `{{name}}`. + +### Install from local clone + +```bash +codex plugin marketplace add /path/to/{{name}} +``` + +Then open `/plugins` in Codex and install `{{name}}`. + +### Platform notes + +**Context file:** Codex uses `AGENTS.md` as its primary context file. + +**Hooks:** If this plugin includes hooks, enable the Codex hooks feature flag: + +```toml +# ~/.codex/config.toml +[features] +codex_hooks = true +``` + +Without this flag, hooks are silently ignored. + +**Multi-agent:** If this plugin's skills use subagent dispatch, confirm multi-agent mode is enabled: + +```toml +# ~/.codex/config.toml +[features] +multi_agent = true +``` + +### Verify + +Start a new Codex session and check one of: + +- `/plugins` shows `{{name}}` as installed +- `~/.codex/config.toml` contains both the marketplace entry and the enabled plugin entry +- the relevant `$` skill resolves in a fresh session +``` + +- [ ] **Step 2: Write antigravity.md install template** + +Write to `lib/templates/install-docs/install/antigravity.md`: + +```markdown +## Antigravity + +### Install from GitHub + +```bash +git clone {{repository}} +cp -R {{name}}/.agents/skills/{{name}} .agents/skills/ +``` + +Or for global scope: + +```bash +cp -R {{name}}/.agents/skills/{{name}} ~/.gemini/antigravity/skills/ +``` + +### Install from local clone + +```bash +cp -R /path/to/{{name}}/.agents/skills/{{name}} .agents/skills/ +``` + +Or for global scope: + +```bash +cp -R /path/to/{{name}}/.agents/skills/{{name}} ~/.gemini/antigravity/skills/ +``` + +### Verify + +Start a new Antigravity session and check that skills from {{displayName}} appear in the skill listing at conversation start. +``` + +- [ ] **Step 3: Write openclaw.md install template** + +Write to `lib/templates/install-docs/install/openclaw.md`: + +```markdown +## OpenClaw + +### Install from registry + +Install from ClawHub: + +```bash +openclaw plugins install clawhub:{{name}} +``` + +Or from npm: + +```bash +openclaw plugins install @org/{{name}} +``` + +### Install from GitHub + +Clone the repo and install locally: + +```bash +git clone {{repository}} +openclaw plugins install -l ./{{name}} +``` + +### Install from local clone + +Add to `plugins.load.paths` in `~/.openclaw/openclaw.json`: + +```json +{ + "plugins": { + "load": { + "paths": ["/path/to/{{name}}"] + } + } +} +``` + +### Verify + +```bash +openclaw plugins list +``` + +Skills from {{displayName}} should appear in the plugin listing. +``` + +- [ ] **Step 4: Commit** + +```bash +git add lib/templates/install-docs/install/codex.md lib/templates/install-docs/install/antigravity.md lib/templates/install-docs/install/openclaw.md +git commit -m "feat: add journey-structured install templates for Codex, Antigravity, OpenClaw" +``` + +--- + +### Task 3: Create publish/ templates (all 6 platforms) + +**Files:** +- Create: `lib/templates/install-docs/publish/claude-code.md` +- Create: `lib/templates/install-docs/publish/cursor.md` +- Create: `lib/templates/install-docs/publish/gemini-cli.md` +- Create: `lib/templates/install-docs/publish/codex.md` +- Create: `lib/templates/install-docs/publish/antigravity.md` +- Create: `lib/templates/install-docs/publish/openclaw.md` + +- [ ] **Step 1: Create the publish/ directory** + +Run: `mkdir -p lib/templates/install-docs/publish` + +- [ ] **Step 2: Write claude-code.md publish template** + +Write to `lib/templates/install-docs/publish/claude-code.md`: + +```markdown +## Claude Code + +### Prerequisites + +Create `.claude-plugin/marketplace.json` listing the plugins the repo contains. No submission or review process — any Git repo with a valid marketplace manifest can be consumed. + +### Team / org distribution + +Add to the team's project `.claude/settings.json` so teammates get the marketplace automatically: + +```json +{ + "extraKnownMarketplaces": { + "{{marketplaceName}}": { + "source": { + "source": "github", + "repo": "{{repository}}" + } + } + } +} +``` + +Auto-enable plugins via `"enabledPlugins"` in the same settings file. +``` + +- [ ] **Step 3: Write cursor.md publish template** + +Write to `lib/templates/install-docs/publish/cursor.md`: + +```markdown +## Cursor + +### Prerequisites + +- Plugin must be open-source in a Git repository +- `.cursor-plugin/plugin.json` manifest required (minimum: `name` field) + +### Submit to registry + +1. Go to `cursor.com/marketplace/publish` +2. Submit the plugin for review +3. Every plugin and update is manually reviewed before listing + +### Team / org distribution + +Cursor 2.6+ (Teams/Enterprise): admins import GitHub repos as team marketplaces via Dashboard Settings. Admins set plugins as required or optional. +``` + +- [ ] **Step 4: Write gemini-cli.md publish template** + +Write to `lib/templates/install-docs/publish/gemini-cli.md`: + +```markdown +## Gemini CLI + +### Prerequisites + +Include `gemini-extension.json` at the repo root with `name`, `version`, and `description` fields. The repo must be public on GitHub. + +### Submit to registry + +No manual submission process. To get listed in the gallery: + +1. Add the `gemini-cli-extension` topic to the repository's About section on GitHub +2. The gallery crawler indexes tagged repos daily; listing appears within ~1 week + +Browse existing extensions at [geminicli.com/extensions](https://geminicli.com/extensions/). +``` + +- [ ] **Step 5: Write codex.md publish template** + +Write to `lib/templates/install-docs/publish/codex.md`: + +```markdown +## Codex + +### Prerequisites + +- `.codex-plugin/plugin.json` manifest +- `.agents/plugins/marketplace.json` listing the plugin with source path, description, version +- For a single-plugin GitHub repo, the marketplace entry should point at the repo root with `source.path: "./"` + +Self-serve publishing to the official Plugin Directory is coming soon. In the meantime, plugins are distributed via Git repos with marketplace manifests. +``` + +- [ ] **Step 6: Write antigravity.md publish template** + +Write to `lib/templates/install-docs/publish/antigravity.md`: + +```markdown +## Antigravity + +### Prerequisites + +- `.agents/skills/{{name}}/SKILL.md` with standard frontmatter (`name`, `description`) +- Optional: `AGENTS.md` context file + +Antigravity auto-discovers skills from `.agents/skills/` directories — no platform-specific manifest or registry submission required. Share the Git repository URL to distribute. +``` + +- [ ] **Step 7: Write openclaw.md publish template** + +Write to `lib/templates/install-docs/publish/openclaw.md`: + +```markdown +## OpenClaw + +### Prerequisites + +- `openclaw/openclaw.plugin.json` manifest with `id` and `configSchema` (required for native plugins) +- `package.json` with `openclaw.extensions` and `openclaw.compat` (required for npm distribution) +- Optional: `AGENTS.md` context file, `skills/*/SKILL.md` for skill-bearing plugins + +### Submit to registry + +**ClawHub:** + +```bash +npm i -g clawhub +clawhub login +clawhub package publish your-org/{{name}} +``` + +**npm (alternative):** + +```bash +npm publish --access public +``` + +Users can install from either registry. Bare names check ClawHub first, then npm. +``` + +- [ ] **Step 8: Commit** + +```bash +git add lib/templates/install-docs/publish/ +git commit -m "feat: add author-focused publish templates for all 6 platforms" +``` + +--- + +### Task 4: Create header templates and delete old files + +**Files:** +- Create: `lib/templates/install-docs/install-header.md` +- Create: `lib/templates/install-docs/publish-header.md` +- Delete: `lib/templates/install-docs/adding-platform/` (6 files) +- Delete: `lib/templates/install-docs/antigravity.md` +- Delete: `lib/templates/install-docs/claude-code.md` +- Delete: `lib/templates/install-docs/codex.md` +- Delete: `lib/templates/install-docs/cursor.md` +- Delete: `lib/templates/install-docs/gemini-cli.md` +- Delete: `lib/templates/install-docs/openclaw.md` +- Delete: `lib/templates/install-docs/publishing.md` +- Delete: `lib/templates/install-docs/publishing/` (6 files) + +- [ ] **Step 1: Write install-header.md** + +Write to `lib/templates/install-docs/install-header.md`: + +```markdown +# Installation + +How to install **{{displayName}}** on each supported platform. +``` + +- [ ] **Step 2: Write publish-header.md** + +Write to `lib/templates/install-docs/publish-header.md`: + +```markdown +# Publishing & Discoverability + +How to get **{{displayName}}** listed and distributed on each platform. + +See [INSTALL.md](INSTALL.md) for end-user installation instructions. +``` + +- [ ] **Step 3: Delete old top-level install templates** + +Run: + +```bash +git rm lib/templates/install-docs/antigravity.md lib/templates/install-docs/claude-code.md lib/templates/install-docs/codex.md lib/templates/install-docs/cursor.md lib/templates/install-docs/gemini-cli.md lib/templates/install-docs/openclaw.md +``` + +- [ ] **Step 4: Delete old adding-platform/ directory** + +Run: + +```bash +git rm -r lib/templates/install-docs/adding-platform/ +``` + +- [ ] **Step 5: Delete old publishing/ directory and header** + +Run: + +```bash +git rm -r lib/templates/install-docs/publishing/ +git rm lib/templates/install-docs/publishing.md +``` + +- [ ] **Step 6: Commit** + +```bash +git add lib/templates/install-docs/install-header.md lib/templates/install-docs/publish-header.md +git commit -m "feat: add header templates, delete old install/adding-platform/publishing templates" +``` + +--- + +### Task 5: Regenerate INSTALL.md + +**Files:** +- Modify: `INSTALL.md` + +Assemble from: `install-header.md` + `whole-repo-note.md` + each `install/*.md` template with variables resolved for this repo. + +Variable values for this repo: +- `{{name}}` = `plugin-portability` +- `{{displayName}}` = `Plugin Portability` +- `{{repository}}` = `hiivmind/plugin-portability` +- `{{marketplaceName}}` = `plugin-portability-marketplace` + +- [ ] **Step 1: Write the regenerated INSTALL.md** + +Write to `INSTALL.md`: + +```markdown +# Installation + +How to install **Plugin Portability** on each supported platform. + +## Important: Whole-repo install required + +This plugin uses shared hooks, context files, and platform manifests that live outside +individual skill directories. Installing via `npx skills` (which copies only the `skills/` +directory) will lose these shared files and break session-start injection. + +Every install path below clones or references the full repo. See +[docs/ecosystem-landscape.md](docs/ecosystem-landscape.md) for background on why this is +necessary across today's agent platforms. + +## Claude Code + +### Install from GitHub + +Register the plugin's marketplace, then install: + +```bash +/plugin marketplace add hiivmind/plugin-portability +/plugin install plugin-portability@plugin-portability-marketplace +``` + +### Install from local clone + +```bash +claude --plugin-dir /path/to/plugin-portability +``` + +Or add to `.claude/settings.json` for persistent access: + +```json +{ + "extraKnownMarketplaces": { + "plugin-portability-marketplace": { + "source": { + "source": "github", + "repo": "hiivmind/plugin-portability" + } + } + } +} +``` + +### Verify + +```bash +claude plugin list +``` + +Look for `plugin-portability` in the output. + +## Cursor + +### Install from registry + +Search for **plugin-portability** in the Cursor marketplace panel, visit `cursor.com/marketplace`, or run in Agent chat: + +``` +/add-plugin hiivmind/plugin-portability +``` + +### Install from GitHub + +``` +/add-plugin hiivmind/plugin-portability +``` + +### Install from local clone + +Symlink or copy the plugin directory and restart Cursor (Developer: Reload Window): + +```bash +ln -s /path/to/plugin-portability ~/.cursor/plugins/local/plugin-portability +``` + +### Verify + +Open Cursor and check that skills from plugin-portability appear when typing `/` in chat. Rules should appear in Cursor Settings > Rules with the plugin name prefix. + +## Gemini CLI + +### Install from registry + +Browse the gallery at [geminicli.com/extensions](https://geminicli.com/extensions/) and search for **plugin-portability**, or install directly: + +```bash +gemini extensions install hiivmind/plugin-portability +``` + +With version pin: + +```bash +gemini extensions install hiivmind/plugin-portability --ref +``` + +### Install from GitHub + +```bash +gemini extensions install hiivmind/plugin-portability +``` + +### Install from local clone + +```bash +gemini extensions link /path/to/plugin-portability +``` + +Changes are reflected immediately without reinstalling. + +### Verify + +```bash +gemini extensions list +``` + +Look for `plugin-portability` in the output. + +## Codex + +### Install from registry + +Open `/plugins` in Codex, search for **plugin-portability**, and install it. + +### Install from GitHub + +Register the repo as a marketplace source: + +```bash +codex plugin marketplace add hiivmind/plugin-portability +``` + +Then open `/plugins` in Codex and install `plugin-portability`. + +### Install from local clone + +```bash +codex plugin marketplace add /path/to/plugin-portability +``` + +Then open `/plugins` in Codex and install `plugin-portability`. + +### Platform notes + +**Context file:** Codex uses `AGENTS.md` as its primary context file. + +**Hooks:** If this plugin includes hooks, enable the Codex hooks feature flag: + +```toml +# ~/.codex/config.toml +[features] +codex_hooks = true +``` + +Without this flag, hooks are silently ignored. + +**Multi-agent:** If this plugin's skills use subagent dispatch, confirm multi-agent mode is enabled: + +```toml +# ~/.codex/config.toml +[features] +multi_agent = true +``` + +### Verify + +Start a new Codex session and check one of: + +- `/plugins` shows `plugin-portability` as installed +- `~/.codex/config.toml` contains both the marketplace entry and the enabled plugin entry +- the relevant `$` skill resolves in a fresh session + +## Antigravity + +### Install from GitHub + +```bash +git clone hiivmind/plugin-portability +cp -R plugin-portability/.agents/skills/plugin-portability .agents/skills/ +``` + +Or for global scope: + +```bash +cp -R plugin-portability/.agents/skills/plugin-portability ~/.gemini/antigravity/skills/ +``` + +### Install from local clone + +```bash +cp -R /path/to/plugin-portability/.agents/skills/plugin-portability .agents/skills/ +``` + +Or for global scope: + +```bash +cp -R /path/to/plugin-portability/.agents/skills/plugin-portability ~/.gemini/antigravity/skills/ +``` + +### Verify + +Start a new Antigravity session and check that skills from Plugin Portability appear in the skill listing at conversation start. + +## OpenClaw + +### Install from registry + +Install from ClawHub: + +```bash +openclaw plugins install clawhub:plugin-portability +``` + +Or from npm: + +```bash +openclaw plugins install @org/plugin-portability +``` + +### Install from GitHub + +Clone the repo and install locally: + +```bash +git clone hiivmind/plugin-portability +openclaw plugins install -l ./plugin-portability +``` + +### Install from local clone + +Add to `plugins.load.paths` in `~/.openclaw/openclaw.json`: + +```json +{ + "plugins": { + "load": { + "paths": ["/path/to/plugin-portability"] + } + } +} +``` + +### Verify + +```bash +openclaw plugins list +``` + +Skills from Plugin Portability should appear in the plugin listing. +``` + +- [ ] **Step 2: Verify INSTALL.md has no old content** + +Run: `grep -n "antigravity --install-extension\|Adding Another Platform\|Using the skills\|Extension install\|OpenVSX\|open-vsx.org\|skill-installer install" INSTALL.md` + +Expected: no output (no matches). + +- [ ] **Step 3: Commit** + +```bash +git add INSTALL.md +git commit -m "feat: regenerate INSTALL.md from journey-structured templates" +``` + +--- + +### Task 6: Regenerate PUBLISHING.md + +**Files:** +- Modify: `PUBLISHING.md` + +Assemble from: `publish-header.md` + each `publish/*.md` template with variables resolved. + +- [ ] **Step 1: Write the regenerated PUBLISHING.md** + +Write to `PUBLISHING.md`: + +```markdown +# Publishing & Discoverability + +How to get **Plugin Portability** listed and distributed on each platform. + +See [INSTALL.md](INSTALL.md) for end-user installation instructions. + +## Claude Code + +### Prerequisites + +Create `.claude-plugin/marketplace.json` listing the plugins the repo contains. No submission or review process — any Git repo with a valid marketplace manifest can be consumed. + +### Team / org distribution + +Add to the team's project `.claude/settings.json` so teammates get the marketplace automatically: + +```json +{ + "extraKnownMarketplaces": { + "plugin-portability-marketplace": { + "source": { + "source": "github", + "repo": "hiivmind/plugin-portability" + } + } + } +} +``` + +Auto-enable plugins via `"enabledPlugins"` in the same settings file. + +## Cursor + +### Prerequisites + +- Plugin must be open-source in a Git repository +- `.cursor-plugin/plugin.json` manifest required (minimum: `name` field) + +### Submit to registry + +1. Go to `cursor.com/marketplace/publish` +2. Submit the plugin for review +3. Every plugin and update is manually reviewed before listing + +### Team / org distribution + +Cursor 2.6+ (Teams/Enterprise): admins import GitHub repos as team marketplaces via Dashboard Settings. Admins set plugins as required or optional. + +## Gemini CLI + +### Prerequisites + +Include `gemini-extension.json` at the repo root with `name`, `version`, and `description` fields. The repo must be public on GitHub. + +### Submit to registry + +No manual submission process. To get listed in the gallery: + +1. Add the `gemini-cli-extension` topic to the repository's About section on GitHub +2. The gallery crawler indexes tagged repos daily; listing appears within ~1 week + +Browse existing extensions at [geminicli.com/extensions](https://geminicli.com/extensions/). + +## Codex + +### Prerequisites + +- `.codex-plugin/plugin.json` manifest +- `.agents/plugins/marketplace.json` listing the plugin with source path, description, version +- For a single-plugin GitHub repo, the marketplace entry should point at the repo root with `source.path: "./"` + +Self-serve publishing to the official Plugin Directory is coming soon. In the meantime, plugins are distributed via Git repos with marketplace manifests. + +## Antigravity + +### Prerequisites + +- `.agents/skills/plugin-portability/SKILL.md` with standard frontmatter (`name`, `description`) +- Optional: `AGENTS.md` context file + +Antigravity auto-discovers skills from `.agents/skills/` directories — no platform-specific manifest or registry submission required. Share the Git repository URL to distribute. + +## OpenClaw + +### Prerequisites + +- `openclaw/openclaw.plugin.json` manifest with `id` and `configSchema` (required for native plugins) +- `package.json` with `openclaw.extensions` and `openclaw.compat` (required for npm distribution) +- Optional: `AGENTS.md` context file, `skills/*/SKILL.md` for skill-bearing plugins + +### Submit to registry + +**ClawHub:** + +```bash +npm i -g clawhub +clawhub login +clawhub package publish hiivmind/plugin-portability +``` + +**npm (alternative):** + +```bash +npm publish --access public +``` + +Users can install from either registry. Bare names check ClawHub first, then npm. +``` + +- [ ] **Step 2: Verify PUBLISHING.md has no install commands** + +Run: `grep -n "openclaw plugins install\|gemini extensions install\|codex plugin marketplace add\|/plugin install\|/add-plugin\|cp -R\|git clone" PUBLISHING.md` + +Expected: no output (no install commands in the publishing doc). + +- [ ] **Step 3: Commit** + +```bash +git add PUBLISHING.md +git commit -m "feat: regenerate PUBLISHING.md as author-only, no install commands" +``` + +--- + +### Task 7: Update reconciliation matrix + +**Files:** +- Modify: `docs/reconciliation-matrix.md` (lines around 201-214) + +- [ ] **Step 1: Update the publishing-and-discoverability.md section in the matrix** + +Find the `### publishing-and-discoverability.md` section and add a row documenting the template restructure: + +Add after the existing table rows: + +```markdown +| Template structure | Three overlapping sets (install, adding-platform, publishing) | Two audience-based sets (install/, publish/) with journey structure | Fixed (restructured per 2026-04-28 spec) | +``` + +- [ ] **Step 2: Verify no stale references to old paths** + +Run: `grep -rn "adding-platform\|install-docs/antigravity\|install-docs/claude-code\|install-docs/codex\|install-docs/cursor\|install-docs/gemini-cli\|install-docs/openclaw\|install-docs/publishing\.md" docs/reconciliation-matrix.md` + +Expected: no output. + +- [ ] **Step 3: Commit** + +```bash +git add docs/reconciliation-matrix.md +git commit -m "docs: update reconciliation matrix for template restructure" +``` + +--- + +### Task 8: Final verification + +- [ ] **Step 1: Verify file tree matches spec** + +Run: `find lib/templates/install-docs -type f | sort` + +Expected output: + +``` +lib/templates/install-docs/install-header.md +lib/templates/install-docs/install/antigravity.md +lib/templates/install-docs/install/claude-code.md +lib/templates/install-docs/install/codex.md +lib/templates/install-docs/install/cursor.md +lib/templates/install-docs/install/gemini-cli.md +lib/templates/install-docs/install/openclaw.md +lib/templates/install-docs/publish-header.md +lib/templates/install-docs/publish/antigravity.md +lib/templates/install-docs/publish/claude-code.md +lib/templates/install-docs/publish/codex.md +lib/templates/install-docs/publish/cursor.md +lib/templates/install-docs/publish/gemini-cli.md +lib/templates/install-docs/publish/openclaw.md +lib/templates/install-docs/whole-repo-note.md +``` + +- [ ] **Step 2: Verify no fabricated commands survive** + +Run: `grep -rn "antigravity --install-extension\|antigravity publish\|antigravity package\|open-vsx.org\|OpenVSX\|openvsx\|antigravity-awesome-skills\|skill-installer install\|clawhub\.dev" lib/templates/ INSTALL.md PUBLISHING.md` + +Expected: no output. + +- [ ] **Step 3: Verify glob still matches for Phase 7** + +Run: `find lib/templates/install-docs -name "*.md" | wc -l` + +Expected: 15 (6 install + 6 publish + 2 headers + 1 whole-repo-note). + +- [ ] **Step 4: Verify no install commands in PUBLISHING.md** + +Run: `grep -c "```bash\|```json" PUBLISHING.md` + +Expected: a small number (only the ClawHub publish commands and the Claude Code settings.json snippet — no install commands). + +- [ ] **Step 5: Verify consistent journey structure in INSTALL.md** + +Run: `grep "^### " INSTALL.md | sort | uniq -c | sort -rn` + +Expected: "Install from GitHub" appears 6 times, "Install from local clone" appears 6 times, "Verify" appears 6 times, "Install from registry" appears 4 times (Cursor, Gemini CLI, Codex, OpenClaw), "Platform notes" appears 1 time (Codex). + +- [ ] **Step 6: Commit verification results (if any fixes needed)** + +Only if earlier steps revealed issues. Fix and commit with: + +```bash +git add -A +git commit -m "fix: address issues found during template restructure verification" +``` diff --git a/docs/superpowers/specs/2026-04-28-adding-a-platform-guide-design.md b/docs/superpowers/specs/2026-04-28-adding-a-platform-guide-design.md new file mode 100644 index 0000000..eef9c10 --- /dev/null +++ b/docs/superpowers/specs/2026-04-28-adding-a-platform-guide-design.md @@ -0,0 +1,221 @@ +# Adding a Platform Guide — Design Spec + +**Date:** 2026-04-28 +**Status:** Approved + +## Problem + +CONTRIBUTING.md has a 6-line "Adding a New Platform" section that lists file paths but explains nothing: no architecture context, no data shape requirements, no verification steps, no dependency ordering. A contributor (human or agent) starting from this checklist would need to reverse-engineer the architecture by reading 5+ existing files. + +There is no document in the repo that explains the end-to-end architecture — how research docs feed platform specs, how specs feed rubrics and templates, and how the skill ties it all together. + +## Solution + +A single guide at `lib/principles/adding-a-platform.md` that serves both human contributors and coding agents. It opens with an architecture overview, walks through 7 phases in dependency order, and ends with a cross-cutting update list and final verification checklist. Every phase has concrete verification gates. + +CONTRIBUTING.md's "Adding a New Platform" section is replaced with a one-liner pointing to the guide. + +## Audience + +Both human contributors and coding agents. The guide uses clear procedures with concrete checks — an agent can evaluate the verification gates mechanically, a human can check them by inspection. + +## Document Structure + +### Part 1: Architecture Overview (~80 lines) + +Dependency diagram showing how the 7 artifact types connect: + +``` +Research doc (docs/platforms/) + ↓ sourced facts with citations +Platform spec (lib/references/platforms/) + ↓ structured PlatformSpec dictionary + ├→ Rubric (lib/rubrics/) — conditions reference spec fields + ├→ Manifest templates (lib/templates/manifests/) — field names from spec + ├→ Install/publish templates (lib/templates/install-docs/) — commands from spec + ├→ Pattern updates (lib/patterns/) — hook events, publishing mechanisms + └→ Skill pseudocode (skills/plugin-portability/SKILL.md) — platform in selection list +``` + +Key principles: +- **Research is the source of truth.** Every platform-specific claim traces back to a cited fact in the research doc. When research and other files disagree, research wins. +- **The platform spec is the single structured representation.** Rubrics, templates, and patterns all derive from the spec — they don't independently describe platform behavior. +- **Rubric conditions are scored, not prose.** Each condition has an ID, a type, points, and pseudocode. Schema at `lib/rubrics/rubric-framework.md`. +- **Templates use `{{mustache}}` variables.** Resolved at generation time for a specific target plugin. + +Points to `lib/references/platform-api.md` for the PlatformSpec type and `lib/rubrics/rubric-framework.md` for the condition schema — doesn't re-document them. + +### Part 2: Phases (~200 lines across 7 phases) + +Each phase follows the same format: + +``` +## Phase N: + +**Create:** `exact/path/to/file` + +**Inputs:** +- What to read to write this file +- Structural reference (existing file for the same slot from another platform) + +**What goes in this file:** +Brief description of required content and shape. + +**Verification gate:** +- [ ] Concrete check 1 +- [ ] Concrete check 2 +- [ ] ... +``` + +#### Phase 1: Research + +**Create:** `docs/platforms/.md` + +**Inputs:** Platform's official documentation, GitHub repos, release announcements. + +**What goes in this file:** Sourced documentation organized by section (manifest, skills, hooks, context files, tools, install/distribution, runtime). Every claim has an inline citation (`[source](url)`). Follow the section structure of existing research docs (e.g., `docs/platforms/cursor.md`). + +**Verification gate:** +- [ ] File exists at `docs/platforms/.md` +- [ ] Covers the 9 standard sections: plugin structure, manifest, skills, context files, hooks, tool mapping, install and distribution, runtime components, sources +- [ ] Every factual claim has a `[source](url)` citation +- [ ] No claims copied from another platform's research doc without independent verification + +#### Phase 2: Platform spec + +**Create:** `lib/references/platforms/.md` + +**Inputs:** Research doc from Phase 1, PlatformSpec type definition (`lib/references/platform-api.md`), an existing spec as structural reference. + +**What goes in this file:** A `REGISTRY[""]` block conforming to the PlatformSpec type. Every field populated — `null` for capabilities the platform doesn't support. Key sections: tools, hooks, context, skills, marketplace. + +**Verification gate:** +- [ ] File exists at `lib/references/platforms/.md` +- [ ] Contains `REGISTRY[""] = {` +- [ ] Every field in PlatformSpec type has a value (null is valid, missing is not) +- [ ] Tool entries reference actual platform tool names from research doc +- [ ] Hook events match the platform's actual event names and casing convention +- [ ] No fields copy-pasted from another platform without verification against research + +#### Phase 3: Rubric + +**Create:** `lib/rubrics/.yaml` + +**Inputs:** Platform spec from Phase 2, rubric framework (`lib/rubrics/rubric-framework.md`), an existing rubric as structural reference, pseudocode principles (`lib/principles/pseudocode-principles.md`). + +**What goes in this file:** YAML list of conditions following the condition schema. Each condition has `id`, `type`, `component`, `critical`, `points`, `check`. Conditions are grouped by category (manifest, skills, context, hooks, toolmap, install). Pseudocode in `check` fields uses the LOAD_AND_VERIFY / GLOB_AND_VERIFY patterns. + +**Verification gate:** +- [ ] File exists at `lib/rubrics/.yaml` +- [ ] Every condition has all required fields (`id`, `type`, `component`, `critical`, `points`, `check`) +- [ ] Condition IDs follow the format `._..` +- [ ] `type` is either `checkable` or `judgement` +- [ ] `check` pseudocode for `checkable` conditions references concrete file paths or spec fields +- [ ] YAML parses without errors + +#### Phase 4: Manifest templates + +**Create:** `lib/templates/manifests//` with one `.tmpl` file per manifest the platform requires. + +**Inputs:** Platform spec from Phase 2 (manifest fields), research doc (manifest format), an existing manifest template directory as structural reference. + +**What goes in this file:** JSON or TOML template files using `{{mustache}}` variables. Fields match what the platform actually requires per the research doc. + +**Verification gate:** +- [ ] Directory exists at `lib/templates/manifests//` +- [ ] At least one `.tmpl` file present +- [ ] Template files are valid JSON/TOML (ignoring `{{mustache}}` placeholders) +- [ ] Required fields from the platform spec are present in the template +- [ ] Every `{{variable}}` in the template is either a core variable (`{{name}}`, `{{displayName}}`, `{{version}}`, `{{description}}`, `{{repository}}`, `{{marketplaceName}}`) or a metadata variable documented in the template registry (`lib/references/templates/registry.md`) or sourced from the plugin's package metadata (`{{author.name}}`, `{{author.email}}`, `{{license}}`, `{{keywords}}`, `{{homepage}}`, `{{skillsList}}`) +- [ ] New template entry added to `lib/references/templates/registry.md` with correct `schema`, `platform`, `mode`, `template_path`, `target_path` + +#### Phase 5: Install and publish templates + +**Create:** `lib/templates/install-docs/install/.md` and `lib/templates/install-docs/publish/.md` + +**Inputs:** Platform spec from Phase 2 (install commands, marketplace info), research doc (install/distribution section), `lib/patterns/publishing-and-discoverability.md`. + +**What goes in the install template:** Journey-structured sections: "Install from registry" (conditional — only if platform has one), "Install from GitHub" (always), "Install from local clone" (always), "Verify" (always). Uses `{{mustache}}` variables. + +**What goes in the publish template:** Author-focused sections: "Prerequisites" (always — required manifests), "Submit to registry" (conditional), "Team / org distribution" (conditional). No install commands. + +**Verification gate:** +- [ ] Both files exist at the expected paths +- [ ] Install template has "Install from GitHub", "Install from local clone", and "Verify" sections +- [ ] Install template has "Install from registry" only if the platform has a registry per the spec +- [ ] Publish template has "Prerequisites" section +- [ ] Publish template contains zero install commands (no `install`, `clone`, `cp` commands) +- [ ] Both templates use `{{mustache}}` variables, not hardcoded values + +#### Phase 6: Pattern updates + +**Modify:** Multiple files in `lib/patterns/`. + +**Inputs:** Research doc, platform spec. + +**What to update:** +- `lib/patterns/publishing-and-discoverability.md` — add platform to quick reference table and add a platform section +- `lib/patterns/hook-merging.md` — add platform's hook format if it has hooks +- Other pattern files as needed based on platform capabilities + +**Verification gate:** +- [ ] `grep "" lib/patterns/publishing-and-discoverability.md` returns hits +- [ ] If platform has hooks: `grep "" lib/patterns/hook-merging.md` returns hits +- [ ] All platform-specific claims in pattern files are consistent with the research doc + +#### Phase 7: Skill integration + +**Modify:** `skills/plugin-portability/SKILL.md` + +**Inputs:** All artifacts from Phases 1-6. + +**What to update:** +- Add platform to the platform selection `options` array in the intent-gathering pseudocode +- Add platform to the hardcoded `ELSE` fallback list (`platforms = ["claude-code", "cursor", ...]`) — this is the "All platforms" default path +- Update the "All platforms" option description if it enumerates platform names + +**Verification gate:** +- [ ] Platform appears in the `options` array with `label` and `description` +- [ ] `description` accurately summarizes the platform (no fabricated features) +- [ ] Platform appears in the `ELSE` fallback list (grep for `platforms = \[` and confirm the new platform is included) +- [ ] "All platforms" option description includes the new platform if it enumerates names +- [ ] Skill's `GLOB_AND_VERIFY` patterns match the new files (test: `find lib/templates/install-docs -name "*.md" | wc -l` increased by 2) + +### Part 3: Cross-cutting updates (~30 lines) + +Files that need a mention of the new platform but don't warrant their own phase: + +- `docs/reconciliation-matrix.md` — add a section for the new platform +- `README.md` — add platform to the "What it does" artifacts table +- `CHANGELOG.md` — entry for the new platform addition +- `lib/patterns/publishing-and-discoverability.md` — covered in Phase 6 but listed here for completeness + +### Part 4: Final verification checklist (~20 lines) + +End-to-end checks after all phases complete: + +- [ ] `find lib/references/platforms -name "*.md" | wc -l` matches expected platform count +- [ ] `find lib/rubrics -name "*.yaml" | wc -l` matches expected platform count +- [ ] `find lib/templates/install-docs/install -name "*.md" | wc -l` matches expected platform count +- [ ] `find lib/templates/install-docs/publish -name "*.md" | wc -l` matches expected platform count +- [ ] Platform appears in the skill's platform selection options +- [ ] Platform appears in `lib/patterns/publishing-and-discoverability.md` quick reference table +- [ ] Phase 7 glob `lib/templates/install-docs/**/*.md` matches all template files +- [ ] No hardcoded platform counts in README or CONTRIBUTING that are now stale + +## CONTRIBUTING.md Change + +Replace the "Adding a New Platform" section with: + +```markdown +## Adding a New Platform + +See [lib/principles/adding-a-platform.md](lib/principles/adding-a-platform.md) for the full guide — architecture overview, phased checklist, and verification gates. +``` + +## File Impact + +| Action | File | +|--------|------| +| Create | `lib/principles/adding-a-platform.md` | +| Modify | `CONTRIBUTING.md` (trim section to one-liner) | diff --git a/docs/superpowers/specs/2026-04-28-install-publish-template-restructure-design.md b/docs/superpowers/specs/2026-04-28-install-publish-template-restructure-design.md new file mode 100644 index 0000000..082a055 --- /dev/null +++ b/docs/superpowers/specs/2026-04-28-install-publish-template-restructure-design.md @@ -0,0 +1,161 @@ +# Install & Publish Template Restructure + +**Date:** 2026-04-28 +**Status:** Approved + +## Problem + +The install/publish template system has three overlapping layers: + +| Layer | Path | Files | +|-------|------|-------| +| Install templates | `lib/templates/install-docs/*.md` | 6 per-platform | +| Adding-platform templates | `lib/templates/install-docs/adding-platform/*.md` | 6 per-platform | +| Publishing templates | `lib/templates/install-docs/publishing/*.md` | 6 per-platform + header | + +These suffer from: + +1. **Duplication between install and adding-platform.** The adding-platform templates are the same install commands with `/path/to/existing/` prefixed. "Adding another platform" is just "install from local clone." +2. **Publishing templates contain install commands.** Every publishing template has a "How users find and install" section that duplicates the install template. Publishing is author-facing; install commands are user-facing. +3. **No user-journey structure.** Install templates are random collections of commands (marketplace install, local dev, project install, verify) with no consistent ordering or framing. Users can't scan for the install path that matches their situation. +4. **Factual errors propagated through templates.** Antigravity templates described VS Code extension publishing via OpenVSX (irrelevant to skills). Codex templates included fabricated `$skill-installer install` subcommands. These were partially fixed in the pattern file but the templates and generated outputs still carried the bad data. + +## Solution + +Replace three template sets with two, structured around two audiences: + +- **Plugin user** → `install/` templates → generates `INSTALL.md` +- **Plugin author** → `publish/` templates → generates `PUBLISHING.md` + +## File Structure + +### After + +``` +lib/templates/install-docs/ + install/ + claude-code.md + cursor.md + gemini-cli.md + codex.md + antigravity.md + openclaw.md + publish/ + claude-code.md + cursor.md + gemini-cli.md + codex.md + antigravity.md + openclaw.md + install-header.md + publish-header.md + whole-repo-note.md +``` + +### Deleted + +- `lib/templates/install-docs/adding-platform/` (6 files) — absorbed into "Install from local clone" +- `lib/templates/install-docs/antigravity.md`, `claude-code.md`, `codex.md`, `cursor.md`, `gemini-cli.md`, `openclaw.md` (6 top-level files) — replaced by `install/` directory +- `lib/templates/install-docs/publishing.md` — replaced by `publish-header.md` + +## Install Template Skeleton + +Every install template follows the same journey order. Sections are conditional — omitted when they don't apply to the platform. + +``` +## {{platformDisplayName}} + +### Install from registry + + +### Install from GitHub + + +### Install from local clone + + +### Verify + +``` + +### Ordering rationale + +Registry first (easiest path), GitHub second (universal), local clone third (development use case). Verify last (confirms any of the above worked). + +### Conditional registry section + +| Platform | Registry | Section present? | +|----------|----------|-----------------| +| Claude Code | None (Git repos) | No | +| Cursor | cursor.com/marketplace | Yes | +| Gemini CLI | geminicli.com/extensions | Yes | +| Codex | /plugins browser | Yes | +| Antigravity | None | No | +| OpenClaw | ClawHub (clawhub.ai) | Yes | + +### Dropped content + +- **"Using the skills" sections** — runtime documentation, not install documentation. Belongs in README or skill descriptions. +- **"Adding Another Platform" framing** — the local clone section serves this case without a separate concept. + +## Publish Template Skeleton + +Every publish template is author-facing. No install commands. + +``` +## {{platformDisplayName}} + +### Prerequisites + + +### Submit to registry + + +### Team / org distribution + +``` + +### Conditional sections + +| Platform | Prerequisites | Submit to registry | Team distribution | +|----------|--------------|-------------------|-------------------| +| Claude Code | `.claude-plugin/marketplace.json` | No (no registry) | Yes (`extraKnownMarketplaces`) | +| Cursor | `.cursor-plugin/plugin.json` | Yes (marketplace/publish) | Yes (team marketplaces) | +| Gemini CLI | `gemini-extension.json` | Yes (GitHub topic auto-index) | No | +| Codex | `.codex-plugin/plugin.json` + `marketplace.json` | No (self-serve coming soon) | No | +| Antigravity | `.agents/skills/*/SKILL.md` | No (no registry) | No | +| OpenClaw | `openclaw.plugin.json` | Yes (ClawHub + npm) | No | + +Platforms with only a Prerequisites section (Antigravity) are correct — "publish" for Antigravity is "put files in the right places and share the repo." + +## Generated Outputs + +### INSTALL.md + +Assembled from: `install-header.md` + (conditionally) `whole-repo-note.md` + one `install/*.md` per target platform. + +No "Fresh Install" vs "Adding Another Platform" split. One section per platform with journey-ordered subsections. + +### PUBLISHING.md + +Assembled from: `publish-header.md` + one `publish/*.md` per target platform. Author-facing only. + +## Skill Impact + +Phase 7 (DOCUMENT) uses `GLOB_AND_VERIFY("lib/templates/install-docs/**/*.md", ...)`. The recursive glob matches the new `install/` and `publish/` subdirectories without changes. The Phase 7 pseudocode says "LOAD_AND_VERIFY install doc template for platform" — the templates are self-describing (each starts with the platform name as a heading), so the LLM will find the right template by matching platform name to file. No skill pseudocode changes required. + +## Relationship to Pattern File + +`lib/patterns/publishing-and-discoverability.md` remains as a background reference — the research-backed source of truth that templates are distilled from. It is not loaded by any skill at runtime and is not affected by this restructure. It was corrected earlier in this session (Gemini auto-discovery mechanism, Antigravity OpenVSX removal, Codex fabricated commands). + +## Migration Checklist + +1. Create `install/` directory with 6 journey-structured templates +2. Create `publish/` directory with 6 author-focused templates +3. Create `install-header.md` and `publish-header.md` +4. Delete `adding-platform/` directory (6 files) +5. Delete top-level per-platform files (6 files) +6. Delete `publishing.md` header +7. Regenerate `INSTALL.md` from new install templates +8. Regenerate `PUBLISHING.md` from new publish templates +9. Update `docs/reconciliation-matrix.md` to reflect new template paths diff --git a/lib/patterns/publishing-and-discoverability.md b/lib/patterns/publishing-and-discoverability.md index f57b0b8..7cf8729 100644 --- a/lib/patterns/publishing-and-discoverability.md +++ b/lib/patterns/publishing-and-discoverability.md @@ -4,23 +4,23 @@ How to get a plugin discovered and installed on each platform. Use this referenc ## Quick Reference -| Platform | Public marketplace | Submission | Review | Discovery | Install | -|----------|--------------------|------------|--------|-----------|---------| -| Claude Code | No (Git repos) | N/A | N/A | Share repo URL | 1. `/plugin marketplace add owner/repo` 2. `/plugin install name@marketplace` | -| Cursor | cursor.com/marketplace | cursor.com/marketplace/publish | Manual, open-source only | Marketplace search or `/add-plugin` | `/add-plugin owner/repo` | -| Gemini CLI | geminicli.com/extensions | Via gallery | Not vetted | Gallery search | `gemini extensions install ` | -| Codex (skills) | Community directories | GitHub repo | N/A | `$skill-installer` search | `$skill-installer ` | -| Codex (plugins) | Not yet public | N/A | N/A | `codex plugin marketplace add` | Via marketplace | -| Antigravity | No (Git repos + npm) | N/A | N/A | Community collections | Copy to `.agents/skills/` | -| OpenClaw | ClawHub (clawhub.ai) | ClawHub CLI or npm | Curated | ClawHub search | `openclaw plugins install clawhub:` | +| Platform | Registry | How to list | How to install | +|----------|----------|-------------|----------------| +| Claude Code | None (Git repos) | Share repo URL | `/plugin marketplace add owner/repo` then `/plugin install name@marketplace` | +| Cursor | cursor.com/marketplace | Submit at cursor.com/marketplace/publish (manual review, open-source only) | `/add-plugin owner/repo` | +| Gemini CLI | geminicli.com/extensions (908+) | Add `gemini-cli-extension` topic to GitHub repo; auto-indexed daily | `gemini extensions install ` | +| Codex (skills) | None | Publish as GitHub repo with `SKILL.md` | `$skill-installer ` or copy to `~/.codex/skills/` | +| Codex (plugins) | Official directory (self-serve coming soon) | Browse via `/plugins` in Codex | `codex plugin marketplace add owner/repo` | +| Antigravity | None | Share repo URL | Copy to `.agents/skills/` | +| OpenClaw | ClawHub (clawhub.ai) | `clawhub package publish` or `clawhub skill publish` | `openclaw plugins install clawhub:` | ## Claude Code -No public marketplace or gallery. Distribution is via Git repositories. +No public marketplace. Distribution is via Git repositories. ### Publishing -Authors create a `.claude-plugin/marketplace.json` in their repo listing the plugins it contains. There is no submission or review process — any Git repo with a valid marketplace manifest can be consumed. +Create `.claude-plugin/marketplace.json` listing the plugins the repo contains. No submission or review process — any Git repo with a valid marketplace manifest can be consumed. Marketplace entry sources: - `"source": "github"` with `"repo": "owner/repo"` @@ -28,9 +28,9 @@ Marketplace entry sources: - `"source": "git-subdir"` for monorepos - `"source": "npm"` for npm-published packages -### Discovery and install +### Install -Users register the marketplace, then install: +Register the marketplace, then install from it: ``` /plugin marketplace add owner/repo @@ -54,27 +54,26 @@ Add to project `.claude/settings.json` so teammates get the marketplace automati } ``` -Can also auto-enable plugins via `"enabledPlugins"` in the same settings file. +Auto-enable plugins via `"enabledPlugins"` in the same settings file. ## Cursor -Public marketplace at `cursor.com/marketplace`. Curated and manually reviewed. +Public marketplace at `cursor.com/marketplace`. Every plugin and update is manually reviewed. ### Publishing 1. Plugin must be open-source in a Git repository 2. `.cursor-plugin/plugin.json` manifest required (minimum: `name` field) 3. Submit at `cursor.com/marketplace/publish` -4. Every plugin and update is manually reviewed -### Discovery and install +### Install -- Browse the marketplace at `cursor.com/marketplace` +- Browse `cursor.com/marketplace` - In Agent chat: `/add-plugin owner/repo` (GitHub shorthand or full URL) ### Team distribution -Cursor 2.6+ (Teams/Enterprise plans): admins import GitHub repos as team marketplaces via Dashboard Settings. Admins set plugins as required or optional. +Cursor 2.6+ (Teams/Enterprise): admins import GitHub repos as team marketplaces via Dashboard Settings. Admins set plugins as required or optional. ### Local development @@ -82,67 +81,78 @@ Symlink to `~/.cursor/plugins/local//`. Restart required (Developer: Reloa ## Gemini CLI -Extensions gallery at [geminicli.com/extensions](https://geminicli.com/extensions/) with 897+ extensions. +Extensions gallery at [geminicli.com/extensions](https://geminicli.com/extensions/) with 908+ extensions. Google does not vet or endorse listed extensions. ### Publishing -Extensions are published as GitHub repositories. The gallery lists them but Google does not vet, endorse, or guarantee functionality or security. Users should review extensions before installing. +No manual submission process. To get listed: -Official extensions org: `github.com/gemini-cli-extensions` (43+ repos from Google). +1. Host extension in a **public GitHub repository** +2. Add the `gemini-cli-extension` topic to the repository's About section +3. Include `gemini-extension.json` at repo root with `name`, `version`, `description` +4. The gallery crawler indexes tagged repos daily; listing appears within ~1 week -### Requirements +Official extensions org: `github.com/gemini-cli-extensions`. -`gemini-extension.json` manifest with `name`, `version`, and `description` fields. +### Install -### Discovery and install +```bash +gemini extensions install +gemini extensions install --ref # version pin +gemini extensions install --auto-update +``` -- Browse the gallery at `geminicli.com/extensions` -- Install: `gemini extensions install ` -- Install with version pin: `gemini extensions install --ref ` +Scopes: user-level (`~/.gemini/extensions/`) or workspace (`.gemini/extensions/`). Toggle with `gemini extensions enable/disable [--scope workspace]`. ### Local development -`gemini extensions link ` creates a symlink for local dev. Changes require CLI restart. +`gemini extensions link ` creates a symlink. Changes are reflected immediately without reinstalling. -## Codex — Skill Discovery Path +## Codex — Skills -For repos that are mostly instructions with no plugin UI metadata needed. +For repos that are mostly instructions with no plugin metadata needed. ### Publishing -- Publish as a standalone GitHub repo with `SKILL.md` frontmatter +Publish as a GitHub repo with `SKILL.md` frontmatter (`name` and `description` in YAML). -### Requirements - -`skills//SKILL.md` with `name` and `description` in YAML frontmatter. +### Install -### Discovery and install +```bash +$skill-installer -- `$skill-installer ` — install by name -- `$skill-installer install ` — install by URL -- Manual: copy or symlink to `~/.codex/skills//` or `~/.agents/skills//` +# Manual alternatives +cp -R skill-folder/ ~/.codex/skills// +ln -s /path/to/skill-folder ~/.agents/skills/ +``` -Skills install into `~/.codex/skills//` by default. Restart Codex after adding new skills. +Restart Codex after adding new skills. -## Codex — Plugin Packaging Path +## Codex — Plugins -For first-class plugin packages with marketplace metadata and bundled components (hooks, MCP, apps). +For packages with marketplace metadata and bundled components (hooks, MCP, apps). ### Publishing -Public self-serve plugin publishing is "coming soon" per OpenAI docs. Currently, plugins are distributed via Git repos with marketplace manifests. - -### Requirements +Self-serve publishing to the official Plugin Directory is coming soon. Currently plugins are distributed via Git repos with marketplace manifests. +Requirements: - `.codex-plugin/plugin.json` manifest - `marketplace.json` listing the plugin with source path, description, version -### Discovery and install +### Install -- Register a marketplace source: `codex plugin marketplace add owner/repo` -- Also accepts: `--ref `, `--sparse `, SSH URLs, local paths -- Repo-local marketplace: `/.agents/plugins/marketplace.json` -- Home-local marketplace: `~/.agents/plugins/marketplace.json` +```bash +codex plugin marketplace add owner/repo +codex plugin marketplace add owner/repo --ref main +codex plugin marketplace add --sparse .agents/plugins +codex plugin marketplace add ./local-marketplace-root +``` + +Browse and search via `/plugins` in the Codex interactive UI. + +Repo-local marketplace: `/.agents/plugins/marketplace.json` +Home-local marketplace: `~/.agents/plugins/marketplace.json` ### Upgrade @@ -150,32 +160,25 @@ Public self-serve plugin publishing is "coming soon" per OpenAI docs. Currently, ## Antigravity -No official skill marketplace or registry. Distribution is via Git repositories, community npm installers, and manual sharing. +No official marketplace or registry. Distribution is via Git repositories and manual sharing. ### Publishing -Skills are published as GitHub repositories. Community skill collections (e.g., `antigravity-awesome-skills` with 1,400+ skills) provide npm-based cross-platform installers. - -### Requirements - -- `.agents/skills//SKILL.md` with standard frontmatter -- `AGENTS.md` context file (optional but recommended) +Publish skills as GitHub repositories with `.agents/skills//SKILL.md` (standard frontmatter). Antigravity auto-discovers skills from `.agents/skills/` directories — no platform-specific manifest required. -Antigravity auto-discovers skills from `.agents/skills/` directories. No platform-specific manifest is required for skill distribution. +Optional: `AGENTS.md` context file. -### Discovery and install +### Install -- Community collections: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) -- npm installer: `npx antigravity-awesome-skills` (installs to `~/.gemini/antigravity/skills/`) -- Manual: copy skill directory into `.agents/skills/` (workspace) or `~/.gemini/antigravity/skills/` (global) - -### Local development - -Copy or symlink skill directory into `.agents/skills/`. Changes are picked up on next session start. +```bash +# Workspace scope +cp -R /path/to/skill-name .agents/skills/ -### VS Code extensions +# Global scope +cp -R /path/to/skill-name ~/.gemini/antigravity/skills/ +``` -As a VS Code fork, Antigravity uses **OpenVSX** for IDE extensions (separate from the skill system). Install via `--install-extension `. +Changes are picked up on next session start. ## OpenClaw @@ -183,7 +186,7 @@ Public registry at [ClawHub](https://clawhub.ai). Also supports npm distribution ### Publishing -Plugins are published via ClawHub CLI or npm: +Via ClawHub CLI or npm: ```bash npm i -g clawhub @@ -198,10 +201,9 @@ Alternatively, publish to npm with `openclaw.extensions` in `package.json`. - `openclaw.plugin.json` manifest with `id` and `configSchema` (required for native plugins) - `package.json` with `openclaw.extensions` and `openclaw.compat` (required for npm distribution) -- `AGENTS.md` context file (optional but recommended) -- `skills/*/SKILL.md` with standard frontmatter (for skill-bearing plugins) +- Optional: `AGENTS.md` context file, `skills/*/SKILL.md` for skill-bearing plugins -### Discovery and install +### Install - ClawHub: `openclaw plugins install clawhub:` - Skills: `openclaw skills install ` diff --git a/lib/principles/adding-a-platform.md b/lib/principles/adding-a-platform.md new file mode 100644 index 0000000..228a4d5 --- /dev/null +++ b/lib/principles/adding-a-platform.md @@ -0,0 +1,294 @@ +# Adding a New Platform + +End-to-end guide for adding a new platform to plugin-portability. Covers the architecture, what to create in what order, and how to verify each step. + +Audience: human contributors and coding agents. Every phase ends with a verification gate — concrete checks that can be evaluated mechanically or by inspection. + +--- + +## Architecture + +A platform is represented by 7 artifact types. They have a strict dependency order: + +``` +Research doc (docs/platforms/.md) + ↓ sourced facts with citations +Platform spec (lib/references/platforms/.md) + ↓ structured PlatformSpec dictionary + ├→ Rubric (lib/rubrics/.yaml) + │ conditions reference spec fields + ├→ Manifest templates (lib/templates/manifests//) + │ field names from spec + ├→ Install/publish templates (lib/templates/install-docs/) + │ commands from spec + ├→ Pattern updates (lib/patterns/) + │ hook events, publishing mechanisms + └→ Skill pseudocode (skills/plugin-portability/SKILL.md) + platform in selection list and ELSE fallback +``` + +### Key principles + +**Research is the source of truth.** Every platform-specific claim in any file traces back to a cited fact in the research doc. When research and other files disagree, research wins. + +**The platform spec is the single structured representation.** Rubrics, templates, and patterns all derive from the spec — they don't independently describe platform behavior. The spec conforms to the `PlatformSpec` type defined in `lib/references/platform-api.md`. + +**Rubric conditions are scored, not prose.** Each condition has an ID, a type (`checkable` or `judgement`), points, and pseudocode. The schema is defined in `lib/rubrics/rubric-framework.md`. + +**Templates use `{{mustache}}` variables.** They're resolved at generation time for a specific target plugin. Variables fall into three categories: +- **Core:** `{{name}}`, `{{displayName}}`, `{{version}}`, `{{description}}`, `{{repository}}`, `{{marketplaceName}}` +- **Package metadata:** `{{author.name}}`, `{{author.email}}`, `{{license}}`, `{{keywords}}`, `{{homepage}}` +- **Generated:** `{{skillsList}}` and any platform-specific values produced by builder-mode templates + +### Existing files to read first + +| File | What it tells you | +|------|-------------------| +| `lib/references/platform-api.md` | PlatformSpec type definition and lookup functions | +| `lib/rubrics/rubric-framework.md` | Condition schema (id, type, component, critical, points, check) | +| `lib/principles/pseudocode-principles.md` | How to write pseudocode, registries, and LOAD_AND_VERIFY gates | +| `lib/references/templates/registry.md` | Template registry (schema, platform, mode, paths) | +| An existing platform's full set of artifacts | Structural reference for every phase | + +--- + +## Phase 1: Research + +**Create:** `docs/platforms/.md` + +**Inputs:** +- Platform's official documentation, GitHub repos, release announcements +- An existing research doc (e.g., `docs/platforms/cursor.md`) as structural reference + +**What goes in this file:** + +Sourced documentation organized into the 9 standard sections. Every factual claim must have an inline `[source](url)` citation. + +The 9 sections are: + +1. Plugin Structure +2. Manifest +3. Skills +4. Context Files +5. Hooks +6. Tool Mapping +7. Install and Distribution +8. Runtime Components +9. Sources + +Follow the heading format of existing research docs (`## 1. Plugin Structure`, etc.). + +**Verification gate:** +- [ ] File exists at `docs/platforms/.md` +- [ ] All 9 standard sections present +- [ ] Every factual claim has a `[source](url)` citation +- [ ] No claims copied from another platform's research doc without independent verification + +--- + +## Phase 2: Platform spec + +**Create:** `lib/references/platforms/.md` + +**Inputs:** +- Research doc from Phase 1 +- `lib/references/platform-api.md` (PlatformSpec type definition) +- An existing spec (e.g., `lib/references/platforms/cursor.md`) as structural reference + +**What goes in this file:** + +A `REGISTRY[""]` block conforming to the PlatformSpec type. Every field must be populated — use `null` for capabilities the platform doesn't support. Key sections: + +- **tools** — map canonical operations (`file.read`, `shell.execute`, etc.) to the platform's native tool names +- **hooks** — event names, config path, naming convention (PascalCase/camelCase/snake_case), structure +- **context** — primary context file, secondary files, priority rules +- **skills** — path, frontmatter fields, discovery mechanism +- **marketplace** — marketplace path or `null` + +**Verification gate:** +- [ ] File exists at `lib/references/platforms/.md` +- [ ] Contains `REGISTRY[""] = {` +- [ ] Every field in PlatformSpec type has a value (`null` is valid, missing is not) +- [ ] Tool entries reference actual platform tool names from the research doc +- [ ] Hook events match the platform's actual event names and casing convention +- [ ] No fields copy-pasted from another platform without verification against research + +--- + +## Phase 3: Rubric + +**Create:** `lib/rubrics/.yaml` + +**Inputs:** +- Platform spec from Phase 2 +- `lib/rubrics/rubric-framework.md` (condition schema) +- `lib/principles/pseudocode-principles.md` (pseudocode patterns) +- An existing rubric (e.g., `lib/rubrics/cursor.yaml`) as structural reference + +**What goes in this file:** + +YAML file with a header block and a `categories` map. The header declares the platform, manifest path, context files, and hooks path. Categories group conditions by concern. + +Each condition has: + +```yaml +- id: ._.. + type: checkable | judgement + component: + critical: true | false + points: 1 + check: | + pseudocode (checkable) or prose description (judgement) + template: optional — path to template that fixes this condition +``` + +Standard categories: `1_manifest`, `2_skills`, `3_context`, `4_hooks`, `5_toolmap`, `6_install`. + +Pseudocode in `check` fields should use LOAD_AND_VERIFY / GLOB_AND_VERIFY patterns from `lib/principles/pseudocode-principles.md`. + +**Verification gate:** +- [ ] File exists at `lib/rubrics/.yaml` +- [ ] Every condition has all required fields (`id`, `type`, `component`, `critical`, `points`, `check`) +- [ ] Condition IDs follow the format `._..` +- [ ] `type` is either `checkable` or `judgement` +- [ ] `check` pseudocode for `checkable` conditions references concrete file paths or spec fields +- [ ] YAML parses without errors: `python3 -c "import yaml; yaml.safe_load(open('lib/rubrics/.yaml'))"` + +--- + +## Phase 4: Manifest templates + +**Create:** `lib/templates/manifests//` with one `.tmpl` file per manifest the platform requires. + +**Inputs:** +- Platform spec from Phase 2 (manifest fields) +- Research doc (manifest format and required fields) +- `lib/references/templates/registry.md` (template registry) +- An existing manifest template directory (e.g., `lib/templates/manifests/cursor-plugin/`) as structural reference + +**What goes in these files:** + +JSON or TOML template files using `{{mustache}}` variables. Each template should have a `{{! fixes: }}` comment at the top linking it to the rubric condition it satisfies. + +Fields must match what the platform actually requires per the research doc. + +**Verification gate:** +- [ ] Directory exists at `lib/templates/manifests//` +- [ ] At least one `.tmpl` file present +- [ ] Template files are valid JSON/TOML (ignoring `{{mustache}}` placeholders) +- [ ] Required fields from the platform spec are present in the template +- [ ] Every `{{variable}}` is either a core variable, a package metadata variable, or documented in the template registry +- [ ] New template entry added to `lib/references/templates/registry.md` with correct `schema`, `platform`, `mode`, `template_path`, `target_path` + +--- + +## Phase 5: Install and publish templates + +**Create:** +- `lib/templates/install-docs/install/.md` +- `lib/templates/install-docs/publish/.md` + +**Inputs:** +- Platform spec from Phase 2 (install commands, marketplace info) +- Research doc (install and distribution section) +- `lib/patterns/publishing-and-discoverability.md` +- Existing install/publish templates as structural reference + +**Install template structure:** + +Follow the journey-structured format. Sections are conditional — omit when they don't apply: + +1. **Install from registry** — only if the platform has a registry +2. **Install from GitHub** — always present +3. **Install from local clone** — always present +4. **Verify** — always present + +Use `{{mustache}}` variables throughout. + +**Publish template structure:** + +Author-facing only. No install commands: + +1. **Prerequisites** — always present (required manifests/metadata) +2. **Submit to registry** — only if the platform has a submission process +3. **Team / org distribution** — only if the platform has a mechanism + +**Verification gate:** +- [ ] Both files exist at the expected paths +- [ ] Install template has "Install from GitHub", "Install from local clone", and "Verify" sections +- [ ] Install template has "Install from registry" only if the platform has a registry +- [ ] Publish template has "Prerequisites" section +- [ ] Publish template contains zero install commands (`grep -c "install\|clone\|cp " ` returns 0 or only false positives) +- [ ] Both templates use `{{mustache}}` variables, not hardcoded values + +--- + +## Phase 6: Pattern updates + +**Modify:** Files in `lib/patterns/` + +**Inputs:** +- Research doc from Phase 1 +- Platform spec from Phase 2 + +**What to update:** + +- `lib/patterns/publishing-and-discoverability.md` — add platform to the quick reference table and add a dedicated platform section +- `lib/patterns/hook-merging.md` — add the platform's hook format if it supports hooks +- Other pattern files as needed based on platform capabilities + +**Verification gate:** +- [ ] `grep "" lib/patterns/publishing-and-discoverability.md` returns hits +- [ ] If the platform has hooks: `grep "" lib/patterns/hook-merging.md` returns hits +- [ ] All platform-specific claims in pattern files are consistent with the research doc + +--- + +## Phase 7: Skill integration + +**Modify:** `skills/plugin-portability/SKILL.md` + +**Inputs:** All artifacts from Phases 1–6. + +**What to update:** + +Three locations in the skill's intent-gathering pseudocode: + +1. **The `options` array** in the "Select target platforms" question — add a new entry with `label` and `description` +2. **The `ELSE` fallback list** — the `platforms = ["claude-code", "cursor", ...]` line that defines the "All platforms" default +3. **The "All platforms" option description** — if it enumerates platform names, add the new one + +**Verification gate:** +- [ ] Platform appears in the `options` array with `label` and `description` +- [ ] `description` accurately summarizes the platform (no fabricated features) +- [ ] Platform appears in the `ELSE` fallback list: `grep 'platforms = \[' skills/plugin-portability/SKILL.md` shows the new platform +- [ ] "All platforms" option description includes the new platform +- [ ] Template file count increased: `find lib/templates/install-docs -name "*.md" | wc -l` is 2 more than before + +--- + +## Cross-cutting updates + +Files that need a mention of the new platform but don't have their own phase: + +| File | What to update | +|------|----------------| +| `docs/reconciliation-matrix.md` | Add a new section for the platform tracking claim verification status | +| `README.md` | Add platform to the "What it does" artifacts table | +| `CHANGELOG.md` | Add an entry for the new platform | + +--- + +## Final verification checklist + +Run these end-to-end checks after all phases and cross-cutting updates are complete: + +- [ ] `find lib/references/platforms -name "*.md" | wc -l` matches expected platform count +- [ ] `find lib/rubrics -name "*.yaml" | wc -l` matches expected platform count +- [ ] `find lib/templates/install-docs/install -name "*.md" | wc -l` matches expected platform count +- [ ] `find lib/templates/install-docs/publish -name "*.md" | wc -l` matches expected platform count +- [ ] Platform appears in the skill's platform selection options and ELSE fallback list +- [ ] Platform appears in `lib/patterns/publishing-and-discoverability.md` quick reference table +- [ ] Phase 7 glob `lib/templates/install-docs/**/*.md` matches all template files +- [ ] No hardcoded platform counts in README or CONTRIBUTING that are now stale +- [ ] `INSTALL.md` and `PUBLISHING.md` are regenerated from the new templates (or noted as needing regeneration for a specific target plugin) diff --git a/lib/references/platforms/antigravity.md b/lib/references/platforms/antigravity.md index 4df428b..ef91f59 100644 --- a/lib/references/platforms/antigravity.md +++ b/lib/references/platforms/antigravity.md @@ -114,7 +114,7 @@ REGISTRY["antigravity"] = { } ``` -### Antigravity-specific notes +## Antigravity-specific notes - ALL tool names differ from Claude Code (every single one is renamed). - No hook system at all. diff --git a/lib/references/platforms/codex.md b/lib/references/platforms/codex.md index b1ef7bc..c6127b8 100644 --- a/lib/references/platforms/codex.md +++ b/lib/references/platforms/codex.md @@ -104,7 +104,7 @@ REGISTRY["codex"] = { } ``` -### Codex-specific notes +## Codex-specific notes - Hooks require `codex_hooks = true` feature flag in `config.toml`. - Subagent dispatch requires `multi_agent = true` feature flag. diff --git a/lib/references/platforms/cursor.md b/lib/references/platforms/cursor.md index 326a69d..d4ea684 100644 --- a/lib/references/platforms/cursor.md +++ b/lib/references/platforms/cursor.md @@ -112,7 +112,7 @@ REGISTRY["cursor"] = { } ``` -### Cursor-specific notes +## Cursor-specific notes - Cursor hooks use `"version": 1` at top level of hooks-cursor.json. - Flat hook structure: no nested `hooks[]` array; each entry has `event`, diff --git a/lib/references/platforms/openclaw.md b/lib/references/platforms/openclaw.md index d8f4260..249d6a7 100644 --- a/lib/references/platforms/openclaw.md +++ b/lib/references/platforms/openclaw.md @@ -114,7 +114,7 @@ REGISTRY["openclaw"] = { } ``` -### OpenClaw-specific notes +## OpenClaw-specific notes - Hooks are TypeScript SDK-based: `api.registerHook(event, handler)` or `api.on(event, handler)`. No file-based hook config. diff --git a/lib/templates/install-docs/adding-platform/antigravity.md b/lib/templates/install-docs/adding-platform/antigravity.md deleted file mode 100644 index 7d2170c..0000000 --- a/lib/templates/install-docs/adding-platform/antigravity.md +++ /dev/null @@ -1,11 +0,0 @@ -### Antigravity - -Copy your skills into Antigravity's expected directory structure: - -```bash -cp -r /path/to/existing/{{name}}/skills .agents/skills/{{name}}/ -``` - -Create `antigravity/package.json` with your plugin metadata (name, version, description, keywords). - -Restart Antigravity to pick up the new skills. diff --git a/lib/templates/install-docs/adding-platform/claude-code.md b/lib/templates/install-docs/adding-platform/claude-code.md deleted file mode 100644 index 2a71c7b..0000000 --- a/lib/templates/install-docs/adding-platform/claude-code.md +++ /dev/null @@ -1,15 +0,0 @@ -### Claude Code - -Point Claude Code at your existing checkout: - -```bash -claude --plugin-dir /path/to/existing/{{name}} -``` - -Or add to `.claude/settings.json` for persistent access: - -```json -{ - "extraKnownMarketplaces": ["/path/to/existing/{{name}}"] -} -``` diff --git a/lib/templates/install-docs/adding-platform/codex.md b/lib/templates/install-docs/adding-platform/codex.md deleted file mode 100644 index f8295f5..0000000 --- a/lib/templates/install-docs/adding-platform/codex.md +++ /dev/null @@ -1,15 +0,0 @@ -### Codex - -For local development against an existing checkout, register the checkout itself as a marketplace: - -```bash -codex marketplace add /path/to/existing/{{name}} -``` - -Then open `/plugins` in Codex and install `{{name}}`. - -If you only want skill discovery, symlink the skills directory from your existing checkout: - -```bash -ln -s /path/to/existing/{{name}}/skills ~/.agents/skills/{{name}} -``` diff --git a/lib/templates/install-docs/adding-platform/cursor.md b/lib/templates/install-docs/adding-platform/cursor.md deleted file mode 100644 index 00c5b73..0000000 --- a/lib/templates/install-docs/adding-platform/cursor.md +++ /dev/null @@ -1,9 +0,0 @@ -### Cursor - -Symlink your existing checkout into Cursor's plugin directory: - -```bash -ln -s /path/to/existing/{{name}} ~/.cursor/plugins/local/{{name}} -``` - -Restart Cursor (Developer: Reload Window). diff --git a/lib/templates/install-docs/adding-platform/gemini-cli.md b/lib/templates/install-docs/adding-platform/gemini-cli.md deleted file mode 100644 index f0e65cb..0000000 --- a/lib/templates/install-docs/adding-platform/gemini-cli.md +++ /dev/null @@ -1,7 +0,0 @@ -### Gemini CLI - -Point Gemini at your existing checkout: - -```bash -gemini extensions install /path/to/existing/{{name}} -``` diff --git a/lib/templates/install-docs/adding-platform/openclaw.md b/lib/templates/install-docs/adding-platform/openclaw.md deleted file mode 100644 index 8155a30..0000000 --- a/lib/templates/install-docs/adding-platform/openclaw.md +++ /dev/null @@ -1,11 +0,0 @@ -### OpenClaw - -Create `openclaw/openclaw.plugin.json` with your plugin metadata (id, name, description, version, skills list). - -Add the plugin to your local OpenClaw config for testing: - -```bash -openclaw plugins install --path /path/to/existing/{{name}} -``` - -Verify with `openclaw plugins list` to confirm the plugin loads correctly. diff --git a/lib/templates/install-docs/antigravity.md b/lib/templates/install-docs/antigravity.md deleted file mode 100644 index 7e718fc..0000000 --- a/lib/templates/install-docs/antigravity.md +++ /dev/null @@ -1,29 +0,0 @@ -## Antigravity - -### Skill-only install - -Copy the skills directory into your workspace or global config: - -```bash -# Workspace-local (per-project) -cp -r /path/to/{{name}}/skills .agents/skills/{{name}}/ - -# Global (available in all workspaces) -cp -r /path/to/{{name}}/skills ~/.gemini/antigravity/skills/{{name}}/ -``` - -### Extension install - -Install from the OpenVSX registry or from a local `.vsix` package: - -```bash -# From OpenVSX (if published) -antigravity --install-extension {{name}} - -# From local .vsix file -antigravity --install-extension /path/to/{{name}}.vsix -``` - -### Verify - -Start a new Antigravity session and check that skills from {{displayName}} appear in the skill listing at conversation start. Skills should be listed when the agent enumerates available capabilities. diff --git a/lib/templates/install-docs/claude-code.md b/lib/templates/install-docs/claude-code.md deleted file mode 100644 index 17ac5d1..0000000 --- a/lib/templates/install-docs/claude-code.md +++ /dev/null @@ -1,31 +0,0 @@ -## Claude Code - -### Marketplace install - -```bash -claude plugin install {{name}}@{{marketplaceName}} -``` - -### Local development - -```bash -claude --plugin-dir ./path-to-{{name}} -``` - -### Project install - -Add to `.claude/settings.json`: - -```json -{ - "extraKnownMarketplaces": ["./path-to-marketplace"] -} -``` - -### Verify - -```bash -claude plugin list -``` - -Look for `{{name}}` in the output. diff --git a/lib/templates/install-docs/codex.md b/lib/templates/install-docs/codex.md deleted file mode 100644 index f63277c..0000000 --- a/lib/templates/install-docs/codex.md +++ /dev/null @@ -1,75 +0,0 @@ -## Codex - -Codex supports two different install shapes. Use the one that matches what this repo ships. - -### Native plugin packaging - -If the repo includes both `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`, install it as a Codex plugin: - -```bash -codex marketplace add {{repository}} -``` - -Then open `/plugins` in Codex and install `{{name}}`. - -Codex persists the plugin enablement as a separate config entry: - -```toml -[plugins."{{name}}@{{marketplaceName}}"] -enabled = true -``` - -### Local development for plugin repos - -Use this only when you are intentionally testing a local checkout rather than installing from GitHub: - -```bash -codex marketplace add /path/to/{{name}} -``` - -Then open `/plugins` in Codex and install `{{name}}`. - -### Skill discovery - -If the repo is published as raw skills only, or you only want the skills and do not need Codex plugin packaging, clone the repo and expose the skills directory: - -```bash -git clone {{repository}} -ln -s $(pwd)/{{name}}/skills ~/.agents/skills/{{name}} -``` - -Use this path when the repo does not ship Codex plugin manifests, or when you intentionally want skills without plugin packaging. - -### Context file - -Codex uses `AGENTS.md` as its primary context file. - -### Hooks - -If this plugin includes hooks (`hooks/hooks.json`), enable the Codex hooks feature flag: - -```toml -# ~/.codex/config.toml -[features] -codex_hooks = true -``` - -Without this flag, hooks are silently ignored. Codex uses the same `hooks/hooks.json` format as Claude Code — no separate hook file is needed. - -### Multi-agent support - -If this plugin's skills use subagent dispatch, confirm multi-agent mode is enabled: - -```toml -# ~/.codex/config.toml -[features] -multi_agent = true -``` - -### Verify - -Start a new Codex session and check one of: - -- `/plugins` shows `{{name}}` as installed -- `~/.codex/config.toml` contains both the marketplace entry and the enabled plugin entry -- the relevant `$` skill resolves in a fresh session diff --git a/lib/templates/install-docs/cursor.md b/lib/templates/install-docs/cursor.md deleted file mode 100644 index 1d97c49..0000000 --- a/lib/templates/install-docs/cursor.md +++ /dev/null @@ -1,21 +0,0 @@ -## Cursor - -### Marketplace install - -Search for **{{name}}** in the Cursor marketplace panel, visit `cursor.com/marketplace`, or run `/add-plugin {{name}}` in Cursor chat. - -### Local development - -Copy or symlink the plugin directory to `~/.cursor/plugins/local/{{name}}/` and restart Cursor (Developer: Reload Window). - -```bash -# Symlink (recommended for development) -ln -s /path/to/{{name}} ~/.cursor/plugins/local/{{name}} - -# Or copy -cp -r /path/to/{{name}} ~/.cursor/plugins/local/{{name}}/ -``` - -### Verify - -Open Cursor and check that skills from {{name}} appear when typing `/` in chat. Rules should appear in Cursor Settings > Rules with the plugin name prefix. diff --git a/lib/templates/install-docs/gemini-cli.md b/lib/templates/install-docs/gemini-cli.md deleted file mode 100644 index f7ae761..0000000 --- a/lib/templates/install-docs/gemini-cli.md +++ /dev/null @@ -1,27 +0,0 @@ -## Gemini CLI - -### Install from GitHub - -```bash -gemini extensions install {{repository}} -``` - -### Install from local path - -```bash -gemini extensions install /path/to/{{name}} -``` - -### Verify - -```bash -gemini extensions list -``` - -Look for `{{name}}` in the output. Restart Gemini CLI if it was running during install. - -### Hook configuration - -Gemini CLI hooks are configured in your user `settings.json`, not in the repo. If this plugin includes hooks, add the following to `~/.gemini/settings.json`: - -(See the hook guidance section in the generated install docs for the specific configuration to copy.) diff --git a/lib/templates/install-docs/install-header.md b/lib/templates/install-docs/install-header.md new file mode 100644 index 0000000..91fb8e1 --- /dev/null +++ b/lib/templates/install-docs/install-header.md @@ -0,0 +1,3 @@ +# Installation + +How to install **{{displayName}}** on each supported platform. diff --git a/lib/templates/install-docs/install/antigravity.md b/lib/templates/install-docs/install/antigravity.md new file mode 100644 index 0000000..ccbab63 --- /dev/null +++ b/lib/templates/install-docs/install/antigravity.md @@ -0,0 +1,30 @@ +## Antigravity + +### Install from GitHub + +```bash +git clone {{repository}} +cp -R {{name}}/.agents/skills/{{name}} .agents/skills/ +``` + +Or for global scope: + +```bash +cp -R {{name}}/.agents/skills/{{name}} ~/.gemini/antigravity/skills/ +``` + +### Install from local clone + +```bash +cp -R /path/to/{{name}}/.agents/skills/{{name}} .agents/skills/ +``` + +Or for global scope: + +```bash +cp -R /path/to/{{name}}/.agents/skills/{{name}} ~/.gemini/antigravity/skills/ +``` + +### Verify + +Start a new Antigravity session and check that skills from {{displayName}} appear in the skill listing at conversation start. diff --git a/lib/templates/install-docs/install/claude-code.md b/lib/templates/install-docs/install/claude-code.md new file mode 100644 index 0000000..baa5a02 --- /dev/null +++ b/lib/templates/install-docs/install/claude-code.md @@ -0,0 +1,39 @@ +## Claude Code + +### Install from GitHub + +Register the plugin's marketplace, then install: + +```bash +/plugin marketplace add {{repository}} +/plugin install {{name}}@{{marketplaceName}} +``` + +### Install from local clone + +```bash +claude --plugin-dir /path/to/{{name}} +``` + +Or add to `.claude/settings.json` for persistent access: + +```json +{ + "extraKnownMarketplaces": { + "{{marketplaceName}}": { + "source": { + "source": "github", + "repo": "{{repository}}" + } + } + } +} +``` + +### Verify + +```bash +claude plugin list +``` + +Look for `{{name}}` in the output. diff --git a/lib/templates/install-docs/install/codex.md b/lib/templates/install-docs/install/codex.md new file mode 100644 index 0000000..ed33648 --- /dev/null +++ b/lib/templates/install-docs/install/codex.md @@ -0,0 +1,53 @@ +## Codex + +### Install from registry + +Open `/plugins` in Codex, search for **{{name}}**, and install it. + +### Install from GitHub + +Register the repo as a marketplace source: + +```bash +codex plugin marketplace add {{repository}} +``` + +Then open `/plugins` in Codex and install `{{name}}`. + +### Install from local clone + +```bash +codex plugin marketplace add /path/to/{{name}} +``` + +Then open `/plugins` in Codex and install `{{name}}`. + +### Platform notes + +**Context file:** Codex uses `AGENTS.md` as its primary context file. + +**Hooks:** If this plugin includes hooks, enable the Codex hooks feature flag: + +```toml +# ~/.codex/config.toml +[features] +codex_hooks = true +``` + +Without this flag, hooks are silently ignored. + +**Multi-agent:** If this plugin's skills use subagent dispatch, confirm multi-agent mode is enabled: + +```toml +# ~/.codex/config.toml +[features] +multi_agent = true +``` + +### Verify + +Start a new Codex session and check one of: + +- `/plugins` shows `{{name}}` as installed +- `~/.codex/config.toml` contains both the marketplace entry and the enabled plugin entry +- the relevant `$` skill resolves in a fresh session diff --git a/lib/templates/install-docs/install/cursor.md b/lib/templates/install-docs/install/cursor.md new file mode 100644 index 0000000..4f41885 --- /dev/null +++ b/lib/templates/install-docs/install/cursor.md @@ -0,0 +1,27 @@ +## Cursor + +### Install from registry + +Search for **{{name}}** in the Cursor marketplace panel, visit `cursor.com/marketplace`, or run in Agent chat: + +``` +/add-plugin {{repository}} +``` + +### Install from GitHub + +``` +/add-plugin {{repository}} +``` + +### Install from local clone + +Symlink or copy the plugin directory and restart Cursor (Developer: Reload Window): + +```bash +ln -s /path/to/{{name}} ~/.cursor/plugins/local/{{name}} +``` + +### Verify + +Open Cursor and check that skills from {{name}} appear when typing `/` in chat. Rules should appear in Cursor Settings > Rules with the plugin name prefix. diff --git a/lib/templates/install-docs/install/gemini-cli.md b/lib/templates/install-docs/install/gemini-cli.md new file mode 100644 index 0000000..c878411 --- /dev/null +++ b/lib/templates/install-docs/install/gemini-cli.md @@ -0,0 +1,37 @@ +## Gemini CLI + +### Install from registry + +Browse the gallery at [geminicli.com/extensions](https://geminicli.com/extensions/) and search for **{{name}}**, or install directly: + +```bash +gemini extensions install {{repository}} +``` + +With version pin: + +```bash +gemini extensions install {{repository}} --ref +``` + +### Install from GitHub + +```bash +gemini extensions install {{repository}} +``` + +### Install from local clone + +```bash +gemini extensions link /path/to/{{name}} +``` + +Changes are reflected immediately without reinstalling. + +### Verify + +```bash +gemini extensions list +``` + +Look for `{{name}}` in the output. diff --git a/lib/templates/install-docs/install/openclaw.md b/lib/templates/install-docs/install/openclaw.md new file mode 100644 index 0000000..83542f4 --- /dev/null +++ b/lib/templates/install-docs/install/openclaw.md @@ -0,0 +1,46 @@ +## OpenClaw + +### Install from registry + +Install from ClawHub: + +```bash +openclaw plugins install clawhub:{{name}} +``` + +Or from npm: + +```bash +openclaw plugins install @org/{{name}} +``` + +### Install from GitHub + +Clone the repo and install locally: + +```bash +git clone {{repository}} +openclaw plugins install -l ./{{name}} +``` + +### Install from local clone + +Add to `plugins.load.paths` in `~/.openclaw/openclaw.json`: + +```json +{ + "plugins": { + "load": { + "paths": ["/path/to/{{name}}"] + } + } +} +``` + +### Verify + +```bash +openclaw plugins list +``` + +Skills from {{displayName}} should appear in the plugin listing. diff --git a/lib/templates/install-docs/openclaw.md b/lib/templates/install-docs/openclaw.md deleted file mode 100644 index f77f830..0000000 --- a/lib/templates/install-docs/openclaw.md +++ /dev/null @@ -1,46 +0,0 @@ -## OpenClaw - -### ClawHub install - -Install directly from the ClawHub registry: - -```bash -openclaw plugins install {{name}} -``` - -### npm install - -If published to npm under an org scope: - -```bash -openclaw plugins install @org/openclaw-{{name}} -``` - -### Local install - -Add the plugin path to `plugins.load.paths` in your `openclaw.json` config: - -```json -{ - "plugins": { - "load": { - "paths": ["/path/to/{{name}}"] - } - } -} -``` - -### Bundle detection - -OpenClaw can auto-detect plugins that use the `.claude-plugin/` directory layout. If your plugin already has a `.claude-plugin/plugin.json`, OpenClaw may load it without conversion. Test with a local install first. - -### Verify - -Check that the plugin loads successfully in the gateway logs: - -```bash -openclaw plugins list -openclaw logs --filter="plugin:{{name}}" -``` - -Skills from {{displayName}} should appear in the plugin listing and be invocable from chat. diff --git a/lib/templates/install-docs/publishing.md b/lib/templates/install-docs/publish-header.md similarity index 57% rename from lib/templates/install-docs/publishing.md rename to lib/templates/install-docs/publish-header.md index c4c468d..f92e4cd 100644 --- a/lib/templates/install-docs/publishing.md +++ b/lib/templates/install-docs/publish-header.md @@ -1,5 +1,5 @@ # Publishing & Discoverability -How to get **{{displayName}}** discovered and installed on each platform. +How to get **{{displayName}}** listed and distributed on each platform. See [INSTALL.md](INSTALL.md) for end-user installation instructions. diff --git a/lib/templates/install-docs/publish/antigravity.md b/lib/templates/install-docs/publish/antigravity.md new file mode 100644 index 0000000..cd2a25c --- /dev/null +++ b/lib/templates/install-docs/publish/antigravity.md @@ -0,0 +1,8 @@ +## Antigravity + +### Prerequisites + +- `.agents/skills/{{name}}/SKILL.md` with standard frontmatter (`name`, `description`) +- Optional: `AGENTS.md` context file + +Antigravity auto-discovers skills from `.agents/skills/` directories — no platform-specific manifest or registry submission required. Share the Git repository URL to distribute. diff --git a/lib/templates/install-docs/publish/claude-code.md b/lib/templates/install-docs/publish/claude-code.md new file mode 100644 index 0000000..8419b72 --- /dev/null +++ b/lib/templates/install-docs/publish/claude-code.md @@ -0,0 +1,24 @@ +## Claude Code + +### Prerequisites + +Create `.claude-plugin/marketplace.json` listing the plugins the repo contains. No submission or review process — any Git repo with a valid marketplace manifest can be consumed. + +### Team / org distribution + +Add to the team's project `.claude/settings.json` so teammates get the marketplace automatically: + +```json +{ + "extraKnownMarketplaces": { + "{{marketplaceName}}": { + "source": { + "source": "github", + "repo": "{{repository}}" + } + } + } +} +``` + +Auto-enable plugins via `"enabledPlugins"` in the same settings file. diff --git a/lib/templates/install-docs/publish/codex.md b/lib/templates/install-docs/publish/codex.md new file mode 100644 index 0000000..c16b0ba --- /dev/null +++ b/lib/templates/install-docs/publish/codex.md @@ -0,0 +1,9 @@ +## Codex + +### Prerequisites + +- `.codex-plugin/plugin.json` manifest +- `.agents/plugins/marketplace.json` listing the plugin with source path, description, version +- For a single-plugin GitHub repo, the marketplace entry should point at the repo root with `source.path: "./"` + +Self-serve publishing to the official Plugin Directory is coming soon. In the meantime, plugins are distributed via Git repos with marketplace manifests. diff --git a/lib/templates/install-docs/publish/cursor.md b/lib/templates/install-docs/publish/cursor.md new file mode 100644 index 0000000..a1e6a9d --- /dev/null +++ b/lib/templates/install-docs/publish/cursor.md @@ -0,0 +1,16 @@ +## Cursor + +### Prerequisites + +- Plugin must be open-source in a Git repository +- `.cursor-plugin/plugin.json` manifest required (minimum: `name` field) + +### Submit to registry + +1. Go to `cursor.com/marketplace/publish` +2. Submit the plugin for review +3. Every plugin and update is manually reviewed before listing + +### Team / org distribution + +Cursor 2.6+ (Teams/Enterprise): admins import GitHub repos as team marketplaces via Dashboard Settings. Admins set plugins as required or optional. diff --git a/lib/templates/install-docs/publish/gemini-cli.md b/lib/templates/install-docs/publish/gemini-cli.md new file mode 100644 index 0000000..8a5076b --- /dev/null +++ b/lib/templates/install-docs/publish/gemini-cli.md @@ -0,0 +1,14 @@ +## Gemini CLI + +### Prerequisites + +Include `gemini-extension.json` at the repo root with `name`, `version`, and `description` fields. The repo must be public on GitHub. + +### Submit to registry + +No manual submission process. To get listed in the gallery: + +1. Add the `gemini-cli-extension` topic to the repository's About section on GitHub +2. The gallery crawler indexes tagged repos daily; listing appears within ~1 week + +Browse existing extensions at [geminicli.com/extensions](https://geminicli.com/extensions/). diff --git a/lib/templates/install-docs/publish/openclaw.md b/lib/templates/install-docs/publish/openclaw.md new file mode 100644 index 0000000..c8680cb --- /dev/null +++ b/lib/templates/install-docs/publish/openclaw.md @@ -0,0 +1,25 @@ +## OpenClaw + +### Prerequisites + +- `openclaw/openclaw.plugin.json` manifest with `id` and `configSchema` (required for native plugins) +- `package.json` with `openclaw.extensions` and `openclaw.compat` (required for npm distribution) +- Optional: `AGENTS.md` context file, `skills/*/SKILL.md` for skill-bearing plugins + +### Submit to registry + +**ClawHub:** + +```bash +npm i -g clawhub +clawhub login +clawhub package publish your-org/{{name}} +``` + +**npm (alternative):** + +```bash +npm publish --access public +``` + +Users can install from either registry. Bare names check ClawHub first, then npm. diff --git a/lib/templates/install-docs/publishing/antigravity.md b/lib/templates/install-docs/publishing/antigravity.md deleted file mode 100644 index 6cee9d3..0000000 --- a/lib/templates/install-docs/publishing/antigravity.md +++ /dev/null @@ -1,19 +0,0 @@ -## Antigravity - -Public registry at [open-vsx.org](https://open-vsx.org/) (open, community-maintained). - -### Publishing - -1. Ensure `antigravity/package.json` manifest is present with all required fields -2. Package the extension: `antigravity package` -3. Create an account and namespace on [open-vsx.org](https://open-vsx.org/) -4. Publish: `antigravity publish` or upload the `.vsix` file via the web UI - -### How users find and install {{displayName}} - -- Search for **{{name}}** on [open-vsx.org](https://open-vsx.org/) -- Install via CLI: `antigravity --install-extension {{name}}` - -### Team distribution - -Share the `.vsix` file directly or host on a private extension registry. diff --git a/lib/templates/install-docs/publishing/claude-code.md b/lib/templates/install-docs/publishing/claude-code.md deleted file mode 100644 index 57ac054..0000000 --- a/lib/templates/install-docs/publishing/claude-code.md +++ /dev/null @@ -1,29 +0,0 @@ -## Claude Code - -No public marketplace — distribution is via Git repositories. - -### Publishing - -Create a `.claude-plugin/marketplace.json` in your repo. No submission or review process — any Git repo with a valid marketplace manifest can be consumed. - -### How users find and install {{displayName}} - -1. Register the marketplace: `/plugin marketplace add {{repository}}` -2. Install: `/plugin install {{name}}@{{marketplaceName}}` - -### Team distribution - -Teams can auto-register the marketplace by adding to their project `.claude/settings.json`: - -```json -{ - "extraKnownMarketplaces": { - "{{marketplaceName}}": { - "source": { - "source": "github", - "repo": "{{repository}}" - } - } - } -} -``` diff --git a/lib/templates/install-docs/publishing/codex.md b/lib/templates/install-docs/publishing/codex.md deleted file mode 100644 index 8ecc730..0000000 --- a/lib/templates/install-docs/publishing/codex.md +++ /dev/null @@ -1,38 +0,0 @@ -## Codex - -Two publishing paths — choose based on what you're distributing. - -### Skill discovery (lightweight) - -For repos that are mostly instructions with no plugin UI metadata: - -- Submit a PR to `github.com/openai/skills` for inclusion in the curated catalog -- Or publish as a standalone GitHub repo — users install through Codex skill discovery -- Only recommend `$skill-installer install {{repository}}` when the distributed artifact is truly a skill-only repo and does not depend on root-level plugin manifests, hooks, or shared context files - -### Plugin packaging (full) - -For first-class plugin packages with marketplace metadata: - -- Create `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` -- For a single-plugin GitHub repo, the marketplace entry should point at the repo root with `source.path: "./"` -- Users register via `codex marketplace add {{repository}}` -- Users then enable the plugin from `/plugins` -- Public self-serve plugin publishing is coming soon per OpenAI docs - -### How users find and install {{displayName}} - -**Skill-only repo:** - -```bash -git clone {{repository}} -ln -s $(pwd)/{{name}}/skills ~/.agents/skills/{{name}} -``` - -**Plugin repo:** - -```bash -codex marketplace add {{repository}} -``` - -Then enable `{{name}}` from `/plugins`. diff --git a/lib/templates/install-docs/publishing/cursor.md b/lib/templates/install-docs/publishing/cursor.md deleted file mode 100644 index fca13e2..0000000 --- a/lib/templates/install-docs/publishing/cursor.md +++ /dev/null @@ -1,19 +0,0 @@ -## Cursor - -Public marketplace at `cursor.com/marketplace` (curated, manually reviewed). - -### Publishing - -1. Ensure the plugin is open-source in a Git repository -2. `.cursor-plugin/plugin.json` manifest must be present -3. Submit at `cursor.com/marketplace/publish` -4. Every plugin and update is manually reviewed - -### How users find and install {{displayName}} - -- Browse the marketplace at `cursor.com/marketplace` -- In Agent chat: `/add-plugin {{repository}}` - -### Team distribution - -Cursor 2.6+ (Teams/Enterprise): admins import GitHub repos as team marketplaces via Dashboard Settings. diff --git a/lib/templates/install-docs/publishing/gemini-cli.md b/lib/templates/install-docs/publishing/gemini-cli.md deleted file mode 100644 index 9725896..0000000 --- a/lib/templates/install-docs/publishing/gemini-cli.md +++ /dev/null @@ -1,15 +0,0 @@ -## Gemini CLI - -Extensions gallery at [geminicli.com/extensions](https://geminicli.com/extensions/). - -### Publishing - -Publish as a GitHub repository with a `gemini-extension.json` manifest (requires `name`, `version`, `description`). Extensions are not vetted by Google. - -### How users find and install {{displayName}} - -```bash -gemini extensions install {{repository}} -``` - -Users can browse the gallery or install directly from the GitHub URL. diff --git a/lib/templates/install-docs/publishing/openclaw.md b/lib/templates/install-docs/publishing/openclaw.md deleted file mode 100644 index 4ff261b..0000000 --- a/lib/templates/install-docs/publishing/openclaw.md +++ /dev/null @@ -1,23 +0,0 @@ -## OpenClaw - -Public registries: [ClawHub](https://clawhub.ai) (curated) and npm (open). - -### Publishing to ClawHub - -1. Ensure `openclaw/openclaw.plugin.json` manifest is present with required fields (`id`, `configSchema`) -2. Install the ClawHub CLI: `npm i -g clawhub` -3. Authenticate: `clawhub login` -4. Publish: `clawhub package publish your-org/{{name}}` -5. Submissions are reviewed before appearing in the registry - -### Publishing to npm - -1. Add an npm-compatible `package.json` with `openclaw.extensions` and `openclaw.compat` -2. Publish: `npm publish --access public` -3. Users install with: `openclaw plugins install @org/{{name}}` - -### How users find and install {{displayName}} - -- Browse [ClawHub](https://clawhub.ai) or search npm for `{{name}}` -- Install via ClawHub: `openclaw plugins install clawhub:{{name}}` -- Install via npm: `openclaw plugins install @org/{{name}}` diff --git a/skills/plugin-portability/SKILL.md b/skills/plugin-portability/SKILL.md index 5b2076a..45352c1 100644 --- a/skills/plugin-portability/SKILL.md +++ b/skills/plugin-portability/SKILL.md @@ -104,7 +104,7 @@ INTENT_UPFRONT(): { label: "Cursor", description: "VS Code fork with rules, hooks, MCP" }, { label: "Gemini CLI", description: "Google CLI with @ includes and settings-based hooks" }, { label: "Codex", description: "OpenAI CLI with TOML agents and spawn_agent" }, - { label: "Antigravity", description: "Google VS Code fork, OpenVSX, .agents/skills/" }, + { label: "Antigravity", description: "Google VS Code fork, .agents/skills/ auto-discovery" }, { label: "OpenClaw", description: "TypeScript gateway with plugin SDK hooks" } ], multiSelect: true