From bfb5d43bc22734777abbdd87875982fa0cc00a50 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Sun, 28 Dec 2025 17:40:51 +0900 Subject: [PATCH] Add AGENTS.md knowledge base documentation files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add src/agents/AGENTS.md with agent module documentation - Update root AGENTS.md with latest generation timestamp (2025-12-28T17:15:00+09:00, commit f5b74d5) - Update src/features/AGENTS.md with builtin-commands and claude-code-plugin-loader documentation - Update src/hooks/AGENTS.md with thinking-block-validator hook documentation 🤖 Generated with assistance of [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode) --- AGENTS.md | 4 +- src/agents/AGENTS.md | 89 ++++++++++++++++++++++++++++++++++++++++++ src/features/AGENTS.md | 2 + src/hooks/AGENTS.md | 1 + 4 files changed, 94 insertions(+), 2 deletions(-) create mode 100644 src/agents/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index c419669..983d689 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # PROJECT KNOWLEDGE BASE -**Generated:** 2025-12-24T17:07:00+09:00 -**Commit:** 0172241 +**Generated:** 2025-12-28T17:15:00+09:00 +**Commit:** f5b74d5 **Branch:** dev ## OVERVIEW diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md new file mode 100644 index 0000000..466fae8 --- /dev/null +++ b/src/agents/AGENTS.md @@ -0,0 +1,89 @@ +# AGENTS KNOWLEDGE BASE + +## OVERVIEW + +AI agent definitions for multi-model orchestration. 7 specialized agents: Sisyphus (orchestrator), oracle (strategy), librarian (research), explore (grep), frontend-ui-ux-engineer, document-writer, multimodal-looker. + +## STRUCTURE + +``` +agents/ +├── sisyphus.ts # Primary orchestrator (Claude Opus 4.5) +├── oracle.ts # Strategic advisor (GPT-5.2) +├── librarian.ts # Multi-repo research (Claude Sonnet 4.5) +├── explore.ts # Fast codebase grep (Grok Code) +├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro) +├── document-writer.ts # Technical docs (Gemini 3 Flash) +├── multimodal-looker.ts # PDF/image analysis (Gemini 3 Flash) +├── build-prompt.ts # Shared build agent prompt +├── plan-prompt.ts # Shared plan agent prompt +├── types.ts # AgentModelConfig interface +├── utils.ts # createBuiltinAgents(), getAgentName() +└── index.ts # builtinAgents export +``` + +## AGENT MODELS + +| Agent | Default Model | Fallback | Purpose | +|-------|---------------|----------|---------| +| Sisyphus | anthropic/claude-opus-4-5 | - | Primary orchestrator with extended thinking | +| oracle | openai/gpt-5.2 | - | Architecture, debugging, code review | +| librarian | anthropic/claude-sonnet-4-5 | google/gemini-3-flash | Docs, OSS research, GitHub examples | +| explore | opencode/grok-code | google/gemini-3-flash, anthropic/claude-haiku-4-5 | Fast contextual grep | +| frontend-ui-ux-engineer | google/gemini-3-pro-preview | - | UI/UX code generation | +| document-writer | google/gemini-3-pro-preview | - | Technical writing | +| multimodal-looker | google/gemini-3-flash | - | PDF/image analysis | + +## HOW TO ADD AN AGENT + +1. Create `src/agents/my-agent.ts`: + ```typescript + import type { AgentConfig } from "@opencode-ai/sdk" + + export const myAgent: AgentConfig = { + model: "provider/model-name", + temperature: 0.1, + system: "Agent system prompt...", + tools: { include: ["tool1", "tool2"] }, // or exclude: [...] + } + ``` +2. Add to `builtinAgents` in `src/agents/index.ts` +3. Update `types.ts` if adding new config options + +## AGENT CONFIG OPTIONS + +| Option | Type | Description | +|--------|------|-------------| +| model | string | Model identifier (provider/model-name) | +| temperature | number | 0.0-1.0, most use 0.1 for consistency | +| system | string | System prompt (can be multiline template literal) | +| tools | object | `{ include: [...] }` or `{ exclude: [...] }` | +| top_p | number | Optional nucleus sampling | +| maxTokens | number | Optional max output tokens | + +## MODEL FALLBACK LOGIC + +`createBuiltinAgents()` in utils.ts handles model fallback: + +1. Check user config override (`agents.{name}.model`) +2. Check installer settings (claude max20, gemini antigravity) +3. Use default model + +**Fallback order for explore**: +- If gemini antigravity enabled → `google/gemini-3-flash` +- If claude max20 enabled → `anthropic/claude-haiku-4-5` +- Default → `opencode/grok-code` (free) + +## ANTI-PATTERNS (AGENTS) + +- **High temperature**: Don't use >0.3 for code-related agents +- **Broad tool access**: Prefer explicit `include` over unrestricted access +- **Monolithic prompts**: Keep prompts focused; delegate to specialized agents +- **Missing fallbacks**: Consider free/cheap fallbacks for rate-limited models + +## SHARED PROMPTS + +- **build-prompt.ts**: Base prompt for build agents (OpenCode default + Sisyphus variants) +- **plan-prompt.ts**: Base prompt for plan agents (Planner-Sisyphus) + +Used by `src/index.ts` when creating Builder-Sisyphus and Planner-Sisyphus variants. diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 0a8d8f7..8997104 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -12,10 +12,12 @@ features/ │ ├── manager.ts # Task lifecycle, notifications │ ├── manager.test.ts │ └── types.ts +├── builtin-commands/ # Built-in slash command definitions ├── claude-code-agent-loader/ # Load agents from ~/.claude/agents/*.md ├── claude-code-command-loader/ # Load commands from ~/.claude/commands/*.md ├── claude-code-mcp-loader/ # Load MCPs from .mcp.json │ └── env-expander.ts # ${VAR} expansion +├── claude-code-plugin-loader/ # Load external plugins from installed_plugins.json ├── claude-code-session-state/ # Session state persistence ├── claude-code-skill-loader/ # Load skills from ~/.claude/skills/*/SKILL.md └── hook-message-injector/ # Inject messages into conversation diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index 36abe0f..77ae00f 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -27,6 +27,7 @@ hooks/ ├── rules-injector/ # Conditional rules from .claude/rules/ ├── session-recovery/ # Recover from session errors ├── think-mode/ # Auto-detect thinking triggers +├── thinking-block-validator/ # Validate thinking blocks in messages ├── context-window-monitor.ts # Monitor context usage (standalone) ├── empty-task-response-detector.ts ├── session-notification.ts # OS notify on idle (standalone)