opencode-rules AGENTS.md

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/<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 synthetic parts via chat.message.

Architecture

• One package, two default plugin exports: server entry src/index.ts returns { id, server }; TUI entry tui/index.tsx returns { id, tui }. 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).
• OpenCode's plugin loader calls every named export as a plugin initializer; any added named export must be callable (see the __testOnly pattern in src/index.ts).
• 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 injected as one synthetic text part appended to the user message via chat.message, 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 no-reply session.prompt, with transient fallback and retry when persistence fails. Ephemeral rules (agent, model, branch, tools) are delivered as one transient synthetic message per matching turn via experimental.chat.messages.transform 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 experimental OpenCode hooks (experimental.chat.messages.transform, experimental.session.compacting); re-verify against @opencode-ai/plugin when upgrading.
• Per-session matched-rule state is written atomically to ~/.opencode/state/opencode-rules/{sessionID}.json, which the TUI sidebar reads.