diff --git a/docs/research/plugin-systems-comparison.md b/docs/research/plugin-systems-comparison.md new file mode 100644 index 0000000..789a8e5 --- /dev/null +++ b/docs/research/plugin-systems-comparison.md @@ -0,0 +1,135 @@ +# Plugin Systems Comparison: Ours vs Claude vs emes + +> **Date:** 2026-01-09 +> **Status:** Living document +> **Related:** [ADR-005](../adr/005-dual-publish-plugin-architecture.md) + +## Overview + +Three plugin/skill systems for AI coding agents: + +| System | Origin | Focus | +|--------|--------|-------| +| **Ours** | This repo | Cross-agent portability | +| **Claude Plugins** | Anthropic (Oct 2025) | Claude Code extensibility | +| **emes** | [evil-mind-evil-sword](https://github.com/evil-mind-evil-sword) | Mechanical quality enforcement | + +## Feature Comparison + +| Aspect | **Our System** | **Claude Plugins** | **emes** | +|--------|---------------|-------------------|----------| +| Primary file | `SKILL.md` | `plugin.json` + `skills/*.md` | `plugin.json` + tools | +| Distribution | Nix + `deploy-skill.sh` | `/plugin install` + marketplace | `/plugin install @emes` | +| Discovery | Symlink to `~/.claude/skills/` | Auto-discovery from `skills/` | Auto-discovery | +| Multi-agent | ✅ Gemini, OpenCode, Claude | ❌ Claude only | ❌ Claude only | +| Hooks | ❌ None | ✅ 9 lifecycle events | ✅ Uses hooks heavily | +| Issue tracking | beads | N/A | tissue (their own) | +| Quality gates | ❌ Manual | ✅ Hooks possible | ✅ idle (blocks exit) | +| Messaging | N/A | N/A | jwz (async, identity-aware) | + +## Architectural Principles + +| Principle | Ours | Claude | emes | +|-----------|------|--------|------| +| Context injection | Push (SKILL.md loaded upfront) | Push (skill loaded upfront) | **Pull on-demand** | +| Enforcement | Prompt-based ("please do X") | Hooks available but optional | **Mechanical (hooks required)** | +| Content style | Inline markdown | Inline markdown | **References to files** | +| Interface | Human-readable | Human-readable | **Machine-first (JSON)** | + +## Unique Strengths + +### What We Have (that others don't) + +1. **Cross-agent support** - Works with Gemini, OpenCode, not just Claude +2. **Nix deployment** - Declarative, reproducible, system-level +3. **Lenses pattern** - Multi-pass focused review (bloat, security, coupling, etc.) +4. **beads integration** - Issue tracking across sessions + +### What Claude Has (that others don't) + +1. **Official support** - Anthropic-maintained, documented +2. **Marketplace ecosystem** - Community plugins, discovery +3. **Scope control** - user/project/local installation +4. **9 lifecycle hooks** - SessionStart, PostToolUse, PreCompact, etc. + +### What emes Has (that others don't) + +1. **idle** - Quality gate that mechanically blocks exit until reviewer approves +2. **tissue** - Issue tracker designed for agents (JSON, non-interactive) +3. **jwz** - Async messaging with git context and identity +4. **alice** - Adversarial reviewer agent (Opus-based) +5. **Mechanical enforcement** - Hooks enforce policy, not prompts + +## emes Tool Details + +| Tool | Purpose | Language | +|------|---------|----------| +| **idle** | Quality gate - blocks exit until alice reviews | Shell + hooks | +| **tissue** | Git-native issue tracking, machine-first | Zig | +| **jwz** | Async messaging with identity/git context | Zig | +| **marketplace** | Plugin distribution registry | JSON | +| **alice** | Read-only Opus reviewer, creates issues | Agent | + +### emes Key Principles + +From their architecture: + +1. **Pull context on-demand** - Don't inject large prompts upfront +2. **Mechanical enforcement** - Use hooks to enforce, not prompt instructions +3. **References over inline** - Point to files, don't embed content +4. **Machine-first interfaces** - JSON output, non-interactive CLIs + +## Philosophical Stances + +| System | Core Belief | +|--------|-------------| +| **Ours** | "Skills should work everywhere" - agent-agnostic | +| **Claude** | "Plugins extend Claude Code" - platform-specific | +| **emes** | "Enforce quality mechanically" - trust hooks, not prompts | + +## Integration Points + +### We Could Adopt from emes + +- [ ] **idle pattern** - Quality gate for code-review skill (skills-9jk) +- [ ] **tissue** - Alternative to beads? (probably not, beads is good) +- [ ] **Pull on-demand** - Reduce upfront context injection +- [ ] **Machine-first** - JSON output modes for scripts + +### We Could Adopt from Claude + +- [x] **plugin.json** - Already doing via dual-publish +- [x] **marketplace.json** - Already created +- [ ] **Hooks** - Add to skills that need lifecycle events +- [ ] **Scope control** - Let users choose install scope + +## Current Strategy: Dual-Publish + +We maintain both systems: + +``` +skills/my-skill/ +├── .claude-plugin/ +│ └── plugin.json # Claude plugin system +├── skills/ +│ └── my-skill.md # Claude auto-discovery +├── SKILL.md # Nix deployment (cross-agent) +└── README.md +``` + +**Rationale:** Cross-agent support is important. Gemini can't use Claude plugins (skills-bo8). + +## Open Questions + +1. Should we adopt tissue or stick with beads? +2. How much of emes philosophy (mechanical enforcement) should we adopt? +3. Can we make lenses work as Claude plugin hooks? +4. Should skills output JSON for machine consumption? + +## References + +- [Claude Code Plugin Docs](https://code.claude.com/docs/en/plugins) +- [emes org](https://github.com/evil-mind-evil-sword) +- [emes idle](https://github.com/evil-mind-evil-sword/idle) +- [emes tissue](https://github.com/evil-mind-evil-sword/tissue) +- [Anthropic marketplace](https://github.com/anthropics/claude-code/blob/main/.claude-plugin/marketplace.json)