docs(agents): regenerate all AGENTS.md with deep codebase analysis
This commit is contained in:
YeonGyu-Kim
+52
-35
@@ -2,53 +2,70 @@
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Background systems that extend plugin capabilities: agents, skills, Claude Code compatibility layer, MCP managers, and task orchestration.
|
||||
18 feature modules extending plugin capabilities: agent orchestration, skill loading, Claude Code compatibility, MCP management, task storage, and tmux integration.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
features/
|
||||
├── 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
|
||||
├── background-agent/ # Task lifecycle, concurrency (50 files, 8330 LOC)
|
||||
│ ├── manager.ts # Main task orchestration (1646 lines)
|
||||
│ ├── concurrency.ts # Parallel execution limits per provider/model
|
||||
│ └── spawner/ # Task spawning utilities (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
|
||||
│ ├── skill-discovery.ts # getAllSkills() with caching
|
||||
│ └── 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 (1111), playwright, dev-browser, frontend-ui-ux
|
||||
├── builtin-commands/ # 6 command templates (11 files, 1511 LOC)
|
||||
│ └── templates/ # refactor, ralph-loop, init-deep, handoff, start-work, stop-continuation
|
||||
├── claude-tasks/ # Task schema + storage (7 files, 1165 LOC)
|
||||
├── 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)
|
||||
```
|
||||
|
||||
## 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
|
||||
Task creation → Queue → Concurrency check → Execute → Monitor/Poll → Notification → Cleanup
|
||||
|
||||
**Skill Loading Pipeline (4-scope priority):**
|
||||
opencode-project (`.opencode/skills/`) > opencode (`~/.config/opencode/skills/`) > project (`.claude/skills/`) > user (`~/.claude/skills/`)
|
||||
|
||||
**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
|
||||
5 loaders: agent-loader, command-loader, mcp-loader, plugin-loader, session-state
|
||||
|
||||
**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
|
||||
**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
|
||||
```
|
||||
|
||||
## HOW TO ADD
|
||||
|
||||
|
||||
@@ -1,16 +1,15 @@
|
||||
# CLAUDE TASKS FEATURE KNOWLEDGE BASE
|
||||
# CLAUDE TASKS KNOWLEDGE BASE
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Claude Code compatible task schema and storage. Provides core task management utilities used by task-related tools and features.
|
||||
Claude Code compatible task schema and storage. Core task management with file-based persistence and atomic writes.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
claude-tasks/
|
||||
├── types.ts # Task schema (Zod)
|
||||
├── types.test.ts # Schema validation tests (8 tests)
|
||||
├── storage.ts # File operations
|
||||
├── 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
|
||||
@@ -21,44 +20,36 @@ claude-tasks/
|
||||
|
||||
```typescript
|
||||
type TaskStatus = "pending" | "in_progress" | "completed" | "deleted"
|
||||
|
||||
interface Task {
|
||||
id: string
|
||||
subject: string // Imperative: "Run tests" (was: title)
|
||||
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 (was: dependsOn)
|
||||
owner?: string // Agent name
|
||||
activeForm?: string // Present continuous: "Running tests"
|
||||
blocks: string[] // Task IDs this task blocks
|
||||
blockedBy: string[] // Task IDs blocking this task
|
||||
owner?: string // Agent name
|
||||
metadata?: Record<string, unknown>
|
||||
repoURL?: string
|
||||
parentID?: string
|
||||
threadID?: string
|
||||
}
|
||||
```
|
||||
|
||||
**Key Differences from Legacy**:
|
||||
- `subject` (was `title`)
|
||||
- `blockedBy` (was `dependsOn`)
|
||||
- `blocks` (new field)
|
||||
- `activeForm` (new field)
|
||||
|
||||
## STORAGE UTILITIES
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `getTaskDir(config)` | Returns task storage directory path |
|
||||
| `resolveTaskListId(config)` | Resolves task list ID (env → config → cwd basename) |
|
||||
| `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 |
|
||||
| `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 |
|
||||
|
||||
## ANTI-PATTERNS
|
||||
|
||||
- Direct fs operations (use storage utilities)
|
||||
- Skipping lock acquisition for writes
|
||||
- Ignoring null returns from readJsonSafe
|
||||
- Using old schema field names (title, dependsOn)
|
||||
- Using old field names (title → subject, dependsOn → blockedBy)
|
||||
|
||||
Reference in New Issue
Block a user