docs: regenerate AGENTS.md hierarchy via init-deep

🤖 Generated with assistance of OhMyOpenCode (https://github.com/code-yeongyu/oh-my-opencode)
2025-12-31 14:07:14 +09:00
parent 502e9f504f
commit 5412578600
3 changed files with 198 additions and 5 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
 # PROJECT KNOWLEDGE BASE

-**Generated:** 2025-12-28T19:26:00+09:00
-**Commit:** 122e918
+**Generated:** 2025-12-31T14:05:00+09:00
+**Commit:** 502e9f5
 **Branch:** dev

 ## OVERVIEW
@@ -20,7 +20,8 @@ oh-my-opencode/
 │   ├── features/      # Claude Code compatibility - see src/features/AGENTS.md
 │   ├── config/        # Zod schema, TypeScript types
 │   ├── auth/          # Google Antigravity OAuth (antigravity/)
-│   ├── shared/        # Utilities: deep-merge, pattern-matcher, logger, etc.
+│   ├── shared/        # Utilities: deep-merge, pattern-matcher, logger, etc. - see src/shared/AGENTS.md
+│   ├── cli/           # CLI installer, doctor, run - see src/cli/AGENTS.md
 │   └── index.ts       # Main plugin entry (OhMyOpenCodePlugin)
 ├── script/            # build-schema.ts, publish.ts, generate-changelog.ts
 ├── assets/            # JSON schema
@@ -34,7 +35,7 @@ oh-my-opencode/
 | Add agent | `src/agents/` | Create .ts, add to builtinAgents in index.ts, update types.ts |
 | Add hook | `src/hooks/` | Create dir with createXXXHook(), export from index.ts |
 | Add tool | `src/tools/` | Dir with index/types/constants/tools.ts, add to builtinTools |
-| Add MCP | `src/mcp/` | Create config, add to index.ts |
+| Add MCP | `src/mcp/` | Create config, add to index.ts and types.ts |
 | LSP behavior | `src/tools/lsp/` | client.ts (connection), tools.ts (handlers) |
 | AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding |
 | Google OAuth | `src/auth/antigravity/` | OAuth plugin for Google models |
@@ -42,6 +43,9 @@ oh-my-opencode/
 | Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
 | Background agents | `src/features/background-agent/` | manager.ts for task management |
 | Interactive terminal | `src/tools/interactive-bash/` | tmux session management |
+| CLI installer | `src/cli/install.ts` | Interactive TUI installation |
+| Doctor checks | `src/cli/doctor/checks/` | Health checks for environment |
+| Shared utilities | `src/shared/` | Cross-cutting utilities |

 ## CONVENTIONS

@@ -64,6 +68,8 @@ oh-my-opencode/
 - **Year 2024**: NEVER use 2024 in code/prompts (use current year)
 - **Rush completion**: Never mark tasks complete without verification
 - **Over-exploration**: Stop searching when sufficient context found
+- **High temperature**: Don't use >0.3 for code-related agents
+- **Broad tool access**: Prefer explicit `include` over unrestricted access

 ## UNIQUE STYLES

@@ -109,8 +115,19 @@ bun test               # Run tests

 ## CI PIPELINE

- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master
+- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master, rolling `next` draft release
 - **publish.yml**: Manual workflow_dispatch, version bump, changelog, OIDC npm publish
+- **sisyphus-agent.yml**: Agent-in-CI for automated issue handling via `@sisyphus-dev-ai` mentions
+
+## COMPLEXITY HOTSPOTS
+
+| File | Lines | Description |
+|------|-------|-------------|
+| `src/index.ts` | 690 | Main plugin orchestration, all hook/tool initialization |
+| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 670 | Session compaction, multi-stage recovery pipeline |
+| `src/cli/config-manager.ts` | 669 | JSONC parsing, environment detection, installation |
+| `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting, endpoint fallbacks |
+| `src/tools/lsp/client.ts` | 611 | LSP protocol, stdin/stdout buffering, JSON-RPC |

 ## NOTES

@@ -119,3 +136,4 @@ bun test               # Run tests
 - **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
 - **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)
 - **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
+- **JSONC support**: Config files support comments (`// comment`, `/* block */`) and trailing commas
--- a/src/cli/AGENTS.md
+++ b/src/cli/AGENTS.md
@@ -0,0 +1,93 @@
+# CLI KNOWLEDGE BASE
+
+## OVERVIEW
+
+Command-line interface for oh-my-opencode. Interactive installer, health diagnostics (doctor), and runtime commands. Entry point: `bunx oh-my-opencode`.
+
+## STRUCTURE
+
+```
+cli/
+├── index.ts              # Commander.js entry point, subcommand routing
+├── install.ts            # Interactive TUI installer
+├── config-manager.ts     # Config detection, parsing, merging (669 lines)
+├── types.ts              # CLI-specific types
+├── doctor/               # Health check system
+│   ├── index.ts          # Doctor command entry
+│   ├── constants.ts      # Check categories, descriptions
+│   ├── types.ts          # Check result interfaces
+│   └── checks/           # 17 individual health checks
+├── get-local-version/    # Version detection utility
+│   ├── index.ts
+│   └── formatter.ts
+└── run/                  # OpenCode session launcher
+    ├── index.ts
+    └── completion.test.ts
+```
+
+## CLI COMMANDS
+
+| Command | Purpose | Key File |
+|---------|---------|----------|
+| `install` | Interactive setup wizard | `install.ts` |
+| `doctor` | Environment health checks | `doctor/index.ts` |
+| `run` | Launch OpenCode session | `run/index.ts` |
+
+## DOCTOR CHECKS
+
+17 checks in `doctor/checks/`:
+
+| Check | Validates |
+|-------|-----------|
+| `version.ts` | OpenCode version >= 1.0.150 |
+| `config.ts` | Plugin registered in opencode.json |
+| `bun.ts` | Bun runtime available |
+| `node.ts` | Node.js version compatibility |
+| `git.ts` | Git installed |
+| `anthropic-auth.ts` | Claude authentication |
+| `openai-auth.ts` | OpenAI authentication |
+| `google-auth.ts` | Google/Gemini authentication |
+| `lsp-*.ts` | Language server availability |
+| `mcp-*.ts` | MCP server connectivity |
+
+## INSTALLATION FLOW
+
+1. **Detection**: Find existing `opencode.json` / `opencode.jsonc`
+2. **TUI Prompts**: Claude subscription? ChatGPT? Gemini?
+3. **Config Generation**: Build `oh-my-opencode.json` based on answers
+4. **Plugin Registration**: Add to `plugin` array in opencode.json
+5. **Auth Guidance**: Instructions for `opencode auth login`
+
+## CONFIG-MANAGER
+
+The largest file (669 lines) handles:
+
+- **JSONC support**: Parses comments and trailing commas
+- **Multi-source detection**: User (~/.config/opencode/) + Project (.opencode/)
+- **Schema validation**: Zod-based config validation
+- **Migration**: Handles legacy config formats
+- **Error collection**: Aggregates parsing errors for doctor
+
+## HOW TO ADD A DOCTOR CHECK
+
+1. Create `src/cli/doctor/checks/my-check.ts`:
+   ```typescript
+   import type { DoctorCheck } from "../types"
+   
+   export const myCheck: DoctorCheck = {
+     name: "my-check",
+     category: "environment",
+     check: async () => {
+       // Return { status: "pass" | "warn" | "fail", message: string }
+     }
+   }
+   ```
+2. Add to `src/cli/doctor/checks/index.ts`
+3. Update `constants.ts` if new category
+
+## ANTI-PATTERNS (CLI)
+
+- **Blocking prompts in non-TTY**: Check `process.stdout.isTTY` before TUI
+- **Hardcoded paths**: Use shared utilities for config paths
+- **Ignoring JSONC**: User configs may have comments
+- **Silent failures**: Doctor checks must return clear status/message
--- a/src/shared/AGENTS.md
+++ b/src/shared/AGENTS.md
@@ -0,0 +1,82 @@
+# SHARED UTILITIES KNOWLEDGE BASE
+
+## OVERVIEW
+
+Cross-cutting utility functions used across agents, hooks, tools, and features. Path resolution, config management, text processing, and Claude Code compatibility helpers.
+
+## STRUCTURE
+
+```
+shared/
+├── index.ts              # Barrel export (import { x } from "../shared")
+├── claude-config-dir.ts  # Resolve ~/.claude directory
+├── command-executor.ts   # Shell command execution with variable expansion
+├── config-errors.ts      # Global config error tracking
+├── config-path.ts        # User/project config path resolution
+├── data-path.ts          # XDG data directory resolution
+├── deep-merge.ts         # Type-safe recursive object merging
+├── dynamic-truncator.ts  # Token-aware output truncation
+├── file-reference-resolver.ts  # @filename syntax resolution
+├── file-utils.ts         # Symlink resolution, markdown detection
+├── frontmatter.ts        # YAML frontmatter parsing
+├── hook-disabled.ts      # Check if hook is disabled in config
+├── jsonc-parser.ts       # JSON with Comments parsing
+├── logger.ts             # File-based logging to OS temp
+├── migration.ts          # Legacy name compatibility (omo -> Sisyphus)
+├── model-sanitizer.ts    # Normalize model names
+├── pattern-matcher.ts    # Tool name matching with wildcards
+├── snake-case.ts         # Case conversion for objects
+└── tool-name.ts          # Normalize tool names to PascalCase
+```
+
+## UTILITY CATEGORIES
+
+| Category | Utilities | Used By |
+|----------|-----------|---------|
+| Path Resolution | `getClaudeConfigDir`, `getUserConfigPath`, `getProjectConfigPath`, `getDataDir` | Features, Hooks |
+| Config Management | `deepMerge`, `parseJsonc`, `isHookDisabled`, `configErrors` | index.ts, CLI |
+| Text Processing | `resolveCommandsInText`, `resolveFileReferencesInText`, `parseFrontmatter` | Commands, Rules |
+| Output Control | `dynamicTruncate` | Tools (Grep, LSP) |
+| Normalization | `transformToolName`, `objectToSnakeCase`, `sanitizeModelName` | Hooks, Agents |
+| Compatibility | `migration.ts` | Config loading |
+
+## WHEN TO USE WHAT
+
+| Task | Utility | Notes |
+|------|---------|-------|
+| Find Claude Code configs | `getClaudeConfigDir()` | Never hardcode `~/.claude` |
+| Merge settings (default → user → project) | `deepMerge(base, override)` | Arrays replaced, objects merged |
+| Parse user config files | `parseJsonc()` | Supports comments and trailing commas |
+| Check if hook should run | `isHookDisabled(name, disabledHooks)` | Respects `disabled_hooks` config |
+| Truncate large tool output | `dynamicTruncate(text, budget, reserved)` | Token-aware, prevents overflow |
+| Resolve `@file` references | `resolveFileReferencesInText()` | maxDepth=3 prevents infinite loops |
+| Execute shell commands | `resolveCommandsInText()` | Supports `!`\`command\`\` syntax |
+| Handle legacy agent names | `migrateLegacyAgentNames()` | `omo` → `Sisyphus` |
+
+## CRITICAL PATTERNS
+
+### Dynamic Truncation
+```typescript
+import { dynamicTruncate } from "../shared"
+// Keep 50% headroom, max 50k tokens
+const output = dynamicTruncate(result, remainingTokens, 0.5)
+```
+
+### Deep Merge Priority
+```typescript
+const final = deepMerge(defaults, userConfig)
+final = deepMerge(final, projectConfig) // Project wins
+```
+
+### Safe JSONC Parsing
+```typescript
+const { config, error } = parseJsoncSafe(content)
+if (error) return fallback
+```
+
+## ANTI-PATTERNS (SHARED)
+
+- **Hardcoding paths**: Use `getClaudeConfigDir()`, `getUserConfigPath()`
+- **Manual JSON.parse**: Use `parseJsonc()` for user files (comments allowed)
+- **Ignoring truncation**: Large outputs MUST use `dynamicTruncate`
+- **Direct string concat for configs**: Use `deepMerge` for proper priority