AGENTS.md@packages/omo-senpi/plugin git:20260909.a30875fA

Immutable. This exact content is served forever at /api/v1/blob/0289c32a38ff5c41.

# omo-senpi plugin

The single Pi package `@code-yeongyu/omo-senpi`: one generated extension entry, generated skills, a tracked DAG runtime, and the scripts that build, stage, sync, and install all of it. Local-path installs only (`senpi install <abs-path-to-here>`); `git:`/`npm:` installs are unsupported because `extensions/` and `skills/` are generated build outputs.

## STRUCTURE

| Path | Purpose |
|------|---------|
| `package.json` | Pi manifest: `pi.extensions = ["./extensions/omo.js"]`, `pi.skills = ["./skills"]` (never `./skills-conditional`), `imports["#omo-task-runtime"] = "./extensions/omo-task.js"` (the dev package maps that specifier to `src/extension/omo-task.ts`). `files` ships extensions, skills, skills-conditional, runtime, `scripts/install.mjs`, README, NOTICE, LICENSE. |
| `extensions/` | Generated, gitignored, minified single-line bundles. Five artifacts: `omo.js` (main entry from `src/extension/bundled-index.ts`; exports `composeOmoSenpiExtension`, default export, `omoSenpiComponents`), `omo-task.js` (`createTaskComponent`; initializes `globalThis.__zod_globalConfig`/`__zod_globalRegistry`), `omo-member.js` (team member extension, built from `packages/senpi-task/src/team/member-extension/index.ts`), `memory-run-supervisor.mjs` (memory reflection supervisor), `omo-init-deep-advisor.js`; plus persona sources `dream-persona.md`, `facts-persona.md`, `kibitzer-persona.md`, `reflection-persona.md`. |
| `skills/` | Generated by `plugin/scripts/sync-skills.mjs` from the native `skills/` pool, the component-owned `ulw-loop`, and the repo `shared-skills` pool. Gitignored except the tracked senpi-local `init-deep`/`onboarding` overrides; the README lists all 19 shipped skills. |
| `skills-conditional/` | Generated by `plugin/scripts/stage-x-search-skill.mjs` from `src/components/x-search/skill/SKILL.md`. Gitignored. Must not join `pi.skills`: the x-search skill is contributed at runtime via `resources_discover` only when an xAI credential exists. `files` still ships the directory so the bundled extension can resolve `../skills-conditional/x-search/SKILL.md`, and the payload allowlists in `script/build-omo-native.ts` / `script/build-omo-binary.ts` plus the required-artifact lists must keep it too — the npm payload shipped without it until 2026-09-04. Staging builds receive the copy in `$OMO_SENPI_PLUGIN_OUTPUT`. |
| `runtime/dag/` | Tracked DAG runtime shipped with the plugin. `sdk.js` exports `define`, `start`, `attach`, `snapshot`, `wait`, `cancel`, `retry`, `send`, `amend` (run lifecycle, snapshot/wait, messaging, amendment); `library.js` validates library names (`^[A-Za-z0-9][A-Za-z0-9._-]*$`) and loads definitions from configured library dirs (the `dag-library` skill's save target). `runtime/agent-toolkit/` and `runtime/ast-grep-mcp/` are staged, gitignored vendored runtimes. |
| `scripts/` | Hand-authored build/stage/sync/install pipeline. Own AGENTS.md. |

## WHERE TO LOOK

| Task | Location |
|------|----------|
| Bundle stale or wrong | `plugin/scripts/AGENTS.md` + `build-extension.mjs --check`; never debug the bundle itself |
| DAG orchestration API | `runtime/dag/sdk.js`; named/reusable dags via `runtime/dag/library.js` |
| Install behavior / launchers | `plugin/scripts/AGENTS.md` (`install.mjs`, `build-install.mjs`) and `../src/install/` |
| Shipped-skill list, disable flags, LSP migration | `README.md` (six `lsp_*` tools always registered; project `.pi/lsp-client.json` command/env entries ignored for safety) |
| Conditional x-search skill stale or missing | `plugin/scripts/stage-x-search-skill.mjs` (`--check` verifies the staged copy matches source); never add it to `pi.skills` |

## CONVENTIONS

- Dag RPC wire payloads are snake_case (`run_id`, `node_id`); the JavaScript API is camelCase (`runId`, `nodeIds`). Deliberate wire/API boundary.
- Bundles carry `// omo:<fingerprint>` build markers; freshness checks compare markers and source digests, and paths inside artifacts are made portable at build time.

## ANTI-PATTERNS

- NEVER hand-edit anything under `extensions/`, `skills/`, `skills-conditional/`, or the staged `runtime/` dirs; regenerate via `plugin/scripts/` (`build-extension.mjs`, `sync-skills.mjs`, `stage-x-search-skill.mjs`, the other stage scripts). Generated hook text repeats this: "Do not edit by hand - regenerated on startup". Do not add credential-gated skills to `pi.skills`.
- Treat bundles as opaque: minified one-liners up to ~870KB with minifier-local symbol names; LSP diagnostics on them are noise. Source of truth is `../src/` plus the build scripts.
- Do not widen the Pi manifest surface without keeping `../src/package-shape.test.ts` and `../src/plugin-manifest.test.ts` green.

## COMMANDS

```bash
node plugin/scripts/build-extension.mjs [--check]   # all six artifacts; --check verifies freshness
bun run test:senpi                                   # repo gate: build + stage + typecheck + test
```