ad-spec

<background_information> Drafts doc/specs/<NNNN>-<short-slug>.md for one feature. Status lifecycle: draft → accepted → shipped | superseded by SPEC-NNNN. Spec is the layer-4 artifact in the kit's six-layer stack — Constitution (AGENTS.md + WORKFLOW.md) → Domain (CONTEXT.md) → Product (doc/product/PRD.md) → Spec (this skill) → Plan/Decisions (ARCHITECTURE.md + doc/adr/ + doc/tasks/) → Code. Multiple tasks implement one spec; ADRs may be driven by spec constraints. The Domain layer (ubiquitous language per Evans 2003) is the source of canonical nouns the spec must use; if the spec introduces a new noun, resolve it through CONTEXT.md first. The Product layer (PRD) is the source of target user, product-level success metrics, and cross-feature constraints the spec inherits from.

Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire when the user asks to "draft a spec" for a single feature, invoke this skill manually. If the user asks for a "PRD" or "product requirements" — route them to ad-prd instead; PRDs are Layer 3 (product-level), not feature-level. </background_information>

Step 2 — confirm scope. The spec captures one feature. If the user's request implies multiple, ask which to write first; the others become follow-up specs. A "feature" here is the smallest user-visible outcome that has its own success criteria — not a task (work unit) and not a binding architectural decision (ADR).

Step 3 — interview to fill. Ask one question per missing field, in this order:

• Context: business context first per ADR-0008. Why the feature exists, the user / constraint / problem it addresses, the cost of not building it.
• User Scenarios: Given-When-Then for the key flows. Each scenario independently testable.
• Functional Requirements: testable statements. Plain bullets (no checkbox — Spec is decision-record per ADR-0030 §1; implementation tracking lives in per-Spec tasks).
• Non-functional Requirements: perf / security / a11y / observability — only when binding.
• Success Criteria: measurable per WORKFLOW.md §1. Plain bullets; pass/fail observable, not aspirational. Per-criterion progress tracking lives in per-Spec tasks.
• Edge Cases: empty inputs, large inputs, concurrent access, missing prerequisites, permission errors.
• Out of Scope: explicit non-goals.
• Open Questions: deferred decisions. Each becomes an ADR or a documented punt.
• Related: ADRs touched, tasks implementing it (lazy), other specs this one supersedes or depends on.

Status starts at draft. Created: today, ISO format. Owner: ask. Do NOT invent values; leave <TODO> and ask.

Step 4 — write the file. Path: doc/specs/<NNNN>-<short-slug>.md. Use the template below.

Stop after writing. Do NOT flip status to accepted — that requires user review.

Step 5 — editing guidance for later turns. Append to Open Questions; close with resolution paragraphs, never delete. Flip Status to accepted on user sign-off; shipped once all per-Spec tasks complete; superseded when replaced. Add tasks to Related as they are created. Implementation tracking (per-criterion progress) lives in per-Spec tasks, not in the Spec. Never rewrite existing prose — append rationale to Open Questions rather than mutating original requirement text.

Status: <draft | accepted | shipped | superseded by SPEC-NNNN> Created: <YYYY-MM-DD> Owner: <name or role>

Context

<Why this feature exists. The user, the constraint, the problem. What would break if this feature did not ship.>

User Scenarios

<Given-When-Then for the key flows. Each scenario independently testable.>

• Scenario 1: <short title>
  • Given <starting state>
  • When <action>
  • Then <observable outcome>

Requirements

Functional

• <R1: testable statement>
• <R2>

Non-functional

• <perf / security / a11y / observability — only when binding>

Success Criteria

Definitional. Measurable conditions; pass/fail observable, not aspirational. Per-criterion progress tracking lives in per-Spec tasks.

• <criterion 1: measurable, observable>
• <criterion 2>

Edge Cases

• <empty input behavior>
• <large input / failure modes>
• <permission / concurrency / state-restoration cases>

Out of Scope

<Explicit non-goals. Anything readers might assume is in scope but isn't.>

Open Questions

<Deferred decisions. Each becomes an ADR or a documented punt.>

Related

• ADRs: <list with links — written as the spec is accepted>
• Tasks: <doc/tasks/NNNN-... — appended as tasks are created>
• Supersedes / Depends on: <other spec links if any>

<output_contract> A single new file at doc/specs/<NNNN>-<short-slug>.md. Status draft. Tasks list empty (filled lazily as tasks land). No existing specs modified. No invented values.

Spec is a narrative document but is exempt from ADR-0008's no-dates rule for the same reason ADRs and tasks are: the Status lifecycle and Created field are part of the auditability primitive. Remaining documentation discipline rules apply at write time:

• No emoji anywhere in the file.
• Context is the business-context-first section — why the feature exists before what it does.
• One scope: one feature per spec.
• No speculation. Open Questions go in their named section.
• No commented-out requirements or TODO/FIXME — every deferred item references a tracked work item or lives under Open Questions. </output_contract>

Next

• /ad-ground for the four-source research pass before code (WORKFLOW §4 + §5).
• /ad-task to break the spec into work units; each task carries a Spec ref field pointing back to this file.
• /ad-adr if scoping the spec surfaced a binding architectural decision.
• Flip Status to accepted once you sign off and tasks start being created. Flip to shipped after release.