# AGENTS.md: Spec-driven workflow

For any feature bigger than a small fix, work through three documents in `specs/<feature>/` before writing code.

## 1. `spec.md` (what and why)
- Problem, users, and goals; explicit non-goals.
- User-visible behavior as numbered requirements (`R1: A signed-in user can export orders as CSV`), with acceptance criteria written as Given/When/Then.
- Edge cases and error states. Open questions at the top, marked `[?]`.
- No implementation details here. Ask the user to confirm the spec before continuing.

## 2. `plan.md` (how)
- Architecture and data model changes, APIs/contracts, libraries, and why. Reference existing code to reuse.
- Security, performance, and migration considerations.
- How each requirement (R1, R2...) will be verified.

## 3. `tasks.md` (steps)
- A checklist of small tasks, each tied to requirements, in dependency order, each with its test.
- Mark tasks done (`[x]`) as you complete them so work can resume in a new session.

## Implementing
- Do tasks in order. Write or update the test for a task first, then the code.
- If you discover the spec or plan is wrong, stop and update the document (and tell the user) instead of silently diverging.
- Keep commits per task, referencing the task.

## Done
All tasks checked, every requirement has a passing test, and the docs reflect what was built.