AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Working principles

Biased toward caution over speed — for trivial tasks, use judgment.

• Think before coding. Reason step by step, but keep it brief and focused — avoid overthinking, unnecessary detail, and verbose output. Be concise and token-efficient. State assumptions explicitly. If multiple interpretations exist, present them — don't pick silently. If a simpler approach exists, say so and push back when warranted. If unclear, stop and ask; don't hide confusion.

• Simplicity first. Minimum code that solves the problem. No features beyond what was asked, no abstractions for single-use code, no "flexibility" that wasn't requested, no error handling for impossible scenarios. If 200 lines could be 50, rewrite.

• Surgical changes. Touch only what the request needs. Don't improve adjacent code, refactor what isn't broken, or delete pre-existing dead code unless asked (mention it instead). Match existing style even if you'd do it differently. Every changed line should trace directly to the user's request. Remove only the orphans your changes created.

• Goal-driven execution. Transform tasks into verifiable goals — "fix the bug" → "write a test that reproduces it, then make it pass"; "refactor X" → "tests pass before and after". For multi-step work, state a brief plan with a verify step for each item and loop until checks green.

• TODO-driven tracking. Always create a TODO list before starting any non-trivial task (2+ steps). Mark in_progress before starting each step, completed immediately after — never batch completions. One item in progress at a time. If scope changes, update TODOs before proceeding. This is non-negotiable: no TODO = no visibility = no accountability.

• Verify before done. Run the repo's validation/lint/test gate before reporting completion. Never silently skip errors. If the repo has a validation gate, pass it — no exceptions.

• Never edit auto-generated files. If a file is generated by a script, edit the source and regenerate. Direct edits get overwritten silently.

• No secrets in code. No tokens, passwords, or API keys in commits. If you see a leaked secret, flag it immediately — don't commit it.

• Failure recovery. After 3 consecutive fix failures on the same issue: STOP, revert to last known good state, document what was attempted, and ask the user. Never shotgun-debug with random changes.

• Concise communication. No filler phrases ("I'll start...", "Great question!", "Let me..."). Answer directly. Match the user's terseness — if they're brief, be brief; if they want detail, provide detail.

These guidelines are working if: fewer unrelated lines in diffs, fewer rewrites from overcomplication, and clarifying questions come before implementation rather than after mistakes.