docs(research): verified Claude Code + Codex plugin format reference

[selfcontained]

What this is

A research/reference document, not a feature. Adds docs/plugin-spec-reference.md — a verified spec of the external plugin formats for Claude Code and OpenAI Codex. No runtime code changes, no Dispatch plugin/skill content.

This is prerequisite scoping for the dispatch-usage-skills-bundle idea. Two earlier build attempts went off the rails partly because the agent had to research plugin-format details while designing Dispatch's own skill content, and the two kinds of uncertainty compounded. This removes the first kind.

What's in it

For both platforms: directory layout, exact plugin.json / marketplace.json schemas (field names, types, required vs optional), the literal self-hosted install commands, non-interactive/scriptable install, versioning and update semantics, trust/signing model, and version-gated feature requirements.

Every claim is grounded in either current official docs (URL cited) or an observed CLI run (command + output shown inline). Probes ran against throwaway CLAUDE_CONFIG_DIR / CODEX_HOME roots — nothing touched the real ~/.claude or ~/.codex. Nine items that could not be verified are listed explicitly rather than guessed at.

Verified against claude 2.1.231 and codex-cli 0.147.0 on 2026-08-13.

Findings that differ from what the idea assumed

• codex plugin add --non-interactive does not exist. The third-party blog claim is wrong; only --json exists. It isn't needed either — codex plugin * are already plain non-TUI subcommands. --json requires Codex ≥ 0.137 (it landed later than the commands themselves).
• Codex plugin CLI first shipped in Codex CLI v0.131.0 (2026-05-18), confirmed by checking plugin_cmd.rs presence across openai/codex release tags — absent at v0.130.0, present at v0.131.0. Not behind a feature flag, not labelled beta.
• The two formats converge one-way. Codex reads Claude Code's .claude-plugin/marketplace.json and .claude-plugin/plugin.json as fallbacks — verified by installing a Claude-format-only repo under Codex. Claude Code does not read Codex's .agents/plugins/marketplace.json. The Codex-side fallback is real (confirmed in source constants) but appears in no OpenAI doc, so it's flagged as undocumented and potentially unstable.
• A single repo tree serving both platforms is verified working — two marketplace files at the root, two plugin manifest dirs per plugin, shared skills/. Both CLIs install from it. Documented as option B alongside the cheaper Claude-format-only option A.
• Trust model confirmed for Claude Code with a verbatim quote ("execute arbitrary code on your machine with your user privileges", unsigned, unsandboxed). Codex's docs say only "Review and trust plugin hooks before you enable them" — the equivalent characterization there is flagged as inference, not policy.

Checks

Documentation only, no runtime change — per the task brief the usual pnpm run check / e2e gates don't apply and were skipped.

🤖 Generated with Claude Code

[selfcontained]

Superseded — the spec content and settled v1 design are now merged via #952. Closing per plan (build landed, spec doc's job as a standalone reference is done).