scaffold-dev

Append a Keep-a-Changelog 1.1.0 bullet to `<canonical>/CHANGELOG.md` under `## [Unreleased]` in one of six categories (Added / Changed / Deprecated / Removed / Fixed / Security); prompts for category AND entry text, never silently picks. Use this when the user says `add changelog entry`, `append to changelog`, `log changelog`, `changelog: <entry>`, or invokes `/changelog`. Does NOT cut a release section. Fails fast when `CHANGELOG.md` is absent — surfaces a `/scaffold-docs` hint.

Author a new SRE-style operational runbook under `<canonical>/docs/runbooks/<topic-kebab>.md` (six sections: Overview, Symptoms, Immediate response, Diagnosis, Mitigation, Postmortem link); extracts topic inline or prompts; collision-aware (2-option menu on duplicate). Use this when the user says `author runbook for X`, `write a runbook`, `create operational runbook`, `write runbook`, or invokes `/runbook [topic]`. Does NOT execute runbooks (operator behavior).

Run the three-layer slice-close ceremony — auto-demo (halt-on-first-fail), manual-demo, architect-critic review at close depth, `retrospective.md` authoring, memory-bank harvest sweeping `report.md` + handoffs with `[report]`/`[handoff]` source tags, then worktree + branch cleanup (only after harvest). Also owns sprint-close handoff cleanup on the final slice. Use this when the user says `close VS-N.M.K`, `slice close`, `wrap up the slice`, or `run slice-close ceremony`.

File a non-blocking gap as a project-repo GitHub issue and record a lean [TD] index pointer. Use when the user says `/defer`, "defer this", "file this as tech debt", "track this for later", or when the orchestrator captures a deferral at round-close. Orchestrator-side only — never invoked from the implementer-agent subagent (it has no gh access).

Execute one work item per its handoff doc — pre-flight gates clean state + spec ambiguity, then TDD loop + verification commands + `report.md`; stages but NEVER commits (orchestrator owns the commit boundary). Dual-use: standalone skill (`/work-item <handoff-path>`) AND system prompt for `scaffold-dev:implementer-agent` subagent. Use this when the user says `execute work item N.NN`, `implement the work item`, `handoff at <path>`, or `/work-item <handoff-path>`.

Flip an ADR's Status from Proposed to Accepted post-merge and append an Empirical validation section (operator-reported signal + date). Use this when the user says "flip ADR status", "mark ADR accepted", "accept ADR <n>", "empirical validation for ADR", or invokes `/flip-adr <adr-number-or-path>`. Resolves the ADR via the manifest-routed product/process dirs, verifies it is currently in the Proposed status, and refuses if it is already Accepted or not found. Targeted edit only — never re-authors the ADR body.

Compose a forward or return session handoff doc for out-of-slice transitions (sprint-boundary carry-forward, mid-slice context-bloat, bug-fix detour). Use this when the user says `handoff to next session`, `hand this off`, `context bloated`, `fresh session for VS-N.M.K`, `compose a handoff`, `write a return handoff`, or invokes `/handoff [--return ...]`. NEVER edits `.gitignore`, NEVER commits; `scaffold-dev:implementer-agent` is forbidden from invoking this skill.

Per-work-item verification gate — runs `auto:` AC lines (halt-on-first-fail), cross-checks `report.md` outcomes, checks machine-checkable rules from `03-code-patterns.md`; surfaces source-tagged errors (`[AC]`, `[report cross-check]`, `[rule]`) + menu on fail; reports green on all-pass. Use this when the user wants to verify work item N.NN, check round 1, asks "is this work item done", or says "verify the implementation". Read-only: never commits, merges, or auto-fixes.

Drive the full vertical-slice lifecycle — decompose into 4-5 work items, identify rounds via DAG, author specs upfront, offer grill-me at three gates, invoke architect-critic, then per round spawn worktrees + dispatch `scaffold-dev:implementer-agent` subagents. Use this when the user wants to plan VS-1.1.1, orchestrate VS-1.1.1, start a new vertical slice, or says "let's plan the next slice". Refuses to start without a workspace-init pairing manifest.

Author a new MADR-lite ADR under the manifest-routed target — product ADRs to `<canonical>/docs/adr/`, process ADRs to `<ai-workspace>/docs/adr/`; always prompts to disambiguate product-vs-process (never auto-picks). Use this when the user says `record ADR`, `log this decision`, `add architecture decision`, `ADR for X`, or invokes `/adr`. Fails fast when the ADR directory is missing (does NOT auto-create); surfaces a `/scaffold-docs` remediation hint. Offers a status protocol at authoring time — `accepted-on-author` (default) or `proposed-then-flip` for an ADR that companions a build slice (later flipped to Accepted via `/flip-adr` once an empirical signal lands).

Verify that the citations in a draft vertical-slice spec resolve — file paths and quoted function signatures via deterministic checks, REQ-ID and ARCH §-ref denotation via agent judgment. Use this when the user wants to verify spec citations, check a draft spec for citation drift, asks "do the REQ-IDs / file paths / signatures in this spec still resolve?", or before locking a slice spec. Read-only — never edits the spec. Manifest-routed. Skill-only invocation; no dedicated slash command.

Drive an arbitrary pull request through the full review-fix-merge loop — fetch reviewer findings, disposition each, drive the fixes, re-review on the new head, defer leftovers, and merge on explicit ack. Slice-decoupled and manifest-free: works on any gh repo. Use when the user says /work-pr, 'work this PR', 'drive PR #N to merge', 'review and fix this PR', 'run the pre-merge gate on PR N', 'get this PR mergeable', or hands you a PR number/URL to take to merge. NOT for slice/sprint close — closing-vertical-slice and writing-sprint-retrospective own those PR paths.

Aggregate per-slice retrospectives for a closed sprint and author `sprint-N/sprint-retrospective.md` (goal vs. delivered, per-slice rollup, cross-slice patterns, memory-bank totals, lessons). Refuses if ANY slice lacks `retrospective.md` — names the un-closed slice, points at `closing-vertical-slice`. Read-only against slice retros. Use this when the user says `close sprint N`, `write sprint retro`, `aggregate sprint retros`, `sprint retrospective for sprint N`, or invokes `/close-sprint N`.