sapient/oh-my-openagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update AGENTS documentation metadata and agent model references

Browse Source 
- Update generated timestamp and commit hash metadata
- Normalize agent model names with provider prefixes (anthropic/, opencode/, google/)
- Remove deprecated Google OAuth/Antigravity references
- Update line counts and complexity hotspot entries
- Adjust test count from 82 to 80+ files and assertions from 2559+ to 2500+

🤖 Generated with assistance of oh-my-opencode
This commit is contained in:
justsisyphus
2026-01-15 15:53:51 +09:00
parent 89fa9ff167
commit a38dc28e40
7 changed files with 71 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
AGENTS.md
View File

@@ -1,7 +1,7 @@
# PROJECT KNOWLEDGE BASE
**Generated:** 2026-01-13T14:45:00+09:00
**Commit:** e47b5514
**Generated:** 2026-01-15T14:53:00+09:00
**Commit:** 89fa9ff1
**Branch:** dev
## OVERVIEW
@@ -13,16 +13,15 @@ OpenCode plugin implementing Claude Code/AmpCode features. Multi-model agent orc
```
oh-my-opencode/
├── src/
│ ├── agents/ # AI agents (7+): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker, prometheus, metis, momus
│ ├── agents/ # AI agents (10+): Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker, prometheus, metis, momus
│ ├── hooks/ # 22+ lifecycle hooks - see src/hooks/AGENTS.md
│ ├── tools/ # LSP, AST-Grep, Grep, Glob, session mgmt - see src/tools/AGENTS.md
│ ├── features/ # Claude Code compat layer - see src/features/AGENTS.md
│ ├── auth/ # Google Antigravity OAuth - see src/auth/AGENTS.md
│ ├── shared/ # Cross-cutting utilities - see src/shared/AGENTS.md
│ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md
│ ├── mcp/ # MCP configs: context7, grep_app, websearch
│ ├── config/ # Zod schema (12k lines), TypeScript types
│ └── index.ts # Main plugin entry (563 lines)
│ ├── config/ # Zod schema, TypeScript types
│ └── index.ts # Main plugin entry (580 lines)
├── script/ # build-schema.ts, publish.ts, generate-changelog.ts
├── assets/ # JSON schema
└── dist/ # Build output (ESM + .d.ts)
@@ -39,7 +38,6 @@ oh-my-opencode/
| Add skill | `src/features/builtin-skills/` | Create skill dir with SKILL.md |
| LSP behavior | `src/tools/lsp/` | client.ts (connection), tools.ts (handlers) |
| AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding |
| Google OAuth | `src/auth/antigravity/` | OAuth plugin for Google/Gemini models |
| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes |
| Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
| Background agents | `src/features/background-agent/` | manager.ts for task management |
@@ -50,7 +48,7 @@ oh-my-opencode/
| Shared utilities | `src/shared/` | Cross-cutting utilities |
| Slash commands | `src/hooks/auto-slash-command/` | Auto-detect and execute `/command` patterns |
| Ralph Loop | `src/hooks/ralph-loop/` | Self-referential dev loop until completion |
| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (677 lines) |
| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (684 lines) |
## TDD (Test-Driven Development)
@@ -83,7 +81,7 @@ oh-my-opencode/
- **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
- **Exports**: Barrel pattern in index.ts; explicit named exports for tools/hooks
- **Naming**: kebab-case directories, createXXXHook/createXXXTool factories
- **Testing**: BDD comments `#given/#when/#then`, TDD workflow (RED-GREEN-REFACTOR), 82 test files
- **Testing**: BDD comments `#given/#when/#then`, TDD workflow (RED-GREEN-REFACTOR), 80+ test files
- **Temperature**: 0.1 for code agents, max 0.3
## ANTI-PATTERNS (THIS PROJECT)
@@ -140,7 +138,7 @@ bun run typecheck # Type check
bun run build # ESM + declarations + schema
bun run rebuild # Clean + Build
bun run build:schema # Schema only
bun test # Run tests (82 test files, 2559+ BDD assertions)
bun test # Run tests (80+ test files, 2500+ BDD assertions)
```
## DEPLOYMENT
@@ -157,26 +155,23 @@ bun test # Run tests (82 test files, 2559+ BDD assertions)
- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master, rolling `next` draft release
- **publish.yml**: Manual workflow_dispatch, version bump, changelog, OIDC npm publish
- **sisyphus-agent.yml**: Agent-in-CI for automated issue handling via `@sisyphus-dev-ai` mentions
## COMPLEXITY HOTSPOTS
| File | Lines | Description |
|------|-------|-------------|
| `src/agents/orchestrator-sisyphus.ts` | 1486 | Orchestrator agent, 7-section delegation, accumulated wisdom |
| `src/agents/orchestrator-sisyphus.ts` | 1485 | Orchestrator agent, 7-section delegation, accumulated wisdom |
| `src/features/builtin-skills/skills.ts` | 1230 | Skill definitions (frontend-ui-ux, playwright) |
| `src/agents/prometheus-prompt.ts` | 988 | Planning agent, interview mode, multi-agent validation |
| `src/auth/antigravity/fetch.ts` | 798 | Token refresh, multi-account rotation, endpoint fallback |
| `src/auth/antigravity/thinking.ts` | 755 | Thinking block extraction, signature management |
| `src/cli/config-manager.ts` | 725 | JSONC parsing, multi-level config, env detection |
| `src/hooks/sisyphus-orchestrator/index.ts` | 677 | Orchestrator hook impl |
| `src/agents/prometheus-prompt.ts` | 991 | Planning agent, interview mode, multi-agent validation |
| `src/features/background-agent/manager.ts` | 928 | Task lifecycle, concurrency |
| `src/cli/config-manager.ts` | 730 | JSONC parsing, multi-level config, env detection |
| `src/hooks/sisyphus-orchestrator/index.ts` | 684 | Orchestrator hook impl |
| `src/tools/sisyphus-task/tools.ts` | 667 | Category-based task delegation |
| `src/agents/sisyphus.ts` | 643 | Main Sisyphus prompt |
| `src/tools/lsp/client.ts` | 632 | LSP protocol, JSON-RPC |
| `src/features/background-agent/manager.ts` | 825 | Task lifecycle, concurrency |
| `src/auth/antigravity/response.ts` | 598 | Response transformation, streaming |
| `src/tools/sisyphus-task/tools.ts` | 583 | Category-based task delegation |
| `src/index.ts` | 563 | Main plugin, all hook/tool init |
| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 555 | Multi-stage recovery |
| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template |
| `src/index.ts` | 580 | Main plugin, all hook/tool init |
| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 554 | Multi-stage recovery |
## MCP ARCHITECTURE
@@ -187,14 +182,14 @@ Three-tier MCP system:
## CONFIG SYSTEM
- **Zod validation**: `src/config/schema.ts` (12k lines)
- **Zod validation**: `src/config/schema.ts`
- **JSONC support**: Comments and trailing commas
- **Multi-level**: User (`~/.config/opencode/`) → Project (`.opencode/`)
- **CLI doctor**: Validates config and reports errors
## NOTES
- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 82 test files
- **Testing**: Bun native test (`bun test`), BDD-style `#given/#when/#then`, 80+ test files
- **OpenCode**: Requires >= 1.0.150
- **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
- **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)

25
src/agents/AGENTS.md
View File

@@ -6,20 +6,21 @@ AI agent definitions for multi-model orchestration, delegating tasks to speciali
## STRUCTURE
```
agents/
├── orchestrator-sisyphus.ts # Orchestrator agent (1486 lines) - 7-section delegation, wisdom
├── orchestrator-sisyphus.ts # Orchestrator agent (1485 lines) - 7-section delegation, wisdom
├── sisyphus.ts # Main Sisyphus prompt (643 lines)
├── sisyphus-junior.ts # Junior variant for delegated tasks
├── oracle.ts # Strategic advisor (GPT-5.2)
├── librarian.ts # Multi-repo research (GLM-4.7-free)
├── explore.ts # Fast codebase grep (Grok Code)
├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro)
├── document-writer.ts # Technical docs (Gemini 3 Pro)
├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro Preview)
├── document-writer.ts # Technical docs (Gemini 3 Pro Preview)
├── multimodal-looker.ts # PDF/image analysis (Gemini 3 Flash)
├── prometheus-prompt.ts # Planning agent prompt (988 lines) - interview mode
├── prometheus-prompt.ts # Planning agent prompt (991 lines) - interview mode
├── metis.ts # Plan Consultant agent - pre-planning analysis
├── momus.ts # Plan Reviewer agent - plan validation
├── build-prompt.ts # Shared build agent prompt
├── plan-prompt.ts # Shared plan agent prompt
├── sisyphus-prompt-builder.ts # Factory for orchestrator prompts
├── types.ts # AgentModelConfig interface
├── utils.ts # createBuiltinAgents(), getAgentName()
└── index.ts # builtinAgents export
@@ -28,15 +29,15 @@ agents/
## AGENT MODELS
| Agent | Default Model | Purpose |
|-------|---------------|---------|
| Sisyphus | claude-opus-4-5 | Primary orchestrator. 32k extended thinking budget. |
| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator. 32k extended thinking budget. |
| oracle | openai/gpt-5.2 | High-IQ debugging, architecture, strategic consultation. |
| librarian | glm-4.7-free | Multi-repo analysis, docs research, GitHub examples. |
| explore | grok-code | Fast contextual grep. Fallbacks: Gemini-3-Flash, Haiku-4-5. |
| frontend-ui-ux | gemini-3-pro | Production-grade UI/UX generation and styling. |
| document-writer | gemini-3-pro | Technical writing, guides, API documentation. |
| Prometheus | claude-opus-4-5 | Strategic planner. Interview mode, orchestrates Metis/Momus. |
| Metis | claude-sonnet-4-5 | Plan Consultant. Pre-planning risk/requirement analysis. |
| Momus | claude-sonnet-4-5 | Plan Reviewer. Validation and quality enforcement. |
| librarian | opencode/glm-4.7-free | Multi-repo analysis, docs research, GitHub examples. |
| explore | opencode/grok-code | Fast contextual grep. Fallbacks: Gemini-3-Flash, Haiku-4-5. |
| frontend-ui-ux | google/gemini-3-pro-preview | Production-grade UI/UX generation and styling. |
| document-writer | google/gemini-3-pro-preview | Technical writing, guides, API documentation. |
| Prometheus | anthropic/claude-opus-4-5 | Strategic planner. Interview mode, orchestrates Metis/Momus. |
| Metis | anthropic/claude-sonnet-4-5 | Plan Consultant. Pre-planning risk/requirement analysis. |
| Momus | anthropic/claude-sonnet-4-5 | Plan Reviewer. Validation and quality enforcement. |
## HOW TO ADD AN AGENT
1. Create `src/agents/my-agent.ts` exporting `AgentConfig`.

20
src/cli/AGENTS.md
View File

@@ -6,17 +6,16 @@ CLI for oh-my-opencode: interactive installer, health diagnostics (doctor), runt
## STRUCTURE
```
cli/
├── index.ts # Commander.js entry, subcommand routing (184 lines)
├── install.ts # Interactive TUI installer (436 lines)
├── config-manager.ts # JSONC parsing, env detection (725 lines)
├── index.ts # Commander.js entry, subcommand routing (146 lines)
├── install.ts # Interactive TUI installer (462 lines)
├── config-manager.ts # JSONC parsing, env detection (730 lines)
├── types.ts # CLI-specific types
├── commands/ # CLI subcommands (auth.ts)
├── doctor/ # Health check system
│ ├── index.ts # Doctor command entry
│ ├── runner.ts # Health check orchestration
│ ├── constants.ts # Check categories
│ ├── types.ts # Check result interfaces
│ └── checks/ # 10+ check modules (17+ individual checks)
│ └── checks/ # 10 check modules (14 individual checks)
├── get-local-version/ # Version detection
└── run/ # OpenCode session launcher
├── completion.ts # Completion logic
@@ -28,16 +27,17 @@ cli/
|---------|---------|
| `install` | Interactive setup wizard with subscription detection |
| `doctor` | Environment health checks (LSP, Auth, Config, Deps) |
| `run` | Launch OpenCode session with event handling |
| `auth` | Manage authentication providers |
| `run` | Launch OpenCode session with todo/background completion enforcement |
| `get-local-version` | Detect and return local plugin version & update status |
## DOCTOR CHECKS
17+ checks in `doctor/checks/`:
- `version.ts`: OpenCode >= 1.0.150
14 checks in `doctor/checks/`:
- `version.ts`: OpenCode >= 1.0.150 & plugin update status
- `config.ts`: Plugin registration & JSONC validity
- `dependencies.ts`: bun, node, git, gh-cli
- `dependencies.ts`: AST-Grep (CLI/NAPI), Comment Checker
- `auth.ts`: Anthropic, OpenAI, Google (Antigravity)
- `lsp.ts`, `mcp.ts`: Tool connectivity checks
- `gh.ts`: GitHub CLI availability
## CONFIG-MANAGER
- **JSONC**: Supports comments and trailing commas via `parseJsonc`

7
src/features/AGENTS.md
View File

@@ -6,13 +6,13 @@ Claude Code compatibility layer + core feature modules. Commands, skills, agents
## STRUCTURE
```
features/
├── background-agent/ # Task lifecycle, notifications (825 lines manager.ts)
├── background-agent/ # Task lifecycle, notifications (928 lines manager.ts)
├── boulder-state/ # Boulder state persistence
├── builtin-commands/ # Built-in slash commands
│ └── templates/ # start-work, refactor, init-deep, ralph-loop
├── builtin-skills/ # Built-in skills (1230 lines skills.ts)
│ ├── git-master/ # Atomic commits, rebase, history search
│ ├── playwright/ # Browser automation skill
│ ├── playwright # Browser automation skill
│ └── frontend-ui-ux/ # Designer-turned-developer skill
├── claude-code-agent-loader/ # ~/.claude/agents/*.md
├── claude-code-command-loader/ # ~/.claude/commands/*.md
@@ -24,8 +24,7 @@ features/
├── opencode-skill-loader/ # Skills from OpenCode + Claude paths
├── skill-mcp-manager/ # MCP servers in skill YAML
├── task-toast-manager/ # Task toast notifications
├── hook-message-injector/ # Inject messages into conversation
└── context-injector/ # Context collection and injection
└── hook-message-injector/ # Inject messages into conversation
```
## LOADER PRIORITY

6
src/hooks/AGENTS.md
View File

@@ -6,8 +6,9 @@
## STRUCTURE
```
hooks/
├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (555 lines)
├── sisyphus-orchestrator/ # Main orchestration & agent delegation (677 lines)
├── sisyphus-orchestrator/ # Main orchestration & agent delegation (684 lines)
├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (554 lines)
├── todo-continuation-enforcer.ts # Force completion of [ ] items (445 lines)
├── ralph-loop/ # Self-referential dev loop (364 lines)
├── claude-code-hooks/ # settings.json hook compatibility layer
├── comment-checker/ # Prevents AI slop/excessive comments
@@ -23,7 +24,6 @@ hooks/
├── start-work/ # Initializes work sessions (ulw/ulw)
├── think-mode/ # Dynamic thinking budget adjustment
├── background-notification/ # OS notification on task completion
├── todo-continuation-enforcer.ts # Force completion of [ ] items
└── tool-output-truncator.ts # Prevents context bloat from verbose tools
```

22
src/shared/AGENTS.md
View File

@@ -7,6 +7,7 @@ Cross-cutting utilities for path resolution, config management, text processing,
```
shared/
├── index.ts # Barrel export
├── agent-variant.ts # Agent model/prompt variation logic
├── claude-config-dir.ts # ~/.claude resolution
├── command-executor.ts # Shell exec with variable expansion
├── config-errors.ts # Global error tracking
@@ -14,23 +15,31 @@ shared/
├── data-path.ts # XDG data directory
├── deep-merge.ts # Type-safe recursive merge
├── dynamic-truncator.ts # Token-aware truncation
├── external-plugin-detector.ts # Detect marketplace plugins
├── file-reference-resolver.ts # @filename syntax
├── file-utils.ts # Symlink, markdown detection
├── first-message-variant.ts # Initial prompt variations
├── frontmatter.ts # YAML frontmatter parsing
├── hook-disabled.ts # Check if hook disabled
├── jsonc-parser.ts # JSON with Comments
├── logger.ts # File-based logging
├── migration.ts # Legacy name compat (omo → Sisyphus)
├── model-sanitizer.ts # Normalize model names
├── opencode-config-dir.ts # ~/.config/opencode resolution
├── opencode-version.ts # Version comparison logic
├── pattern-matcher.ts # Tool name matching
├── permission-compat.ts # Legacy permission mapping
├── session-cursor.ts # Track message history pointer
├── snake-case.ts # Case conversion
└── tool-name.ts # PascalCase normalization
├── tool-name.ts # PascalCase normalization
└── zip-extractor.ts # Plugin installation utility
```
## WHEN TO USE
| Task | Utility |
|------|---------|
| Find ~/.claude | `getClaudeConfigDir()` |
| Find ~/.config/opencode | `getOpenCodeConfigDir()` |
| Merge configs | `deepMerge(base, override)` |
| Parse user files | `parseJsonc()` |
| Check hook enabled | `isHookDisabled(name, list)` |
@@ -38,6 +47,9 @@ shared/
| Resolve @file | `resolveFileReferencesInText()` |
| Execute shell | `resolveCommandsInText()` |
| Legacy names | `migrateLegacyAgentNames()` |
| Version check | `isOpenCodeVersionAtLeast(version)` |
| Map permissions | `normalizePermission()` |
| Track session | `SessionCursor` |
## CRITICAL PATTERNS
```typescript
@@ -49,10 +61,14 @@ const final = deepMerge(deepMerge(defaults, userConfig), projectConfig)
// Safe JSONC parsing for user-edited files
const { config, error } = parseJsoncSafe(content)
// Version-gated features
if (isOpenCodeVersionAtLeast('1.0.150')) { /* ... */ }
```
## ANTI-PATTERNS
- Hardcoding paths (use `getClaudeConfigDir`, `getUserConfigPath`)
- Hardcoding paths (use `getClaudeConfigDir`, `getOpenCodeConfigDir`)
- Using `JSON.parse` for user configs (always use `parseJsonc`)
- Ignoring output size (large tool outputs MUST use `dynamicTruncate`)
- Manual case conversion (use `toSnakeCase`, `normalizeToolName`)
- Manual version parsing (use `opencode-version.ts` utilities)
- Raw permission checks (use `permission-compat.ts`)

8
src/tools/AGENTS.md
View File

@@ -1,7 +1,7 @@
# TOOLS KNOWLEDGE BASE
## OVERVIEW
Custom tools extending agent capabilities: LSP (11 tools), AST-aware search/replace, background tasks, and multimodal analysis.
Custom tools extending agent capabilities: LSP (7 tools), AST-aware search/replace, background tasks, and multimodal analysis.
## STRUCTURE
```
@@ -20,11 +20,11 @@ tools/
│ ├── tools.ts # Tool implementations
│ └── config.ts, types.ts, utils.ts
├── session-manager/ # OpenCode session history management
├── sisyphus-task/ # Category-based delegation (583 lines)
├── sisyphus-task/ # Category-based delegation (667 lines)
├── skill/ # Skill loading/execution
├── skill-mcp/ # Skill-embedded MCP invocation
├── slashcommand/ # Slash command execution
└── index.ts # builtinTools export (82 lines)
└── index.ts # builtinTools export (75 lines)
```
## TOOL CATEGORIES
@@ -46,7 +46,7 @@ tools/
## LSP SPECIFICS
- **Lifecycle**: Lazy initialization on first call; auto-shutdown on idle.
- **Config**: Merges `opencode.json` and `oh-my-opencode.json`.
- **Capability**: Supports full LSP spec including `codeAction/resolve` and `prepareRename`.
- **Capability**: Supports full LSP spec including `rename` and `prepareRename`.
## AST-GREP SPECIFICS
- **Precision**: Uses tree-sitter for structural matching (avoids regex pitfalls).