# 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: the human says approve, ok, go or close, and **you** run `ai-eng spec approve` or `ai-eng spec close` underneath. Never ask the human to type a command; never run an approval 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.

## Git workflow
- A session that writes code works in `<repo>.worktrees/<slug>` on the branch `feat/<slug>`, cut from the local `main`. A session that only reads opens no worktree.
- The merge destination is the local `main`, never `origin`: rebase inside the worktree, then, from the primary tree on `main`, `git merge --no-ff feat/<slug>` — one merge commit per feature, the one undoable unit.
- A build session never pushes: the only push is the pull-request step the human triggers, against `origin/main`, cut from the local `main` without a worktree.
- A build session does not touch the primary tree; only the merge step writes there, once, after that session's branch has merged.
- The design artifacts `.ai-engineering/brainstorm.html`, `.ai-engineering/spec.html` and `.ai-engineering/plan.html` are written and committed in the primary tree before any worktree is cut, and no worktree ever stages them.
- `.ai-engineering/recap.html` is generated at the app review on the feature branch and reaches the primary tree with the merge.
- A session may edit the shared files on its own branch like any other change, and the merge step is their single writer in the primary tree, never a parallel session writing them there: `.ai-engineering/PRD.html` when the feature changes scope, plus `CHANGELOG.md`, `LEARNINGS.md`, `FILEMAP.md` and `PERMISSIONS.md`.

## 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.