ai-spec

Write the spec

What it produces

specs/NNN-slug/spec.md, committed in the user's repository and visible in their diff. It is a decision record, not code, a plan or permission the agent gave itself.

The tier to ask for

Spec writing is mechanical once the research has done the hard thinking; ask the low tier, the model the repository's [models] section configures for it — never a model name coded here, and never a provider the repository did not choose. model_router maps research and spec to the low tier; if the pin leaves it unconfigured, fall back to default_tier. Say which tier you ran on so the command event's tier_model can be read against reality.

Procedure

1. Validate the intake and reach shared understanding before any discovery (spec 037 / B-037-3, spec 048): read references/intake.md first, then the goal, constraints and acceptance; ask only what the environment cannot answer, keep a live draft with a TODO per gap from the first answer, and do not scaffold until the owner confirms the two-sentence plain-words read-back; under an unattended goal the run records that read-back as unconfirmed and carries on. The input is the contract: a malformed goal produces a malformed spec.

2. Read CONSTITUTION.md, the related records and repository evidence and current primary sources relevant to the decision before asking anyone. State what was read, what is true now and what remains unknown. Never infer a control from its documentation alone. If CONSTITUTION.md is absent or incomplete, the spec records what is missing rather than assuming it exists — a repo without it is a repo without the framework's identity.

3. State the problem in words a non-technical reader can follow. Separate fixed constraints, current facts, intended outcomes and the harm of leaving it unchanged.

4. Present exactly three real options. For each, say what it gives, costs, risks and rules out; do not invent a weak option merely to lose.

5. Recommend one, explain why the others lose, then challenge the recommendation once with the strongest realistic failure case. Revise it or keep it and say why.

6. Record assumptions and unresolved risks separately. Do not turn either into fact or an accepted risk, and do not invent an owner, approval or green result.

7. Give observable BDD examples for the important success, denial and undecidable paths, using Given/When/Then and outcomes somebody can check.

8. Ask only questions whose answers change the decision, after presenting the evidence and provisional recommendation. A human answer overrides inference; update the options, recommendation and risks it changes rather than appending a contradictory answer.

9. Create the draft with ai-eng spec new <slug>; add --ref owner/repo#45 only when that is the real work item. If this supersedes shipped work, create a new spec, link the old record and explain the change; never rewrite history.

10. Architecture advice belongs inside the options, never beside them. Where a boundary, a dependency, a duplicated source of truth or the cost of reversing it decides between two options, say so in the option that carries it. A separate architectural opinion nobody has to answer is the advisor this project chose not to build.

11. Keep decisions in their spec unless they constrain future specs. For the ones that do — architectural and cross-cutting: a boundary (API, auth, storage) or a global convention later specs must know and respect — list them under ## Decisions marked - [X] and promote with ai-eng decide "<title>"; the verb promotes only marked titles, and proposal is not approval. Everything else stays inside the spec, which is its record. Leave every production-ready box unticked until the named command supplies fresh evidence.

12. When the critics report, fold them in place: the grill's questions into ## Grill and the council's gaps, cuts and refutations into ## Council, each section opening with its ran: round <n>, <date> — <n> min declaration, and revise the options, decision and risks those findings attacked rather than answering beside them.