/spec-kickoff

The comprehension layer of the planwright pipeline (REQ-B2.4, REQ-B2.2): a section-by-section walkthrough of a spec bundle until human and agent hold the same understanding, recorded as <root>/<spec>/kickoff-brief.md — the durable contract (two-brief model, D-3). Downstream skills (/execute-task, /orchestrate) operate from the brief, not the spec; what this walkthrough gets wrong, execution gets wrong.

Sign-off is the first key of a two-key launch (D-44): it flips the spec Draft→Ready and, on a clean completion, marks the spec PR ready (D-6, D-7; the walkthrough is the bundle's review). The human's merge is the second key, making the Ready spec operational (the first dispatch derives Active, not this skill). This skill marks only the spec PR ready, never merges, never dispatches execution.

Doctrine

This skill is procedure, not doctrine. Resolve and read the run-start rule docs via the rule-doc resolution convention (scripts/resolve-rule-doc.sh <doc-name> under the resolved planwright root); their definitions govern wherever this skill names a concept:

• security-posture — artifact data-hygiene.

Invoking plugin scripts (REQ-D1.1, D-7). Call scripts/<name>.sh by the resolved literal absolute path, never $VAR/scripts/<name>.sh — doctrine/plugin-script-invocation.md.

spec-format (pre-flight step 2) — the meta-spec: bundle format, status lifecycle, amendment ritual, sign-off records, content anchors, and sanctioned anchor command forms. This skill is the writer its sign-off rules name; it follows them exactly. Three more, at Sign-off step 1:

• discovery-rigor — the lens checklist, coverage table, and fan-out behind the lens review.
• autopilot-reflex — the altitude gate (D-11) behind the altitude check.
• validation-rigor — validation of lens findings before disposition.

If any of those five does not resolve — at run start or point of use — halt naming the missing doc and the chain consulted (REQ-K1.7). The rest degrade gracefully instead:

• decision-domains — the gap check's catalog. Absent: note it in one line, skip the gap check, and record the skip in the brief.
• interaction-style — governs the flow's exchanges; kickoff-dialogue (point-of-use) records their /spec-kickoff instantiation. Either doc absent: follow the inline summary (progress indicator, small bites, selectors with a recommendation, delta-plus-open running summary, one-line resume confirmation) and the walk/sign-off spine below, and note which is missing.
• kickoff-verification — the kickoff lens/verification mechanics: the mid-walk lens, the stale-reference sweep and sign-off lens-review scope, fan-out, altitude and ship-gate checks, and the terminal ready-flip CI gate. Each pass's load-bearing spine stays inline. Absent: run each from that spine and its halt-if-absent base (discovery-rigor, autopilot-reflex), and skip the ready-flip, leaving the PR draft (fail closed).

Doctrine manifest (the reading model above in machine-parseable form, per doctrine/instruction-hygiene.md; run-start loads before work begins, point-of-use loads at the named step or branch):

Doctrine: run-start security-posture Doctrine: run-start interaction-style Doctrine: point-of-use spec-format (pre-flight step 2) Doctrine: point-of-use discovery-rigor (the sign-off lens pass) Doctrine: point-of-use autopilot-reflex (the sign-off altitude check) Doctrine: point-of-use validation-rigor (lens-finding validation) Doctrine: point-of-use decision-domains (the sign-off gap check) Doctrine: point-of-use kickoff-verification (kickoff lens/sweep passes and the ready-flip gate) Doctrine: point-of-use kickoff-dialogue (discipline instantiation, approval summary, structured-log emit)

Modes

Modes, selected at pre-flight from status and brief state:

• First activation (Draft, no signed brief — or a partial one, see resumability): the full walkthrough through first sign-off, the Draft→Ready flip, push, draft PR, and — on clean completion — the terminal spec-PR ready-flip (sign-off step 8).
• Delta re-walkthrough (Ready or Active, signed brief): entered when pre-flight step 2's freshness comparison finds changed spec content (the remedy REQ-F1.9's gate names) or the human asks. Walk only the delta; the lens pass is delta-scoped; the outcome is an appended amendment-log entry with a fresh anchor.
• Amendment (Active; human-declared, never inferred): the REQ-A3.3 meaning-class vs expression-only split, applied at sign-off (sign-off steps 1 and 5).

Change-handling scales with the lifecycle stage (REQ-D1.4). A Ready bundle takes pre-merge changes through a delta re-walkthrough / re-sign-off, not the amendment ritual, the spec PR staying as it was; the amendment ritual is reserved for an Active bundle (work in flight). A Done bundle reopens to Draft first (the REQ-A1.6 reopen cycle below) — never amended in place. The per-class ritual detail is spec-format's amendment ritual.

A reopened bundle (Status Draft with a complete signed brief — the REQ-A3.1 / REQ-A1.6 reopen cycle) is a scoped kickoff of the delta, not a first activation: walk the extension delta in the delta re-walkthrough shape, and the sign-off flips Draft→Ready again (the delta's first dispatch derives Active). A Done spec has nothing to kick off: point at /spec-draft --extend. Retired and Superseded are terminal: refuse — no skill-driven transition leaves them.

Pre-flight

1. Parse $ARGUMENTS. Resolve <root> and its posture per docs/spec-location.md; outside same-repo, its table governs every git step, <root>/<spec>, and walkthrough suggestion. Expect a bare <spec> (alias specs/<spec>, one trailing slash allowed). Validate the mapped identifier against the anchored, full-string pattern ^[a-z0-9][a-z0-9-]*$, maximum length 64 (REQ-A1.8), before it appears in any path, branch name, or command; a failing identifier is never interpolated. No argument: list the bundles under <root> (underscore-prefixed accumulators are not bundles) and ask.
2. Verify the bundle and select the mode. All four files must exist (requirements.md, design.md, tasks.md, test-spec.md). A missing file or unreadable status is a structural defect: surface it and point at /spec-draft. Resolve and read spec-format here. Read the **Status:** line:
   • Draft → first activation; a resume when step 6 finds a partial brief; a reopened-bundle delta kickoff when the brief is complete and signed (per the Modes section).
   • Ready or Active with a signed brief → run the freshness comparison: parse the brief's most recent anchor entry, recompute the anchor over <root>/<spec> with the command it records, and compare. Mismatch → delta re-walkthrough; derive the delta from the four spec files' git history since the entry plus any uncommitted changes, and confirm scope with the human first. Match → nothing is stale; ask what the human brings (a re-walk on request, or — on an Active bundle — an amendment, always human-declared; a Ready bundle's pre-merge change is the delta re-walk path, REQ-D1.4). On a format-version 2 bundle the stored header rests at Ready, so distinguish Ready from Active via the render (scripts/spec-status.sh, path per the guide), never a stored Active. Brief or anchor entry absent, unparseable, or non-sanctioned → the sign-off record needs creating or repairing; this skill's sign-off flow is the repair REQ-F1.9 names: walk it as a whole-bundle delta re-walkthrough (a missing brief gets the full first-activation structure minus the already-done flip).
   • Done / Retired / Superseded → per the Modes section.
3. Run the validator. scripts/spec-validate.sh <root>/<spec> when present and executable. Draft findings are warnings: surface them, fix structural ones with the human before walking, and record the outcome for the brief header. Ready or Active findings are errors (status-aware — Ready blocks on errors exactly as Active does): surface them and carry each into the walk as a must-fix item; the delta walk fixes them, and sign-off step 4's re-validation refuses to record while any remain. Validator absent or not executable: degrade rather than halt (REQ-K1.7), but a merged signed-off bundle is dispatchable, so this run's sign-off would land unvalidated: ask the human whether to proceed anyway (naming the Draft→Ready flip only when this run flips) or to stop, install the validator, and re-run.
4. Read the config. commit_on_kickoff, mark_spec_pr_ready_on_kickoff, and kickoff_ready_ci_wait (default 10m) from config/defaults.yml overridden by <repo>/.claude/planwright.local.yml (local wins). The booleans default true; an absent, unreadable, or malformed value falls back to its default with a one-line warning. mark_spec_pr_ready_on_kickoff gates the terminal ready-flip and kickoff_ready_ci_wait bounds its CI wait (sign-off step 8).
5. Resolve the working location (D-44, graceful in every starting state). The spec branch is planwright/<spec>/spec (the namespace tasks-pr-sync no-ops on); the spec worktree is <repo>/.claude/worktrees/<spec>-spec (D-37).
   • Already in the spec worktree: proceed; on dirty/diverged state, surface it and ask first — never auto-stash, auto-commit, or clean.
   • In the main checkout or an unrelated worktree: if the spec worktree exists, print the re-open hand-launch (claude --worktree <spec>-spec) and stop; if only the branch exists (worktree pruned), recreate it via Claude Code's native mechanism (never raw git worktree, D-37); if neither, create both, then git switch -c planwright/<spec>/spec inside it, off the current main view.
   • Not a git repository: degrade per REQ-K1.7 — say so up front, walk and write the brief in place, skip every branch/commit/push/PR step, and surface at the end what was skipped. No remote configured: proceed; the push/PR step degrades when reached.
6. Detect a partial brief (resumability). If kickoff-brief.md exists, classify it: per-section Signed off: lines present but no final sign-off record with an anchor → a killed session left a resumable partial brief. Confirm the signed sections at one line each — never a replay of their content (interaction-style's Running summary rule; the brief holds the record) — and resume at the first unsigned section; signed sections are not re-walked unless the human asks. A final record lacking its anchor line is the same case (anchor-written-last, by design): resume at the sign-off step.
7. Surface the optional independent walkthrough (suggest only). Recommend /spec-walkthrough specs/<spec> for an unaided cold read — a complement, never a dependency (REQ-F1.1, REQ-F1.2, D-11; comprehend-first stays in-band per kickoff-dialogue).

The walkthrough

Section by section, in the brief's required structure (spec-format defines it; written incrementally, one section to disk as signed). It covers components 1–7; the rest (sign-off section, amendment log) are written by the sign-off flow below, not walked. Every exchange follows the interaction-style rules (progress indicator [section <n>/7], small bites, selectors with a recommendation, delta-plus-open running summary after each section) and instantiates the three disciplines in-band, and emits the structured decision/transcript log the eval grades, per kickoff-dialogue (REQ-F1.1, REQ-G1.3). Every projection this run emits (running summaries, the resume confirmation, the lens-pass projection, the handoff) is mirrored into it as a turn record (D-19). The disciplines: comprehend-first (section 2), with adaptive-level calibration (frontier detection, fade, a lightweight per-concept uptake estimate, no learner model; REQ-B1.3, REQ-B1.4, D-4); backward-chaining completeness bounded per pass; present without steering. Each section ends with an explicit Signed off: <date> line — what resumability keys on.

1. Header block. Spec path, spec commit at walkthrough start, walkthrough date, validator outcome from pre-flight. Written first, no sign-off needed.
2. Goal & glossary. Restate the goal in the agent's own words — a restatement, not a summary: what the spec is for, rules out, and assumes. Surface implicit terms (vocabulary the spec uses but never defines) and record resolutions to every ambiguity the restatement exposes.
3. Requirements walkthrough. Per REQ group: restate the group's intent, probe edge cases and gaps Socratically, and record per-group outcomes and decisions. Collect spec edits in a consolidated list rather than scattering them (applied per the edit rules below).
4. Design walkthrough. Every D-ID accounted for — confirmed (rationale intact), amended (what changed and why), or superseded — with a reconciled ledger. A design decision that contradicts a walked requirement is an inconsistency (below), not a ledger entry.
5. Verification approach. Review the coverage mix across test-spec tags, state verification ownership (which CI runs [test] entries, who sweeps [manual]), and check for dead paths — REQs whose named verification cannot actually run.
6. Task graph. Reconstruct the dependency graph from the Dependencies: lines (authoritative; any diagram is derived), identify parallelism and the effort-weighted critical path, and record deliberate non-edges so nobody "fixes" them later.
7. Risk register. Numbered rows of risk + mitigation / early signal. Inputs: risks surfaced during the walk, the human's cold-review questions, and the decision-domains gap check — walk the catalog against the spec (the prose seed plus overlay-added domains via the merged path scripts/resolve-catalog.sh decision-domains, REQ-D1.1); any catalogued domain the spec touches but never decides becomes a risk-register row naming the domain and the undecided question (REQ-G1.4, D-39). Catalog absent: record the one-line skip here. Open questions must be resolved into decisions or explicitly accepted risks before sign-off.

Spec edits during the walkthrough. A Draft bundle is unsigned: edits land in place, applied with the human section by section, and the consolidated list is recorded in the brief. On a signed bundle the stage-scaled change-handling above governs (REQ-D1.4); post-merge changes follow spec-format's supersede / changelog rules. An agent-authored meaning-class edit applied here also gets the mid-walk delta-scoped lens pass at the point of application — its disposition recorded in the brief section carrying it, an erroring pass surfaced (kickoff-verification, REQ-B1.4, D-5).

The inconsistency halt (REQ-B2.3). A genuine spec inconsistency — two requirements that contradict, a design decision that contradicts a requirement, a Done-when no deliverable can satisfy — halts the walkthrough rather than being papered over. Present the contradiction with both readings and the smallest edit that resolves each way. The human resolves by editing the spec (the affected sections re-walk) or recording an explicit override in the brief (the contradiction stands, named, with the chosen reading and rationale). Until one happens there is no sign-off, no Ready flip, and no anchor entry: the run ends with the partial brief on disk and the halt reason stated. Fail closed.

Sign-off

Sign-off runs only when every section above is signed and no inconsistency is open. Its steps are ordered so a session killed at any point fails closed: the most recent anchor entry never describes spec content that was not walked.

1. The lens review pass. On a re-walkthrough or amendment, first ask the human to classify the delta on the REQ-A3.3 axis (recorded later in the Class: line, but needed now to scope this pass). Then run the Discovery-Rigor lens review of the bundle per kickoff-verification (scope, fan-out, and the canonical lens-coverage table there; D-45, REQ-A3.3). The kickoff-specific altitude (REQ-H1.3) and ship-gate (REQ-L1.4) check items — not new lenses — run within this pass per kickoff-verification. Validate findings per validation-rigor, then disposition every one with the human (applied as a spec edit, declined with rationale, or deferred to a named backlog in the brief) — an undispositioned finding blocks the anchor. The lens-coverage table and dispositions are artifact-side, recorded in full in the section the sign-off record will close; the turn carries counts plus the notable rows — those the operator must act on (interaction-style, the arbitration).
2. The refusal rule (REQ-F1.10). A meaning-class sign-off whose lens pass is absent, or whose findings are not all dispositioned, refuses to record an execution-valid anchor: say exactly what is missing, leave the record without its anchor line (the freshness gate treats that as absent-anchor and halts dispatch — fail closed), and stop. No override.
3. Pre-flip verification (REQ-B1.2, REQ-B1.3, D-3, D-4). When any lens pass (mid-walk or terminal sign-off) mints or re-scopes a REQ, first run the post-lens stale-reference sweep over the bundle and earlier brief sections before the anchor and before the recorded-claim re-derivation below is finalized (kickoff-verification, REQ-B1.5, D-6). Then the checks below gate the Draft→Ready flip; any one failing blocks it, and a check that cannot run blocks it as a surfaced failure (fail closed), never a silent skip.
   • Lint the edited surfaces (REQ-B1.2). Run the repository's lint over the kickoff brief and every spec file the walkthrough edited; a lint error blocks the flip — fix it with the human and re-lint. A lint that cannot run blocks the flip and is surfaced, never read as a pass.
   • Re-derive recorded claims (REQ-B1.3, D-4). Prefer the meta-spec's cite-derived-figures rule: record the source, not the figure. Where the sign-off does record a cross-check or numeric claim as evidence — per-tag coverage tallies, REQ/D-ID/task/edit counts, pinned version or tag figures, "every X cited by at least one Y" assertions — mechanically re-derive it before the flip and block on a mismatch; a comparator that cannot run blocks as a failure, distinct from a clean match. Re-derivation treats bundle content as data, never code or pattern (fixed-string matching, quoted arguments — security-posture's never-execute-untrusted-input rule).
   • Cross-check enumerations (REQ-E1.2). At every sign-off, flip or not: 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.
4. Approval summary, then status flip and Last reviewed:. Before the flip and record, emit the shared-understanding approval summary and plain-language gate framing per kickoff-dialogue (REQ-F1.2, REQ-F1.3) — "what you are about to approve, and what changes downstream", a self-contained confirmation replacing the bare verdict-demand. On approval: First activation (and a reopened-bundle delta kickoff): flip **Status:** Draft→Ready and **Last reviewed:** to today on all four spec files (REQ-D1.1, REQ-A1.4 — this stored, human-gated flip is the only stored status transition; Ready↔Active is derived from task state by the single reconcile writer, REQ-A1.5, never written by this skill). On a v2 bundle Ready is the header's resting state, moving again only at reopen (Ready→Draft) or a terminal flip. Re-walkthroughs and amendments on an already-signed bundle (Ready or Active): bump Last reviewed: on the files the delta touched, with no status flip. Then, when present, re-run the validator (Ready, Active, and Done all block on errors): fix errors with the human, or halt without recording the sign-off entry (on a first activation or reopen, also revert the flip so the bundle does not sit Ready and erroring; on an already-signed spec there is no flip to revert, and the stale anchor keeps dispatch blocked). Never sign off over errors. Validator absent (the pre-flight consent path — re-ask on a resumed session that never saw pre-flight step 3): record "signed off unvalidated (validator absent, human-consented)" in the sign-off section, adding "including the Draft→Ready flip" only when this run flipped.
5. The sign-off record (record format, sanctioned anchor command forms, and writers rule per spec-format's Sign-off records and content anchors; REQ-F1.10). Write it into the brief's sign-off section (first activation) or as an appended amendment-log entry (everything later) — sections above the amendment log are append-only after first sign-off. Carry Class:, Lens-pass: (meaning-class only), and the anchor line last (the fail-closed ordering). Compute the anchor with scripts/spec-anchor.sh <root>/<spec>, recorded as specs/<spec>, after every spec-file edit of this run (flip, Last reviewed:, applied findings) is on disk; it fails closed on a defective bundle — surface its stderr and stop with no anchor line, never hand-roll it. Absent that script, descend spec-format's sanctioned-form list (logical before interim whole-file), recording the exact command used. It writes an expression-only entry only when the human classified the entire delta expression-only.
6. Commit (D-41) when commit_on_kickoff is true: one commit on planwright/<spec>/spec with the brief, the four spec files, and any observation fragment from this run — first activation feat(spec): <spec> kickoff, brief + Ready flip; later events docs(spec): <spec> <event>. Rewriting the spec branch is a human gate (doctrine/human-gates.md). Opt-out: leave the work uncommitted, say so, and skip push/PR.
7. Push and draft PR (REQ-B2.4, D-44). Run the Observations and Maintenance steps below first, so their chore commits precede the push (the ready-flip commits nothing). Terminal re-anchor (REQ-C1.4, D-5): anchored content edited after the sign-off record was written takes spec-format's recompute-and-re-record ritual as the final pre-push step. Then push: "$CLAUDE_PLUGIN_ROOT"/scripts/kickoff-spec-push.sh <spec> (the only push a kickoff may make; raw spec-branch pushes are refused). Then the PR: if one exists for the branch, update its body; otherwise gh pr create --draft with --title and --body. The title must pass the conventional PR-title lint (scripts/check-commit-msgs.sh, enforced in CI at 100 chars): feat(spec): <spec> kickoff sign-off for a first activation, docs(spec): <spec> <event> for later events. The body carries the spec path, brief path, walkthrough scope (full or delta), validator outcome, lens-pass summary, and the anchor. On no remote, push rejection, or gh absence/auth failure: degrade per REQ-K1.6/K1.7 — the work is committed; record a note in the spec's tasks.md ## Awaiting input section naming the pending push/PR step and the failure, surface it in the handoff, and stop. Never retry into an opaque failure. Then the pre-spec-ready-flip point (REQ-A1.2, REQ-E1.6, REQ-J1.2, D-13), whether or not a flip follows: resolve it (scripts/resolve-steps.sh pre-spec-ready-flip --explain --attended), run and record its steps under one new run, each record carrying its end head, complete it (scripts/step-record.sh write --completion --run <run> --point pre-spec-ready-flip), then post scripts/step-record.sh status --point pre-spec-ready-flip --repo <base repo> on the head the list ends on. A failure status or a failed post refuses the flip, recording the pending flip to Awaiting input naming the step (or the post).
8. Mark the spec PR ready (terminal step, D-6/D-7; REQ-D1.2, REQ-D1.3, REQ-D1.5). Only on a clean completion — the sign-off record above is written with its anchor (no inconsistency halt, no carried open question, every lens finding dispositioned). Configured verification is the pre-spec-ready-flip point (D-7), not a hardcoded core step. When mark_spec_pr_ready_on_kickoff is true and the completion is clean, un-draft the spec PR — but first gate the flip on the head SHA's CI per kickoff-verification (REQ-B1.1, D-3), which also owns the point-status and draft-state checks before gh pr ready <spec-PR>. This is the mark_spec_pr_ready_on_kickoff policy (doctrine/human-gates.md): only the spec PR; task PRs follow ready_flip_policy. Merge stays the human's second key, under merge_policy.
   • Do not flip on an unclean completion: leave the PR draft and say so in the handoff.
   • Opt-out: mark_spec_pr_ready_on_kickoff: false suppresses the flip, leaving the PR draft.
   • Degrade, never retry into opacity (bootstrap REQ-K1.6/K1.7): if the flip itself fails — no remote, gh absent or auth failure, PR not found — the recorded sign-off stands (never roll it back); record the pending ready-flip in the spec's tasks.md ## Awaiting input section naming the failure, surface it in the handoff, and stop.

Hand off. The full report — mode and scope, sections walked, spec edits applied, gap-check outcome, lens-pass summary, the anchor, commit/push/PR outcome or degradation notes, the spec PR's ready/draft state with its reason — is artifact-side: written into the PR body once step 8 resolves, or, when no PR exists, regenerated on request. The turn is its projection (interaction-style, the arbitration): counts of sections, edits, and findings, the actionable residue (a degradation note, a PR left draft and why, an open question), and the next step — merge the spec PR once ready, then /orchestrate specs/<spec>.

Data hygiene throughout (security-posture): the brief, risk register, and PR body are committed — no secrets, credentials, internal hostnames, or sensitive detail; neutralize what discussion surfaces before writing it.

Observations

When anything outside this kickoff's scope surfaces during the walk, record one fragment per item through the shared helper scripts/obs-record.sh --slug <topic> --scope <repo> --text '<observation>' (resolved under the planwright root) and commit it (with the sign-off commit, or as its own chore commit); surface a non-zero helper exit rather than dropping the observation. Do not act on observations during the kickoff; they are seed material for /spec-draft.

Maintenance

Before the push step on a run that reaches sign-off (so the chore commit lands pushed), or at the halt point otherwise, compare these instructions against the resolved doctrine docs listed above (REQ-B3.2, D-42) — especially spec-format and decision-domains. If a concept this skill names has changed meaning, gained or lost a step, or moved between docs, record a drift observation through the shared helper (scripts/obs-record.sh --slug skill-drift --scope <repo> --text 'skill-drift(spec-kickoff): <what>' — keeping the skill-drift(...) prefix; in repositories without specs/, surface the drift to the user instead), commit it as its own chore commit, and tell the user what drifted; surface a non-zero helper exit rather than dropping it. Do not edit this skill or the doctrine docs to resolve the drift; /spec-draft owns folding drift into spec amendments.