Writing specs with AI

For product managers, engineering managers, and anyone whose job is stating intent. No IDE, no terminal, no YAML expertise required.

An onspec spec is a short structured file: what the feature does, stated as criteria a machine can check. You don't write that structure by hand. You describe the feature to an AI assistant, it drafts the file, and your judgment goes where it matters: answering the questions the structure forces. What's the actual pass/fail behavior? What is this feature deliberately not doing?

The prompt

Paste this into Claude, ChatGPT, or any assistant, then add your feature description at the bottom.

spec drafting prompt
You are helping me draft a spec for onspec (onspec.sh): a markdown file with YAML frontmatter defining acceptance criteria for a software feature. My team will review it in a pull request, and it will then be verified automatically against the code, so every criterion must be a single, concretely checkable behavior.

Rules:
- Output one complete file in a code block, nothing else after your questions are answered.
- Frontmatter fields: id (placeholder SPEC-XXXX), title, status: draft, covers (path globs if I name code areas, otherwise a single "TODO-engineering-to-fill" entry), criteria, invariants, non_goals.
- Each criterion: id (C1, C2, ...), text (one observable behavior a test could pass or fail), verify: test, and NO evidence field. Engineers anchor criteria to tests during implementation.
- Reject vague wording in criteria: no "fast", "user-friendly", "properly", "seamless", "handle gracefully". Behavior, inputs, outputs.
- If my description is ambiguous or incomplete, ask me up to 3 clarifying questions BEFORE drafting. Prefer asking over assuming.
- non_goals are required: what this feature deliberately does not do, from my description or your questions.
- Do not invent numbers, limits, or behaviors I did not state or confirm.
- Below the frontmatter, add a short context section: why this exists, key decisions, anything a future maintainer needs.

My feature description:
[describe your feature here]

What "checkable" means

The whole system rests on criteria a machine can decide. The assistant enforces this, but you'll review its work, so calibrate your eye:

✗ vagueExport should be fast and handle large files gracefully.
✓ checkableExporting 50,000 rows completes without error and produces one row per record.
✗ vagueArchived records are handled properly.
✓ checkableArchived records appear in the export when include_archived=true; the default export excludes them.

The non_goals list is just as load-bearing: it's the fence that keeps an implementing agent from over-building, and the record of scope decisions your team actually made.

From draft to merged, in the browser

  1. Open your repo on GitHub → specs/ folder → Add file → Create new file. Name it something like csv-export.spec.md, paste the draft.
  2. Propose the file. GitHub turns it into a pull request. This PR is where your team debates the intent, in rendered markdown, with comments, like any document review.
  3. Engineering fills the blanks during review: the real covers globs, the spec id, and later, evidence pointers as tests get written. onspec lint grades the spec's readiness.
  4. Approval is explicit. When the team agrees, the status line changes to approved in the reviewed PR and it merges. From that moment the spec governs the code, and every future change to covered code is checked against it.

If your team runs the dispatch workflow, that merge also opens the implementation work order automatically. Your spec doesn't describe the work. It is the work.

Two habits that keep the system honest