/spec-draft

The authoring entry point of the planwright pipeline (REQ-B1.1): a Socratic, interactive elicitation that turns an idea plus its seed material into a compliant four-file bundle at <root>/<spec>/, Status Draft, committed on the spec branch. Drafting ends where comprehension begins: /spec-kickoff walks the Draft to sign-off and flips it Ready. This skill never pushes, never opens a PR, and never flips a status to Ready — sign-off is a human gate (doctrine/human-gates.md) it has no business near.

Doctrine

Resolve and read the manifest's rule docs below via the rule-doc resolution convention (scripts/resolve-rule-doc.sh <doc-name> or the documented PLANWRIGHT_ROOT/CLAUDE_PLUGIN_ROOT chain), per doctrine/instruction-hygiene.md: run-start entries before work begins, point-of-use entries at the step each names, so no bundle write happens before spec-format loads. Their definitions govern wherever this skill names a concept. A doc that does not resolve, at run start or its point of use, halts with a clear message naming it and the chain consulted (REQ-K1.7: a clear message is the graceful arm); decision-domains alone degrades instead, as Design step 3 says.

Doctrine: run-start interaction-style Doctrine: run-start research-rigor Doctrine: run-start security-posture Doctrine: run-start proportionality Doctrine: point-of-use spec-format (elicitation start — conventions + the bundle write) Doctrine: point-of-use engineering-decisions (the design phase) Doctrine: point-of-use customization-boundary (the design-phase capability-vs-style call) Doctrine: point-of-use autopilot-reflex (the altitude gate, Design step 3) Doctrine: point-of-use decision-domains (the design-phase catalog walk)

Pre-flight

1. Parse arguments. $ARGUMENTS carries the proposed feature name — free-form idea text by design (the name is a hint, D-22) — and optionally --extend <spec> (extend mode on an existing bundle; alias specs/<spec>, one trailing slash allowed). The feature name is not used directly: the skill derives the spec identifier (<spec>) from it, and that derived identifier is what appears in paths, branch names, and commands. Validate the derived identifier (and any identifier a seed or --extend proposes) against the anchored, full-string pattern ^[a-z0-9][a-z0-9-]*$, maximum length 64 (REQ-A1.8), never flight, before any such use. When the feature name is not already a conforming identifier, propose a conforming kebab-case variant and ask; nothing non-conforming is ever interpolated. No name given: elicit the idea first (seed gathering below) and propose a name from it. Resolve <root> and its posture per docs/spec-location.md; outside same-repo, its table governs <root>/<spec>, the git steps and walkthrough suggestion below. When --extend <spec> is present, additionally verify the target: <root>/<spec>/requirements.md must exist and its Status must be non-terminal. A nonexistent target gets a clear message listing the specs that do exist; a Retired or Superseded target is refused per the extend-mode terminal rule, up front rather than after elicitation starts.
2. Altitude routing (inception REQ-J1.2, D-16). Pitch-shaped input (independently ownable tracks, no candidate home repository, three or more discipline domains, or a pitch-form document) sits above a spec: recommend /inception with a one-line reason, drafting here the other option. Recommend only, never route; a decline drafts normally.
3. Detect the git state. Not a git repository: degrade per REQ-K1.7 — say so up front, elicit and write the bundle in place, and skip every branch/worktree/commit step below, surfacing at the end what was skipped and why. No remote configured: irrelevant here; note it only so the human knows /spec-kickoff's push step will degrade.
4. Read the config. commit_on_draft from config/defaults.yml overridden by <repo>/.claude/planwright.local.yml (local wins). Default true; an absent, unreadable, or malformed config file falls back to the default with a one-line warning surfaced immediately at this step — before any fallback-driven action (such as the auto-commit) can fire — and repeated in the handoff (REQ-K1.7).
5. Resolve the working location (D-44, graceful in every starting state). The spec branch is planwright/<spec>/spec (the reserved namespace the tasks-pr-sync hook no-ops on); the spec worktree is <repo>/.claude/worktrees/<spec>-spec (D-37 placement; the directory name disambiguates the literal branch suffix spec, which would collide across specs, while staying open to hand-launch claude --worktree <spec>-spec).
   • Already in the spec's own worktree: proceed. Dirty or diverged state: surface it and ask before touching anything — never auto-stash, auto-commit, or clean.
   • In the main checkout or an unrelated worktree: if the spec worktree exists, do not work here — print the re-open hand-launch (claude --worktree <spec>-spec) and stop. If the branch exists but the worktree was pruned, recreate the worktree from the branch (native mechanics below). If neither exists, create them: worktree via Claude Code's native mechanism (EnterWorktree — never raw git worktree, D-37), then git switch -c planwright/<spec>/spec inside it, branched from the current main view.
   • Worktree/branch resolution happens after the name is final — which for a fresh idea may be after seed gathering and fold-detection have run (both are read-only against the existing checkout).

Seed gathering (REQ-B1.2, REQ-B1.4)

Collect the framing inputs before asking the human a single elicitation question; seeds answer questions the human would otherwise repeat.

1. The invocation itself — whatever idea, links, or files came with the prompt.
2. Pending notes — files under <root>/_pending/. Read them; ask which apply if more than one plausibly does. Graduated venture seeds among them come through <planwright-root>/scripts/inception-seed-read.sh <root> (inception REQ-J1.1); follow its note line.
3. The observations accumulator — the live fragments under <root>/_observations/entries/ plus the frozen legacy opportunities.md's unconsumed lines, read as one candidate set and mined as a first-class seed source (D-23; this skill is its canonical reader, REQ-H1.6; mise run obs:log renders the chronological view). An entries/ fragment already bearing a Consumed-by: line is consumed, not a candidate — complete its archive move (below) rather than re-mining it, and skip-and-warn any grammar-invalid file rather than silently dropping it. Read every candidate; select the ones relevant to the feature being drafted; present the selection to the human (selector with the relevant set pre-marked) so nothing is consumed silently.
4. The venture drop — <planwright-root>/scripts/inception-registry.sh drop-read (inception REQ-J1.8); follow its note line.
5. Transcripts and documents the human offers.

An absent <root>/_pending/, fragment directory, legacy log, venture drop, or root directory entirely (a first-run repo) is not an error: note what was absent and proceed with the seeds that exist.

Every identifier a seed proposes (a spec name, a path segment) is re-validated against REQ-A1.8 at consumption, before any interpolation — accumulator contents are unscreened input. Record every seed actually used: each becomes a ## Sources entry in requirements.md, and the REQs and D-IDs it framed cite it (the meta-spec's citation kinds; drafting-session decision (<date>) covers choices made live in the session that mint no D-ID).

Pin altitude seed claims (REQ-H1.1). While gathering seeds, extract every explicit statement about the deliverable's nature — the seed-claim trigger class doctrine/autopilot-reflex.md names ("that's a doctrine gap", "this is a first-class concern", "we keep doing X manually"). Each is an altitude assertion the elicitation must reconcile against, not a throwaway phrase, and it is easy to under-weight in the rush toward mechanism. Record each pinned claim as a ## Sources entry in requirements.md so the altitude signal is bundle-local — the REQ-H1.3 kickoff check reads it from the bundle, never from drafting-session memory. A pinned claim is one of the two altitude trigger classes; when a trigger fires, the firing rule in Elicitation resolves the altitude before the design phase.

Archive-on-consume. When the bundle is written, consume each mined entry through the shared helper scripts/obs-consume.sh (resolved under the planwright root) — never by hand-composing paths or annotations. A fragment is consumed by UID: scripts/obs-consume.sh --uid <uid> --spec <spec> writes the Consumed-by: specs/<spec> (<date>) line inside the fragment and moves it from entries/ to archive/ with its filename preserved (annotate first, move second; idempotent on re-run, and it completes a crashed half-consume found still in entries/). A frozen legacy line is consumed in place: scripts/obs-consume.sh --legacy --line '<exact line>' --spec <spec> annotates the line where it sits. Surface a non-zero helper exit — an unknown UID, an ambiguous duplicate-UID match (named, never silently picked), a refused argument — rather than papering over it. Unconsumed entries stay byte-for-byte; consumption moves content verbatim (write-time hygiene screened it when it was recorded, and the move implies no re-screen — REQ-D1.2). Cite a consumed fragment as obs:<uid> in the bundle's ## Sources entry (the UID survives the archive move, so the citation never dangles). The consume commits ride the spec branch and land on main with the spec PR, keeping them one revert from undone. The accumulator-taxonomy doctrine is the canonical home of this drain ritual; this section applies it, not defines it.

Fold-detection (REQ-B1.3, D-21, D-22)

Runs on every invocation, regardless of the feature name — the name is a hint, not a command. Skipped only when --extend already named the target.

1. Scan every existing spec under <root> (any non-terminal status: Draft, Ready, Active, Done). Read each bundle's requirements.md Goal and Scope sections — bounded by design; the overlap signal lives in goal/scope. A malformed bundle (missing requirements.md, unparseable header) is skipped with a notice naming it; the scan never halts the session over someone else's broken bundle (REQ-K1.7 — the validator owns reporting it).
2. Judge semantic overlap between the new idea and each scanned spec: same problem domain, same external interface, same decision space.
3. On overlap, check D-21's spin-new triggers: the new idea introduces a new external interface; is independently ownable; forces decisions orthogonal to the bundle's domain; or would push the bundle past "one feature a reader holds in their head".
4. Overlap and no trigger fires: surface an extend recommendation — a selector naming the overlapping spec, why it overlaps, with extend as the recommended option and spin-new as the alternative. The human decides. Never auto-fold; never silently obey the name over a clear overlap.
5. No overlap, or a trigger fires: proceed as a new bundle, noting in one line what was scanned and why nothing folded.

Extend mode

Entered via --extend <spec> or the human accepting the recommendation. Extend mode follows the target bundle's declared Format-version: (invariant-tasks D-7): a v1 target keeps every v1 convention unchanged — new task blocks join ## Forward plan, the v1 state sections stay — while a v2 target takes the v2 shape (new blocks join ## Tasks in dependency order; no placement sections or state annotations are ever written to it), and a v3 target takes that shape plus the optional Repository: field (a v2 target whose extension adds one bumps its declaration to 3); an unparseable target Format-version: is refused — fail closed, never the v1 conventions (D-7). Operates on the existing bundle per the meta-spec's stable-ID discipline:

• Append, never renumber. New REQs and D-IDs continue the existing ID space; dotted task ids insert between existing tasks.
• Supersede what changes meaning. A changed requirement or decision mints a new ID adjacent to the old, old marked Superseded-by; bodies of superseded records are never edited (D-20).
• Grow test-spec.md with entries for every new REQ; re-sync tasks.md (new task blocks per the declared version above, dependency lines updated); append a dated Changelog entry describing the extension.
• Reopen cycle (REQ-A3.1): extending a Done bundle flips its stored Status to Draft on all four headers — a v1 bundle stores Done, so the write is Done→Draft; a v2 bundle derives Done over a stored Ready, so the write is Ready→Draft — and the scoped kickoff of the delta flips it back to Ready, the delta's first dispatch deriving Active. Extending an Active bundle leaves its stored status untouched — the delta is Draft content inside it, and /spec-kickoff's delta re-walkthrough is the sign-off path; say so in the handoff. Retired and Superseded are terminal: refuse, suggesting a new bundle citing the old as a Source.
• Extension work happens on the spec's own branch/worktree, same as a fresh draft.

Elicitation

Six phases, each governed by the interaction-style rules: show the progress indicator ([<phase> <n>/6]), work in small bites, present decisions as selectors with a recommendation, and end each phase with the running summary in delta-plus-open form: the decisions since the previous summary, their one-line rationale, and what remains open, never a restatement of everything so far (interaction-style's Running summary rule under the turn/artifact arbitration; the bundle on disk is the cumulative record). Each such projection (a phase summary, the read-through below) is mirrored into the structured decision/transcript log as a turn record (D-19). Per the phase re-anchor (doctrine/autopilot-reflex.md, REQ-H1.2), the summary also restates the claimed altitude and flags any drift between the claim and what the elicitation is currently producing ("the seed claimed doctrine; the last phase produced only mechanism tasks"). The restatement is cheap; its absence is how a session silently slides altitude. Before phase 1, resolve and read spec-format (its point-of-use read): the meta-spec defines every structural convention referenced here and governs the Completion bundle write; follow it exactly so the bundle passes the validator the first time.

1. Goal & scope. The problem, the one-paragraph goal, in-scope / out-of-scope lists. Elicit what the feature must not do — out-of-scope entries prevent more drift than REQs do.
2. Requirements. Thematic REQ groups (## REQ-<Group> — <theme>), each requirement a single SHALL/MUST bullet with a stable ID and a citation. Derive candidate REQs from the seeds and goal, present per group for correction; the human supplies judgment, not formatting.
3. Design. Altitude gate first (REQ-H1.1). Resolve and read autopilot-reflex now (its point-of-use read). Before designing any mechanism, check whether an altitude trigger has fired — a pinned seed claim (seed gathering above) or a mid-flow signal surfaced during elicitation (a recurring capability-vs-style call, an "is this even core?" hesitation, a mechanism acquiring rules that read like doctrine): the two trigger classes doctrine/autopilot-reflex.md defines. If one has fired, resolve the deliverable's altitude now, and record the call as an early altitude D-ID cited from the bundle's goal (the trigger-scoped altitude record the doctrine requires — a conversational resolution with no artifact can be pencil-whipped, so the D-ID is what the REQ-H1.3 kickoff check verifies). Designing first and retrofitting the altitude is how a doctrine deliverable ends up specced as a one-repo script. No trigger fired: no record is required (per proportionality, the ceremony is scoped to the specs that exhibited the risk) — proceed. Then resolve and read engineering-decisions (its point-of-use read; it governs this phase's recommendations) and record, for each load-bearing choice, a D-ID with all three fields (Decision / Alternatives considered / Chosen because). This phase fires Research Rigor triggers (new dependency, unfamiliar domain, security-touching pattern, version-sensitive API, mature-project comparison): research before recommending, cite what was consulted. Capability-vs-style call: when a choice is whether a preference belongs in core or in an adopter/team overlay, resolve, read, and apply customization-boundary (its point-of-use read) — does the general capability land in core as an opt-in, default-preserving config knob, while the specific value/style stays in an overlay? Default tilt is overlay when in doubt; a preference graduates to a core knob only with drain-loop evidence that it generalizes. Builder hook point: walk the decision-domains catalog for domains the feature touches; flag any the spec touches but does not decide, and escalate stake-bearing decisions (authn/z, data modeling, security posture, integration surface) as explicit design decisions — never auto-default them. Walk the catalog's prose seed (doctrine/decision-domains.md, the normative full text) and any adopter/team/machine-local additions via the merged path scripts/resolve-catalog.sh decision-domains, so overlay domains apply too rather than a single-layer read (REQ-D1.1). When the planwright builder skill exists it plugs in here (stack detection, guard recommendations); until then the catalog walk is the manual form and a missing catalog doc degrades to a one-line notice. Hook point and catalog scan, not a dependency: drafting works without the builder.
4. Tasks. Decompose into task blocks with the five definition fields (Deliverables / Done when / Dependencies / Citations / Estimated effort); IDs stable from birth. Done when: conditions an agent can evaluate. All blocks land in a single ## Tasks section in dependency order, and the three human-payload sections (## Awaiting input, ## Deferred, ## Out of scope) are written with (none yet) placeholders — no placement sections and no state annotations: a block carries its five definition fields and nothing else, because execution state is derived, never authored (invariant-tasks D-2). Dependency edges are load-bearing (orchestration selection reads them): ask about ordering the human knows and the text doesn't show — in particular, tasks whose deliverables gate other tasks' verification (CI, guards, validators) should carry explicit edges from the tasks they protect, or they dispatch too late. When the elicitation surfaces a second repository (a task whose code lives outside the bundle's work repository), offer that task the optional Repository: field: one alias per block, resolved only through the machine-local work-repository registry, never a path or URL (spec-format Format-version 3); work spanning repositories splits into tasks joined by dependency edges.
5. Test-spec. Every REQ pinned to at least one verification path, tagged [test] / [manual] / [design-level] / [Gherkin] (mixed: [test + manual]). Prefer [test] where automation is honest; say which CI runs it.

6. Review & validate. Assemble all four files (shared header block, **Status:** Draft, **Last reviewed:** <date>, **Format-version:** 2 (**Format-version:** 3 only when some task names a repository), and — fixed vocabulary, on all four files (D-5) — the canonical pointer line **Execution:** derived — see the status render).

   Self-critique pass (REQ-C1.1, D-7). Before the validator runs and before commit, run one scoped self-critique lens pass over the freshly assembled bundle: assume the draft is incomplete and re-read it for gaps, contradictions, uncited claims, mis-scoped or unverifiable REQs, dangling citations, and missing edge cases (doctrine/discovery-rigor.md's self-critique pass, applied to the assembled bundle rather than a diff). Declared scoping (proportionality): this pass is inline, not a Discovery-Rigor fan-out — the Draft bundle gets the heavyweight lens fan-out at /spec-kickoff activation, so a fan-out here would spend the rigor budget twice (D-7); the lighter inline pass is the proportional form where a human review still follows. Disposition every finding — never silently drop one: either fix it in place in the bundle, or surface it to the human as an open question in the read-through summary below. A pass that cannot complete (it errors) is surfaced as an erroring pass, never treated as a clean one.

   Enumeration cross-check (REQ-E1.2). In the same pass, flag every enumerated count and corpus claim in the bundle, and either verify it against the surface it enumerates or convert it to a decided rule, per spec-format's Decided rules over enumerated claims. Drafting is where the count is born.

   Then present the read-through as a projection, never the assembled bundle (interaction-style, the arbitration): the bundle on disk is the artifact; the turn carries a bounded excerpt (the goal and the section headings with counts), the self-critique dispositions as counts plus the open questions surfaced to the human (an erroring pass named as such, never counted as clean), and the delta-plus-open summary, with the full disposition list one request away. Run scripts/spec-validate.sh <root>/<spec> when present and executable (findings are warnings on Draft: surface them, fix structural ones, let the human defer judgment ones); validator absent: note it and continue — authoring is a graceful-degradation path (REQ-K1.7), and /spec-kickoff enforces before anything executes.

Data hygiene throughout (REQ-D1.6): no secrets, credentials, internal hostnames, or sensitive operational detail in any committed artifact — spec files, Sources entries, archived observations. Seeds may contain them; committed prose neutralizes them.

Completion

1. Write the bundle at <root>/<spec>/ in the spec worktree (plus the _observations consumption writes — fragment moves into archive/ and any frozen-legacy in-place annotations — when entries were consumed).
2. Neutralize machine-local references (REQ-D1.1, REQ-D1.2, D-4). Before committing, rewrite every [[name]] memory-link token in would-be-committed spec prose into plain prose plus a ## Sources pointer. A [[name]] link resolves only against the authoring session's private memory store, never for a reader of the committed bundle, so state the fact in prose and cite the source: a recorded observation carries a fragment UID and is cited as obs:<uid> (the Observation citation kind — see Archive-on-consume above), while any other machine-local reference — including an unconsumed frozen legacy line, which has no UID — becomes a ## Sources entry naming the source. When the prose must mention the token syntax itself (a spec about this rule does), wrap the mention in an inline code span (`[[name]]`) so it reads as documentation, not a live link. This is mechanically backstopped: check:memory-links (scripts/check-memory-links.sh, under mise run check) flags any bare [[name]] token in a committed spec file, so a draft that skips this step fails CI rather than shipping an unresolvable reference.
3. Commit (D-41) when commit_on_draft is true: one commit on planwright/<spec>/spec containing the four files and the _observations consumption writes, message feat(spec): draft specs/<spec> bundle (extend mode: feat(spec): extend specs/<spec>, <summary>). Rewriting the spec branch is a human gate (doctrine/human-gates.md). Opt-out set: leave the work uncommitted and say so explicitly.
4. Hand off. Report: the bundle path and branch, validator outcome, seeds consumed (and archived), fold-detection outcome, and the next step — /spec-kickoff specs/<spec> for the walkthrough and sign-off.
   • Optionally recommend /spec-walkthrough specs/<spec> for an unaided, plain-language read before sign-off (REQ-F1.1, REQ-F1.2, D-11) — a suggestion only, never a step this skill performs.

Maintenance

After the run completes (or halts), compare these instructions against the resolved doctrine docs listed above (REQ-B3.2, D-42) — especially spec-format (file conventions, citation kinds, status lifecycle) and interaction-style. If a concept this skill names has changed meaning, gained or lost a step, or moved between docs, record a one-line drift observation through the shared helper (scripts/obs-record.sh --slug skill-drift --scope <repo> --text 'skill-drift(spec-draft): <what>' — the entry text keeps the skill-drift(...) prefix) and commit the fragment as its own chore commit, per REQ-B3.2 / D-42; surface a non-zero helper exit rather than silently dropping the observation, and tell the user what drifted. In repositories without specs/, surface the drift to the user instead of recording it. Do not edit this skill or the doctrine docs to resolve the drift; the accumulator's canonical reader (/spec-draft) owns folding drift into spec amendments.