AGENTS.md — governed by {ai} Engineering (ai-eng --version)

Guidance for AI coding agents working in this repository. Human teammates should be able to follow every line too. Only rules an agent CANNOT deduce from the code live here; if a rule becomes obvious from reading the code, delete it from this file.

Security

• Never bypass a git hook or a check: no --no-verify, no -n on commit, no HUSKY=0.
• Never silence a linter: no noqa, @ts-ignore, eslint-disable, nosec.
• No secrets, no personal data, no machine-specific absolute paths in any file.

Code style

• KISS, YAGNI, DRY, SOLID, TDD, Clean Code.
• Explain it so someone who doesn't code can follow along.
• Readable code (Boswell & Foucher): minimize the time it takes someone else to understand your code.
  • Names say purpose or value; no generic names (data, temp, helper are forbidden).
  • Prefix booleans (is, has, can, should); prefix limits (max, min).
  • Use positive conditions (if (isValid) over if (!isInvalid)).
  • Early returns over deep nesting; flat control flow wins.
  • Comments explain why, not what; never repeat the function signature in prose.
  • Explain "huh?" moments; skip the obvious.
  • One function, one job. Extract unrelated subproblems.
  • Write less code: rethink requirements, use stdlib, prune unused code.

Build and test commands

typecheck: bun run typecheck (oxlint --type-aware --type-check) · lint: bun run lint (oxlint) · test: bun test · arch: bun test tests/arch.spec.ts

Workflow

• Green gate before "done": show the output of the check that proves it.
• A decision that always comes out the same is code, not a prompt.
• Task status convention (when a todo list exists): mark each task 🟢 done (paste the proving output) · 🟡 pending (name the next action) · 🔴 blocked on you (ask the exact question). No todo list → state status inline: done-with-proof, pending, or blocked.

Lifecycle

• Every skill declares its own contract — lane, artifact, successor — in a ## Lifecycle block inside its SKILL.md: follow the Next: a skill hands you instead of asking what comes first.
• The lanes are light (spike and bounded work — no contract), standard (ai-brainstorm then ai-orchestrator) and full (architectural, with the triggered nodes).
• Approvals are spoken: when the human says approve, ok, or go, record that approval in the appropriate artifact and follow its next step. Never ask the human to type a command; never approve on your own initiative.

Architecture layers

You may edit src/** freely; the arch-test reads .ai-engineering/arch.rules.json — propose layer changes there via PR, never by editing the test in silence.

Voice

Replies to a person, and handoffs to another agent, follow the voice standard in the ai-write skill (references/voice.md). The file ships in the binary and is installed with the skill canon; this section is the part that has to be in context:

• First line is the action.
• More than one step is a numbered list, one action per step.
• Last line is one next action that takes under two minutes.
• Say which step just finished before starting the next.

Session hygiene (context economy)

/clear between tasks · /compact before stopping, not after · batch prompting · check /usage when the context inflates.

Where to work

• Work in the open checkout. Use a worktree only when requested or another feature is active; pause if work may overlap.
• Prefer host worktree support; otherwise run ai-eng worktree new <branch> and use its reported path. The person chooses or approves the branch.
• Resume in the feature checkout. Never stash, reset, overwrite, or remove foreign work; preserve uncertainty and ask.
• After review, offer a PR, local merge, or keeping the branch. Prefer PR with a forge remote, otherwise local merge; ai-eng worktree merge <slug> handles it.

Git workflow

See Where to work for checkout, worktree, and integration choices. .ai-engineering/recap.html is optional and never required for merge.

Pull requests

• Run lint and the full test suite before committing; the commit must pass everything it will face in CI.
• Add or update tests for the code you change, even if nobody asked.
• After moving files or changing imports, re-run lint and typecheck.
• Title format: <area>: <imperative summary> (e.g. chain: cache verdicts per tool_use_id).
• Commit messages: subject ≤ 50 chars; body explains WHY when it is not obvious.

Anti-drift

This list contains only what the agent CANNOT deduce from the project.