spec-draft — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited spec-draft (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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 specs/<spec>/, Status Draft, committed on the spec branch. Drafting ends where comprehension begins: /spec-kickoff walks the Draft to sign-off and flips it Active. This skill never pushes, never opens a PR, and never flips a status to Active — sign-off is a reserved human control it has no business near.
Resolve and read these rule docs at run start via the rule-doc resolution convention (scripts/resolve-rule-doc.sh <doc-name> or the documented PLANWRIGHT_ROOT/CLAUDE_PLUGIN_ROOT chain): spec-format (the meta-spec the bundle must conform to — its conventions govern every file this skill writes), interaction-style (governs every exchange in the flow), research-rigor (REQ-D1.5 wires its triggers into drafting), security-posture (artifact data-hygiene for everything committed), engineering-decisions (governs design-phase recommendations), and proportionality, plus customization-boundary (the capability-vs-style scoping call the design phase applies when a candidate feature looks like a packaged preference — see Design step 3). Their definitions govern wherever this skill names a concept. If one of those does not resolve, halt with a clear message naming the missing doc and the chain consulted (REQ-K1.7: a clear message is the graceful arm; proceeding without doctrine is the opaque failure). Also resolve decision-domains (the design phase walks its catalog) — this one degrades instead of halting: if absent, the design phase notes the missing catalog in one line and proceeds (the builder/catalog wiring is a hook point, not a dependency).
$ARGUMENTS carries the proposed feature name —free-form idea text by design (the name is a hint, D-22) — and optionally --extend <spec> (jump straight to extend mode on an existing bundle). 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) 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. When --extend <spec> is present, additionally verify the target: specs/<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.
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 (this skill never pushes); note it only so the human knows /spec-kickoff's push step will degrade.
commit_on_draft from config/defaults.ymloverridden 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).
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 attachable via claude --worktree <spec>-spec).
state: surface it and ask before touching anything — never auto-stash, auto-commit, or clean.
exists, do not work here — print the re-open command (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 (claude --worktree / EnterWorktree — never raw git worktree, D-37), then git switch -c planwright/<spec>/spec inside it, branched from the current main view.
a fresh idea may be after seed gathering and fold-detection have run (both are read-only against the existing checkout).
Collect the framing inputs before asking the human a single elicitation question; seeds answer questions the human would otherwise repeat.
prompt.
specs/_pending/. Read them; ask whichapply if more than one plausibly does.
specs/_observations/opportunities.md, minedas a first-class seed source (D-23; this skill is its canonical reader, REQ-H1.6). Read every entry; 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.
An absent specs/_pending/, observations log, or specs/ 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).
Archive-on-consume. When the bundle is written, move each consumed observations-log entry from specs/_observations/opportunities.md to specs/_observations/archive.md (create with a # Consumed observations heading if absent), appending the annotation — consumed-by: specs/<spec> (<date>) (space-separated) to the entry line. Before archiving, re-read each consumed entry against the data-hygiene rule below: archive.md is a committed artifact, so sensitive operational detail a raw entry carries is neutralized in the archived copy (the unconsumed original was already committed; neutralizing the copy adds no new exposure but stops carrying it forward). Order the move so a failure cannot lose entries: append to archive.md first, trim opportunities.md second (the same crash-safe ordering REQ-F1.10 uses for anchor lines); if the archive append fails, surface it and leave the log untouched. Touch only the consumed entries; the log is append-only for everyone else, and unconsumed entries stay byte-for-byte. The trim rides the spec branch and lands on main with the spec PR, keeping it one revert from undone. (The accumulator-taxonomy doctrine, when it ships, is the canonical home of this drain ritual; until then this section defines it.)
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.
specs/ (any non-terminal status: Draft,Active, Done). Read each bundle's requirements.md Goal and Scope sections — bounded input by design; full-bundle reads don't scale and 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).
problem domain, same external interface, same decision space.
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".
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.
line what was scanned and why nothing folded.
Entered via --extend <spec> or the human accepting the recommendation. Operates on the existing bundle per the meta-spec's stable-ID discipline:
space; dotted task ids insert between existing tasks.
a new ID adjacent to the old, old marked Superseded-by; bodies of superseded records are never edited (D-20).
tasks.md (new task blocks in Forward plan, dependency lines updated); append a dated Changelog entry** describing the extension.
Done→Draft (all four headers); the scoped kickoff of the delta flips it back to Active. Extending an Active bundle leaves it Active — the delta is Draft content inside an Active bundle, 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.
draft.
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, end each phase with the running summary of everything decided so far. The meta-spec (spec-format) defines every structural convention referenced here; follow it exactly so the bundle passes the validator the first time.
out-of-scope lists. Elicit what the feature must not do — out-of-scope entries prevent more drift than REQs do.
## REQ-<Group> — <theme>), eachrequirement 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.
(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, apply customization-boundary — 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.
(Deliverables / Done when / Dependencies / Citations / Estimated effort); IDs stable from birth. Done when: conditions an agent can evaluate. All blocks start in ## Forward plan; the other five state sections are written with (none yet) placeholders. 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.
[test] / [manual] / [design-level] / [Gherkin] (mixed: [test + manual]). Prefer [test] where automation is honest; say which CI runs it.
**Status:** Draft, **Last reviewed:** <date>, **Format-version:** 1), present the bundle for a final read-through with the cumulative summary. Run scripts/spec-validate.sh specs/<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.
specs/<spec>/ in the spec worktree (plus theobservations-log archive trim, when entries were consumed).
commit_on_draft is true: one commit onplanwright/<spec>/spec containing the four files and the _observations trim, message feat(spec): draft specs/<spec> bundle (extend mode: feat(spec): extend specs/<spec> — <summary>). New commits only — never force-push, amend, squash, or rebase (REQ-J1.4). Opt-out set: leave the work uncommitted and say so explicitly.
seeds consumed (and archived), fold-detection outcome, and the next step — /spec-kickoff specs/<spec> for the walkthrough and sign-off. Push, PR, and the Active flip all belong to kickoff and the human. This skill stops here.
/spec-walkthrough specs/<spec> themselves for an unaided, plain-language read of the freshly drafted bundle before sign-off — the unaided complement to /spec-kickoff's guided dialogue (REQ-F1.1, REQ-F1.2, D-11). Surface it as a suggestion only, never a step this skill performs: the human chooses whether to take the independent pass.
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, append a drift observation to specs/_observations/opportunities.md (format: - <YYYY-MM-DD> [<repo>] <observation>, prefixed skill-drift(spec-draft):; in repositories without specs/, surface the drift to the user instead of writing the log), commit the append as its own chore commit, and tell the user what drifted. Do not edit this skill or the doctrine docs to resolve the drift; the observation log's reader owns folding drift into spec amendments.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.