From a84066c1dd77e331b178e4a28eecec6415f4a0f6 Mon Sep 17 00:00:00 2001
From: dan <dan@delpad>
Date: Fri, 9 Jan 2026 11:44:15 -0800
Subject: [PATCH] docs: add ADR-005 for dual-publish plugin architecture

Captures the decision to maintain both:
- Nix deployment (cross-agent: Gemini, OpenCode)
- Claude plugin system (hooks, marketplace)

Documents trade-offs, consequences, and mitigations.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../005-dual-publish-plugin-architecture.md   | 117 ++++++++++++++++++
 docs/emes-conversion-guide.md                 |   2 +
 2 files changed, 119 insertions(+)
 create mode 100644 docs/adr/005-dual-publish-plugin-architecture.md

diff --git a/docs/adr/005-dual-publish-plugin-architecture.md b/docs/adr/005-dual-publish-plugin-architecture.md
new file mode 100644
index 0000000..3d4febb
--- /dev/null
+++ b/docs/adr/005-dual-publish-plugin-architecture.md
@@ -0,0 +1,117 @@
+# ADR-005: Dual-Publish Plugin Architecture
+
+## Status
+
+Accepted (2026-01-09)
+
+## Context
+
+Claude Code introduced an official plugin system (October 2025) with:
+- `.claude-plugin/plugin.json` for metadata
+- `skills/` directory for auto-discovery
+- Marketplace distribution via `/plugin install`
+- Lifecycle hooks (SessionStart, PostToolUse, etc.)
+
+We already had a working system:
+- `SKILL.md` files with YAML frontmatter
+- Nix deployment to `~/.claude/skills/`
+- Cross-agent support (Gemini, OpenCode, Claude)
+- Lenses pattern for multi-pass code review
+
+### The Problem
+
+1. **Claude's system is Claude-only** - Gemini can't read Claude plugins (see skills-bo8: path restrictions)
+2. **Our system lacks hooks** - No lifecycle events, mechanical enforcement
+3. **Distribution differs** - Nix vs marketplace
+
+### Alternatives Considered
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **Migrate fully to Claude plugins** | Native UX, hooks, marketplace | Lose Gemini/OpenCode support |
+| **Keep Nix-only** | Cross-agent, system-level | No hooks, no marketplace |
+| **Dual-publish (chosen)** | Best of both | Maintenance overhead |
+
+## Decision
+
+**Dual-publish**: Maintain both systems in parallel.
+
+Each skill has:
+```
+skills/my-skill/
+├── .claude-plugin/
+│   └── plugin.json        # Claude plugin metadata
+├── skills/
+│   └── my-skill.md        # Claude auto-discovery
+├── SKILL.md               # Nix deployment (cross-agent)
+└── README.md
+```
+
+The repo root has:
+```
+.claude-plugin/
+└── marketplace.json       # Plugin registry for /plugin install
+```
+
+### How It Works
+
+**Nix path (Gemini, OpenCode, system-level):**
+1. `deploy-skill.sh` copies skill to dotfiles
+2. Home-manager deploys to `~/.claude/skills/`
+3. Agents read `SKILL.md` directly
+
+**Claude plugin path:**
+1. User adds marketplace: `/plugin marketplace add dan/skills`
+2. User installs: `/plugin install orch@dan-skills`
+3. Claude discovers `skills/orch.md` automatically
+
+**Content is identical** - `skills/orch.md` is a copy of `SKILL.md`.
+
+### Marketplace Structure
+
+```json
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "dan-skills",
+  "version": "1.0.0",
+  "description": "Dual-publish for cross-agent support",
+  "owner": { "name": "dan" },
+  "plugins": [
+    { "name": "orch", "source": "./skills/orch" }
+  ]
+}
+```
+
+## Consequences
+
+### Positive
+
+- **Cross-agent support preserved** - Gemini, OpenCode continue working
+- **Claude features available** - Hooks, marketplace, `/plugin install`
+- **Gradual migration** - Convert skills one at a time
+- **No breaking changes** - Existing Nix deployment unchanged
+
+### Negative
+
+- **Duplication** - `SKILL.md` and `skills/<name>.md` must stay in sync
+- **Two mental models** - Nix vs plugin system
+- **Testing complexity** - Must verify both paths work
+
+### Mitigations
+
+- **Automation**: Script to sync `SKILL.md` → `skills/<name>.md`
+- **CI validation**: Check files are identical
+- **Documentation**: `docs/emes-conversion-guide.md`
+
+## Related
+
+- **skills-6x1**: Epic for emes plugin architecture
+- **skills-bo8**: Gemini path restriction issue (motivates cross-agent need)
+- **skills-1ks**: Task to convert remaining skills
+- **skills-17f**: Forgejo access for distribution
+
+## References
+
+- [Claude Code Plugin Docs](https://code.claude.com/docs/en/plugins)
+- [emes org](https://github.com/evil-mind-evil-sword) - Inspiration for plugin patterns
+- [Anthropic marketplace.json](https://github.com/anthropics/claude-code/blob/main/.claude-plugin/marketplace.json)
diff --git a/docs/emes-conversion-guide.md b/docs/emes-conversion-guide.md
index 6b86092..79df787 100644
--- a/docs/emes-conversion-guide.md
+++ b/docs/emes-conversion-guide.md
@@ -2,6 +2,8 @@
 
 Converting skills to support both Nix deployment (cross-agent) AND Claude plugin system.
 
+> **Architecture Decision:** See [ADR-005](adr/005-dual-publish-plugin-architecture.md) for rationale.
+
 ## Why Dual-Publish?
 
 | System | Pros | Cons |