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:
+44
-32
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user