AGENTS.md

1# src/features/claude-code-plugin-loader/ — Unified Claude Code Plugin Loader
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7This module is the full Claude Code plugin compatibility layer. It discovers and loads ALL plugin components (commands, agents, skills, hooks, MCP servers, LSP servers) from `.opencode/plugins/` and `~/.claude/plugins/`. Shared manifest/discovery/load primitives are extracted to [`packages/claude-code-compat-core/`](../../../../../packages/claude-code-compat-core); this directory keeps OpenCode-specific integration and error surfacing.
8 
9## WHY IT EXISTS
10 
11Claude Code plugins ship commands/agents/skills as separate files with `plugin.json` manifest. OmO uses this loader to ingest them into its own registry so existing Claude Code plugins work unchanged under OmO.
12 
13## LOAD PIPELINE
14 
15```
16loadAllPluginComponents(ctx)
17  → discoverPlugins()                  # scan .opencode/plugins + ~/.claude/plugins
18  → readPluginManifest(plugin.json)    # parse name/version/commands/agents/skills/hooks/mcpServers
19  → loadPluginCommands()
20  → loadPluginAgents()
21  → loadPluginSkills()
22  → loadPluginHooks()                  # register hook handlers
23  → loadPluginMcpServers()             # feed into mcp-config-handler (tier 2)
24  → loadPluginLspServers()
25  → return LoadedPluginBundle
26```
27 
28Called from `src/plugin-handlers/plugin-components-loader.ts` during Phase 2 of config handler (10s timeout with error isolation — one broken plugin does not sink the plugin load).
29 
30## KEY FILES
31 
32| File | Purpose |
33|------|---------|
34| `index.ts` | Barrel: `loadAllPluginComponents`, `PluginManifest`, `ClaudeSettings` types |
35| `plugin-discovery.ts` | Find plugin directories across scopes |
36| `plugin-manifest-parser.ts` | Parse `plugin.json` with Zod validation |
37| `command-loader.ts` | Load commands from `commands/` or `COMMANDS.md` |
38| `agent-loader.ts` | Load agents from `agents/` or `AGENTS.md` frontmatter |
39| `skill-loader.ts` | Load skills from `skills/` or `SKILL.md` |
40| `hook-loader.ts` | Load hooks config from `hooks/` or manifest |
41| `mcp-loader.ts` | Extract MCP server configs |
42| `lsp-loader.ts` | Extract LSP server configs |
43| `settings-loader.ts` | Parse Claude Code `settings.json` |
44 
45## PLUGIN MANIFEST (plugin.json)
46 
47```jsonc
48{
49  "name": "my-plugin",
50  "version": "1.0.0",
51  "description": "...",
52  "commands": ["./commands"],       // or string[] of paths
53  "agents": ["./agents"],
54  "skills": ["./skills"],
55  "hooks": "./hooks/config.json",
56  "mcpServers": "./.mcp.json",
57  "lspServers": "./lsp"
58}
59```
60 
61## SCOPES
62 
63| Scope | Path | Priority |
64|-------|------|----------|
65| `project` | `.opencode/plugins/` | Highest |
66| `local` | `~/.opencode/plugins/` | Medium |
67| `user` | `~/.claude/plugins/` | Medium |
68| `managed` | Built-in | Lowest |
69 
70## ERROR ISOLATION
71 
72Each plugin loads in isolation — if one fails (bad manifest, missing file, syntax error), others still load. Errors surface as warnings in `bunx oh-my-opencode doctor`.
73 
74## RELATED
75 
76- Phase 2 loader: `src/plugin-handlers/plugin-components-loader.ts`
77- Tier 2 MCP integration: `src/features/claude-code-mcp-loader/`
78- Claude Code compat hooks: `src/hooks/claude-code-hooks/`
79