From 330e437f08b68c194a383953a31848810e6c7957 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Wed, 20 May 2026 17:18:44 +0900 Subject: [PATCH] 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) --- .agents/AGENTS.md | 60 ++++++++++++++++++++++++ .opencode/AGENTS.md | 49 ++++++++++++++++++++ AGENTS.md | 22 ++++----- docs/AGENTS.md | 61 +++++++++++++++++++++++++ packages/AGENTS.md | 57 +++++++++++++++++++++++ packages/web/AGENTS.md | 2 +- src/AGENTS.md | 10 ++-- src/cli/AGENTS.md | 9 ++-- src/config/AGENTS.md | 4 +- src/features/AGENTS.md | 55 +++++++++++----------- src/features/background-agent/AGENTS.md | 22 +++++++-- src/hooks/AGENTS.md | 8 ++-- src/plugin-handlers/AGENTS.md | 2 +- src/plugin/AGENTS.md | 13 ++++-- src/shared/AGENTS.md | 4 +- 15 files changed, 314 insertions(+), 64 deletions(-) create mode 100644 .agents/AGENTS.md create mode 100644 .opencode/AGENTS.md create mode 100644 docs/AGENTS.md create mode 100644 packages/AGENTS.md diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md new file mode 100644 index 000000000..23b844492 --- /dev/null +++ b/.agents/AGENTS.md @@ -0,0 +1,60 @@ +# .agents/ — Project-Scope Skills & Commands (Migration Target) + +**Generated:** 2026-05-20 + +## OVERVIEW + +Project-scope skills + slash commands under the new `.agents/` directory name. During the `oh-my-opencode` → `oh-my-openagent` rename transition, this directory is the **target** of the migration from `.opencode/`. It is a strict SUPERSET of `.opencode/` (5 → 9 skills; same 4 commands). + +Loaded alongside `.opencode/` by [`src/features/opencode-skill-loader/`](file:///Users/yeongyu/local-workspaces/omo/src/features/opencode-skill-loader/). When both directories declare the same skill or command name, the higher-priority scope wins per the loader's deduplication rules. + +## SKILLS (9, superset of `.opencode/`) + +| Skill | Also in `.opencode/`? | Purpose | +|-------|------------------------|---------| +| `work-with-pr/` | yes | Full PR lifecycle | +| `work-with-pr-workspace/` | yes | Iteration workspace + benchmark inputs | +| `github-triage/` | yes | Read-only issue/PR triage with evidence reports | +| `hyperplan/` | yes | Adversarial multi-agent planning | +| `pre-publish-review/` | yes | 16-agent pre-publish release gate | +| `get-unpublished-changes/` | NEW | Skill form of the `/get-unpublished-changes` command | +| `omomomo/` | NEW | Skill form of the `/omomomo` easter egg | +| `publish/` | NEW | Skill form of the `/publish` command | +| `remove-deadcode/` | NEW | Skill form of the `/remove-deadcode` command | + +The 4 "NEW" skills here are skill-format equivalents of the 4 slash commands that exist in BOTH `.opencode/command/` and `.agents/command/`. They allow the same instructions to be triggered either by an explicit `/command` invocation OR by skill auto-loading on matching prompts. + +## COMMANDS (4 slash commands) + +Identical set to `.opencode/command/`: +- `/get-unpublished-changes` +- `/omomomo` +- `/publish` +- `/remove-deadcode` + +## OTHER CONTENTS + +- `background-tasks.json` — Runtime state (parallel to `.opencode/background-tasks.json` during the transition). +- `bun.lock`, `package.json`, `node_modules/` — Skill dependencies. +- `.gitignore` — Local scope ignore. + +## MIGRATION STATUS + +| Concern | Plan | +|---------|------| +| Why TWO directories? | `.opencode/` is the legacy layout. `.agents/` is the future-proof name after the harness rename. | +| When does `.opencode/` go away? | After the multi-harness refactor lands and existing users have re-installed. Tracked in [ROADMAP](file:///Users/yeongyu/local-workspaces/omo/ROADMAP.md). | +| What if both exist with conflicting skills? | The skill-loader dedupes by name. Higher-priority scope wins. The 5 shared skills (`work-with-pr`, `hyperplan`, etc.) are byte-identical between the two dirs today; if they diverge, fix here first. | +| Where do NEW skills go? | `.agents/` only. Do NOT add new entries to `.opencode/`. | + +## CONVENTIONS + +- **All NEW skills go in `.agents/`.** `.opencode/` is frozen aside from drift-sync of the 5 shared skills. +- **Drift between shared skills is a bug.** When you update a shared skill, update both copies in the SAME commit until `.opencode/` is removed. +- **Slash commands stay duplicated.** Both directories must contain the same `command/*.md` set for the transition window. + +## ANTI-PATTERNS + +- Never add a skill to `.opencode/` that does not also exist in `.agents/`. +- Never let the 5 shared skills drift. CI should eventually enforce byte equality; for now, manual diligence. +- Never delete `.opencode/` until the multi-harness refactor lands. diff --git a/.opencode/AGENTS.md b/.opencode/AGENTS.md new file mode 100644 index 000000000..f7497e49f --- /dev/null +++ b/.opencode/AGENTS.md @@ -0,0 +1,49 @@ +# .opencode/ — Project-Scope Skills & Commands + +**Generated:** 2026-05-20 + +## OVERVIEW + +Project-scope OpenCode configuration: 5 skills and 4 slash commands committed alongside the source. Picked up by [`src/features/opencode-skill-loader/`](file:///Users/yeongyu/local-workspaces/omo/src/features/opencode-skill-loader/) and the slash-command discovery pipeline. + +**Relationship to `.agents/`:** `.agents/` is the migration target during the `oh-my-opencode` → `oh-my-openagent` rename. It is a SUPERSET of `.opencode/` (mirrors all 5 skills + adds 4 more, mirrors the 4 commands). Both directories load during the transition; consumers should prefer `.agents/`. + +## SKILLS (5) + +| Skill | Purpose | +|-------|---------| +| `work-with-pr/` | Full PR lifecycle skill: worktree → implement → atomic commits → PR → verification loop → merge. | +| `work-with-pr-workspace/` | Iteration workspace for `work-with-pr` — captures benchmark inputs for the iteration-* subdirs. | +| `github-triage/` | Read-only triage of issues + PRs. 1 item = 1 background task. Writes evidence-backed reports. Never takes GitHub actions. | +| `hyperplan/` | Adversarial multi-agent planning. 5 hostile category members cross-critique, lead synthesizes. | +| `pre-publish-review/` | Nuclear-grade 16-agent pre-publish release gate. Runs `/get-unpublished-changes`, spawns ultrabrain agents per change, oracle for synthesis. | + +Each skill follows the standard layout (`SKILL.md` + optional `scripts/`, `references/`, `assets/`). + +## COMMANDS (4 slash commands) + +| Command | Purpose | +|---------|---------| +| `/get-unpublished-changes` | Compare HEAD with the latest published npm version and list unpublished changes. | +| `/omomomo` | Easter-egg command — about oh-my-opencode. | +| `/publish` | Publish via GitHub Actions workflow. Argument: ``. | +| `/remove-deadcode` | Remove unused code with LSP-verified safety + atomic commits. | + +## OTHER CONTENTS + +- `background-tasks.json` — Runtime state for active background tasks (gitignored from sensitive content but tracked structurally). +- `bun.lock`, `package.json`, `node_modules/` — Skill dependencies (some skills install their own packages). +- `.gitignore` — Local scope ignore patterns. + +## CONVENTIONS + +- **Skill YAML frontmatter is mandatory.** [`opencode-skill-loader`](file:///Users/yeongyu/local-workspaces/omo/src/features/opencode-skill-loader/) rejects skills without `name` + `description`. +- **Project-scope > user-scope.** A skill at `.opencode/skills/X/` overrides `~/.config/opencode/skills/X/` of the same name. +- **Trigger words** in the skill description determine when OpenCode loads the skill. Be specific. +- **Commands are user-visible.** Name them with a leading `/` (the loader normalizes filename → command). + +## ANTI-PATTERNS + +- Never duplicate a built-in skill from `src/features/builtin-skills/` here without a clear reason. +- Never commit `background-tasks.json` contents that include session IDs or token secrets. +- Never write a skill that calls `session.promptAsync` directly — go through `dispatchInternalPrompt` (see root AGENTS.md "Internal message injection is dangerous"). diff --git a/AGENTS.md b/AGENTS.md index 0bbe59a76..3c5e6bcf6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,11 +2,11 @@ > **HOLD THE FUCK UP. THIS ENTIRE GODDAMN CODEBASE IS BEING RIPPED APART AND REBUILT RIGHT NOW. A MASSIVE MULTI-HARNESS AGENT OS REFACTOR IS IN PROGRESS — WE ARE RESTRUCTURING EVERYTHING TO SUPPORT MULTIPLE AGENT HARNESSES (OPENCODE, CODEX, PI, AND OTHERS). DO NOT TRUST THE STRUCTURE BELOW AS STABLE. READ THE [ROADMAP](./ROADMAP.md) BEFORE YOU TOUCH ANYTHING OR SO HELP ME GOD.** -**Generated:** 2026-05-18 | **Commit:** 4d417a33b | **Branch:** dev | **Release:** v4.2.0 +**Generated:** 2026-05-20 | **Commit:** 39aadbf9f | **Branch:** dev | **Release:** v4.2.0 ## OVERVIEW -OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 54–61 lifecycle hooks (base / +team-mode) across 59 dirs, 20–39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), Boulder feature (boulder-state work tracking + cli/boulder subcommand), configurable agent ordering, and Claude Code compatibility. **Repository contains 2165 TypeScript files across `src/`, `script/`, `test-support/`, and `packages/web/`, ~314k LOC; `src/` itself has 122 barrel `index.ts` files.** Entry: `src/index.ts` is now an 18-line wrapper that delegates to `src/testing/create-plugin-module.ts` `createPluginModule()` → 7-step init. +OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 54–61 lifecycle hooks (base / +team-mode) across 57 dirs, 20–39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), Boulder feature (boulder-state work tracking + cli/boulder subcommand), configurable agent ordering, and Claude Code compatibility. **Repository contains ~2167 TypeScript files across `src/`, `script/`, `test-support/`, and `packages/web/`, ~313k LOC; `src/` itself has 120 barrel `index.ts` files.** Entry: `src/index.ts` is an 18-line wrapper that delegates to `src/testing/create-plugin-module.ts` `createPluginModule()` → 7-step init. ## STRUCTURE @@ -15,24 +15,24 @@ oh-my-opencode/ ├── src/ │ ├── index.ts # Plugin entry; thin wrapper that re-exports `createPluginModule()` from `src/testing/` │ ├── plugin-config.ts # JSONC multi-level config: user → project → defaults (Zod v4) -│ ├── plugin-interface.ts # 10 OpenCode hook handlers +│ ├── plugin-interface.ts # 11 OpenCode hook handlers (+2 wired in src/testing/create-plugin-module.ts) │ ├── create-managers.ts # 4 managers (Tmux, Background, SkillMcp, ConfigHandler) │ ├── create-tools.ts # ToolRegistry composition │ ├── create-hooks.ts # 5-tier hook composition │ ├── agents/ # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior) -│ ├── hooks/ # ~52 lifecycle hooks across 59 dirs (incl. 5 zauc-mocks + 1 shared + 1 `.sisyphus/` legacy state) +│ ├── hooks/ # ~52 lifecycle hooks across 57 dirs (incl. 5 zauc-mocks + 1 shared + 1 `.sisyphus/` legacy state + 1 `team-session-events/`; 2 unwired WIP: `task-reminder/`, `hashline-edit-diff-enhancer/`) │ ├── tools/ # 13 native tool dirs; LSP + AST-grep now served via built-in MCPs │ ├── features/ # 20 feature modules (incl. team-mode, background-agent, skill-mcp-manager, opencode-skill-loader, tmux-subagent, mcp-oauth, claude-code-plugin-loader, boulder-state, etc.) -│ ├── shared/ # 278 utility files (170 non-test); logger → oh-my-opencode.log in os.tmpdir() (50 MB cap, .1/.2 backups) +│ ├── shared/ # 297 utility files (179 non-test); logger → oh-my-opencode.log in os.tmpdir() (50 MB cap, .1/.2 backups) │ ├── config/ # Zod v4 schema system (30 schema files) │ ├── cli/ # CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version, boulder │ ├── mcp/ # 5 built-in MCPs (3 remote + local stdio lsp + ast_grep) -│ ├── plugin/ # 10 OpenCode hook handlers + 5-tier hook composition +│ ├── plugin/ # 11 OpenCode hook handlers + 5-tier hook composition │ ├── plugin-handlers/ # 6-phase config loading pipeline │ ├── openclaw/ # Bidirectional external integration (Discord/Telegram/HTTP/shell + reply listener daemon) │ ├── generated/ # model-capabilities.generated.json (refreshed via build:model-capabilities) │ └── testing/ # Test utilities + `create-plugin-module.ts` (extracted plugin entry factory, 182 LOC) -├── packages/ # 11 platform-specific binary packages, lsp-tools-mcp submodule, and web package +├── packages/ # 11 platform-specific binary packages + lsp-tools-mcp submodule + ast-grep-mcp + rules-core + web │ └── web/ # Marketing site (Next.js 15 + Cloudflare Workers). Independent package with own bun.lock ├── bin/ # Platform-detection JS shim (oh-my-opencode + oh-my-openagent) ├── script/ # Build/publish automation (singular, not scripts/) @@ -62,7 +62,7 @@ pluginModule.server(input, options) ├─→ createManagers() # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler ├─→ createTools() # SkillContext + AvailableCategories + ToolRegistry ├─→ createHooks() # 5-tier: Session + ToolGuard + Transform + Continuation + Skill - └─→ createPluginInterface() # 10 OpenCode hook handlers → PluginInterface + └─→ createPluginInterface() # 11 OpenCode hook handlers → PluginInterface ``` ## 13 OPENCODE HOOK HANDLERS @@ -269,7 +269,7 @@ bunx oh-my-opencode mcp-oauth login # Tier-3 MCP OAuth (PKCE + DCR - **Config migration:** idempotent via `_migrations` tracking, atomic writes with timestamped backups. - **Build:** `bun build` (ESM) + `tsc --emitDeclarationOnly`, externals: `@ast-grep/napi`, `zod`. - **CI tests:** root tests run through plain `bun test`; `packages/web/**` has its own package-level CI workflow. -- **122 barrel `index.ts` files** establish module boundaries. +- **120 barrel `index.ts` files** establish module boundaries. - **Architecture rules** enforced via the `rules-injector` hook reading `.omo/rules/*.md`. As of v4.2.0 only `test-discipline.md` ships; legacy `modular-code-enforcement.md` was retired. - **Windows builds:** run on `windows-latest` (not cross-compiled) to avoid Bun segfaults. - **Platform binaries:** detect AVX2 + libc family at runtime, fallback to baseline if needed. @@ -280,7 +280,7 @@ bunx oh-my-opencode mcp-oauth login # Tier-3 MCP OAuth (PKCE + DCR - **Docs:** see [`docs/guide/`](file:///Users/yeongyu/local-workspaces/omo/docs/guide/) for user-facing guides (overview, installation, orchestration, agent-model-matching, team-mode), [`docs/reference/`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/) for CLI/configuration/features reference. v4.2.0+ adds [`CHANGELOG.md`](file:///Users/yeongyu/local-workspaces/omo/CHANGELOG.md), [`docs/reference/known-issues.md`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/known-issues.md), [`docs/reference/prompt-async-gate-rfc.md`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/prompt-async-gate-rfc.md), and [`docs/reference/release-process.md`](file:///Users/yeongyu/local-workspaces/omo/docs/reference/release-process.md). - **Rules files** (auto-injected by `rules-injector` hook): [`.omo/rules/modular-code-enforcement.md`](file:///Users/yeongyu/local-workspaces/omo/.omo/rules/modular-code-enforcement.md) + [`.omo/rules/test-discipline.md`](file:///Users/yeongyu/local-workspaces/omo/.omo/rules/test-discipline.md) (forbids `setTimeout(resolve, N)` / `await sleep(N)` in tests unless time IS the SUT). Scans `.omo/rules/`, `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, plus `.github/copilot-instructions.md` and `.mdc` files. - **Process cleanup:** Background-agent error handlers are now log-only — no force-exit on transient errors. Opt out entirely via `OMO_DISABLE_PROCESS_CLEANUP=1` env var. -- **First-prompt watchdog:** `src/hooks/runtime-fallback/first-prompt-watchdog.ts` (193 LOC) detects subagent sessions producing no progress within 90s and triggers fallback / abort. -- **ParentWakeNotifier:** Background-agent parent-wake state extracted to `src/features/background-agent/parent-wake-notifier.ts` (432 LOC) with dependency-injected client and enqueue callback. +- **First-prompt watchdog:** `src/hooks/runtime-fallback/first-prompt-watchdog.ts` (206 LOC) detects subagent sessions producing no progress within 90s and triggers fallback / abort. +- **ParentWakeNotifier:** Background-agent parent-wake state extracted to `src/features/background-agent/parent-wake-notifier.ts` (587 LOC) with dependency-injected client and enqueue callback. - **Workspace migration:** Runtime state migrated from `.sisyphus/` → `.omo/`. Legacy `.sisyphus/` still exists during transition; `src/shared/legacy-workspace-migration.ts` copies it forward on first load. - **CI nuance:** PRs targeting `master` are hard-blocked — they MUST target `dev`. CI auto-commits schema changes on master push and creates a draft "next" release on dev push. diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 000000000..a16a715f7 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,61 @@ +# 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/](file:///Users/yeongyu/local-workspaces/omo/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](file:///Users/yeongyu/local-workspaces/omo/docs/guide/overview.md) | +| Installing the plugin | [docs/guide/installation.md](file:///Users/yeongyu/local-workspaces/omo/docs/guide/installation.md) | +| How agents collaborate | [docs/guide/orchestration.md](file:///Users/yeongyu/local-workspaces/omo/docs/guide/orchestration.md) | +| Picking the right model per agent | [docs/guide/agent-model-matching.md](file:///Users/yeongyu/local-workspaces/omo/docs/guide/agent-model-matching.md) | +| Team Mode (opt-in multi-agent) | [docs/guide/team-mode.md](file:///Users/yeongyu/local-workspaces/omo/docs/guide/team-mode.md) | +| Configuration field reference | [docs/reference/configuration.md](file:///Users/yeongyu/local-workspaces/omo/docs/reference/configuration.md) | +| Feature-by-feature reference | [docs/reference/features.md](file:///Users/yeongyu/local-workspaces/omo/docs/reference/features.md) | +| CLI command reference | [docs/reference/cli.md](file:///Users/yeongyu/local-workspaces/omo/docs/reference/cli.md) | +| Known issues & workarounds | [docs/reference/known-issues.md](file:///Users/yeongyu/local-workspaces/omo/docs/reference/known-issues.md) | +| `prompt_async_gate` deep-dive | [docs/reference/prompt-async-gate-rfc.md](file:///Users/yeongyu/local-workspaces/omo/docs/reference/prompt-async-gate-rfc.md) | +| Release process | [docs/reference/release-process.md](file:///Users/yeongyu/local-workspaces/omo/docs/reference/release-process.md) | +| Rules-injector cross-module comparison | [docs/reference/rules-injection-cross-module-comparison.md](file:///Users/yeongyu/local-workspaces/omo/docs/reference/rules-injection-cross-module-comparison.md) | +| Sample configs | [docs/examples/](file:///Users/yeongyu/local-workspaces/omo/docs/examples/) (default, coding-focused, planning-focused) | +| Privacy & ToS | [docs/legal/](file:///Users/yeongyu/local-workspaces/omo/docs/legal/) | +| Manifesto | [docs/manifesto.md](file:///Users/yeongyu/local-workspaces/omo/docs/manifesto.md) | +| Ollama troubleshooting | [docs/troubleshooting/ollama.md](file:///Users/yeongyu/local-workspaces/omo/docs/troubleshooting/ollama.md) | +| Internal design plans/specs | [docs/superpowers/plans/](file:///Users/yeongyu/local-workspaces/omo/docs/superpowers/plans/) + [docs/superpowers/specs/](file:///Users/yeongyu/local-workspaces/omo/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 `
` / `` (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`](file:///Users/yeongyu/local-workspaces/omo/.github/workflows/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/`](file:///Users/yeongyu/local-workspaces/omo/src/agents/) or [`src/features/builtin-skills/`](file:///Users/yeongyu/local-workspaces/omo/src/features/builtin-skills/). +- Never document changing config keys without also updating [`src/config/schema/`](file:///Users/yeongyu/local-workspaces/omo/src/config/schema/) and re-running `bun run build:schema`. diff --git a/packages/AGENTS.md b/packages/AGENTS.md new file mode 100644 index 000000000..076e73705 --- /dev/null +++ b/packages/AGENTS.md @@ -0,0 +1,57 @@ +# packages/ — Monorepo Packages + +**Generated:** 2026-05-20 + +## OVERVIEW + +15 sibling packages across 4 roles. None of these are published as part of the main `oh-my-opencode` / `oh-my-openagent` npm dist (root `package.json` `files` only ships `dist/`, `bin/`, `postinstall.mjs`). They are sibling packages with their own publication / deployment targets. + +## ROLE MAP + +| Role | Count | Packages | +|------|-------|----------| +| **Platform binaries** | 11 | One per (OS × arch × variant). Uniform layout: `bin/` + `package.json` only. Selected at install time by `bin/` shim + `postinstall.mjs`. | +| **MCP packages** | 2 | `lsp-tools-mcp` (git submodule), `ast-grep-mcp` | +| **Utility** | 1 | `rules-core` | +| **Web** | 1 | `web` | + +## PLATFORM BINARIES (11) + +`oh-my-opencode-darwin-arm64`, `oh-my-opencode-darwin-x64`, `oh-my-opencode-darwin-x64-baseline`, `oh-my-opencode-linux-arm64`, `oh-my-opencode-linux-arm64-musl`, `oh-my-opencode-linux-x64`, `oh-my-opencode-linux-x64-baseline`, `oh-my-opencode-linux-x64-musl`, `oh-my-opencode-linux-x64-musl-baseline`, `oh-my-opencode-windows-x64`, `oh-my-opencode-windows-x64-baseline`. + +Each contains only a `bin/` and a `package.json`. Built by [`script/build-binaries.ts`](file:///Users/yeongyu/local-workspaces/omo/script/build-binaries.ts) via `bun compile`. Published by the `publish-platform.yml` workflow. + +`-baseline` variants are pure x86_64 (no AVX2) for older CPUs. `-musl` variants link against musl libc for Alpine. Runtime selection happens in `bin/` and `postinstall.mjs`. + +## MCP PACKAGES + +| Package | Layout | Purpose | +|---------|--------|---------| +| `lsp-tools-mcp/` | Full standalone project (own `.git` submodule, `.github/`, `CHANGELOG.md`, `LICENSE`, `src/`, `test/`, `biome.json`, `vitest.config.ts`) | Serves `lsp_diagnostics`, `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_prepare_rename`, `lsp_rename`, `lsp_status` tools via stdio MCP. Registered as tier-1 MCP `lsp` in [`src/mcp/`](file:///Users/yeongyu/local-workspaces/omo/src/mcp/). | +| `ast-grep-mcp/` | Internal package (`src/`, `dist/`, `tsconfig.json`) | Serves `ast_grep_search` + `ast_grep_replace` tools via stdio MCP. Registered as tier-1 MCP `ast_grep`. | + +## UTILITY + +| Package | Layout | Purpose | +|---------|--------|---------| +| `rules-core/` | `src/`, `index.d.ts`, `tsconfig.json` | Shared rules-injector core logic published independently for reuse outside the plugin. | + +## WEB + +| Package | Sub-AGENTS.md | Purpose | +|---------|---------------|---------| +| `web/` | yes ([packages/web/AGENTS.md](file:///Users/yeongyu/local-workspaces/omo/packages/web/AGENTS.md)) | Marketing site. Next.js 15 + Cloudflare Workers via `@opennextjs/cloudflare`. Independent `bun.lock` + `tsconfig.json`. Only place in the repo where `@/*` path aliases are allowed. | + +## CONVENTIONS + +- **No new package without explicit need.** Adding a sibling package complicates publish + CI. Justify the boundary first. +- **Platform binaries** are generated. Do NOT edit by hand. Modify [`script/build-binaries.ts`](file:///Users/yeongyu/local-workspaces/omo/script/build-binaries.ts). +- **`lsp-tools-mcp` is a git submodule.** Initialize with `git submodule update --init --recursive` after fresh clone. +- **`packages/web/` is excluded from root `bun test`** via `bunfig.toml`. It has its own [`web-ci.yml`](file:///Users/yeongyu/local-workspaces/omo/.github/workflows/web-ci.yml) workflow. +- **CI builds** for non-platform packages run as part of the root `ci.yml`. Platform binaries build only via `publish-platform.yml` when triggered by `publish.yml`. + +## ANTI-PATTERNS + +- Never publish a sibling package manually. Use the GitHub Actions workflows. +- Never copy code between packages by hand. Either share via `rules-core` (or a new utility package) or accept the duplication and document it. +- Never modify `bin/` inside a platform package — those are compiled artifacts. diff --git a/packages/web/AGENTS.md b/packages/web/AGENTS.md index 9757b24d7..4ae965f05 100644 --- a/packages/web/AGENTS.md +++ b/packages/web/AGENTS.md @@ -1,6 +1,6 @@ # packages/web/ — Marketing Site (Next.js + Cloudflare Workers) -**Generated:** 2026-05-14 +**Generated:** 2026-05-20 ## OVERVIEW diff --git a/src/AGENTS.md b/src/AGENTS.md index f96ee65b7..1232c1bc7 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -1,10 +1,10 @@ # src/ — Plugin Source -**Generated:** 2026-05-18 +**Generated:** 2026-05-20 ## OVERVIEW -Entry `index.ts` orchestrates a 7-step initialization. Total: 1351 source files + 722 tests across the directories below. Cross-cutting helpers live in `shared/`; module boundaries are established by 122 barrel `index.ts` files. +Entry `index.ts` orchestrates a 7-step initialization. Total: ~1314 source files + 730 tests across the directories below. Cross-cutting helpers live in `shared/`; module boundaries are established by 120 barrel `index.ts` files. ## KEY FILES @@ -13,7 +13,7 @@ Entry `index.ts` orchestrates a 7-step initialization. Total: 1351 source files | `index.ts` | Plugin entry; default-exports `pluginModule: PluginModule` with `{ id, server }` | | `plugin-config.ts` | JSONC parse, multi-level merge (user + walked project), Zod v4 validation, migration | | `plugin-state.ts` | `createModelCacheState()` — model resolution cache shared across handlers | -| `plugin-interface.ts` | 10 OpenCode hook handlers wired into `Hooks` | +| `plugin-interface.ts` | 11 OpenCode hook handlers wired into `Hooks` (the 12th + 13th — `experimental.session.compacting` + `experimental.compaction.autocontinue` — are wired in `src/testing/create-plugin-module.ts`) | | `create-managers.ts` | TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler | | `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry composition | | `create-hooks.ts` | 5-tier composition: `createCoreHooks() + createContinuationHooks() + createSkillHooks()` | @@ -89,10 +89,10 @@ Total: 54 base, 61 with team-mode. Each tier produces an object whose values are | Subdir | Files (.ts) | LOC | Purpose | Has AGENTS.md | |--------|-------------|-----|---------|---------------| | `agents/` | 104 | ~20k | 11 agent factories + dynamic prompt builder | yes (+ atlas, hephaestus, prometheus, sisyphus, sisyphus-junior, builtin-agents) | -| `hooks/` | 596 | ~78k | ~52 lifecycle hooks across 58 dirs | yes (+ atlas, anthropic-context-window-limit-recovery, auto-update-checker, claude-code-hooks, comment-checker, compaction-context-injector, keyword-detector, ralph-loop, rules-injector, runtime-fallback, session-recovery, todo-continuation-enforcer) | +| `hooks/` | 596 | ~78k | ~52 lifecycle hooks across 57 dirs | yes (+ atlas, anthropic-context-window-limit-recovery, auto-update-checker, claude-code-hooks, comment-checker, compaction-context-injector, keyword-detector, ralph-loop, rules-injector, runtime-fallback, session-recovery, todo-continuation-enforcer) | | `tools/` | 317 | ~45k | 13 native tool dirs (+1 shared utilities dir); LSP + AST-grep moved to built-in MCPs | yes (+ background-task, call-omo-agent, delegate-task, hashline-edit, look-at, skill) | | `features/` | 404 | ~71k | 20 feature modules (team-mode, background-agent, boulder-state, etc.) | yes (+ 11 sub-AGENTS.md including builtin-skills, team-mode, background-agent, claude-code-*) | -| `shared/` | 290 | ~33k | Cross-cutting utilities, barrel-exported | yes | +| `shared/` | 297 | ~33k | Cross-cutting utilities (179 non-test), barrel-exported | yes | | `cli/` | 158 | ~18k | Commander.js CLI: install, run, doctor, mcp-oauth, boulder | yes (+ config-manager, doctor, run) | | `plugin/` | 58 | ~12k | 10 OpenCode hook handlers + hook composition | yes | | `config/` | 41 | ~2k | 30 Zod v4 schema files | yes | diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index 54dd68ee2..111edb1d6 100644 --- a/src/cli/AGENTS.md +++ b/src/cli/AGENTS.md @@ -1,10 +1,10 @@ -# src/cli/ — CLI: install, run, doctor, mcp-oauth, boulder +# src/cli/ — CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version, version, boulder -**Generated:** 2026-05-15 +**Generated:** 2026-05-20 ## OVERVIEW -Commander.js CLI with 7 commands. Entry: `index.ts` → `runCli()` in `cli-program.ts`. +Commander.js CLI with 8 commands. Entry: `index.ts` → `runCli()` in `cli-program.ts`. ## COMMANDS @@ -14,6 +14,7 @@ Commander.js CLI with 7 commands. Entry: `index.ts` → `runCli()` in `cli-progr | `run ` | Non-interactive session launcher | Agent resolution (flag → env → config → Sisyphus) | | `doctor` | 4-category health checks | System, Config, Tools, Models | | `get-local-version` | Version detection | Installed vs npm latest | +| `version` | Print plugin version | Trivial 2-line subcommand | | `mcp-oauth` | OAuth token management | login (PKCE), logout, status | | `refresh-model-capabilities` | Refresh models.dev cache | Model capabilities refresh | | `boulder` | Boulder state inspector | Format work-state + tasks from `.omo/boulder-state/` | @@ -23,7 +24,7 @@ Commander.js CLI with 7 commands. Entry: `index.ts` → `runCli()` in `cli-progr ``` cli/ ├── index.ts # Entry point → runCli() -├── cli-program.ts # Commander.js program (5 commands) +├── cli-program.ts # Commander.js program (8 commands) ├── install.ts # Routes to TUI or CLI installer ├── cli-installer.ts # Non-interactive (console output) ├── tui-installer.ts # Interactive (@clack/prompts) diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md index 3bb7fa1af..276a99ca3 100644 --- a/src/config/AGENTS.md +++ b/src/config/AGENTS.md @@ -1,10 +1,10 @@ # src/config/ — Zod v4 Schema System -**Generated:** 2026-05-15 +**Generated:** 2026-05-20 ## OVERVIEW -30 non-test schema files composing `OhMyOpenCodeConfigSchema`. Zod v4 validation with `safeParse()`. All fields optional — omitted fields use defaults from the schema. Auto-emitted to `assets/oh-my-opencode.schema.json` via `bun run build:schema`. +30 non-test schema files composing `OhMyOpenCodeConfigSchema` (plus `schema/internal/permission.ts` for shared internal helpers). Zod v4 validation with `safeParse()`. All fields optional — omitted fields use defaults from the schema. Auto-emitted to `assets/oh-my-opencode.schema.json` via `bun run build:schema`. ## SCHEMA TREE diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index f08567642..439782e85 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -1,6 +1,6 @@ # src/features/ — 20 Feature Modules -**Generated:** 2026-05-15 +**Generated:** 2026-05-20 ## OVERVIEW @@ -8,39 +8,42 @@ Standalone feature modules wired into `plugin/` layer. Each is self-contained wi ## MODULE MAP -| Module | Files | Complexity | Purpose | -|--------|-------|------------|---------| -| **background-agent** | 57 | HIGH | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker, archive fallback | -| **opencode-skill-loader** | 30 | HIGH | YAML frontmatter skill discovery from 4 scopes (project > opencode > user > global) | -| **tmux-subagent** | 32 | HIGH | Tmux pane management, grid planning, session orchestration via `runTmuxCommand` | -| **team-mode** | 24 dirs / 100+ files | HIGH | Parallel multi-agent coordination — 12 `team_*` tools, mailbox, tasklist, worktrees, optional tmux layout | -| **mcp-oauth** | 18 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) + step-up auth for MCP servers | -| **skill-mcp-manager** | 18 | HIGH | Tier-3 MCP client lifecycle per session (stdio + HTTP + OAuth) | -| **claude-code-plugin-loader** | 16 | MEDIUM | Unified Claude Code plugin discovery (commands, agents, skills, hooks, MCPs) | -| **builtin-skills** | 17 | LOW–MED | 10 built-in skill files (git-master, playwright, frontend-ui-ux, review-work, ai-slop-remover, dev-browser, playwright-cli, **team-mode**, …) | -| **builtin-commands** | 11 | LOW | Command templates: refactor, init-deep, handoff, ulw-loop, etc. | -| **claude-tasks** | 7 | MEDIUM | Sisyphus task schema + atomic file storage + OpenCode todo API sync | -| **claude-code-mcp-loader** | 11 | MEDIUM | Tier-2 MCP loader: `.mcp.json` parse + `${VAR}` env expansion | -| **context-injector** | 6 | MEDIUM | AGENTS.md/README.md injection into session context | -| **run-continuation-state** | 5 | LOW | Persistent state for `oh-my-opencode run` continuation across invocations | -| **hook-message-injector** | 5 | MEDIUM | System message injection helper used by hooks | -| **boulder-state** | 5 | LOW | Persistent state for boulder/multi-step operations | -| **task-toast-manager** | 4 | MEDIUM | Task progress notifications | -| **tool-metadata-store** | 3 | LOW | Tool execution metadata cache | -| **claude-code-session-state** | 3 | LOW | Subagent session state tracking | -| **claude-code-command-loader** | 3 | LOW | Load `/commands` from `.opencode/commands/` and Claude Code plugins | -| **claude-code-agent-loader** | 3 | LOW | Load agents from `.opencode/agents/` and Claude Code plugins | +File counts are NON-TEST `.ts` files only (test files co-located but excluded from the count). + +| Module | Files | Complexity | Has sub-AGENTS.md | Purpose | +|--------|-------|------------|-------------------|---------| +| **team-mode** | 60 / 8 subdirs | HIGH | yes | Parallel multi-agent coordination — 12 `team_*` tools, mailbox, tasklist, worktrees, optional tmux layout | +| **background-agent** | 30 / 1 subdir (spawner/) | HIGH | yes | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker. Newer files: `parent-wake-notifier.ts` (587 LOC), `loop-detector`, `error-classifier`, `fallback-retry-handler`, `process-cleanup`, `subagent-spawn-limits`, `session-status-classifier`, `compaction-aware-message-resolver`. | +| **tmux-subagent** | 27 | HIGH | yes | Tmux pane management, grid planning, session orchestration via `runTmuxCommand` | +| **opencode-skill-loader** | 25 / 1 subdir (merger/) | HIGH | yes | YAML frontmatter skill discovery from 4 scopes (project > opencode > user > global) | +| **builtin-skills** | 18 / 5 subdirs | LOW–MED | yes | 10 built-in skill files (git-master, playwright, frontend-ui-ux, review-work, ai-slop-remover, dev-browser, playwright-cli, **team-mode**, …) | +| **skill-mcp-manager** | 11 | HIGH | yes | Tier-3 MCP client lifecycle per session (stdio + HTTP + OAuth) | +| **claude-code-plugin-loader** | 11 | MEDIUM | yes | Unified Claude Code plugin discovery (commands, agents, skills, hooks, MCPs) | +| **builtin-commands** | 11 / 1 subdir (templates/) | LOW | yes | Command templates: refactor, init-deep, handoff, ulw-loop, etc. | +| **mcp-oauth** | 10 | HIGH | yes | OAuth 2.0 + PKCE + DCR (RFC 7591) + step-up auth for MCP servers | +| **claude-code-agent-loader** | 7 | LOW | yes | Load agents from `.opencode/agents/` and Claude Code plugins | +| **claude-code-mcp-loader** | 7 | MEDIUM | yes | Tier-2 MCP loader: `.mcp.json` parse + `${VAR}` env expansion | +| **tool-metadata-store** | 6 | LOW–MED | no | Tool execution metadata cache; publish/recover lifecycle + task metadata contract | +| **boulder-state** | 6 | LOW | yes | Persistent state for boulder (active work plan tracking across sessions/worktrees) | +| **context-injector** | 4 | LOW | no | AGENTS.md/README.md injection into session context | +| **hook-message-injector** | 4 | LOW | no | System message injection helper used by hooks | +| **run-continuation-state** | 4 | LOW | no | Persistent state for `oh-my-opencode run` continuation across invocations | +| **claude-code-command-loader** | 4 | LOW | no | Load `/commands` from `.opencode/commands/` and Claude Code plugins | +| **claude-tasks** | 3 | MEDIUM | yes | Sisyphus task schema + atomic file storage + OpenCode todo API sync | +| **task-toast-manager** | 3 | MEDIUM | no | Task progress notifications | +| **claude-code-session-state** | 2 | LOW | no | Subagent session state tracking | ## KEY MODULES -### background-agent (~10k LOC) +### background-agent Core orchestration engine. `BackgroundManager` manages task lifecycle: - States: `pending → running → completed | error | cancelled | interrupt` - Concurrency: per-key (`${providerID}/${modelID}`) limits via `ConcurrencyManager` (FIFO queue) - Polling: 3s interval, completion detected via idle event AND stability detection (10s unchanged) -- Circuit breaker: automatic failure detection and recovery -- `spawner/`: 8 focused files composing via `SpawnerContext` interface +- Circuit breaker: automatic failure detection and recovery in `manager-circuit-breaker.test.ts` +- `spawner/`: focused files composing via `SpawnerContext` interface +- Parent-wake state extracted to `parent-wake-notifier.ts` (587 LOC, dependency-injected client + enqueue callback) ### team-mode (~13k LOC) diff --git a/src/features/background-agent/AGENTS.md b/src/features/background-agent/AGENTS.md index fdb787896..2be854136 100644 --- a/src/features/background-agent/AGENTS.md +++ b/src/features/background-agent/AGENTS.md @@ -1,10 +1,10 @@ # src/features/background-agent/ — Core Orchestration Engine -**Generated:** 2026-05-15 +**Generated:** 2026-05-20 ## OVERVIEW -30 files (~10k LOC). Manages async task lifecycle: launch → queue → run → poll → complete/error. Concurrency limited per model/provider (default 5). Central to multi-agent orchestration. +30 non-test files (62 entries total including tests + spawner/ subdir). Manages async task lifecycle: launch → queue → run → poll → complete/error. Concurrency limited per model/provider (default 5). Central to multi-agent orchestration. ## TASK LIFECYCLE @@ -20,11 +20,25 @@ LaunchInput → pending → [ConcurrencyManager queue] → running → polling | `spawner.ts` | Task spawning: create session → inject prompt → start polling | | `concurrency.ts` | `ConcurrencyManager` — FIFO queue per concurrency key, slot acquisition/release | | `task-poller.ts` | 3s interval polling, completion via idle events + stability detection (10s unchanged) | -| `result-handler.ts` | Process completed tasks: extract result, notify parent, cleanup | | `state.ts` | In-memory task store (Map-based) | | `types.ts` | `BackgroundTask`, `LaunchInput`, `ResumeInput`, `BackgroundTaskStatus` | +| `parent-wake-notifier.ts` | 587 LOC. Dependency-injected client + enqueue callback. Notifies parent session when a background task wants attention. | +| `loop-detector.ts` | Detects polling/event loops that would otherwise burn budget. | +| `error-classifier.ts` | Maps raw provider errors → `BackgroundTaskError` categories. | +| `fallback-retry-handler.ts` | Coordinates retries with the runtime-fallback system. | +| `process-cleanup.ts` | Best-effort cleanup on parent exit. `OMO_DISABLE_PROCESS_CLEANUP=1` opts out entirely. | +| `subagent-spawn-limits.ts` | Enforces per-parent subagent spawn caps. | +| `session-status-classifier.ts` | Normalizes OpenCode session status across versions. | +| `compaction-aware-message-resolver.ts` | Resolves task result content even across mid-task compaction. | +| `attempt-lifecycle.ts` | Tracks retry attempts on a single task. | +| `task-history.ts` | Append-only history for completed tasks. | +| `session-idle-event-handler.ts` | Bridges OpenCode `session.idle` → task-poller completion signal. | +| `session-existence.ts` | Cheap existence check used by recovery code. | +| `abort-with-timeout.ts` | Force-abort tasks past `syncPollTimeoutMs`. | +| `remove-task-toast-tracking.ts` | Strips lingering toast tracker entries on task end. | +| `background-task-notification-template.ts` | Template for parent-session result injection. | -## SPAWNER SUBDIRECTORY (6 files) +## SPAWNER SUBDIRECTORY | File | Purpose | |------|---------| diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index c7abd54da..0828e3803 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -1,10 +1,12 @@ -# src/hooks/ — ~52 Lifecycle Hooks Across 58 Dirs +# src/hooks/ — ~52 Lifecycle Hooks Across 57 Dirs -**Generated:** 2026-05-15 +**Generated:** 2026-05-20 ## OVERVIEW -52 hooks (5 of the 58 dirs are `zauc-mocks-*` test scaffolds + 1 `shared/`). 5-tier composition wired in `src/plugin/hooks/`. All hooks follow `createXXXHook(deps) → HookFunction` factory pattern. +52 registered hooks. The 57 directories break down as: 48 registered hook dirs (with `index.ts`) + 6 standalone hook `.ts` files (bash-file-read-guard, context-window-monitor, empty-task-response-detector, preemptive-compaction, session-notification, tool-output-truncator) + support dirs (`shared/`, `team-session-events/`, 5 `zauc-mocks-*`/`zauc-sync-mocks`, `.sisyphus/` legacy state). 5-tier composition wired in `src/plugin/hooks/`. All hooks follow `createXXXHook(deps) → HookFunction` factory pattern. + +**Unwired WIP (do not modify casually):** `task-reminder/` (has `index.ts` + `createTaskReminderHook` but NOT exported from barrel, NOT imported by any composer) and `hashline-edit-diff-enhancer/` (has only `hook.ts`, NOT registered). Treat as orphaned until wired in. ## TIER COMPOSITION diff --git a/src/plugin-handlers/AGENTS.md b/src/plugin-handlers/AGENTS.md index 0d1f5a00d..c5013c192 100644 --- a/src/plugin-handlers/AGENTS.md +++ b/src/plugin-handlers/AGENTS.md @@ -1,6 +1,6 @@ # src/plugin-handlers/ — 6-Phase Config Loading Pipeline -**Generated:** 2026-05-15 +**Generated:** 2026-05-20 ## CRITICAL: AGENT ORDERING diff --git a/src/plugin/AGENTS.md b/src/plugin/AGENTS.md index e568134bf..c851cb296 100644 --- a/src/plugin/AGENTS.md +++ b/src/plugin/AGENTS.md @@ -1,10 +1,10 @@ -# src/plugin/ — 10 OpenCode Hook Handlers + Hook Composition +# src/plugin/ — 11 OpenCode Hook Handlers + Hook Composition -**Generated:** 2026-05-15 +**Generated:** 2026-05-20 ## OVERVIEW -Core glue layer. Files assemble the 10 OpenCode hook handlers and compose the 5-tier hook system into the `PluginInterface`. Each handler file maps to one OpenCode hook type. +Core glue layer. Files assemble the 11 OpenCode hook handlers wired into `PluginInterface` here (an additional 2 — `experimental.session.compacting` + `experimental.compaction.autocontinue` — are wired in `src/testing/create-plugin-module.ts`). Each handler file maps to one OpenCode hook type. ## HANDLER FILES @@ -15,12 +15,15 @@ Core glue layer. Files assemble the 10 OpenCode hook handlers and compose the 5- | `chat-message.ts` | `chat.message` | First-message variant resolution, session setup, keyword detection trigger | | `chat-params.ts` | `chat.params` | Anthropic effort, think mode, runtime fallback model override | | `chat-headers.ts` | `chat.headers` | Copilot `x-initiator` header injection | -| `event.ts` | `event` | Session lifecycle (created/deleted/idle/error/status), openclaw dispatch, runtime fallback | +| `command-execute-before.ts` | `command.execute.before` | Pre-command guards (slash-command interception, etc.) | +| `event.ts` | `event` | Session lifecycle (created/deleted/idle/error/status), openclaw dispatch, runtime fallback, 4 team-session-event handlers (when team_mode.enabled) | | `tool-execute-before.ts` | `tool.execute.before` | Pre-tool guards | | `tool-execute-after.ts` | `tool.execute.after` | Post-tool hooks (truncation, comment-checker, hashline read tagging, json-error-recovery) | | `messages-transform.ts` | `experimental.chat.messages.transform` | Context injection, thinking-block validation, tool-pair validation, keyword detection | -| `session-compacting.ts` | `experimental.session.compacting` | Context + todo preservation across compaction | +| `system-transform.ts` | `experimental.chat.system.transform` | System-message-level transforms | +| `session-compacting.ts` | `experimental.session.compacting` | Context + todo preservation across compaction (registered via `create-plugin-module.ts`) | | `skill-context.ts` | (helper) | Skill/browser/category context shared with tool creation | +| `build-team-idle-wake-hint-client.ts` | (helper) | Build the team idle-wake-hint client wired into event handlers | ## HOOK COMPOSITION (hooks/ subdir) diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md index ac0045225..22e47ee17 100644 --- a/src/shared/AGENTS.md +++ b/src/shared/AGENTS.md @@ -1,6 +1,6 @@ -# src/shared/ — 278 Utility Files (170 non-test) +# src/shared/ — 297 Utility Files (179 non-test) -**Generated:** 2026-05-15 +**Generated:** 2026-05-20 ## OVERVIEW