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>
This commit is contained in:
dan
parent
3e3363e35d
commit
a84066c1dd
117
docs/adr/005-dual-publish-plugin-architecture.md
Normal file
117
docs/adr/005-dual-publish-plugin-architecture.md
Normal file
|
|
@ -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)
|
||||
|
|
@ -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 |
|
||||
|
|
|
|||
Loading…
Reference in a new issue