docs: regenerate all AGENTS.md files from comprehensive codebase exploration

- Fired 33 parallel explore agents across all major directories - Analyzed 1164 TS files, 133k LOC, 41 hooks, 26 tools, 11 agents, 18 features - Regenerated 13 AGENTS.md files with 905 total lines - Root: plugin architecture, initialization flow, 7 OpenCode hook handlers - src/: entry point orchestration, hook composition pipeline - agents/: 11 agent inventory with tool restrictions and factory patterns - hooks/: 41 hooks organized by 5 tiers, key complex hooks documented - tools/: 26 tools across 14 directories, delegation categories - features/: 18 modules mapped by complexity (HIGH/MEDIUM/LOW) - shared/: 101 utilities in 13 categories, model resolution pipeline - config/: 22 schema files, Zod v4 validation system - cli/: 5 commands, doctor checks, model fallback system - mcp/: 3-tier MCP system architecture - plugin-handlers/: 6-phase config loading pipeline - claude-code-hooks/: CC settings.json compatibility layer - claude-tasks/: task schema + file-based persistence 🤖 Generated with assistance of oh-my-opencode
2026-02-17 11:17:01 +09:00
parent 28a5587144
commit 0a3c1bdd0f
13 changed files with 713 additions and 1015 deletions
@@ -1,83 +1,69 @@
-# FEATURES KNOWLEDGE BASE
+# src/features/ — 18 Feature Modules
+
+**Generated:** 2026-02-17

 ## OVERVIEW

-18 feature modules extending plugin capabilities: agent orchestration, skill loading, Claude Code compatibility, MCP management, task storage, and tmux integration.
+Standalone feature modules wired into plugin/ layer. Each is self-contained with own types, implementation, and tests.

-## STRUCTURE
-```
-features/
-├── background-agent/           # Task lifecycle, concurrency (56 files, 1701-line manager)
-│   ├── manager.ts              # Main task orchestration (1701 lines)
-│   ├── concurrency.ts          # Parallel execution limits per provider/model (137 lines)
-│   ├── task-history.ts         # Task execution history per parent session (76 lines)
-│   └── spawner/                # Task spawning: factory, starter, resumer, tmux (8 files)
-├── tmux-subagent/              # Tmux integration (28 files, 3303 LOC)
-│   └── manager.ts              # Pane management, grid planning (350 lines)
-├── opencode-skill-loader/      # YAML frontmatter skill loading (28 files, 2967 LOC)
-│   ├── loader.ts               # Skill discovery (4 scopes)
-│   ├── skill-directory-loader.ts # Recursive directory scanning (maxDepth=2)
-│   ├── skill-discovery.ts      # getAllSkills() with caching + provider gating
-│   └── merger/                 # Skill merging with scope priority
-├── mcp-oauth/                  # OAuth 2.0 flow for MCP (18 files, 2164 LOC)
-│   ├── provider.ts             # McpOAuthProvider class
-│   ├── oauth-authorization-flow.ts # PKCE, callback handling
-│   └── dcr.ts                  # Dynamic Client Registration (RFC 7591)
-├── skill-mcp-manager/          # MCP client lifecycle per session (12 files, 1769 LOC)
-│   └── manager.ts              # SkillMcpManager class (150 lines)
-├── builtin-skills/             # 5 built-in skills (10 files, 1921 LOC)
-│   └── skills/                 # git-master (1112), playwright (313), dev-browser (222), frontend-ui-ux (80)
-├── builtin-commands/           # 7 command templates (11 files, 1511 LOC)
-│   └── templates/              # refactor (620), init-deep (306), handoff (178), start-work, ralph-loop, stop-continuation
-├── claude-tasks/               # Task schema + storage (7 files) — see AGENTS.md
-├── context-injector/           # AGENTS.md, README.md, rules injection (6 files, 809 LOC)
-├── claude-code-plugin-loader/  # Plugin discovery from .opencode/plugins/ (10 files)
-├── claude-code-mcp-loader/     # .mcp.json with ${VAR} expansion (6 files)
-├── claude-code-command-loader/ # Command loading from .opencode/commands/ (3 files)
-├── claude-code-agent-loader/   # Agent loading from .opencode/agents/ (3 files)
-├── claude-code-session-state/  # Subagent session state tracking (3 files)
-├── hook-message-injector/      # System message injection (4 files)
-├── task-toast-manager/         # Task progress notifications (4 files)
-├── boulder-state/              # Persistent state for multi-step ops (5 files)
-└── tool-metadata-store/        # Tool execution metadata caching (3 files)
-```
+## MODULE MAP

-## KEY PATTERNS
+| Module | Files | Complexity | Purpose |
+|--------|-------|------------|---------|
+| **background-agent** | 49 | HIGH | Task lifecycle, concurrency (5/model), polling, spawner pattern |
+| **tmux-subagent** | 27 | HIGH | Tmux pane management, grid planning, session orchestration |
+| **opencode-skill-loader** | 25 | HIGH | YAML frontmatter skill loading from 4 scopes |
+| **mcp-oauth** | 10 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) for MCP servers |
+| **builtin-skills** | 10 | LOW | 6 skills: git-master, playwright, playwright-cli, agent-browser, dev-browser, frontend-ui-ux |
+| **skill-mcp-manager** | 10 | MEDIUM | MCP client lifecycle per session (stdio + HTTP) |
+| **claude-code-plugin-loader** | 10 | MEDIUM | Unified plugin discovery from .opencode/plugins/ |
+| **builtin-commands** | 9 | LOW | Command templates: refactor, init-deep, handoff, etc. |
+| **claude-code-mcp-loader** | 5 | MEDIUM | .mcp.json loading with ${VAR} env expansion |
+| **context-injector** | 4 | MEDIUM | AGENTS.md/README.md injection into context |
+| **boulder-state** | 4 | LOW | Persistent state for multi-step operations |
+| **hook-message-injector** | 4 | MEDIUM | System message injection for hooks |
+| **claude-tasks** | 4 | MEDIUM | Task schema + file storage + OpenCode todo sync |
+| **task-toast-manager** | 3 | MEDIUM | Task progress notifications |
+| **claude-code-agent-loader** | 3 | LOW | Load agents from .opencode/agents/ |
+| **claude-code-command-loader** | 3 | LOW | Load commands from .opencode/commands/ |
+| **claude-code-session-state** | 2 | LOW | Subagent session state tracking |
+| **tool-metadata-store** | 2 | LOW | Tool execution metadata cache |

-**Background Agent Lifecycle:**
-pending → running → completed/error/cancelled/interrupt
- Concurrency: Per provider/model limits (default: 5), queue-based FIFO
- Events: session.idle + session.error drive completion detection
- Key methods: `launch()`, `resume()`, `cancelTask()`, `getTask()`, `getAllDescendantTasks()`
+## KEY MODULES

-**Skill Loading Pipeline (4-scope priority):**
-opencode-project (`.opencode/skills/`) > opencode (`~/.config/opencode/skills/`) > project (`.claude/skills/`) > user (`~/.claude/skills/`)
+### background-agent (49 files, ~10k LOC)

-**Claude Code Compatibility Layer:**
-5 loaders: agent-loader, command-loader, mcp-loader, plugin-loader, session-state
+Core orchestration engine. `BackgroundManager` manages task lifecycle:
+- States: pending → running → completed/error/cancelled/interrupt
+- Concurrency: per-model/provider limits via `ConcurrencyManager` (FIFO queue)
+- Polling: 3s interval, completion via idle events + stability detection (10s unchanged)
+- spawner/: 8 focused files composing via `SpawnerContext` interface

-**SKILL.md Format:**
-```yaml
---
-name: my-skill
-description: "..."
-model: "claude-opus-4-6"    # optional
-agent: "sisyphus"           # optional
-mcp:                        # optional embedded MCPs
-  server-name:
-    type: http
-    url: https://...
---
-# Skill instruction content
-```
+### opencode-skill-loader (25 files, ~3.2k LOC)

-## HOW TO ADD
+4-scope skill discovery (project > opencode > user > global):
+- YAML frontmatter parsing from SKILL.md files
+- Skill merger with priority deduplication
+- Template resolution with variable substitution
+- Provider gating for model-specific skills

-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
+### tmux-subagent (27 files, ~3.6k LOC)

-## CHILD DOCUMENTATION
+State-first tmux integration:
+- `TmuxSessionManager`: pane lifecycle, grid planning
+- Spawn action decider + target finder
+- Polling manager for session health
+- Event handlers for pane creation/destruction

- See `claude-tasks/AGENTS.md` for task schema and storage details
+### builtin-skills (6 skill objects)
+
+| Skill | Size | MCP | Tools |
+|-------|------|-----|-------|
+| git-master | 1111 LOC | — | Bash |
+| playwright | 312 LOC | @playwright/mcp | — |
+| agent-browser | (in playwright.ts) | — | Bash(agent-browser:*) |
+| playwright-cli | 268 LOC | — | Bash(playwright-cli:*) |
+| dev-browser | 221 LOC | — | Bash |
+| frontend-ui-ux | 79 LOC | — | — |
+
+Browser variant selected by `browserProvider` config: playwright (default) | playwright-cli | agent-browser.
@@ -1,68 +1,43 @@
-# CLAUDE TASKS KNOWLEDGE BASE
+# src/features/claude-tasks/ — Task Schema + Storage
+
+**Generated:** 2026-02-17

 ## OVERVIEW

-Claude Code compatible task schema and storage. Core task management with file-based persistence, atomic writes, and OpenCode todo sync.
-
-## STRUCTURE
-```
-claude-tasks/
-├── types.ts               # Task schema (Zod)
-├── types.test.ts          # Schema validation tests
-├── storage.ts             # File operations (atomic write, locking)
-├── storage.test.ts        # Storage tests (30 tests, 543 lines)
-├── session-storage.ts     # Session-scoped task storage
-├── session-storage.test.ts
-└── index.ts               # Barrel exports
-```
+4 non-test files (~622 LOC). File-based task persistence with atomic writes, locking, and OpenCode todo API sync.

 ## TASK SCHEMA

 ```typescript
-type TaskStatus = "pending" | "in_progress" | "completed" | "deleted"
 interface Task {
-  id: string                    // T-{uuid}
-  subject: string               // Imperative: "Run tests"
-  description: string
-  status: TaskStatus
-  activeForm?: string           // Present continuous: "Running tests"
-  blocks: string[]              // Task IDs this task blocks
-  blockedBy: string[]           // Task IDs blocking this task
-  owner?: string                // Agent name
+  id: string              // T-{uuid} auto-generated
+  subject: string         // Short title
+  description?: string    // Detailed description
+  status: "pending" | "in_progress" | "completed" | "deleted"
+  activeForm?: string     // Current form/template
+  blocks?: string[]       // Tasks this blocks
+  blockedBy?: string[]    // Tasks blocking this
+  owner?: string          // Agent/session
  metadata?: Record<string, unknown>
-  repoURL?: string
-  parentID?: string
-  threadID?: string
+  repoURL?: string        // Associated repository
+  parentID?: string       // Parent task ID
+  threadID?: string       // Session ID (auto-recorded)
 }
 ```

-## STORAGE UTILITIES
+## FILES

-| Function | Purpose |
-|----------|---------|
-| `getTaskDir(config)` | Task storage directory path |
-| `resolveTaskListId(config)` | Task list ID (env → config → cwd) |
-| `readJsonSafe(path, schema)` | Parse + validate, null on failure |
-| `writeJsonAtomic(path, data)` | Atomic write via temp + rename |
-| `acquireLock(dirPath)` | File lock with 30s stale threshold |
-| `generateTaskId()` | `T-{uuid}` format |
-| `findTaskAcrossSessions(config, taskId)` | Locate task in any session |
+| File | Purpose |
+|------|---------|
+| `types.ts` | Task interface + status types |
+| `storage.ts` | `readJsonSafe()`, `writeJsonAtomic()`, `acquireLock()`, `generateTaskId()` |
+| `session-storage.ts` | Per-session task storage, threadID auto-recording |
+| `index.ts` | Barrel exports |

-## TODO SYNC
+## STORAGE

-Automatic bidirectional sync between tasks and OpenCode's todo system.
-
-| Task Status | Todo Status |
-|-------------|-------------|
-| `pending` | `pending` |
-| `in_progress` | `in_progress` |
-| `completed` | `completed` |
-| `deleted` | `null` (removed) |
-
-Sync triggers: `task_create`, `task_update`.
-
-## ANTI-PATTERNS
-
- Direct fs operations (use storage utilities)
- Skipping lock acquisition for writes
- Using old field names (title → subject, dependsOn → blockedBy)
+- Location: `.sisyphus/tasks/` directory
+- Format: JSON files, one per task
+- Atomic writes: temp file → rename
+- Locking: file-based lock for concurrent access
+- Sync: Changes pushed to OpenCode Todo API after each update