docs: refresh all 13 hierarchical AGENTS.md files with current codebase state
This commit is contained in:
YeonGyu-Kim
+51
-19
@@ -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
|
||||
|
||||
@@ -8,12 +8,13 @@ Claude Code compatible task schema and storage. Provides core task management ut
|
||||
|
||||
```
|
||||
claude-tasks/
|
||||
├── types.ts # Task schema (Zod)
|
||||
├── types.test.ts # Schema validation tests (8 tests)
|
||||
├── storage.ts # File operations
|
||||
├── storage.test.ts # Storage tests (14 tests)
|
||||
├── todo-sync.ts # Task → Todo synchronization
|
||||
└── index.ts # Barrel exports
|
||||
├── types.ts # Task schema (Zod)
|
||||
├── types.test.ts # Schema validation tests (8 tests)
|
||||
├── storage.ts # File operations
|
||||
├── storage.test.ts # Storage tests (30 tests, 543 lines)
|
||||
├── session-storage.ts # Session-scoped task storage
|
||||
├── session-storage.test.ts
|
||||
└── index.ts # Barrel exports
|
||||
```
|
||||
|
||||
## TASK SCHEMA
|
||||
@@ -31,9 +32,6 @@ interface Task {
|
||||
blockedBy: string[] // Task IDs blocking this task (was: dependsOn)
|
||||
owner?: string // Agent name
|
||||
metadata?: Record<string, unknown>
|
||||
repoURL?: string // oh-my-opencode specific
|
||||
parentID?: string // oh-my-opencode specific
|
||||
threadID: string // oh-my-opencode specific
|
||||
}
|
||||
```
|
||||
|
||||
@@ -43,14 +41,6 @@ interface Task {
|
||||
- `blocks` (new field)
|
||||
- `activeForm` (new field)
|
||||
|
||||
## TODO SYNC
|
||||
|
||||
Task system includes sync layer (`todo-sync.ts`) that automatically mirrors task state to the project's Todo system.
|
||||
|
||||
- **Creation**: `task_create` adds corresponding Todo item
|
||||
- **Updates**: `task_update` reflects in Todo list
|
||||
- **Completion**: `completed` status marks Todo item done
|
||||
|
||||
## STORAGE UTILITIES
|
||||
|
||||
| Function | Purpose |
|
||||
@@ -60,6 +50,11 @@ Task system includes sync layer (`todo-sync.ts`) that automatically mirrors task
|
||||
| `readJsonSafe(path, schema)` | Parse + validate, returns null on failure |
|
||||
| `writeJsonAtomic(path, data)` | Atomic write via temp file + rename |
|
||||
| `acquireLock(dirPath)` | File-based lock with 30s stale threshold |
|
||||
| `generateTaskId()` | Generates `T-{uuid}` task ID |
|
||||
| `listTaskFiles(config)` | Lists all task IDs in storage |
|
||||
| `getSessionTaskDir(config, sessionID)` | Returns session-scoped task directory |
|
||||
| `listSessionTaskFiles(config, sessionID)` | Lists tasks for specific session |
|
||||
| `findTaskAcrossSessions(config, taskId)` | Locates task in any session directory |
|
||||
|
||||
## ANTI-PATTERNS
|
||||
|
||||
|
||||
Reference in New Issue
Block a user