Spec

Forward-design a handoff-grade spec artifact from a single upstream input, end-to-end. Read the input, draft the spec body covering all eight required semantic-contract elements plus the two spec obligations (machine-checkable acceptance criteria and a Degrees-of-freedom section), write the artifact into its lineage folder, and confirm its path. By default, run end-to-end without interviewing the user element-by-element, but honor an invocation that asks you to check in or work through the spec interactively; do not commit.

The spec is the centerpiece of the workflow and the last artifact the human reads and approves — it is written so the plan can follow mechanically. The spec stays alive from approval until implementation (it can be amended only via owner-approved, record-backed amendments) and freezes only at status.implemented; see ## Frontmatter Status Contract.

Inputs

Accept ONE of the following four input forms. Detect which form was passed before drafting:

1. A proposal artifact path — a proposal document on disk, typically proposals/NNN[-<desc>]/proposal.md in the active thread. The proposal is a common upstream input; it carries intent, context, and a rough shape that the spec elaborates into expected behavior, constraints, and acceptance guidance.
2. A decision-log artifact path — a record carrying one or more settled decisions with sequential ## P<N>: <Title> headings. Each settled decision becomes a citation in the spec body, NOT a copy-paste into a separate spec section — see ## Semantic Contract below.
3. A GitHub issue URL or identifier — accepted forms include a full URL (https://github.com/<owner>/<repo>/issues/<NNN>) or the short owner/repo#NNN form. The issue body becomes the upstream input; treat the issue title and labels as additional context.
4. A raw user prompt — when no artifact is referenced, the user's prompt is itself the input; the spec is forward-designed directly from it.

If the input is ambiguous — multiple plausible proposal lineages could be meant (proposals/001-api/ vs proposals/002-cli/), multiple decision logs cover overlapping topics, the issue identifier is incomplete, or the prompt references "the proposal" or "the spec" with no clear referent — ask the user which artifact is intended. There is no "highest number" or "most recent" fallback; do not silently pick by recency or by NNN.

Semantic Contract