Files

T

YeonGyu-Kim 330e437f08 docs(agents): regenerate hierarchical AGENTS.md for 2026-05-20

Sync the AGENTS.md hierarchy to current code state:

Drift fixes in 11 existing files
- Root: 2026-05-20 commit 39aadbf9f, ~2167 TS files, 120 barrel index.ts,
  57 src/hooks dirs, 297 (179 non-test) src/shared files, 11 OpenCode hook
  handlers in plugin-interface.ts, packages list adds ast-grep-mcp + rules-core,
  first-prompt-watchdog 206 LOC, parent-wake-notifier 587 LOC
- src/AGENTS.md: file counts, plugin-interface handler count
- src/shared/AGENTS.md: title + counts 278/170 -> 297/179
- src/hooks/AGENTS.md: 57 dirs, note unwired WIP (task-reminder,
  hashline-edit-diff-enhancer)
- src/features/AGENTS.md: module map with NON-TEST counts + sub-AGENTS.md
  column, 7 modules without sub-doc
- src/features/background-agent/AGENTS.md: add 12 newer files (parent-wake-
  notifier 587 LOC, loop-detector, error-classifier, fallback-retry-handler,
  process-cleanup, subagent-spawn-limits, session-status-classifier,
  compaction-aware-message-resolver, etc.)
- src/plugin/AGENTS.md: 11 handlers, add system-transform.ts + command-
  execute-before.ts + build-team-idle-wake-hint-client.ts
- src/config/AGENTS.md: note schema/internal/permission.ts
- src/cli/AGENTS.md: 8 commands including 'version'
- src/plugin-handlers/AGENTS.md, packages/web/AGENTS.md: date bump

New AGENTS.md in 4 directories
- packages/AGENTS.md: index of 15 packages (11 platform binaries + 2 MCP
  packages + rules-core + web), role map, conventions
- docs/AGENTS.md: WHERE TO LOOK table for 19 docs across 6 subdirs
- .opencode/AGENTS.md: 5 skills + 4 slash commands + relationship to .agents/
- .agents/AGENTS.md: superset migration target (9 skills + 4 commands)

2026-05-20 17:18:44 +09:00

4.9 KiB

Raw Blame History

docs/ — User-Facing Documentation

Generated: 2026-05-20

OVERVIEW

19 Markdown files across 6 subdirectories + 2 root files. Categorized by audience: user-facing guides + reference, internal design docs (superpowers/), troubleshooting, legal. The web site at packages/web/ consumes some of these (via web-deploy.yml triggers).

WHERE TO LOOK

Audience / Task	Location
New users — what is this?	docs/guide/overview.md
Installing the plugin	docs/guide/installation.md
How agents collaborate	docs/guide/orchestration.md
Picking the right model per agent	docs/guide/agent-model-matching.md
Team Mode (opt-in multi-agent)	docs/guide/team-mode.md
Configuration field reference	docs/reference/configuration.md
Feature-by-feature reference	docs/reference/features.md
CLI command reference	docs/reference/cli.md
Known issues & workarounds	docs/reference/known-issues.md
`prompt_async_gate` deep-dive	docs/reference/prompt-async-gate-rfc.md
Release process	docs/reference/release-process.md
Rules-injector cross-module comparison	docs/reference/rules-injection-cross-module-comparison.md
Sample configs	docs/examples/ (default, coding-focused, planning-focused)
Privacy & ToS	docs/legal/
Manifesto	docs/manifesto.md
Ollama troubleshooting	docs/troubleshooting/ollama.md
Internal design plans/specs	docs/superpowers/plans/ + docs/superpowers/specs/

STRUCTURE

docs/
├── manifesto.md                              # The "why" — referenced from README
├── model-capabilities-maintenance.md         # How model-capabilities cache is refreshed
├── guide/                                    # User-facing tutorial-style guides (5 files)
├── reference/                                # API / config / CLI reference (7 files)
├── examples/                                 # Sample JSONC configs (3 files)
├── legal/                                    # privacy-policy.md + terms-of-service.md
├── superpowers/
│   ├── plans/                                # In-flight design plans (model-settings, background-task-retry, log-rotation)
│   └── specs/                                # Frozen design specs (model-settings-compatibility, background-task-retry-timeline)
└── troubleshooting/
    └── ollama.md

CONVENTIONS

User-facing language only in guide/ and reference/. No OmO internal jargon without explanation.
superpowers/ is internal. Design docs, plans, RFCs. Outside readers should not be expected to follow these.
Path links use the file:// scheme so OpenCode renders them in TUI. Use absolute paths.
No HTML. Markdown only. No <details> / <summary> (causes rendering issues in some terminals).
Code blocks use language fences. Use jsonc for config snippets to preserve comments.
Docs touching packages/web/ re-trigger the web CI via web-ci.yml.

ANTI-PATTERNS

Never add a doc to guide/ or reference/ without a WHERE TO LOOK entry above.
Never paste agent-facing system prompts here. Those live in src/agents/ or src/features/builtin-skills/.
Never document changing config keys without also updating src/config/schema/ and re-running bun run build:schema.

4.9 KiB Raw Blame History