docs: update AGENTS guidance

2026-05-18 11:49:56 +09:00
parent c4dd21e1f3
commit 34e6af1ae6
16 changed files with 1648 additions and 24 deletions
@@ -0,0 +1,43 @@
+# src/features/builtin-commands/ -- Built-in Slash Commands
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+Registry of built-in commands shipped inside the plugin. Each command is a template literal with title, description, and instructions. Registered via `createBuiltinCommandDefinitions()` factory in `commands.ts`. Loaded by `claude-code-command-loader`.
+
+## FILE CATALOG
+
+| File | Purpose |
+|------|---------|
+| `commands.ts` | `createBuiltinCommandDefinitions()` factory + `loadBuiltinCommands()` filter |
+| `index.ts` | Barrel exports |
+| `types.ts` | `BuiltinCommandName` union type + `BuiltinCommandConfig` |
+| `templates/` | One `.ts` file per command |
+
+## TEMPLATES
+
+| Command | Source File | Notes |
+|---------|-------------|-------|
+| `init-deep` | `templates/init-deep.ts` | Hierarchical AGENTS.md generator |
+| `ralph-loop` | `templates/ralph-loop.ts` | Self-referential dev loop |
+| `ulw-loop` | `templates/ralph-loop.ts` | Ultrawork loop variant |
+| `cancel-ralph` | `templates/ralph-loop.ts` | Loop cancellation |
+| `refactor` | `templates/refactor.ts` | LSP + AST-grep refactoring |
+| `start-work` | `templates/start-work.ts` | Prometheus plan executor |
+| `stop-continuation` | `templates/stop-continuation.ts` | Kill all continuations |
+| `handoff` | `templates/handoff.ts` | Session context summary |
+| `remove-ai-slops` | `templates/remove-ai-slops.ts` | AI code smell cleanup |
+| `hyperplan` | `templates/hyperplan.ts` | Adversarial team-mode planning |
+
+## STRUCTURE
+
+Each template exports a string constant containing the command's system prompt. `commands.ts` wraps it in `<command-instruction>` XML and injects `$ARGUMENTS`, `$SESSION_ID`, and `$TIMESTAMP` where needed. Some commands append a team-mode addendum when `teamModeEnabled` is true.
+
+## LOADING
+
+Phase 6 of config loading (`command-config-handler.ts`) merges built-ins with user-installed commands from `.opencode/commands/` and Claude Code plugins. `disabled_commands` in config filters out specific built-ins by name. The `autoSlashCommand` hook in `src/hooks/` executes these on user input.
+
+## TESTS
+
+Co-located `.test.ts` files in `templates/` cover `ralph-loop` and `stop-continuation` logic.
@@ -0,0 +1,46 @@
+# src/features/claude-code-agent-loader/ -- Claude Code Agent Compatibility Layer
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+Sibling to `claude-code-mcp-loader`. Loads Claude Code agent definitions from `.opencode/agents/`, `~/.claude/agents/`, and inline `opencode.json` config, then translates them to OpenCode `AgentConfig`. 12 files.
+
+## LOAD PIPELINE
+
+```
+loadUserAgents() / loadProjectAgents() / loadOpencodeGlobalAgents() / loadOpencodeProjectAgents()
+  -> loader.ts: discover .md files in agents/ directories
+  -> agent-definitions-loader.ts: parse YAML frontmatter + body, load from explicit paths
+  -> json-agent-loader.ts: parse .json / .jsonc agent definitions
+  -> opencode-config-agents-reader.ts: read inline agents from opencode.json
+  -> claude-model-mapper.ts: translate "sonnet" / "opus" / "haiku" -> OpenCode provider/model IDs
+  -> return Record<string, ClaudeCodeAgentConfig>
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Barrel: all exports |
+| `loader.ts` | `loadUserAgents()`, `loadProjectAgents()`, `loadOpencode*Agents()` main entry |
+| `agent-definitions-loader.ts` | `parseMarkdownAgentFile()`, `loadAgentDefinitions()` |
+| `json-agent-loader.ts` | `parseJsonAgentFile()` -- JSON/JSONC agent definitions |
+| `claude-model-mapper.ts` | Claude aliases -> OpenCode `providerID/modelID` |
+| `opencode-config-agents-reader.ts` | Reads inline `agents` and `agent_definitions` from `opencode.json` |
+| `types.ts` | `ClaudeCodeAgentConfig`, `AgentScope`, `LoadedAgent` |
+
+## INTEGRATION
+
+Phase 3 of config loading (`src/plugin-handlers/agent-config-handler.ts`) calls this loader to populate the agent registry before the plugin interface is built.
+
+## COMPANION LOADERS
+
+- **`claude-code-plugin-loader`**: full plugins with commands, skills, hooks, MCPs
+- **`claude-code-mcp-loader`**: Tier 2 MCPs from `.mcp.json`
+
+## RELATED
+
+- Phase 3 integration: `src/plugin-handlers/agent-config-handler.ts`
+- Plugin loader: `src/features/claude-code-plugin-loader/`
+- MCP loader: `src/features/claude-code-mcp-loader/`