diff --git a/AGENTS.md b/AGENTS.md index 80fa6c4ad..2e960e85c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,6 +50,14 @@ Unless user tells you exactly what to write: History: `with { type: "file" }` only copied the entry as a raw asset (workers crashed silently in compiled binaries — issues #1011, #1027), and the later literal-path + extra-entrypoint pattern required keeping spawn literals and two build scripts in sync (issue #1150). The smoke probe below is the live validation of this contract. Validate any new worker with the dedicated smoke probe: `omp --smoke-test` spawns the stats sync worker and the tiny-model subprocess, pings them, and exits — it's wired into `ci:test:smoke` and `scripts/install-tests/run-ci.sh` so binary, source-link, and tarball installs all exercise it. Add a sibling smoke if the new worker is on a different module graph. +## Central Utilities + +Before writing a helper, check whether one already exists — `packages/coding-agent/src/utils/`, `@oh-my-pi/pi-utils`, `@oh-my-pi/pi-tui`, and the domain modules next to your callsite. This applies to **everything**: VCS wrappers, formatting/truncation/path-display helpers, image handling, clipboard, streams, temp files, caching. The central versions carry hardening a fresh copy always loses (timeouts, output caps, non-interactive env, lock avoidance, caching, TUI sanitization). + +- Search first: `grep` for the operation before implementing it. Two implementations of the same thing is a bug even when both work. +- Examples of the pattern: `src/utils/git.ts` and `src/utils/jj.ts` are the only sanctioned way to run git/jj (`import * as git from "../utils/git"` — never hand-spawn via `$`/`Bun.spawn`); rendering goes through the helpers in TUI Sanitization below (`replaceTabs`, `truncateToWidth`, `shortenPath`, `PREVIEW_LIMITS`) rather than ad-hoc string math. +- Missing capability? Extend the central helper (new option, new sub-function on the namespace) and call it — don't fork its logic locally. + ## Bun Over Node Use Bun APIs where they provide a cleaner alternative; fall back to `node:*` only for what Bun doesn't cover. **Never spawn shell commands for operations with proper APIs** (e.g., don't `Bun.spawnSync(["mkdir", "-p", dir])` — use `mkdirSync`). @@ -210,6 +218,7 @@ For the bash tool specifically: - NEVER commit unless asked. - Never use `tsc`/`npx tsc` — always `bun check`. +- Merge commits (maintainer merges of PRs) follow: `Merge PR #: (@)` — e.g. `Merge PR #6386: feat(catalog): add native Meta Model API provider (@eggpeat)`. ## Testing Guidance