Skip to content

AGENTS.md

Latest commit

 

History

History
78 lines (61 loc) · 3.44 KB

AGENTS.md

File metadata and controls

78 lines (61 loc) · 3.44 KB
Raw

AGENTS.md

Canonical agent instructions for this repository. Behavioral rules live in the shipped layers — skills carry judgment (skills/do-it/do-it-code-quality), hooks carry numbers (hooks/write-quality-lint.sh), validators carry drift contracts (scripts/validate-*.mjs). This file holds only what cannot ship: repo-local facts for agents working on do-it itself.

File rules

  • Source and this file are English-only. Paired end-user docs stay bilingual (README.md / README.zh-CN.md, CONTRIBUTING.md).
  • Read and write source as UTF-8 without BOM.
  • Do not read files larger than 30 KB in full; use targeted reads or grep. (install/manage.mjs is over this limit.)

Repository

do-it is a cross-host agent-behavior plugin: skills, advisory/blocking hooks, and read-only subagents shipped to Claude Code, Codex, Cursor, OpenCode, Kimi Code, and Pi from one source tree.

Contribution rules (dogfood-first, issue-first, PR template) are load-bearing: CONTRIBUTING.md. Changes without an observed real-world problem get pushed back.

Source of truth vs build artifacts

Source of truth: skills/do-it/, hooks/, agents/*.toml, commands/, install/, scripts/, tests/.

Never edit build artifacts directly; rebuild them instead:

  • plugins/*/ — per-host bundles, regenerated by npm run build:generated plus node scripts/build-<host>-plugin.mjs (codex script writes plugins/do-it/).
  • index.json, plugins/*/skills/_index.md — generated indexes.
  • .do-it/runtime/ — session state; .pi-subagents/ — run artifacts.

Closed-set contracts

These drift checks run in npm test; touch one side and you must touch all:

  • Quality families — hooks/data/quality-families.tsv ↔ hooks/lib/write-quality-scan.sh ↔ skills/do-it/references/write-quality-families.md ↔ tests/hooks/ (validate:quality-families).
  • Keyword tables — hooks/data/*.tsv are data-only. Project overrides (<cwd>/.do-it/keywords.local.tsv, <git-root of edited file>/.do-it/write-quality.local.tsv) are data-only too: hooks read them line by line and never source project files. Precedence for numeric limits: env var > project file > default.
  • Hook JSON contract — hooks read host JSON on stdin and emit host-shaped JSON; a misconfigured environment must never crash a hook (advisory hooks exit 0).
  • Core single voice — hooks/data/execution-failure-modes.tsv (rule sentences) ↔ skills/do-it/do-it-core/SKILL.md (renders them) ↔ hook emission (router.sh, verification-gate.sh quote the TSV, never embed rule text) ↔ bridge constants (plugins/do-it-pi/extensions/index.ts, OpenCode bundle data) ↔ satellite skills cite core §<rule_id> instead of restating (validate:core-consistency).

Commands

npm run lint:hooks                 # shellcheck the hook scripts
npm run test-hooks                 # hook regression suites (bash)
npm run check:skill-links          # skill cross-reference integrity
npm run validate:quality-families  # family registry/scanner/docs/tests sync
npm run validate:core-consistency  # core-rule registry ↔ skill ↔ hooks ↔ bridges sync
npm test                           # full gate: builds + validators + all tests

Verification

Build + test must pass (npm test, or the narrowest suite covering the changed surface) before claiming done. Report the exact command and result; if unverified, say NOT_VERIFIED with the missing proof.