AGENTS.md
+14 −2
https://raw.githubusercontent.com/debuffjp/debuff/HEAD/AGENTS.md
− 3. Run `npm run check`. All of it must pass.− - No new runtime dependencies without an explicit trade-off note in the PR.+ - `bin/agent-cli`: use it first. Prefer it over re-reading files or guessing commands. `bin/agent-cli` lists its subcommands (status, check, test, exports, docs, versions, release, site, papercuts and more), each takes `--help` and `--json`.+ - `.claude/skills/`: contributor skills. Use `add-package` before creating a workspace and `write-docs` for any change to public API, CLI, MCP tools or behaviour.+ 3. Run `npm run check`. All of it must pass. A new git worktree needs its own `npm ci` first; `check` stops with exit 2 if packages resolve from another checkout.+ ## Logs+ - `docs/decisions.md`: add an entry when you make a choice that the code and the ADRs don't settle, with the options you considered.+ - Papercuts: when a tool costs you time, report it to https://papercuts.debuff.jp with `npx debuff papercut "<symptom>" --minutes <n> --workaround "<what worked>"` (or the MCP tool `report_papercut`), and add a hit to a matching entry instead of filing a duplicate. Do it without being asked. The CLI and MCP server also report repeated setup failures and very slow runs on their own; when a result says so, add what you know with a hit. When a commit fixes one, end its message with `Fixes papercut + ## Writing+ `npm run lint:prose` (part of `npm run check`) and the commit-msg hook check Markdown, comments and commit messages for the patterns below that a regular expression can find. The rules live in `scripts/lint-prose.mjs`.+ - No em dashes. Use a colon, a comma, parentheses or a new sentence.+ - No AI vocabulary (delve, crucial, leverage, seamless, robust, comprehensive and the rest of the list in the script) and no filler such as "it's worth noting". Say the specific thing.+ - No "not just X but Y". State Y.+ - Lists don't need a serial comma ("a, b and c"), matching the rest of the repo.+ - No new runtime dependencies without an explicit trade-off note in the PR. The direction is fewer: wrap any dependency behind our own module so callers never import it directly, and replace it with our own code when that becomes cheap.+ - Never delete docs for something deprecated, renamed or changed in behaviour: people on old versions still look it up. Keep the old docs and mark them with the version where it changed ("Before 0.19…", "Deprecated in 0.19: use `squish`"). This covers READMEs, JSDoc, skills and the debuff.jp site, English and Japanese.