Skip to content

Commit 5412578

Browse files
code-yeongyucode-yeongyu
committed
docs: regenerate AGENTS.md hierarchy via init-deep
🤖 Generated with assistance of OhMyOpenCode (https://github.com/code-yeongyu/oh-my-opencode)
1 parent 502e9f5 commit 5412578

File tree

3 files changed

+198
-5
lines changed

3 files changed

+198
-5
lines changed

‎AGENTS.md‎

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

3-
**Generated:** 2025-12-28T19:26:00+09:00
4-
**Commit:** 122e918
3+
**Generated:** 2025-12-31T14:05:00+09:00
4+
**Commit:** 502e9f5
55
**Branch:** dev
66

77
## OVERVIEW
@@ -20,7 +20,8 @@ oh-my-opencode/
2020
│ ├── features/ # Claude Code compatibility - see src/features/AGENTS.md
2121
│ ├── config/ # Zod schema, TypeScript types
2222
│ ├── auth/ # Google Antigravity OAuth (antigravity/)
23-
│ ├── shared/ # Utilities: deep-merge, pattern-matcher, logger, etc.
23+
│ ├── shared/ # Utilities: deep-merge, pattern-matcher, logger, etc. - see src/shared/AGENTS.md
24+
│ ├── cli/ # CLI installer, doctor, run - see src/cli/AGENTS.md
2425
│ └── index.ts # Main plugin entry (OhMyOpenCodePlugin)
2526
├── script/ # build-schema.ts, publish.ts, generate-changelog.ts
2627
├── assets/ # JSON schema
@@ -34,14 +35,17 @@ oh-my-opencode/
3435
| Add agent | `src/agents/` | Create .ts, add to builtinAgents in index.ts, update types.ts |
3536
| Add hook | `src/hooks/` | Create dir with createXXXHook(), export from index.ts |
3637
| Add tool | `src/tools/` | Dir with index/types/constants/tools.ts, add to builtinTools |
37-
| Add MCP | `src/mcp/` | Create config, add to index.ts |
38+
| Add MCP | `src/mcp/` | Create config, add to index.ts and types.ts |
3839
| LSP behavior | `src/tools/lsp/` | client.ts (connection), tools.ts (handlers) |
3940
| AST-Grep | `src/tools/ast-grep/` | napi.ts for @ast-grep/napi binding |
4041
| Google OAuth | `src/auth/antigravity/` | OAuth plugin for Google models |
4142
| Config schema | `src/config/schema.ts` | Zod schema, run `bun run build:schema` after changes |
4243
| Claude Code compat | `src/features/claude-code-*-loader/` | Command, skill, agent, mcp loaders |
4344
| Background agents | `src/features/background-agent/` | manager.ts for task management |
4445
| Interactive terminal | `src/tools/interactive-bash/` | tmux session management |
46+
| CLI installer | `src/cli/install.ts` | Interactive TUI installation |
47+
| Doctor checks | `src/cli/doctor/checks/` | Health checks for environment |
48+
| Shared utilities | `src/shared/` | Cross-cutting utilities |
4549

4650
## CONVENTIONS
4751

@@ -64,6 +68,8 @@ oh-my-opencode/
6468
- **Year 2024**: NEVER use 2024 in code/prompts (use current year)
6569
- **Rush completion**: Never mark tasks complete without verification
6670
- **Over-exploration**: Stop searching when sufficient context found
71+
- **High temperature**: Don't use >0.3 for code-related agents
72+
- **Broad tool access**: Prefer explicit `include` over unrestricted access
6773

6874
## UNIQUE STYLES
6975

@@ -109,8 +115,19 @@ bun test # Run tests
109115

110116
## CI PIPELINE
111117

112-
- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master
118+
- **ci.yml**: Parallel test/typecheck, build verification, auto-commit schema on master, rolling `next` draft release
113119
- **publish.yml**: Manual workflow_dispatch, version bump, changelog, OIDC npm publish
120+
- **sisyphus-agent.yml**: Agent-in-CI for automated issue handling via `@sisyphus-dev-ai` mentions
121+
122+
## COMPLEXITY HOTSPOTS
123+
124+
| File | Lines | Description |
125+
|------|-------|-------------|
126+
| `src/index.ts` | 690 | Main plugin orchestration, all hook/tool initialization |
127+
| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 670 | Session compaction, multi-stage recovery pipeline |
128+
| `src/cli/config-manager.ts` | 669 | JSONC parsing, environment detection, installation |
129+
| `src/auth/antigravity/fetch.ts` | 621 | Token refresh, URL rewriting, endpoint fallbacks |
130+
| `src/tools/lsp/client.ts` | 611 | LSP protocol, stdin/stdout buffering, JSON-RPC |
114131

115132
## NOTES
116133

@@ -119,3 +136,4 @@ bun test # Run tests
119136
- **Multi-lang docs**: README.md (EN), README.ko.md (KO), README.ja.md (JA), README.zh-cn.md (ZH-CN)
120137
- **Config**: `~/.config/opencode/oh-my-opencode.json` (user) or `.opencode/oh-my-opencode.json` (project)
121138
- **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
139+
- **JSONC support**: Config files support comments (`// comment`, `/* block */`) and trailing commas

‎src/cli/AGENTS.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# CLI KNOWLEDGE BASE
2+
3+
## OVERVIEW
4+
5+
Command-line interface for oh-my-opencode. Interactive installer, health diagnostics (doctor), and runtime commands. Entry point: `bunx oh-my-opencode`.
6+
7+
## STRUCTURE
8+
9+
```
10+
cli/
11+
├── index.ts # Commander.js entry point, subcommand routing
12+
├── install.ts # Interactive TUI installer
13+
├── config-manager.ts # Config detection, parsing, merging (669 lines)
14+
├── types.ts # CLI-specific types
15+
├── doctor/ # Health check system
16+
│ ├── index.ts # Doctor command entry
17+
│ ├── constants.ts # Check categories, descriptions
18+
│ ├── types.ts # Check result interfaces
19+
│ └── checks/ # 17 individual health checks
20+
├── get-local-version/ # Version detection utility
21+
│ ├── index.ts
22+
│ └── formatter.ts
23+
└── run/ # OpenCode session launcher
24+
├── index.ts
25+
└── completion.test.ts
26+
```
27+
28+
## CLI COMMANDS
29+
30+
| Command | Purpose | Key File |
31+
|---------|---------|----------|
32+
| `install` | Interactive setup wizard | `install.ts` |
33+
| `doctor` | Environment health checks | `doctor/index.ts` |
34+
| `run` | Launch OpenCode session | `run/index.ts` |
35+
36+
## DOCTOR CHECKS
37+
38+
17 checks in `doctor/checks/`:
39+
40+
| Check | Validates |
41+
|-------|-----------|
42+
| `version.ts` | OpenCode version >= 1.0.150 |
43+
| `config.ts` | Plugin registered in opencode.json |
44+
| `bun.ts` | Bun runtime available |
45+
| `node.ts` | Node.js version compatibility |
46+
| `git.ts` | Git installed |
47+
| `anthropic-auth.ts` | Claude authentication |
48+
| `openai-auth.ts` | OpenAI authentication |
49+
| `google-auth.ts` | Google/Gemini authentication |
50+
| `lsp-*.ts` | Language server availability |
51+
| `mcp-*.ts` | MCP server connectivity |
52+
53+
## INSTALLATION FLOW
54+
55+
1. **Detection**: Find existing `opencode.json` / `opencode.jsonc`
56+
2. **TUI Prompts**: Claude subscription? ChatGPT? Gemini?
57+
3. **Config Generation**: Build `oh-my-opencode.json` based on answers
58+
4. **Plugin Registration**: Add to `plugin` array in opencode.json
59+
5. **Auth Guidance**: Instructions for `opencode auth login`
60+
61+
## CONFIG-MANAGER
62+
63+
The largest file (669 lines) handles:
64+
65+
- **JSONC support**: Parses comments and trailing commas
66+
- **Multi-source detection**: User (~/.config/opencode/) + Project (.opencode/)
67+
- **Schema validation**: Zod-based config validation
68+
- **Migration**: Handles legacy config formats
69+
- **Error collection**: Aggregates parsing errors for doctor
70+
71+
## HOW TO ADD A DOCTOR CHECK
72+
73+
1. Create `src/cli/doctor/checks/my-check.ts`:
74+
```typescript
75+
import type { DoctorCheck } from "../types"
76+
77+
export const myCheck: DoctorCheck = {
78+
name: "my-check",
79+
category: "environment",
80+
check: async () => {
81+
// Return { status: "pass" | "warn" | "fail", message: string }
82+
}
83+
}
84+
```
85+
2. Add to `src/cli/doctor/checks/index.ts`
86+
3. Update `constants.ts` if new category
87+
88+
## ANTI-PATTERNS (CLI)
89+
90+
- **Blocking prompts in non-TTY**: Check `process.stdout.isTTY` before TUI
91+
- **Hardcoded paths**: Use shared utilities for config paths
92+
- **Ignoring JSONC**: User configs may have comments
93+
- **Silent failures**: Doctor checks must return clear status/message

‎src/shared/AGENTS.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# SHARED UTILITIES KNOWLEDGE BASE
2+
3+
## OVERVIEW
4+
5+
Cross-cutting utility functions used across agents, hooks, tools, and features. Path resolution, config management, text processing, and Claude Code compatibility helpers.
6+
7+
## STRUCTURE
8+
9+
```
10+
shared/
11+
├── index.ts # Barrel export (import { x } from "../shared")
12+
├── claude-config-dir.ts # Resolve ~/.claude directory
13+
├── command-executor.ts # Shell command execution with variable expansion
14+
├── config-errors.ts # Global config error tracking
15+
├── config-path.ts # User/project config path resolution
16+
├── data-path.ts # XDG data directory resolution
17+
├── deep-merge.ts # Type-safe recursive object merging
18+
├── dynamic-truncator.ts # Token-aware output truncation
19+
├── file-reference-resolver.ts # @filename syntax resolution
20+
├── file-utils.ts # Symlink resolution, markdown detection
21+
├── frontmatter.ts # YAML frontmatter parsing
22+
├── hook-disabled.ts # Check if hook is disabled in config
23+
├── jsonc-parser.ts # JSON with Comments parsing
24+
├── logger.ts # File-based logging to OS temp
25+
├── migration.ts # Legacy name compatibility (omo -> Sisyphus)
26+
├── model-sanitizer.ts # Normalize model names
27+
├── pattern-matcher.ts # Tool name matching with wildcards
28+
├── snake-case.ts # Case conversion for objects
29+
└── tool-name.ts # Normalize tool names to PascalCase
30+
```
31+
32+
## UTILITY CATEGORIES
33+
34+
| Category | Utilities | Used By |
35+
|----------|-----------|---------|
36+
| Path Resolution | `getClaudeConfigDir`, `getUserConfigPath`, `getProjectConfigPath`, `getDataDir` | Features, Hooks |
37+
| Config Management | `deepMerge`, `parseJsonc`, `isHookDisabled`, `configErrors` | index.ts, CLI |
38+
| Text Processing | `resolveCommandsInText`, `resolveFileReferencesInText`, `parseFrontmatter` | Commands, Rules |
39+
| Output Control | `dynamicTruncate` | Tools (Grep, LSP) |
40+
| Normalization | `transformToolName`, `objectToSnakeCase`, `sanitizeModelName` | Hooks, Agents |
41+
| Compatibility | `migration.ts` | Config loading |
42+
43+
## WHEN TO USE WHAT
44+
45+
| Task | Utility | Notes |
46+
|------|---------|-------|
47+
| Find Claude Code configs | `getClaudeConfigDir()` | Never hardcode `~/.claude` |
48+
| Merge settings (default → user → project) | `deepMerge(base, override)` | Arrays replaced, objects merged |
49+
| Parse user config files | `parseJsonc()` | Supports comments and trailing commas |
50+
| Check if hook should run | `isHookDisabled(name, disabledHooks)` | Respects `disabled_hooks` config |
51+
| Truncate large tool output | `dynamicTruncate(text, budget, reserved)` | Token-aware, prevents overflow |
52+
| Resolve `@file` references | `resolveFileReferencesInText()` | maxDepth=3 prevents infinite loops |
53+
| Execute shell commands | `resolveCommandsInText()` | Supports `!`\`command\`\` syntax |
54+
| Handle legacy agent names | `migrateLegacyAgentNames()` | `omo` → `Sisyphus` |
55+
56+
## CRITICAL PATTERNS
57+
58+
### Dynamic Truncation
59+
```typescript
60+
import { dynamicTruncate } from "../shared"
61+
// Keep 50% headroom, max 50k tokens
62+
const output = dynamicTruncate(result, remainingTokens, 0.5)
63+
```
64+
65+
### Deep Merge Priority
66+
```typescript
67+
const final = deepMerge(defaults, userConfig)
68+
final = deepMerge(final, projectConfig) // Project wins
69+
```
70+
71+
### Safe JSONC Parsing
72+
```typescript
73+
const { config, error } = parseJsoncSafe(content)
74+
if (error) return fallback
75+
```
76+
77+
## ANTI-PATTERNS (SHARED)
78+
79+
- **Hardcoding paths**: Use `getClaudeConfigDir()`, `getUserConfigPath()`
80+
- **Manual JSON.parse**: Use `parseJsonc()` for user files (comments allowed)
81+
- **Ignoring truncation**: Large outputs MUST use `dynamicTruncate`
82+
- **Direct string concat for configs**: Use `deepMerge` for proper priority

0 commit comments

Comments
 (0)