/spec-workflow

name: spec-workflow
description: >
  Drive the spec-driven lifecycle for any non-trivial work item: SPIDR-split a
  new spec into vertical slices, transition state markers (DRAFT → READY_FOR_REVIEW
  → READY_FOR_IMPLEMENTATION → IN_PROGRESS → REVIEWED → RECONCILED → DONE; also
  DEFERRED for parked slices with a stated resolution trigger), enforce the
  reconciliation checklist before commit, and surface stale specs/ADRs whose
  `last_verified` date has aged past dependency changes. Use when starting
  non-trivial new work, creating a spec, transitioning a slice's state,
  parking a slice as DEFERRED, reconciling a reviewed slice, or auditing
  doc freshness. Do not use for quick one-off fixes that don't need a spec,
  or for bug-shaped work where `jig:bug-fix` is the better fit.
user-invocable: true

> **Working posture ([ADR-0056](../../docs/decisions/adr-0056-adversarial-register-quarantine.md)).** > Adversarial review is a *named, bounded operation.* This workflow invokes > review passes (frame-critique / craft), whose skeptical register belongs > *inside* those isolated reviewer subagents. Outside a review, default to > collaborative and solution-forward; don't carry the adversarial stance into > ordinary conversation.

> Spec 003 promoted this skill from stub to active. The deterministic state > mutations live in `workflow.py`; this SKILL.md drives the judgment layer.

What this skill does

• Guides SPIDR-splitting a new spec into vertical slices (Spike last, not first —

try Rules / Data / Interface / Path first).

• Flags slices that look like horizontal phasing (no user-facing layer touched).
• Drives the spec lifecycle state transitions via `workflow.py`.
• Coordinates implementer + reviewer subagent invocations at the right points.
• Enforces the reconciliation checklist before a slice goes DONE.
• Consults `docs/memory/glossary.md` when drafting ACs to surface unknown domain terms.
• Surfaces skill-routing observability via `workflow.py routing-stats [--days N]` —

a read-only histogram of which skills fired (jig baseline vs. richer/"other" skill per category) from `.claude/skill-usage.jsonl` (slice 041-02).

• Surfaces use-case coverage via `workflow.py coverage [--project-dir DIR]` — a

read-only, **advisory** (non-blocking), project-wide **bidirectional** check (slice 068-03): a deterministic set-difference over the `use_cases:` trace links that reports use cases with no implementing spec (coverage gap) and specs citing no parent use case (scope creep). No-op when the project has no `## Use cases` section.

• Surfaces use-case progress via `workflow.py progress [--summary] [--project-dir DIR]` — a

read-only, **advisory** rollup (slice 116-01, [ADR-0064](../../docs/decisions/adr-0064-use-case-progress-rollup-in-jig.md)): per use case, the specs citing it with their status and done/known slice **counts** (never percentages), then an **Unanchored** bucket for specs citing no resolvable use case. Derived on every run, stores nothing; a progress view, not a drift check. `--summary` prints the compact view `/jig:orient` copies (totals, use cases with no done slice or no spec, Unanchored specs; slice 116-02). No-op when the project has no `## Use cases` section or its marker says `status: unfilled` / `skipped` (not elicited yet).

• Retires the seeded genesis spec via `workflow.py retire-genesis [--project-dir DIR] [--dry-run]`

(slice 121-02, [ADR-0067](../../docs/decisions/adr-0067-genesis-spec-zero.md)). It removes `000-adopt-jig/` (new shape) or, in the legacy shape, `001-adopt-jig/` (either one only when its frontmatter has `skill: scaffold-init`; otherwise reported "not recognised as the jig seed; left in place") plus the legacy `first-spec` stub dir only while it is an untouched stub (only `spec.md`, still `DRAFT`, with the seed's heading, lead, slice heading and `_TODO_` placeholder intact; otherwise kept and reported). It deletes the primer / `adoption-readiness.md` list items that point at the removed spec, backticks any other link in `CLAUDE.md`, `AGENTS.md`, `adoption-readiness.md` and a kept stub, and regenerates the board. Links from your own files are **reported, never rewritten**. It **refuses** (non-zero, nothing written) when no other spec exists, since a re-scaffold would re-seed the genesis. `--dry-run` prints the plan and writes nothing. When the first non-genesis spec rolls up to `DONE`, `transition` prints a one-line hint naming this command (stderr, non-blocking, once).

• Guards the status board via `workflow.py check-board <project-dir>` — a

read-only audit that exits non-zero when `docs/specs/README.md` no longer matches the spec records, or when two spec directories claim one number. Writes nothing, so it is safe to run in CI against a checkout.

• Surfaces gate-bypass telemetry via `workflow.py gate-stats [--days N]` — a

read-only per-gate histogram of how often each gate honored its env-var override (an override-frequency audit trail, not a gate-value verdict) from `.claude/skill-usage.jsonl` (slice 078-02).

SPIDR splitting

All non-trivial specs are SPIDR-split into vertical slices before implementation begins. **Spike is the last resort — try Path / Interface / Data / Rules first.**

• **S — Spike**: research/learning activity. Only when none of P/I/D/R

apply. AI agents default to spiking too eagerly — resist.

• **P — Path**: split by alternative paths through the story (happy

path first, edge paths later).

• **I — Interface**: split by UI / platform / channel (minimal first,

polish later).

• **D — Data**: split by data subset or format (less data first).
• **R — Rules**: split by business rules (simple first, edge cases later).

**Anti-horizontal-phasing rule:** every slice must touch the user-facing layer and deliver end-to-end value. A slice that touches only the DB or only the parser is horizontal phasing — re-split.

See [`worked-example-spidr-split.md`](worked-