AGENTS.md · diff
git:20260731.eb2f7c2 to git:20260812.b6e2821
14 added, 8 removed. Audit A to A.
# Agent instructions
Conventions this repo has settled on. They live here because they cannot be
inferred from the code, and getting them wrong costs a round of rework.
## Build and test
Tests exercise the bundles in `dist/`, so run `npm run build` before `npm test`
after touching anything under `integrations/`.
## Layout
- - One directory per installable capability: `integrations/<capability>/`, with
- per-agent adapters named `<agent>-<form>.mjs`.
- - Every executable file copied into `~/.agent-tools` comes from `dist/`; the
- sources stay in `integrations/`. `config.default.jsonc` is the exception: the
- installer merges it in from the repo root.
- - Capability-bound skills live in `integrations/<cap>/skills/`, never in
- `skills/`: those templates hold unrendered `{{TOKENS}}` and must not ship
- through `npx skills add`.
+ - Self-contained capabilities that work when copied by a Skill installer live
+ in `skills/`. They may bundle `scripts/`, `references/`, and `assets/` in the
+ same Skill directory.
+ - Capabilities that require independent installation, hooks, shared runtimes,
+ generated bundles, or Agent configuration live in
+ `integrations/<capability>/`, with per-agent adapters named
+ `<agent>-<form>.mjs`.
+ - Every executable installed into `~/.agent-tools` by the integration installer
+ comes from `dist/`; sources stay in `integrations/`. Bundled scripts inside a
+ self-contained Skill are installed with that Skill instead.
+ - Integration-owned Skill templates that contain unrendered `{{TOKENS}}` live
+ in `integrations/<capability>/skills/` and must not ship through
+ `npx skills add`. `config.default.jsonc` remains the installer-merged
+ exception from the repo root.
## Settled decisions
- No migration or legacy-compat code. Breaking a layout is fine: bump a minor
version and state the one-time manual cleanup in the summary.
- Add no new env knobs for timing: a value that follows from the caller's shape
belongs in a module constant, with a comment explaining that number. The
overrides already in `codex-hook.mjs` and `claude-statusline.mjs` predate this
and stay unless a change removes them deliberately.
- Never claim compatibility that has not been verified against a real gateway.
- Usage output lines carry no branding prefix; each display surface adds its own
context.
## Docs
- Never use CJK/fullwidth punctuation. Write `,` `.` `:` `;` `(` `)` even in
Chinese text. In `- term — description` lines the separator is `—`, not `-`.
- `README.md`, `README.zh-CN.md`, and both `docs/` trees change together.
- Prefer deleting a sentence over explaining it. Say what the reader must do,
not how it works inside.
## Commits
Single-line Conventional Commits, English, no body or footer. Use `!` for
changes that break an existing install.