Open Plugin - Full Project Review (GPT-5.2 Pro via Oracle)

REVIEW.md

Open Plugin Project Review

Reviewed: 2026-03-02 Reviewer: GPT-5.2 Pro (via Oracle) + Claude Opus 4.6 Scope: Full project review against Claude Code's plugin system for cross-harness viability

---

1) Gap Analysis vs Claude Code

Matches well

• Same core components (skills, commands, agents, rules, hooks, MCP, LSP)
• Same namespacing (plugin-name:component-name)
• Same scopes (user/project/local/managed)
• Same hook action types (command/prompt/agent)
• Same plugin root placeholder concept

Missing from Claude Code

1. Plugin-level settings.json — Claude Code supports a settings.json with an agent key. Open Plugin doesn't spec this at all. Add a settings component spec.
2. outputStyles is a ghost — referenced in manifest schema but has no component spec. Cut it or spec it.
3. Marketplace registry semantics — Claude Code has submission pipeline; Open Plugin only has the interchange file format.

Divergences that cause friction

1. Vendor-neutral .plugin/ vs reality — the installer still has to generate .claude-plugin/ and translate ${PLUGIN_ROOT} → ${CLAUDE_PLUGIN_ROOT}. The "universal" layer requires translation glue.
2. Hooks define more events than Claude Code — extended events (file, shell, MCP lifecycle, UI) that most harnesses won't fire, creating a portability trap.

---

2) Cross-Harness Portability

Portability	Components
High (truly universal)	Plugin directory packaging, namespacing, skills/commands/agents/rules as markdown, marketplace.json index
Medium (protocol-dependent)	MCP servers, LSP servers
Low (harness-shaped)	Hooks (event existence, payload schema all tool-defined), installation UX, slash command UI

Recommendation: Market it as "universal packaging + discovery + namespacing" with "optional automation surfaces where supported" — and encode that conditionality in the spec.

---

3) Spec Quality

Ambiguities that will cause implementer divergence

• Manifest component path fields — three forms (string/array/object) with no formal JSON schema, no normative resolution algorithm, no merge order rules
• Path safety — rules exist but enforcement details missing (symlinks post-install, absolute paths in configs, deep ${PLUGIN_ROOT} replacement)
• Hook payloads are "tool-defined" — need at least a minimal stable JSON payload shape per event
• Name constraints inconsistent — plugin names allow periods, agent names are kebab-case only
• "Spec Version 1.0.0" feels premature — outputStyles unspecced, reference implementations don't cover major spec features

---

4) Code Quality

plugin-ref (reference library)

Good: Small, readable, low deps (zod + yaml), clear CLI.

Major gaps vs spec:

1. Only looks for .plugin/plugin.json — doesn't check vendor-prefixed dirs
2. Ignores manifest component path fields entirely (custom paths, inline configs)
3. discoverHooks() throws away event names (returns flat array)
4. README usage bug (parseManifest takes dir path but docs show file path)
5. No tests at all

add-plugin (installer CLI)

Good: Valuable product idea, practical marketplace discovery fallback.

Critical issues:

1. Command injection — execSync with unsanitized user input (git clone, claude plugin commands). Use spawnSync/execFileSync with argument arrays.
2. Mutates local source directory — writes .claude-plugin/ and rewrites config placeholders in-place. Always stage/copy first.
3. Naive frontmatter parser — hand-rolled line parser breaks on multi-line YAML, arrays, quoted values with colons. Share the YAML parser from plugin-ref.
4. Windows-incompatible — which for detection, unix path assumptions.

---

5) Ecosystem Readiness

Missing for v1.0

1. Stable plugin identity format — no canonical marketplace:plugin-name@version string
2. Integrity/provenance — no checksums, no signing, marketplaces are "run arbitrary code from git"
3. Permissions/capabilities declaration — plugins should declare "contains hooks", "starts MCP servers", etc.
4. Compatibility metadata — required host capabilities, OS/runtime requirements
5. Version resolution rules — what happens when marketplace and manifest versions disagree

---

6) Strategic Recommendations

Priority order for adoption

1. Make spec + reference implementations agree — spec claims features plugin-ref doesn't implement
2. Cut or finish outputStyles — don't ship v1.0 with a dangling surface
3. Define a capabilities model — host declares supportedComponents, plugin declares requiresComponents
4. Make hooks minimally portable — define payload schemas or explicitly mark hooks as tool-specific
5. Fix installer safety — command injection, source mutation, YAML parsing

Minimum viable "cross-harness" spec

Core (portable):

• Plugin directory + manifest
• Skills/commands/agents/rules discovery + namespacing
• Marketplace index format
• ${PLUGIN_ROOT} standard placeholder
• Path safety / traversal rules

Optional modules:

• Hooks (with payload standardization or explicitly tool-defined)
• MCP servers
• LSP servers

Design risks

1. Overfitting to Claude Code — this is "Claude's plugin system, generalized." That's fine, but don't claim hooks are portable until payloads are standardized.
2. Security reputation — "random git repo executes scripts" will kill adoption. Need integrity + warnings.
3. "1.0.0" vs reality — calling it 1.0.0 while tooling doesn't implement major features creates distrust. Either tighten or downgrade to 0.x.

---

Concrete Next Actions

Spec

• Add settings component spec or explicitly exclude
• Remove outputStyles or write the missing spec
• Add normative algorithms for path resolution, ${PLUGIN_ROOT} expansion, conflict resolution
• Add host capabilities declaration

plugin-ref

• Implement vendor manifest discovery + manifest-driven component discovery
• Preserve hook event names in parsed output
• Add conformance test suite (golden plugins + expected output)

add-plugin

• Replace execSync string commands with argument-array process spawning
• Always stage/copy before mutating source dirs
• Use real YAML frontmatter parsing (share with plugin-ref)
• Add --dry-run and security warnings for hooks/MCP/LSP