AlexOrd/agentic-factory

Spec Writer

A spec is a business contract, not a technical design. It answers: what outcome do we buy, how do we know we received it, and what must never break. Code is a lossy projection of the spec — the spec is the durable artifact.

Process

1. Read specs/TEMPLATE.md and create specs/<short-name>.md from it.
2. Interview the requester (or mine the ticket) until you can fill EVERY section without inventing anything. Ask one question at a time.
3. The acceptance criteria are the heart. Each criterion must be:
   • observable (a person or a test can check it),
   • binary (met / not met, no "mostly"),
   • written in business language (what the user gets, not how code works).
4. Explicitly write the out of scope list. An agent without a fence will happily build a second product.
5. Name the irreversible decisions (data migrations, public API shapes, deletions) — these are the human-approval gates.

Quality bar (self-check before finishing)

• Could a competent stranger implement this without asking you anything?
• Could QA verify it using only the acceptance criteria?
• Is every "should" replaced by "must" or deleted?
• Would the requester recognize their problem in the first paragraph?