docs: regenerate hierarchical AGENTS.md with deep investigation

- Root: 181 lines with agent models, complexity hotspots, CI pipeline
- Hooks: 31 lifecycle hooks, execution order, patterns
- Tools: 20+ tools, LSP/AST-Grep specifics, registration
- Features: Background agents, Claude Code compat, skill MCP
- Agents: 10 agents with models, tool restrictions
- Shared: 43 utilities with usage patterns
- CLI: Commander.js entry, doctor checks, TUI framework

Generated via /init-deep with 12 parallel explore agents
This commit is contained in:
justsisyphus
2026-01-17 22:01:56 +09:00
parent 255f535a50
commit 6d99b5c1fc
7 changed files with 385 additions and 280 deletions
+44 -32
View File
@@ -1,39 +1,62 @@
# FEATURES KNOWLEDGE BASE
## OVERVIEW
Claude Code compatibility layer + core feature modules. Commands, skills, agents, MCPs, hooks from Claude Code work seamlessly.
Core feature modules + Claude Code compatibility layer. Background agents, skill MCP, builtin skills/commands, and 5 loaders for Claude Code compat.
## STRUCTURE
```
features/
├── background-agent/ # Task lifecycle, notifications (1165 lines manager.ts)
├── boulder-state/ # Boulder/Todo state persistence
├── builtin-commands/ # Built-in slash commands (ralph-loop, refactor, init-deep)
├── builtin-skills/ # Built-in skills (1203 lines skills.ts)
│ ├── git-master/ # Atomic commits, history search
│ ├── playwright/ # Browser automation
│ └── frontend-ui-ux/ # Designer-developer skill
├── background-agent/ # Task lifecycle (1165 lines manager.ts)
│ ├── manager.ts # Launch → poll → complete orchestration
│ ├── concurrency.ts # Per-provider/model limits
│ └── types.ts # BackgroundTask, LaunchInput
├── skill-mcp-manager/ # MCP client lifecycle
│ ├── manager.ts # Lazy loading, idle cleanup
│ └── types.ts # SkillMcpConfig, transports
├── builtin-skills/ # Playwright, git-master, frontend-ui-ux
│ └── skills.ts # 1203 lines of skill definitions
├── builtin-commands/ # ralph-loop, refactor, init-deep
│ └── templates/ # Command implementations
├── claude-code-agent-loader/ # ~/.claude/agents/*.md
├── claude-code-command-loader/ # ~/.claude/commands/*.md
├── claude-code-mcp-loader/ # .mcp.json files with ${VAR} expansion
├── claude-code-mcp-loader/ # .mcp.json with ${VAR} expansion
├── claude-code-plugin-loader/ # installed_plugins.json
├── claude-code-session-state/ # Session state persistence
├── context-injector/ # AGENTS.md/README.md/Rules injection
├── opencode-skill-loader/ # Skills from OpenCode + Claude paths
├── skill-mcp-manager/ # MCP servers in skill YAML (stdio/http transports)
├── task-toast-manager/ # Task status toast notifications
└── hook-message-injector/ # Message injection into conversation streams
├── opencode-skill-loader/ # Skills from 6 directories
├── context-injector/ # AGENTS.md/README.md injection
├── boulder-state/ # Todo state persistence
├── task-toast-manager/ # Toast notifications
└── hook-message-injector/ # Message injection
```
## LOADER PRIORITY
| Loader | Priority (highest first) |
|--------|--------------------------|
| Type | Priority (highest first) |
|------|--------------------------|
| Commands | `.opencode/command/` > `~/.config/opencode/command/` > `.claude/commands/` > `~/.claude/commands/` |
| Skills | `.opencode/skill/` > `~/.config/opencode/skill/` > `.claude/skills/` > `~/.claude/skills/` |
| Agents | `.claude/agents/` > `~/.claude/agents/` |
| MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` |
## BACKGROUND AGENT
- **Lifecycle**: `launch``poll` (2s interval) → `complete`
- **Stability**: 3 consecutive polls with same message count = idle
- **Concurrency**: Per-provider/model limits (e.g., max 3 Opus, max 10 Gemini)
- **Notification**: Batched system reminders to parent session
- **Cleanup**: 30m TTL, 3m stale timeout, signal handlers
## SKILL MCP
- **Lazy**: Clients created on first tool call
- **Transports**: stdio (local process), http (SSE/Streamable)
- **Environment**: `${VAR}` expansion in config
- **Lifecycle**: 5m idle cleanup, session-scoped
## CONFIG TOGGLES
```jsonc
{
"claude_code": {
@@ -46,20 +69,9 @@ features/
}
```
## BACKGROUND AGENT
- **Lifecycle**: `launch``poll` (idle/stability detection) → `complete`.
- **Concurrency**: Per-provider/model limits in `concurrency.ts`.
- **Notification**: Auto-injects system reminders into parent session on task completion.
- **Cleanup**: Shutdown handler cancels pending waiters; idle tasks pruning (30m TTL).
## SKILL MCP
- **Lazy Loading**: Clients connect on first tool call via `SkillMcpManager`.
- **Transports**: `stdio` (local process) or `http` (SSE/Streamable HTTP).
- **Environment**: `${VAR}` expansion in config via `env-expander.ts`.
- **Lifecycle**: Session-scoped clients; auto-cleanup after 5m idle.
## ANTI-PATTERNS
- **Sequential Delegation**: Calling agents one-by-one; use `delegate_task` for parallel runs.
- **Self-Report Trust**: Trusting agent's "I'm done" without verifying against session state.
- **Main Thread Blocks**: Heavy I/O or long-running logic during loader initialization.
- **Manual Versioning**: Updating `package.json` version field; managed exclusively by CI.
- **Sequential delegation**: Use `delegate_task` for parallel
- **Trust self-reports**: ALWAYS verify agent outputs
- **Main thread blocks**: No heavy I/O in loader init
- **Manual versioning**: CI manages package.json version