AGENTS.md

1# `.spec` Agent Guide
2 
3Use this folder to maintain authored Spec Led Development subjects and generated state.
4 
5<!-- covers: spec.workspace.agents_present spec.workspace.agent_prime_context -->
6 
7## First Read
8 
91. Read `.spec/README.md`.
102. Read `.spec/decisions/README.md` and any ADRs that affect the subject you are changing.
113. Read the current `.spec/specs/*.spec.md` files before editing.
12 
13## Working Rules
14 
15- Keep one subject per file.
16- Put normative statements in `spec-requirements`.
17- Add `spec-scenarios` only when `given` / `when` / `then` improves clarity.
18- Add `spec-meta.decisions` only when a subject depends on a durable cross-cutting ADR.
19- Keep ADRs in `.spec/decisions/*.md` for cross-cutting policy only.
20- Prefer targeted command verifications for behavioral proof.
21- Use file-backed verifications only when the target can carry stable `covers:` markers for every covered id.
22- Keep verification targets repository-root-relative.
23- Use Git history and pull requests as the change log; keep `.spec` current-state only.
24- At session start, run `mix spec.prime --base HEAD`.
25- After code, docs, or tests change, run `mix spec.next`.
26- For bug fixes, prefer `mix spec.next --bugfix`.
27- If next says `needs subject updates`, update the named subject before you finish.
28- If next says `ready for check`, move to `mix spec.check --base ...`.
29- Use `mix spec.validate --debug` when you need low-level verifier output.
30- Run `mix spec.status` when you need coverage or weak-spot summaries.
31