everyinc--compound-engineering-plugin/docs/grok-marketplace-submission.md

Submitting Compound Engineering to the official xAI plugin marketplace

Maintainer runbook for listing Compound Engineering in the official xAI plugin marketplace. This is a periodic "promote a stable version" action, not a per-release step — the direct-install and self-hosted-catalog paths (below) already track the repository automatically.

How the three Grok distribution paths differ

Path	Command	Version tracking	Ongoing cost
Direct install	grok plugin install EveryInc/compound-engineering-plugin	tracks repo HEAD; grok plugin update pulls latest	none
Self-hosted catalog	grok plugin marketplace add EveryInc/compound-engineering-plugin	our .grok-plugin/marketplace.json uses a bare Git URL source (no SHA) → tracks HEAD	none
Official xAI catalog	browse/install from xAI Official marketplace	a SHA-pinned remote source entry in xAI's repo	one PR per promoted version

Only the official catalog carries per-version cost: xAI requires remote sources to pin a full 40-character commit SHA (a moving ref would let a force-push ship new code silently), so updating the official listing means opening a PR that bumps the SHA. Point contributors who want the latest at direct install instead.

Submission steps (remote source — recommended for third-party)

1. Fork xai-org/plugin-marketplace and branch from main.

2. Add one entry to their .grok-plugin/marketplace.json plugins array:

   {
     "name": "compound-engineering",
     "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
     "category": "development",
     "source": {
       "source": "url",
       "url": "https://github.com/EveryInc/compound-engineering-plugin.git",
       "sha": "<full-40-char-commit-sha>"
     },
     "homepage": "https://github.com/EveryInc/compound-engineering-plugin",
     "keywords": ["compound-engineering", "compound engineering", "ce-plan", "ce-work"]
   }
   

3. Pin the SHA to the commit you want to ship (a real commit, not a branch or tag):

   git ls-remote https://github.com/EveryInc/compound-engineering-plugin.git HEAD
   

4. Regenerate their component index and validate locally (this is what their CI runs):

   python3 scripts/generate-plugin-index.py
   python3 scripts/validate-catalog.py
   python3 scripts/generate-plugin-index.py --check
   

5. Open the PR against xai-org/plugin-marketplace and fill in their template. Code-owner review is required.

Notes

• Source from the official org. The source.url must be EveryInc/compound-engineering-plugin (our org), not a personal fork — xAI flags personal-account sources for branded plugins as possible impersonation.
• To roll out an update, bump the pinned sha in the same entry and regenerate the index — do not open a parallel duplicate entry.
• Keep keywords brand-scoped. They power Grok's plugin CTA; generic terms (ai, cli, workflow) get pushed back because they mis-fire on unrelated requests.
• A local source (vendoring our files under xAI's external_plugins/compound-engineering/) is also accepted, but requires re-vendoring on every update — the remote source above is lighter to maintain.