opencode-rules: Instructions file for Codex

Repo Notes

Commands

• Use Aube and install with aube install --frozen-lockfile. Run checks in this order: aube run lint -> aubx tsc --noEmit -> aube run test:run.
• There is no typecheck script; typecheck with aubx tsc --noEmit.
• Run one colocated Vitest file with aube run test:run src/<domain>/<name>.test.ts (or a path under tui/). tsconfig.json excludes test/spec files, so tsc does not typecheck them.
• docs/silent-message-implementation.md describes a superseded design; current delivery is durable synthetic messages via session.synthetic on the v2 plugin contract.

Architecture

• One package, two default plugin exports: server entry src/index.ts returns the v2 { id, setup(ctx) } contract; TUI entry tui/index.tsx returns the v2 CLI-plugin { id, setup(ctx) } contract (slot claims via ctx.ui.slot, e.g. sidebar.content). The package root imports built dist/src/index.js, and "./tui" imports built dist/tui/index.js (its types come from dist/tui/index.d.ts).
• The v2 loader imports ONLY the default export of the server entry; src/index.ts must carry no named exports. Test seams live in src/runtime/create-runtime.ts (createRuntime), consumed by tests via direct import.
• Each injection event is one <system-message> block with one preamble and <rule name="..."> blocks using frontmatter name or the filename stem. Session-durable rules (unconditional, globs, fileContains, keywords, command, project, os, ci) are published via ctx.session.synthetic from the session prompt hook as one persisted synthetic message per turn (resume: false, no description, because the hook runs before the user message is dispatched and a scheduled run would see the rule block alone), not into the system prompt. A durable rule first matched by a live File observation is instead admitted at the earliest applicable dispatch through an awaited ctx.session.synthetic message (resume: false, no description, so it never triggers a reply, wakes an idle session, or renders as a user turn/UI notice), with transient fallback and retry when persistence fails. Ephemeral rules (agent, model, branch, tools) are delivered as one transient synthetic message per matching turn by mutating input.messages in the session context hook and never persisted. Live tool.execute.after observations are the sole matching source for globs/fileContains; history rebuilds Working-context paths (compaction projection) and delivery-ledger identity only, never File observations. Path-derived identity keys prevent durable rules still present in history from being re-appended after content edits or resume; message removal invalidates the ledger so reverted delivery is retried, and after compaction the ledger is rebuilt so missing durable rules are re-appended. Hook guidance uses the same framing.
• Depends on v2 plugin hooks (ctx.tool.hook, ctx.session.hook('context'|'prompt'), ctx.event.subscribe) and client surface (session.context/session.synthetic, mcp.list); the retired session.prompt admission path remains decodable for existing sessions; re-verify against @opencode-ai/plugin@beta when upgrading. Available built-in tool IDs come from the context hook's tool table (the v1 tool.ids RPC is gone); message-removal invalidation keys on session.revert.* events (message.removed is gone).
• Per-session matched-rule state is written atomically to ~/.opencode/state/opencode-rules/{sessionID}.json, which the TUI sidebar reads.