Skip to content

Commit d9ab6ab

Browse files
committed
docs: update AGENTS.md hierarchy with latest structure and line counts
- Root: Add Prometheus/Metis/Momus agents, MCP architecture, 82 test files - agents/: Document 7-section delegation and wisdom notepad - auth/: Multi-account load balancing (10 accounts), endpoint fallback - features/: Update background-agent 825 lines, builtin-skills 1230 lines - hooks/: 22+ hooks with event timing details - tools/: sisyphus-task 583 lines, LSP client 632 lines - cli/: config-manager 725 lines, 17+ doctor checks - shared/: Cross-cutting utilities with usage patterns
1 parent cf53b2b commit d9ab6ab

File tree

8 files changed

+213
-305
lines changed

8 files changed

+213
-305
lines changed

AGENTS.md

Lines changed: 42 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# PROJECT KNOWLEDGE BASE
22

3-
**Generated:** 2026-01-09T15:38:00+09:00
4-
**Commit:** 0581793
3+
**Generated:** 2026-01-13T14:45:00+09:00
4+
**Commit:** e47b5514
55
**Branch:** dev
66

77
## OVERVIEW
@@ -13,16 +13,16 @@ OpenCode plugin implementing Claude Code/AmpCode features. Multi-model agent orc
1313
```
1414
oh-my-opencode/
1515
├── src/
16-
│ ├── agents/ # AI agents (7): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker
17-
│ ├── hooks/ # 22 lifecycle hooks - see src/hooks/AGENTS.md
16+
│ ├── agents/ # AI agents (7+): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker, prometheus, metis, momus
17+
│ ├── hooks/ # 22+ lifecycle hooks - see src/hooks/AGENTS.md
1818
│ ├── tools/ # LSP, AST-Grep, Grep, Glob, session mgmt - see src/tools/AGENTS.md
1919
│ ├── features/ # Claude Code compat layer - see src/features/AGENTS.md
2020
│ ├── auth/ # Google Antigravity OAuth - see src/auth/AGENTS.md
2121
│ ├── shared/ # Cross-cutting utilities - see src/shared/AGENTS.md
2222
│ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md
23-
│ ├── mcp/ # MCP configs: context7, grep_app
24-
│ ├── config/ # Zod schema, TypeScript types
25-
│ └── index.ts # Main plugin entry (548 lines)
23+
│ ├── mcp/ # MCP configs: context7, grep_app, websearch
24+
│ ├── config/ # Zod schema (12k lines), TypeScript types
25+
│ └── index.ts # Main plugin entry (563 lines)
2626
├── script/ # build-schema.ts, publish.ts, generate-changelog.ts
2727
├── assets/ # JSON schema
2828
└── dist/ # Build output (ESM + .d.ts)
@@ -50,7 +50,7 @@ oh-my-opencode/
5050
| Shared utilities | `src/shared/` | Cross-cutting utilities |
5151
| Slash commands | `src/hooks/auto-slash-command/` | Auto-detect and execute `/command` patterns |
5252
| Ralph Loop | `src/hooks/ralph-loop/` | Self-referential dev loop until completion |
53-
| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (660 lines) |
53+
| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (677 lines) |
5454

5555
## TDD (Test-Driven Development)
5656

@@ -83,7 +83,7 @@ oh-my-opencode/
8383
- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
8484
- **Exports**: Barrel pattern in index.ts; explicit named exports for tools/hooks
8585
- **Naming**: kebab-case directories, createXXXHook/createXXXTool factories
86-
- **Testing**: BDD comments `#given/#when/#then`, TDD workflow (RED-GREEN-REFACTOR)
86+
- **Testing**: BDD comments `#given/#when/#then`, TDD workflow (RED-GREEN-REFACTOR), 82 test files
8787
- **Temperature**: 0.1 for code agents, max 0.3
8888

8989
## ANTI-PATTERNS (THIS PROJECT)
@@ -122,13 +122,16 @@ oh-my-opencode/
122122

123123
| Agent | Default Model | Purpose |
124124
|-------|---------------|---------|
125-
| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator |
125+
| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator with extended thinking |
126126
| oracle | openai/gpt-5.2 | Read-only consultation. High-IQ debugging, architecture |
127127
| librarian | opencode/glm-4.7-free | Multi-repo analysis, docs |
128128
| explore | opencode/grok-code | Fast codebase exploration |
129129
| frontend-ui-ux-engineer | google/gemini-3-pro-preview | UI generation |
130130
| document-writer | google/gemini-3-pro-preview | Technical docs |
131131
| multimodal-looker | google/gemini-3-flash | PDF/image analysis |
132+
| Prometheus (Planner) | anthropic/claude-opus-4-5 | Strategic planning, interview-driven |
133+
| Metis (Plan Consultant) | anthropic/claude-sonnet-4-5 | Pre-planning analysis |
134+
| Momus (Plan Reviewer) | anthropic/claude-sonnet-4-5 | Plan validation |
132135

133136
## COMMANDS
134137

@@ -137,7 +140,7 @@ bun run typecheck # Type check
137140
bun run build # ESM + declarations + schema
138141
bun run rebuild # Clean + Build
139142
bun run build:schema # Schema only
140-
bun test # Run tests (76 test files, 2559+ BDD assertions)
143+
bun test # Run tests (82 test files, 2559+ BDD assertions)
141144
```
142145

143146
## DEPLOYMENT
@@ -160,23 +163,38 @@ bun test # Run tests (76 test files, 2559+ BDD assertions)
160163

161164
| File | Lines | Description |
162165
|------|-------|-------------|
163-
| `src/agents/orchestrator-sisyphus.ts` | 1484 | Orchestrator agent, complex delegation |
166+
| `src/agents/orchestrator-sisyphus.ts` | 1486 | Orchestrator agent, 7-section delegation, accumulated wisdom |
164167
| `src/features/builtin-skills/skills.ts` | 1230 | Skill definitions (frontend-ui-ux, playwright) |
165-
| `src/agents/prometheus-prompt.ts` | 982 | Planning agent system prompt |
166-
| `src/auth/antigravity/fetch.ts` | 798 | Token refresh, URL rewriting |
167-
| `src/auth/antigravity/thinking.ts` | 755 | Thinking block extraction |
168-
| `src/cli/config-manager.ts` | 725 | JSONC parsing, env detection |
169-
| `src/hooks/sisyphus-orchestrator/index.ts` | 660 | Orchestrator hook impl |
170-
| `src/agents/sisyphus.ts` | 641 | Main Sisyphus prompt |
171-
| `src/tools/lsp/client.ts` | 612 | LSP protocol, JSON-RPC |
172-
| `src/features/background-agent/manager.ts` | 608 | Task lifecycle |
173-
| `src/auth/antigravity/response.ts` | 599 | Response transformation, streaming |
174-
| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 556 | Multi-stage recovery |
175-
| `src/index.ts` | 548 | Main plugin, all hook/tool init |
168+
| `src/agents/prometheus-prompt.ts` | 988 | Planning agent, interview mode, multi-agent validation |
169+
| `src/auth/antigravity/fetch.ts` | 798 | Token refresh, multi-account rotation, endpoint fallback |
170+
| `src/auth/antigravity/thinking.ts` | 755 | Thinking block extraction, signature management |
171+
| `src/cli/config-manager.ts` | 725 | JSONC parsing, multi-level config, env detection |
172+
| `src/hooks/sisyphus-orchestrator/index.ts` | 677 | Orchestrator hook impl |
173+
| `src/agents/sisyphus.ts` | 643 | Main Sisyphus prompt |
174+
| `src/tools/lsp/client.ts` | 632 | LSP protocol, JSON-RPC |
175+
| `src/features/background-agent/manager.ts` | 825 | Task lifecycle, concurrency |
176+
| `src/auth/antigravity/response.ts` | 598 | Response transformation, streaming |
177+
| `src/tools/sisyphus-task/tools.ts` | 583 | Category-based task delegation |
178+
| `src/index.ts` | 563 | Main plugin, all hook/tool init |
179+
| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 555 | Multi-stage recovery |
180+
181+
## MCP ARCHITECTURE
182+
183+
Three-tier MCP system:
184+
1. **Built-in**: `websearch` (Exa), `context7` (docs), `grep_app` (GitHub search)
185+
2. **Claude Code compatible**: `.mcp.json` files with `${VAR}` expansion
186+
3. **Skill-embedded**: YAML frontmatter in skills (e.g., playwright)
187+
188+
## CONFIG SYSTEM
189+
190+
- **Zod validation**: `src/config/schema.ts` (12k lines)
191+
- **JSONC support**: Comments and trailing commas
192+
- **Multi-level**: User (`~/.config/opencode/`) → Project (`.opencode/`)
193+
- **CLI doctor**: Validates config and reports errors
176194

177195
## NOTES
178196

179-
- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 76 test files
197+
- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 82 test files
180198
- **OpenCode**: Requires >= 1.0.150
181199
- **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
182200
- **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)

src/agents/AGENTS.md

Lines changed: 32 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,23 @@
11
# AGENTS KNOWLEDGE BASE
22

33
## OVERVIEW
4-
5-
AI agent definitions for multi-model orchestration. 7 specialized agents: Sisyphus (orchestrator), oracle (read-only consultation), librarian (research), explore (grep), frontend-ui-ux-engineer, document-writer, multimodal-looker.
4+
AI agent definitions for multi-model orchestration, delegating tasks to specialized experts.
65

76
## STRUCTURE
8-
97
```
108
agents/
11-
├── orchestrator-sisyphus.ts # Orchestrator agent (1484 lines) - complex delegation
12-
├── sisyphus.ts # Main Sisyphus prompt (641 lines)
9+
├── orchestrator-sisyphus.ts # Orchestrator agent (1486 lines) - 7-section delegation, wisdom
10+
├── sisyphus.ts # Main Sisyphus prompt (643 lines)
1311
├── sisyphus-junior.ts # Junior variant for delegated tasks
1412
├── oracle.ts # Strategic advisor (GPT-5.2)
15-
├── librarian.ts # Multi-repo research (Claude Sonnet 4.5)
13+
├── librarian.ts # Multi-repo research (GLM-4.7-free)
1614
├── explore.ts # Fast codebase grep (Grok Code)
1715
├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro)
1816
├── document-writer.ts # Technical docs (Gemini 3 Pro)
1917
├── multimodal-looker.ts # PDF/image analysis (Gemini 3 Flash)
20-
├── prometheus-prompt.ts # Planning agent prompt (982 lines)
21-
├── metis.ts # Plan Consultant agent (404 lines)
22-
├── momus.ts # Plan Reviewer agent (404 lines)
18+
├── prometheus-prompt.ts # Planning agent prompt (988 lines) - interview mode
19+
├── metis.ts # Plan Consultant agent - pre-planning analysis
20+
├── momus.ts # Plan Reviewer agent - plan validation
2321
├── build-prompt.ts # Shared build agent prompt
2422
├── plan-prompt.ts # Shared plan agent prompt
2523
├── types.ts # AgentModelConfig interface
@@ -28,69 +26,35 @@ agents/
2826
```
2927

3028
## AGENT MODELS
31-
32-
| Agent | Default Model | Fallback | Purpose |
33-
|-------|---------------|----------|---------|
34-
| Sisyphus | anthropic/claude-opus-4-5 | - | Primary orchestrator with extended thinking |
35-
| oracle | openai/gpt-5.2 | - | Read-only consultation. High-IQ debugging, architecture |
36-
| librarian | opencode/glm-4.7-free | - | Docs, OSS research, GitHub examples |
37-
| explore | opencode/grok-code | google/gemini-3-flash, anthropic/claude-haiku-4-5 | Fast contextual grep |
38-
| frontend-ui-ux-engineer | google/gemini-3-pro-preview | - | UI/UX code generation |
39-
| document-writer | google/gemini-3-pro-preview | - | Technical writing |
40-
| multimodal-looker | google/gemini-3-flash | - | PDF/image analysis |
29+
| Agent | Default Model | Purpose |
30+
|-------|---------------|---------|
31+
| Sisyphus | claude-opus-4-5 | Primary orchestrator. 32k extended thinking budget. |
32+
| oracle | openai/gpt-5.2 | High-IQ debugging, architecture, strategic consultation. |
33+
| librarian | glm-4.7-free | Multi-repo analysis, docs research, GitHub examples. |
34+
| explore | grok-code | Fast contextual grep. Fallbacks: Gemini-3-Flash, Haiku-4-5. |
35+
| frontend-ui-ux | gemini-3-pro | Production-grade UI/UX generation and styling. |
36+
| document-writer | gemini-3-pro | Technical writing, guides, API documentation. |
37+
| Prometheus | claude-opus-4-5 | Strategic planner. Interview mode, orchestrates Metis/Momus. |
38+
| Metis | claude-sonnet-4-5 | Plan Consultant. Pre-planning risk/requirement analysis. |
39+
| Momus | claude-sonnet-4-5 | Plan Reviewer. Validation and quality enforcement. |
4140

4241
## HOW TO ADD AN AGENT
43-
44-
1. Create `src/agents/my-agent.ts`:
45-
```typescript
46-
import type { AgentConfig } from "@opencode-ai/sdk"
47-
48-
export const myAgent: AgentConfig = {
49-
model: "provider/model-name",
50-
temperature: 0.1,
51-
system: "Agent system prompt...",
52-
tools: { include: ["tool1", "tool2"] }, // or exclude: [...]
53-
}
54-
```
55-
2. Add to `builtinAgents` in `src/agents/index.ts`
56-
3. Update `types.ts` if adding new config options
57-
58-
## AGENT CONFIG OPTIONS
59-
60-
| Option | Type | Description |
61-
|--------|------|-------------|
62-
| model | string | Model identifier (provider/model-name) |
63-
| temperature | number | 0.0-1.0, most use 0.1 for consistency |
64-
| system | string | System prompt (can be multiline template literal) |
65-
| tools | object | `{ include: [...] }` or `{ exclude: [...] }` |
66-
| top_p | number | Optional nucleus sampling |
67-
| maxTokens | number | Optional max output tokens |
42+
1. Create `src/agents/my-agent.ts` exporting `AgentConfig`.
43+
2. Add to `builtinAgents` in `src/agents/index.ts`.
44+
3. Update `types.ts` if adding new config interfaces.
6845

6946
## MODEL FALLBACK LOGIC
47+
`createBuiltinAgents()` handles resolution:
48+
1. User config override (`agents.{name}.model`).
49+
2. Environment-specific settings (max20, antigravity).
50+
3. Hardcoded defaults in `index.ts`.
7051

71-
`createBuiltinAgents()` in utils.ts handles model fallback:
72-
73-
1. Check user config override (`agents.{name}.model`)
74-
2. Check installer settings (claude max20, gemini antigravity)
75-
3. Use default model
76-
77-
**Fallback order for explore**:
78-
- If gemini antigravity enabled → `google/gemini-3-flash`
79-
- If claude max20 enabled → `anthropic/claude-haiku-4-5`
80-
- Default → `opencode/grok-code` (free)
81-
82-
## ANTI-PATTERNS (AGENTS)
83-
84-
- **High temperature**: Don't use >0.3 for code-related agents
85-
- **Broad tool access**: Prefer explicit `include` over unrestricted access
86-
- **Monolithic prompts**: Keep prompts focused; delegate to specialized agents
87-
- **Missing fallbacks**: Consider free/cheap fallbacks for rate-limited models
52+
## ANTI-PATTERNS
53+
- **Trusting reports**: NEVER trust subagent self-reports; always verify outputs.
54+
- **High temp**: Don't use >0.3 for code agents (Sisyphus/Prometheus use 0.1).
55+
- **Sequential calls**: Prefer `sisyphus_task` with `run_in_background` for parallelism.
8856

8957
## SHARED PROMPTS
90-
91-
- **build-prompt.ts**: Base prompt for build agents (OpenCode default + Sisyphus variants)
92-
- **plan-prompt.ts**: Base prompt for plan agents (legacy)
93-
- **prometheus-prompt.ts**: System prompt for Prometheus (Planner) agent
94-
- **metis.ts**: Metis (Plan Consultant) agent for pre-planning analysis
95-
96-
Used by `src/index.ts` when creating Builder-Sisyphus and Prometheus (Planner) variants.
58+
- **build-prompt.ts**: Unified base for Sisyphus and Builder variants.
59+
- **plan-prompt.ts**: Core planning logic shared across planning agents.
60+
- **orchestrator-sisyphus.ts**: Uses a 7-section prompt structure and "wisdom notepad" to preserve learnings across turns.

src/auth/AGENTS.md

Lines changed: 20 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,21 @@
11
# AUTH KNOWLEDGE BASE
22

33
## OVERVIEW
4-
54
Google Antigravity OAuth for Gemini models. Token management, fetch interception, thinking block extraction.
65

76
## STRUCTURE
8-
97
```
108
auth/
119
└── antigravity/
1210
├── plugin.ts # Main export, hooks registration (554 lines)
1311
├── oauth.ts # OAuth flow, token acquisition
1412
├── token.ts # Token storage, refresh logic
1513
├── fetch.ts # Fetch interceptor (798 lines)
16-
├── response.ts # Response transformation (599 lines)
14+
├── response.ts # Response transformation (598 lines)
1715
├── thinking.ts # Thinking block extraction (755 lines)
1816
├── thought-signature-store.ts # Signature caching
1917
├── message-converter.ts # Format conversion
20-
├── accounts.ts # Multi-account management
18+
├── accounts.ts # Multi-account management (up to 10 accounts)
2119
├── browser.ts # Browser automation for OAuth
2220
├── cli.ts # CLI interaction
2321
├── request.ts # Request building
@@ -29,33 +27,29 @@ auth/
2927
```
3028

3129
## KEY COMPONENTS
32-
3330
| File | Purpose |
3431
|------|---------|
35-
| fetch.ts | URL rewriting, token injection, retries |
36-
| thinking.ts | Extract `<antThinking>` blocks |
37-
| response.ts | Streaming SSE parsing |
38-
| oauth.ts | Browser-based OAuth flow |
39-
| token.ts | Token persistence, expiry |
32+
| fetch.ts | URL rewriting, multi-account rotation, endpoint fallback |
33+
| thinking.ts | Thinking block extraction, signature management, budget mapping |
34+
| response.ts | Streaming SSE parsing and response transformation |
35+
| accounts.ts | Load balancing across up to 10 Google accounts |
36+
| thought-signature-store.ts | Caching signatures for multi-turn thinking conversations |
4037

4138
## HOW IT WORKS
42-
43-
1. **Intercept**: fetch.ts intercepts Anthropic/Google requests
44-
2. **Rewrite**: URLs → Antigravity proxy endpoints
45-
3. **Auth**: Bearer token from stored OAuth credentials
46-
4. **Response**: Streaming parsed, thinking blocks extracted
47-
5. **Transform**: Normalized for OpenCode
39+
1. **Intercept**: `fetch.ts` intercepts Anthropic/Google requests.
40+
2. **Route**: Rotates accounts and selects best endpoint (daily → autopush → prod).
41+
3. **Auth**: Injects Bearer tokens from `token.ts` persistence.
42+
4. **Process**: `response.ts` parses SSE; `thinking.ts` manages thought blocks.
43+
5. **Recovery**: Detects GCP permission errors and triggers recovery/rotation.
4844

4945
## FEATURES
50-
51-
- Multi-account (up to 10 Google accounts)
52-
- Auto-fallback on rate limit
53-
- Thinking blocks preserved
54-
- Antigravity proxy for AI Studio access
46+
- Multi-account load balancing (up to 10 accounts)
47+
- Strategic endpoint fallback: daily → autopush → prod
48+
- Persistent thought signatures for continuity in thinking models
49+
- Automated GCP permission error recovery
5550

5651
## ANTI-PATTERNS
57-
58-
- Direct API calls (use fetch interceptor)
59-
- Tokens in code (use token.ts storage)
60-
- Ignoring refresh (check expiry first)
61-
- Blocking on OAuth (always async)
52+
- Hardcoding endpoints: Use `constants.ts` or let `fetch.ts` route.
53+
- Manual token handling: Use `token.ts` and `storage.ts` abstraction.
54+
- Sync OAuth calls: All auth flows must be non-blocking/async.
55+
- Ignoring account rotation: Let `fetch.ts` handle load balancing.

0 commit comments

Comments
 (0)