From a089d4a5849a443583757c01c9869453362c8fe3 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Thu, 21 May 2026 03:44:20 +0900 Subject: [PATCH] docs: update AGENTS.md + ROADMAP.md for package layering refactor --- AGENTS.md | 9 ++++++++- ROADMAP.md | 12 ++++++++---- packages/AGENTS.md | 14 ++++++++++---- 3 files changed, 26 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3c5e6bcf6..fcb786a5f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,14 @@ oh-my-opencode/ │ ├── 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 + ast-grep-mcp + rules-core + web +├── packages/ # 11 platform binaries + 2 MCP packages + 7 Core packages + web +│ ├── utils/ # Shared utilities — deep-merge, snake-case, frontmatter, file-utils, etc. +│ ├── model-core/ # Model resolution pipeline with ProviderCache DI +│ ├── rules-engine/ # Rule discovery + matching (renamed from rules-core) +│ ├── agents-md-core/ # AGENTS.md walk-up discovery + injection +│ ├── ast-grep-core/ # ast-grep types, pattern-hints, runner core with injectable spawn +│ ├── comment-checker-core/ # apply-patch parser, binary runner with injectable spawn +│ ├── boulder-state/ # Work tracking state machine, split storage │ └── 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/) diff --git a/ROADMAP.md b/ROADMAP.md index 1c0320ddd..660714611 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -41,10 +41,14 @@ The refactor splits packages into strict layers by runtime boundary: **Current extraction status:** -- `packages/rules-core` is the first extracted core module. It contains rule discovery, matching, and AGENTS.md utilities. -- `pi-rules` and `codex-rules` currently duplicate this logic. They will migrate to consume `@oma/rules` (or equivalent workspace package) instead. -- `comment-checker` exists in three places: `omo/hooks/comment-checker/`, `pi-comment-checker/`, `codex-comment-checker/`. A core extraction is next. -- `lsp-client` logic lives in `omo/packages/lsp-tools-mcp/`, `pi-lsp-client/`, and `codex-lsp/`. A pure TS core plus MCP wrapper split is planned. +- 7 Core packages are now extracted under `packages/`: `utils`, `model-core`, `rules-engine`, `agents-md-core`, `ast-grep-core`, `comment-checker-core`, `boulder-state`. +- `omo` consumes all 7 via workspace dependencies plus per-file re-export shims at the original `src/` locations. +- `pi-extensions` and `codex-plugins` are not yet migrated to consume these packages. That migration is the next phase. +- The `lsp-tools-mcp` submodule is untouched. `lsp-core` extraction is `[~]` deferred pending submodule strategy. + +Layering achieved: Core (7 pure-TS packages) → Adapter (`omo` plugin) → Platform binaries. Future Pi and Codex adapters will consume the same Core layer. + +The Pi Engine DI abstraction was deferred. It can be revisited once the adapter migration is complete. ## Architecture Direction diff --git a/packages/AGENTS.md b/packages/AGENTS.md index 076e73705..61216a27e 100644 --- a/packages/AGENTS.md +++ b/packages/AGENTS.md @@ -12,7 +12,7 @@ |------|-------|----------| | **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` | +| **Core packages** | 7 | `utils`, `model-core`, `rules-engine` (was `rules-core`), `agents-md-core`, `ast-grep-core`, `comment-checker-core`, `boulder-state` | | **Web** | 1 | `web` | ## PLATFORM BINARIES (11) @@ -30,11 +30,17 @@ Each contains only a `bin/` and a `package.json`. Built by [`script/buil | `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 +## CORE PACKAGES | Package | Layout | Purpose | |---------|--------|---------| -| `rules-core/` | `src/`, `index.d.ts`, `tsconfig.json` | Shared rules-injector core logic published independently for reuse outside the plugin. | +| `utils/` | `src/`, `tsconfig.json` | Shared utilities: deep-merge, snake-case, frontmatter, file-utils, etc. | +| `model-core/` | `src/`, `tsconfig.json` | Model resolution pipeline with ProviderCache dependency injection. | +| `rules-engine/` | `src/`, `tsconfig.json` | Rule discovery + matching engine (renamed from `rules-core`). | +| `agents-md-core/` | `src/`, `tsconfig.json` | AGENTS.md walk-up discovery and injection logic. | +| `ast-grep-core/` | `src/`, `tsconfig.json` | ast-grep types, pattern-hints, and runner core with injectable spawn. | +| `comment-checker-core/` | `src/`, `tsconfig.json` | apply-patch parser and binary runner with injectable spawn. | +| `boulder-state/` | `src/`, `tsconfig.json` | Work tracking state machine with split storage. | ## WEB @@ -53,5 +59,5 @@ Each contains only a `bin/` and a `package.json`. Built by [`script/buil ## 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 copy code between packages by hand. Either share via a core package or accept the duplication and document it. - Never modify `bin/` inside a platform package — those are compiled artifacts.