docs: refresh user-facing guide + reference for current code state
Audit pass against root AGENTS.md (regenerated 2026-05-08) and the canonical sources in src/shared/model-requirements.ts, src/features/team-mode/, src/cli/, src/config/schema/. Each touched file keeps its existing tone but corrects stale facts: - guide/overview.md: project name + dual-package transition reality - guide/installation.md: bun-only invocation, dual oh-my-openagent / oh-my-opencode CLI surface, current doctor categories - guide/orchestration.md: 11 agents, category routing through sisyphus-junior, background concurrency, team-mode link - guide/agent-model-matching.md: Metis primary -> claude-sonnet-4-6 (matches src/shared/model-requirements.ts fallback chain) - guide/team-mode.md: full schema, member eligibility tiers, 12 team_* tools added when enabled - reference/cli.md: trim to current Commander surface (install, doctor, run, mcp-oauth, refresh-model-capabilities, get-local-version) - reference/configuration.md: trim to schema-driven reference, JSONC rules, multi-level merge order, mcp_env_allowlist user-only constraint - reference/features.md: 5-tier hook composition counts, 3-tier MCPs, hashline edit, IntentGate, OpenClaw bidirectional dispatcher Cross-cutting: every `oh-my-opencode.schema.json` URL replaced with the canonical `oh-my-openagent.schema.json` (legacy package name in text bodies preserved where it documents the dual-publish transition).
This commit is contained in:
YeonGyu-Kim
@@ -100,6 +100,17 @@ Parallel multi-agent coordination modeled after Claude Code's experimental Agent
|
||||
|
||||
See the **[Team Mode Guide](../guide/team-mode.md)** for configuration, team spec format, lifecycle, bounds, and storage layout.
|
||||
|
||||
### Architecture Snapshot (current)
|
||||
|
||||
- **Feature modules**: `src/features/` has 20 modules.
|
||||
- **Tool system**: `src/tools/` has 16 tool directories that produce **20 to 39 tools** depending on config gates.
|
||||
- **Hook system**: 5-tier composition is **52 base hooks**. With team mode it becomes **59** (extra tool guard + transforms + direct team session event handlers).
|
||||
- **MCP system**: 3 tiers: built-in remote MCPs (`websearch`, `context7`, `grep_app`), `.mcp.json` loader, and skill-embedded MCP from `SKILL.md` frontmatter.
|
||||
- **Managers**: plugin startup creates 4 managers: TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler.
|
||||
- **Config pipeline**: 6 phases in order: provider, plugin-components, agents, tools, MCPs, commands.
|
||||
- **Canonical core agent order**: Sisyphus, Hephaestus, Prometheus, Atlas.
|
||||
- **OpenClaw**: bidirectional integrations for Discord, Telegram, HTTP, and shell with reply listener daemon.
|
||||
|
||||
## Category System
|
||||
|
||||
A Category is an agent configuration preset optimized for specific domains. Instead of delegating everything to a single AI agent, it is far more efficient to invoke specialists tailored to the nature of the task.
|
||||
@@ -222,6 +233,11 @@ Configure per-agent fallback chains with arrays that can mix plain model strings
|
||||
|
||||
When a model errors, the runtime can move through the configured fallback array. Object entries let you tune the backup model itself instead of only swapping the model name.
|
||||
|
||||
The plugin uses two independent fallback systems:
|
||||
|
||||
- **model-fallback**: proactive model chain selection in chat params.
|
||||
- **runtime-fallback**: reactive recovery after runtime failures from provider/API behavior.
|
||||
|
||||
### File-Based Prompts
|
||||
|
||||
Load agent system prompts from external files using `file://` URLs in the `prompt` field, or append additional content with `prompt_append`. The `prompt_append` field also works on categories.
|
||||
@@ -394,6 +410,8 @@ This content will be injected into the agent's system prompt.
|
||||
|
||||
Same-named skill at higher priority overrides lower.
|
||||
|
||||
Loaded skill display priority follows this order: `project > user > opencode > builtin/plugin`.
|
||||
|
||||
Disable built-in skills via `disabled_skills: ["playwright"]` in config.
|
||||
|
||||
### Category + Skill Combo Strategies
|
||||
@@ -561,6 +579,8 @@ Load custom commands from:
|
||||
|
||||
## Tools
|
||||
|
||||
Tool registration is config-gated. `src/tools/` has 16 directories, and exposed tools range from **20 minimum to 39 maximum**.
|
||||
|
||||
### Code Search Tools
|
||||
|
||||
| Tool | Description |
|
||||
@@ -572,7 +592,9 @@ Load custom commands from:
|
||||
|
||||
| Tool | Description |
|
||||
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **edit** | Hash-anchored edit tool. Uses `LINE#ID` format for precise, safe modifications. Validates content hashes before applying changes — zero stale-line errors. |
|
||||
| **edit** | Hash-anchored edit tool. Uses `LINE#ID` format for precise, safe modifications. Validates content hashes before applying changes and rejects stale hash edits. |
|
||||
|
||||
Hashline IDs use characters from `ZPMQVRWSNKTXJBYH`.
|
||||
|
||||
### LSP Tools (IDE Features for Agents)
|
||||
|
||||
@@ -725,6 +747,16 @@ interactive_bash(tmux_command="capture-pane -p -t dev-app")
|
||||
|
||||
Hooks intercept and modify behavior at key points in the agent lifecycle across the full session, message, tool, and parameter pipeline.
|
||||
|
||||
Current composition counts:
|
||||
|
||||
- Session: 24
|
||||
- Tool Guard: 14
|
||||
- Transform: 5
|
||||
- Continuation: 7
|
||||
- Skill: 2
|
||||
- Total base: 52
|
||||
- With `team_mode.enabled`: +1 Tool Guard, +2 Transform, +4 direct team session event handlers in `src/plugin/event.ts` = 59
|
||||
|
||||
### Hook Events
|
||||
|
||||
| Event | When | Can |
|
||||
@@ -753,7 +785,7 @@ Hooks intercept and modify behavior at key points in the agent lifecycle across
|
||||
|
||||
| Hook | Event | Description |
|
||||
| --------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **keyword-detector** | Message + Transform | Detects keywords and activates modes: `ultrawork`/`ulw` (max performance), `search`/`find` (parallel exploration), `analyze`/`investigate` (deep analysis). |
|
||||
| **keyword-detector** | Message + Transform | IntentGate detector. Activates `ultrawork`/`ulw`, `search`, `analyze`, and `team` modes from message keywords. |
|
||||
| **think-mode** | Params | Auto-detects extended thinking needs. Catches "think deeply", "ultrathink" and adjusts model settings. |
|
||||
| **ralph-loop** | Event + Message | Manages self-referential loop continuation. |
|
||||
| **start-work** | Message | Handles /start-work command execution. |
|
||||
@@ -766,7 +798,7 @@ Hooks intercept and modify behavior at key points in the agent lifecycle across
|
||||
|
||||
| Hook | Event | Description |
|
||||
| ------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| **comment-checker** | PostToolUse | Reminds agents to reduce excessive comments. Smartly ignores BDD, directives, docstrings. |
|
||||
| **comment-checker** | PostToolUse | Runs `@code-yeongyu/comment-checker` to block AI-slop comment patterns. Bypass options: `// @allow` for a line, `// comment-checker-disable-file` at file top. |
|
||||
| **thinking-block-validator** | Transform | Validates thinking blocks to prevent API errors. |
|
||||
| **edit-error-recovery** | PostToolUse + Event | Recovers from edit tool failures. |
|
||||
| **write-existing-file-guard** | PreToolUse | Prevents accidental overwrites of existing files without reading them first. |
|
||||
@@ -869,6 +901,12 @@ Disable specific hooks in config:
|
||||
|
||||
## MCPs
|
||||
|
||||
The plugin uses a three-tier MCP architecture:
|
||||
|
||||
1. Built-in remote MCPs from `src/mcp/`
|
||||
2. Claude Code `.mcp.json` loader with `${VAR}` expansion
|
||||
3. Skill-embedded MCP servers declared in `SKILL.md` frontmatter
|
||||
|
||||
### Built-in MCPs
|
||||
|
||||
| MCP | Description |
|
||||
@@ -893,6 +931,8 @@ mcp:
|
||||
|
||||
The `skill_mcp` tool invokes these operations with full schema discovery.
|
||||
|
||||
Skill MCP clients are isolated per session by key `${sessionID}:${skillName}:${serverName}`.
|
||||
|
||||
#### OAuth-Enabled MCPs
|
||||
|
||||
Skills can define OAuth-protected remote MCP servers. OAuth 2.1 with full RFC compliance (RFC 9728, 8414, 8707, 7591) is supported:
|
||||
|
||||
Reference in New Issue
Block a user