docs: update all 31 AGENTS.md files with current project state

2026-02-21 04:38:18 +09:00
parent 924df193ba
commit b1eccf7425
31 changed files with 57 additions and 39 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,10 +1,10 @@
 # oh-my-opencode — OpenCode Plugin

-**Generated:** 2026-02-19 | **Commit:** 29ebd8c4 | **Branch:** dev
+**Generated:** 2026-02-21 | **Commit:** 86e3c7d1 | **Branch:** dev

 ## OVERVIEW

-OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 44 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1161 TypeScript files, 133k LOC.
+OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 44 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1208 TypeScript files, 143k LOC.

 ## STRUCTURE

@@ -17,13 +17,13 @@ oh-my-opencode/
 │   ├── hooks/                # 44 hooks across 39 directories + 6 standalone files
 │   ├── tools/                # 26 tools across 15 directories
 │   ├── features/             # 19 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.)
-│   ├── shared/               # 101 utility files in 13 categories
-│   ├── config/               # Zod v4 schema system (22 files)
+│   ├── shared/               # 100+ utility files in 13 categories
+│   ├── config/               # Zod v4 schema system (22+ files)
 │   ├── cli/                  # CLI: install, run, doctor, mcp-oauth (Commander.js)
 │   ├── mcp/                  # 3 built-in remote MCPs (websearch, context7, grep_app)
 │   ├── plugin/               # 8 OpenCode hook handlers + 44 hook composition
 │   └── plugin-handlers/      # 6-phase config loading pipeline
-├── packages/                 # Monorepo: comment-checker, opencode-sdk
+├── packages/                 # Monorepo: comment-checker, opencode-sdk, 10 platform binaries
 └── local-ignore/             # Dev-only test fixtures
 ```

@@ -65,6 +65,7 @@ OhMyOpenCodePlugin(ctx)
 | Add new CLI command | `src/cli/cli-program.ts` | Commander.js subcommand |
 | Add new doctor check | `src/cli/doctor/checks/` | Register in checks/index.ts |
 | Modify config schema | `src/config/schema/` + update root schema | Zod v4, add to OhMyOpenCodeConfigSchema |
+| Add new category | `src/tools/delegate-task/constants.ts` | DEFAULT_CATEGORIES + CATEGORY_MODEL_REQUIREMENTS |

 ## MULTI-LEVEL CONFIG

@@ -72,7 +73,7 @@ OhMyOpenCodePlugin(ctx)
 Project (.opencode/oh-my-opencode.jsonc)  →  User (~/.config/opencode/oh-my-opencode.jsonc)  →  Defaults
 ```

-Fields: agents (14 overridable), categories (8 built-in + custom), disabled_* arrays, 19 feature-specific configs.
+Fields: agents (14 overridable, 21 fields each), categories (8 built-in + custom), disabled_* arrays (agents, hooks, mcps, skills, commands, tools), 19 feature-specific configs.

 ## THREE-TIER MCP SYSTEM

@@ -84,12 +85,15 @@ Fields: agents (14 overridable), categories (8 built-in + custom), disabled_* ar

 ## CONVENTIONS

- **Test pattern**: Bun test (`bun:test`), co-located `*.test.ts`, given/when/then style
+- **Test pattern**: Bun test (`bun:test`), co-located `*.test.ts`, given/when/then style (nested describe with `#given`/`#when`/`#then` prefixes)
 - **Factory pattern**: `createXXX()` for all tools, hooks, agents
- **Hook tiers**: Session (21) → Tool-Guard (10) → Transform (4) → Continuation (7) → Skill (2)
+- **Hook tiers**: Session (22) → Tool-Guard (10) → Transform (4) → Continuation (7) → Skill (2)
 - **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all`
 - **Model resolution**: 3-step: override → category-default → provider-fallback → system-default
 - **Config format**: JSONC with comments, Zod v4 validation, snake_case keys
+- **File naming**: kebab-case for all files/directories
+- **Module structure**: index.ts barrel exports, no catch-all files (utils.ts, helpers.ts banned), 200 LOC soft limit
+- **Imports**: relative within module, barrel imports across modules (`import { log } from "./shared"`)

 ## ANTI-PATTERNS

@@ -99,17 +103,29 @@ Fields: agents (14 overridable), categories (8 built-in + custom), disabled_* ar
 - Never commit unless explicitly requested
 - Test: given/when/then — never use Arrange-Act-Assert comments
 - Comments: avoid AI-generated comment patterns (enforced by comment-checker hook)
+- Never create catch-all files (`utils.ts`, `helpers.ts`, `service.ts`)
+- Empty catch blocks `catch(e) {}` — always handle errors

 ## COMMANDS

 ```bash
 bun test                    # Bun test suite
-bun run build              # Build plugin
+bun run build              # Build plugin (ESM + declarations + schema)
+bun run typecheck           # tsc --noEmit
 bunx oh-my-opencode install # Interactive setup
 bunx oh-my-opencode doctor  # Health diagnostics
 bunx oh-my-opencode run     # Non-interactive session
 ```

+## CI/CD
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| ci.yml | push/PR | Tests (split: mock-heavy isolated + batch), typecheck, build, schema auto-commit |
+| publish.yml | manual | Version bump, npm publish, platform binaries, GitHub release, merge to master |
+| publish-platform.yml | called | 11 platform binaries via bun compile (darwin/linux/windows) |
+| sisyphus-agent.yml | @mention | AI agent handles issues/PRs |
+
 ## NOTES

 - Logger writes to `/tmp/oh-my-opencode.log` — check there for debugging
@@ -117,3 +133,5 @@ bunx oh-my-opencode run     # Non-interactive session
 - Plugin load timeout: 10s for Claude Code plugins
 - Model fallback priority: Claude > OpenAI > Gemini > Copilot > OpenCode Zen > Z.ai > Kimi
 - Config migration runs automatically on legacy keys (agent names, hook names, model versions)
+- Build: bun build (ESM) + tsc --emitDeclarationOnly, externals: @ast-grep/napi
+- Test setup: `test-setup.ts` preloaded via bunfig.toml, mock-heavy tests run in isolation in CI
--- a/src/AGENTS.md
+++ b/src/AGENTS.md
@@ -1,6 +1,6 @@
 # src/ — Plugin Source

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/agents/AGENTS.md
+++ b/src/agents/AGENTS.md
@@ -1,6 +1,6 @@
 # src/agents/ — 11 Agent Definitions

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/cli/AGENTS.md
+++ b/src/cli/AGENTS.md
@@ -1,6 +1,6 @@
 # src/cli/ — CLI: install, run, doctor, mcp-oauth

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/cli/config-manager/AGENTS.md
+++ b/src/cli/config-manager/AGENTS.md
@@ -1,6 +1,6 @@
 # src/cli/config-manager/ — CLI Installation Utilities

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/cli/run/AGENTS.md
+++ b/src/cli/run/AGENTS.md
@@ -1,6 +1,6 @@
 # src/cli/run/ — Non-Interactive Session Launcher

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/config/AGENTS.md
+++ b/src/config/AGENTS.md
@@ -1,6 +1,6 @@
 # src/config/ — Zod v4 Schema System

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/features/AGENTS.md
+++ b/src/features/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/ — 19 Feature Modules

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/features/background-agent/AGENTS.md
+++ b/src/features/background-agent/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/background-agent/ — Core Orchestration Engine

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/features/claude-tasks/AGENTS.md
+++ b/src/features/claude-tasks/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/claude-tasks/ — Task Schema + Storage

-**Generated:** 2026-02-17
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/features/mcp-oauth/AGENTS.md
+++ b/src/features/mcp-oauth/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/mcp-oauth/ — OAuth 2.0 + PKCE + DCR for MCP Servers

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/features/opencode-skill-loader/AGENTS.md
+++ b/src/features/opencode-skill-loader/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/opencode-skill-loader/ — 4-Scope Skill Discovery

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/features/tmux-subagent/AGENTS.md
+++ b/src/features/tmux-subagent/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/tmux-subagent/ — Tmux Pane Management

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/AGENTS.md
+++ b/src/hooks/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/ — 44 Lifecycle Hooks

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md
+++ b/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/anthropic-context-window-limit-recovery/ — Multi-Strategy Context Recovery

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/atlas/AGENTS.md
+++ b/src/hooks/atlas/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/atlas/ — Master Boulder Orchestrator

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/claude-code-hooks/AGENTS.md
+++ b/src/hooks/claude-code-hooks/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/claude-code-hooks/ — Claude Code Compatibility

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/keyword-detector/AGENTS.md
+++ b/src/hooks/keyword-detector/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/keyword-detector/ — Mode Keyword Injection

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/ralph-loop/AGENTS.md
+++ b/src/hooks/ralph-loop/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/ralph-loop/ — Self-Referential Dev Loop

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/rules-injector/AGENTS.md
+++ b/src/hooks/rules-injector/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/rules-injector/ — Conditional Rules Injection

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/session-recovery/AGENTS.md
+++ b/src/hooks/session-recovery/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/session-recovery/ — Auto Session Error Recovery

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/hooks/todo-continuation-enforcer/AGENTS.md
+++ b/src/hooks/todo-continuation-enforcer/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/todo-continuation-enforcer/ — Boulder Continuation Mechanism

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/mcp/AGENTS.md
+++ b/src/mcp/AGENTS.md
@@ -1,6 +1,6 @@
 # src/mcp/ — 3 Built-in Remote MCPs

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/plugin-handlers/AGENTS.md
+++ b/src/plugin-handlers/AGENTS.md
@@ -1,6 +1,6 @@
 # src/plugin-handlers/ — 6-Phase Config Loading Pipeline

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/plugin/AGENTS.md
+++ b/src/plugin/AGENTS.md
@@ -1,6 +1,6 @@
 # src/plugin/ — 8 OpenCode Hook Handlers + Hook Composition

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/shared/AGENTS.md
+++ b/src/shared/AGENTS.md
@@ -1,6 +1,6 @@
 # src/shared/ — 101 Utility Files in 13 Categories

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/tools/AGENTS.md
+++ b/src/tools/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/ — 26 Tools Across 15 Directories

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/tools/background-task/AGENTS.md
+++ b/src/tools/background-task/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/background-task/ — Background Task Tool Wrappers

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/tools/call-omo-agent/AGENTS.md
+++ b/src/tools/call-omo-agent/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/call-omo-agent/ — Direct Agent Invocation Tool

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/tools/delegate-task/AGENTS.md
+++ b/src/tools/delegate-task/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/delegate-task/ — Task Delegation Engine

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW

--- a/src/tools/lsp/AGENTS.md
+++ b/src/tools/lsp/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/lsp/ — LSP Tool Implementations

-**Generated:** 2026-02-19
+**Generated:** 2026-02-21

 ## OVERVIEW