docs(agents): refresh AGENTS.md hierarchy via /init-deep

Updated root + 14 core subdirectory AGENTS.md files to reflect current state (commit 2892ca4a on dev). Added 4 new AGENTS.md files for gap directories: hooks/comment-checker (AI slop blocker), features/claude- code-plugin-loader (CC compat layer), features/claude-code-mcp-loader (tier 2 MCP loader), cli/doctor (health diagnostics with 25 check files).
2026-04-18 01:21:20 +09:00
parent 2892ca4adf
commit 5759a9c503
19 changed files with 316 additions and 16 deletions
@@ -1,10 +1,10 @@
 # oh-my-opencode — OpenCode Plugin

-**Generated:** 2026-04-11 | **Commit:** f5dc1c0e | **Branch:** dev
+**Generated:** 2026-04-18 | **Commit:** 2892ca4a | **Branch:** dev

 ## OVERVIEW

-OpenCode plugin (npm: `oh-my-opencode`) extending Claude Code with multi-agent orchestration, 52 lifecycle hooks, 26 tools, skill/command/MCP systems, Hashline edit tool, IntentGate classifier, and Claude Code compatibility. ~1600 TypeScript source files. Dual-published as `oh-my-opencode` + `oh-my-openagent` during transition.
+OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during transition) extending Claude Code with 11 agents, 52 lifecycle hooks, 26 tools, 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate classifier, and Claude Code compatibility. 1766 TypeScript source files, 377k LOC, 104 barrel index.ts files. Entry: `src/index.ts` → 5-step init (loadConfig → createManagers → createTools → createHooks → createPluginInterface).

 ## STRUCTURE

@@ -1,6 +1,6 @@
 # src/ — Plugin Source

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/agents/ — 11 Agent Definitions

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/cli/ — CLI: install, run, doctor, mcp-oauth

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -0,0 +1,82 @@
+# src/cli/doctor/ — Health Diagnostics (25 Check Files)
+
+**Generated:** 2026-04-18
+
+## OVERVIEW
+
+`bunx oh-my-opencode doctor` — parallel diagnostic checks across 4 categories (System, Config, Tools, Models). Catches broken installs, config typos, missing dependencies, provider misconfigurations before they become runtime errors.
+
+## COMMAND FLAGS
+
+```bash
+bunx oh-my-opencode doctor              # Full diagnostics (all 4 categories)
+bunx oh-my-opencode doctor --status     # Compact dashboard (status only)
+bunx oh-my-opencode doctor --verbose    # Deep details (model resolution traces)
+bunx oh-my-opencode doctor --json       # Machine-readable output
+```
+
+## CHECK CATEGORIES
+
+| Category | File | Validates |
+|----------|------|-----------|
+| **SYSTEM** | `checks/system.ts` | OpenCode binary found + version ≥1.0.150, plugin registered in opencode.json, loaded plugin version matches installed |
+| **CONFIG** | `checks/config.ts` | JSONC validity, Zod schema passes, no unknown keys, model override syntax correct |
+| **TOOLS** | `checks/tools.ts` | AST-Grep CLI + NAPI, comment-checker binary, LSP servers reachable, GitHub CLI auth, built-in MCP reachability |
+| **MODELS** | `checks/model-resolution.ts` | models.json cache exists, per-agent fallback resolution, category overrides valid, provider availability |
+
+## SUPPORTING CHECK FILES (25 total)
+
+```
+checks/
+├── index.ts                               # Registration
+├── system.ts                              # Main System aggregator
+├── system-binary.ts                       # OpenCode binary discovery (PATH + desktop app)
+├── system-plugin.ts                       # opencode.json plugin entry detection
+├── system-loaded-version.ts               # Cache vs npm latest
+├── config.ts                              # Main Config aggregator
+├── tools.ts                               # Main Tools aggregator
+├── dependencies.ts                        # AST-Grep CLI/NAPI + comment-checker presence
+├── tools-gh.ts                            # gh cli install + auth status
+├── tools-lsp.ts                           # LSP server enumeration
+├── tools-mcp.ts                           # Built-in + user MCP reachability
+├── model-resolution.ts                    # Main Models aggregator
+├── model-resolution-cache.ts              # models.json presence + freshness
+├── model-resolution-config.ts             # oh-my-opencode.jsonc parse
+├── model-resolution-effective-model.ts    # Per-agent fallback chain trace
+├── model-resolution-variant.ts            # Model variant (max, high, medium) handling
+├── model-resolution-details.ts            # Verbose output formatter
+└── model-resolution-types.ts              # Shared types
+```
+
+## EXECUTION FLOW
+
+```
+doctor command
+  → runner.ts: parallel check execution with 30s per-check timeout
+  → checks/index.ts registers all 4 category checks
+  → each check returns: { status: "ok" | "warn" | "error", detail: string }
+  → formatter.ts: render to stdout (text/status/json)
+  → exit code: 0 (all ok) | 1 (errors) | 2 (warnings only)
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | CLI command entry, flag parsing |
+| `runner.ts` | Parallel `Promise.allSettled()` orchestration, 30s timeout per check |
+| `formatter.ts` | Pretty printing: colored status, hierarchical output |
+| `types.ts` | `DoctorCheck`, `CheckResult`, `DoctorReport` types |
+
+## HOW TO ADD A CHECK
+
+1. Create `src/cli/doctor/checks/{name}.ts` exporting check function matching `DoctorCheck`
+2. Register in `checks/index.ts`
+3. Category-level aggregator (system/config/tools/model-resolution) invokes it
+4. Return `{ status, detail }` — no throws, all errors caught by runner
+
+## EXIT CODES
+
+- `0`: All checks passed (or only info messages)
+- `1`: One or more errors — plugin will likely not work
+- `2`: Warnings only — plugin works with degraded features
@@ -1,6 +1,6 @@
 # src/config/ — Zod v4 Schema System

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/features/ — 19 Feature Modules

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -0,0 +1,78 @@
+# src/features/claude-code-mcp-loader/ — Tier 2 MCP Loader (.mcp.json)
+
+**Generated:** 2026-04-18
+
+## OVERVIEW
+
+11 files. Loads `.mcp.json` files from project/user scopes and expands `${VAR}` env vars. Feeds Tier 2 of the 3-tier MCP system into `mcp-config-handler.ts` during Phase 5 of config loading.
+
+## WHY IT EXISTS
+
+Claude Code ecosystem ships MCPs via `.mcp.json` files with `${VAR}` env var placeholders. OmO consumes these unchanged so existing Claude Code MCP configs work.
+
+## LOAD PIPELINE
+
+```
+loadMcpConfigs(ctx)
+  → scope-filter.ts: discover .mcp.json at project + user scopes
+  → loader.ts: parse JSON
+  → env-expander.ts: replace ${VAR} with process.env[VAR]
+  → transformer.ts: map Claude Code format → OpenCode McpLocal / McpRemote shape
+  → return LoadedMcpServer[]
+```
+
+## MCP FORMAT
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "my-stdio": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["server.js"],
+      "env": {
+        "API_KEY": "${MY_API_KEY}"
+      }
+    },
+    "my-http": {
+      "type": "http",       // "sse" legacy → mapped to http
+      "url": "https://example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${MY_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Barrel: `loadMcpConfigs`, types |
+| `loader.ts` | `loadMcpConfigs()` main entry |
+| `types.ts` | `ClaudeCodeMcpServer`, `LoadedMcpServer`, `McpScope` |
+| `env-expander.ts` | `expandEnvVarsInObject()` — recursive `${VAR}` substitution |
+| `transformer.ts` | Claude Code format → OpenCode `Mcp` shape |
+| `scope-filter.ts` | Project vs user scope precedence |
+
+## THREE-TIER MCP CONTEXT
+
+| Tier | Loader | Scope |
+|------|--------|-------|
+| 1. Built-in | `src/mcp/` `createBuiltinMcps()` | Global, 3 remote HTTP MCPs |
+| 2. **Claude Code** | **This module** | **From `.mcp.json`, project + user** |
+| 3. Skill-embedded | `src/features/skill-mcp-manager/` | Per-session, from SKILL.md YAML |
+
+## SECURITY
+
+- **Env var allowlist**: `mcp_env_allowlist` config restricts which env vars can be expanded
+- **No shell execution**: `${VAR}` is string replacement only, not shell `$()`
+- **Secrets redaction**: `env-cleaner.ts` (in skill-mcp-manager) filters known secret patterns from logs
+
+## RELATED
+
+- Phase 5 integration: `src/plugin-handlers/mcp-config-handler.ts`
+- Skill-embedded MCPs (Tier 3): `src/features/skill-mcp-manager/`
+- Built-in MCPs (Tier 1): `src/mcp/`
@@ -0,0 +1,78 @@
+# src/features/claude-code-plugin-loader/ — Unified Claude Code Plugin Loader
+
+**Generated:** 2026-04-18
+
+## OVERVIEW
+
+16 files. Full Claude Code plugin compatibility layer. Discovers and loads ALL plugin components (commands, agents, skills, hooks, MCP servers, LSP servers) from `.opencode/plugins/` and `~/.claude/plugins/`.
+
+## WHY IT EXISTS
+
+Claude 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.
+
+## LOAD PIPELINE
+
+```
+loadAllPluginComponents(ctx)
+  → discoverPlugins()                  # scan .opencode/plugins + ~/.claude/plugins
+  → readPluginManifest(plugin.json)    # parse name/version/commands/agents/skills/hooks/mcpServers
+  → loadPluginCommands()
+  → loadPluginAgents()
+  → loadPluginSkills()
+  → loadPluginHooks()                  # register hook handlers
+  → loadPluginMcpServers()             # feed into mcp-config-handler (tier 2)
+  → loadPluginLspServers()
+  → return LoadedPluginBundle
+```
+
+Called 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).
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Barrel: `loadAllPluginComponents`, `PluginManifest`, `ClaudeSettings` types |
+| `plugin-discovery.ts` | Find plugin directories across scopes |
+| `plugin-manifest-parser.ts` | Parse `plugin.json` with Zod validation |
+| `command-loader.ts` | Load commands from `commands/` or `COMMANDS.md` |
+| `agent-loader.ts` | Load agents from `agents/` or `AGENTS.md` frontmatter |
+| `skill-loader.ts` | Load skills from `skills/` or `SKILL.md` |
+| `hook-loader.ts` | Load hooks config from `hooks/` or manifest |
+| `mcp-loader.ts` | Extract MCP server configs |
+| `lsp-loader.ts` | Extract LSP server configs |
+| `settings-loader.ts` | Parse Claude Code `settings.json` |
+
+## PLUGIN MANIFEST (plugin.json)
+
+```jsonc
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "...",
+  "commands": ["./commands"],       // or string[] of paths
+  "agents": ["./agents"],
+  "skills": ["./skills"],
+  "hooks": "./hooks/config.json",
+  "mcpServers": "./.mcp.json",
+  "lspServers": "./lsp"
+}
+```
+
+## SCOPES
+
+| Scope | Path | Priority |
+|-------|------|----------|
+| `project` | `.opencode/plugins/` | Highest |
+| `local` | `~/.opencode/plugins/` | Medium |
+| `user` | `~/.claude/plugins/` | Medium |
+| `managed` | Built-in | Lowest |
+
+## ERROR ISOLATION
+
+Each 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`.
+
+## RELATED
+
+- Phase 2 loader: `src/plugin-handlers/plugin-components-loader.ts`
+- Tier 2 MCP integration: `src/features/claude-code-mcp-loader/`
+- Claude Code compat hooks: `src/hooks/claude-code-hooks/`
@@ -1,6 +1,6 @@
 # src/hooks/ — 52 Lifecycle Hooks

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/atlas/ — Master Boulder Orchestrator

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/claude-code-hooks/ — Claude Code Compatibility

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -0,0 +1,62 @@
+# src/hooks/comment-checker/ — AI Slop Comment Blocker
+
+**Generated:** 2026-04-18
+
+## OVERVIEW
+
+Tool Guard tier hook. Runs after `write`/`edit` tools to detect AI-generated comment patterns in code and block them before they land. Backed by `@code-yeongyu/comment-checker` binary (trusted dependency).
+
+## WHAT IT BLOCKS
+
+AI slop comment smells:
+- Restating what code literally does (`// increment counter`)
+- Filler phrases (`// obviously`, `// clearly`, `// simply`)
+- Decorative separators without purpose
+- JSDoc on trivially-named functions
+- `// TODO:` without context
+- Comments contradicting surrounding code
+
+See `@code-yeongyu/comment-checker` for the authoritative blocklist.
+
+## EXECUTION FLOW
+
+```
+tool.execute.after (write | edit | hashline edit)
+  → extract changed lines from tool output
+  → spawn comment-checker binary with changed file path
+  → parse findings (line ranges + violation category)
+  → if findings → inject tool-level error → agent must fix
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `hook.ts` | `createCommentCheckerHook()` — main factory, tool.execute.after handler |
+| `comment-checker-runner.ts` | Spawn binary, parse JSON output |
+| `changed-line-extractor.ts` | Extract which lines changed from tool result |
+| `findings-formatter.ts` | Format violations as actionable error message |
+| `binary-resolver.ts` | Locate `comment-checker` binary (node_modules + PATH) |
+
+## CONFIG
+
+```jsonc
+// oh-my-opencode.jsonc
+{
+  "comment_checker": {
+    "enabled": true,      // default: true
+    "severity": "error"   // error blocks, warning notifies only
+  }
+}
+```
+
+Disable via `"disabled_hooks": ["comment-checker"]`.
+
+## BYPASS FOR LEGITIMATE COMMENTS
+
+Prefix with `// @allow` or mark file scope with `// comment-checker-disable-file` at top. Use sparingly — defeating the purpose.
+
+## RELATED
+
+- Doctor check: `src/cli/doctor/checks/tools.ts` verifies `comment-checker` binary availability
+- Postinstall: `postinstall.mjs` downloads binary if missing
@@ -1,6 +1,6 @@
 # src/mcp/ — 3 Built-in Remote MCPs

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/openclaw/ — Bidirectional External Integration

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/plugin-handlers/ — 6-Phase Config Loading Pipeline

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## CRITICAL: AGENT ORDERING

@@ -1,6 +1,6 @@
 # src/plugin/ — 10 OpenCode Hook Handlers + Hook Composition

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/shared/ — 100+ Utility Files

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/tools/ - 26 Tools Across 16 Directories

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW