docs: refresh all 13 hierarchical AGENTS.md files with current codebase state

src/features/AGENTS.md

@@ -2,29 +2,61 @@
 
 ## OVERVIEW
 
-Background agents, skills, Claude Code compat, builtin commands, MCP managers, etc.
+Background systems that extend plugin capabilities: agents, skills, Claude Code compatibility layer, MCP managers, and task orchestration.
 
 ## STRUCTURE
 
+```
 features/
-├── background-agent/                      # Task lifecycle, concurrency (manager.ts 1642 lines)
-├── builtin-skills/                       # Skills like git-master (1107 lines)
-├── builtin-commands/                     # Commands like refactor (619 lines)
-├── skill-mcp-manager/                    # MCP client lifecycle (640 lines)
-├── claude-code-plugin-loader/            # Plugin loading
-├── claude-code-mcp-loader/               # MCP loading
-├── claude-code-session-state/            # Session state
-├── claude-code-command-loader/           # Command loading
-├── claude-code-agent-loader/             # Agent loading
-├── context-injector/                     # Context injection
-├── hook-message-injector/                # Message injection
-├── task-toast-manager/                   # Task toasts
-├── boulder-state/                        # State management
-├── tmux-subagent/                        # Tmux subagent
-├── mcp-oauth/                            # OAuth for MCP
-├── opencode-skill-loader/                # Skill loading
-├── tool-metadata-store/                  # Tool metadata
+├── background-agent/           # Task lifecycle, concurrency (manager.ts 1646 lines, concurrency.ts)
+├── boulder-state/              # Persistent state for multi-step operations
+├── builtin-commands/           # Command templates: refactor (619 lines), ralph-loop, handoff, init-deep
+├── builtin-skills/             # Skills: git-master (1111 lines), playwright, dev-browser, frontend-ui-ux
+├── claude-code-agent-loader/   # CC agent loading from .opencode/agents/
+├── claude-code-command-loader/ # CC command loading from .opencode/commands/
+├── claude-code-mcp-loader/     # CC MCP loading from .opencode/mcp/
+├── claude-code-plugin-loader/  # CC plugin discovery from .opencode/plugins/
+├── claude-code-session-state/  # Subagent session state tracking
+├── claude-tasks/               # Task schema + storage (has own AGENTS.md)
+├── context-injector/           # Auto-injects AGENTS.md, README.md, rules
+├── hook-message-injector/      # System message injection
+├── mcp-oauth/                  # OAuth flow for MCP servers
+├── opencode-skill-loader/      # YAML frontmatter skill loading
+├── skill-mcp-manager/          # MCP client lifecycle per session (manager.ts 150 lines)
+├── task-toast-manager/         # Task progress notifications
+├── tmux-subagent/              # Tmux integration (manager.ts 350 lines)
+└── tool-metadata-store/        # Tool execution metadata caching
+```
+
+## KEY PATTERNS
+
+**Background Agent Lifecycle:**
+- Task creation -> Queue -> Concurrency check -> Execute -> Monitor -> Cleanup
+- Manager.ts handles full lifecycle with 1646 lines of task orchestration
+- Concurrency.ts manages parallel execution limits per provider/model
+- Tasks survive session restarts via persistent storage
+
+**Claude Code Compatibility Layer:**
+5 directories provide full CC compatibility:
+- agent-loader: Loads custom agents from .opencode/agents/
+- command-loader: Loads slash commands from .opencode/commands/
+- mcp-loader: Loads MCP servers from .opencode/mcp/
+- plugin-loader: Discovers plugins from .opencode/plugins/
+- session-state: Tracks subagent session state and recovery
+
+**Skill Loading Pipeline:**
+1. opencode-skill-loader: Parses YAML frontmatter from skill files
+2. skill-mcp-manager: Manages MCP lifecycle per skill session (manager.ts 150 lines)
+3. Context injection: Auto-loads AGENTS.md, README.md, rules into context
+4. Hook message injector: Injects system messages for skill activation
 
 ## HOW TO ADD
 
-Create dir with index.ts, types.ts, etc.
+1. Create directory under `src/features/`
+2. Add `index.ts`, `types.ts`, `constants.ts` as needed
+3. Export from `index.ts` following barrel pattern
+4. Register in main plugin if plugin-level feature
+
+## CHILD DOCUMENTATION
+
+- See `claude-tasks/AGENTS.md` for task schema and storage details