Skip to content
Skills Library
Programming · Planning

spec-driven-development

/spec-driven-development

Use when the task is a new feature, breaking change, multi-file change, or any work where approval should happen before coding begins.

Licence
MIT
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when the task is a new feature, breaking change, multi-file change, or any work where approval should happen before coding begins.

Original author description

Use when the task is a new feature, breaking change, multi-file change, or any work where approval should happen before coding begins.

How it works

  1. Overview
  2. When To Use
  3. Modes
  4. Workflow
  5. Extended Spec Mode
  6. Machine-Parseable Manifest (JSON Sidecar)
  7. Verification
Original SKILL.md headings · 121 lines, 2,048 words
SKILL.md preview
---
name: spec-driven-development
description: Use when the task is a new feature, breaking change, multi-file change, or any work where approval should happen before coding begins.
type: skill
license: MIT
compatibility:
  - claude-code
  - codex
user-invocable: false
---

# Spec-Driven Development

## Overview

Write the implementation spec before writing code. The spec is the shared source of truth between the engineer, the command flow, and the reviewers. Code without a spec is guessing.

> **Tool discipline (phase-locked):** spec authoring is a read + spec-artifact phase. Write **only** the spec artifacts (`docs/specs/<date>-<slug>.md` and its `.json` sidecar) — never source or test code. Code starts at Phase 3, after the approval gate; a source edit here is a scope violation.

> **Supplied spec/plan (adoption, not authoring):** when the engineer hands in a complete spec or plan as the input (e.g. `docs/specs/…md` or `docs/plans/…md` already on disk), `implement`'s Phase 0.7 *adopts* it as the source of truth. In that case this skill validates the supplied artifact against the schema and reconciles it against the current code (see `prior-work-check`'s existing-plan reconciliation) rather than re-authoring to a fresh path — never overwrite or version-bump the engineer's input. See `implement/SKILL.md` Phase 0.7.

## When To Use

- New endpoints, handlers, routes, or views; database changes or migrations
- Multi-file work or breaking changes
- Any task where approval should happen before coding, or likely to outlast a short focused session

### When NOT To Use

- Typo fixes, one-line config updates with no behavior impact, or small bug fixes that clearly stay within quick-fix scope → `fix`

## Modes

- **Standard (default).** The steps below: ambiguity gate, the spec sections, the JSON sidecar, honest `security_impact`, prior-work check.
- **Extended spec (opt-in).** Adds EARS/ANT requirements with `lint-ears.sh`, the INVEST+C 16-item score, a cited Constitution Check, and a delta against a per-area baseline. Turn it on when the engineer asks for it, or when the Phase 2 rigor score lands at **MAX** — then add the extended sections before the Phase 2.5 gate. Record the mode in the spec header (`Spec mode: extended`). See **Extended Spec Mode** below.

## Workflow

### Steps

1. Read the coding guidelines from the active tech stack's `## Reference Files`, the stack's testing supplement, `.claude/references/domain-finance.md` (finance and security supplement) when scope touches auth/financial/infra, and `architecture-principles.md` if present. Query relevant lessons:
   `bash "$([ -n "${MTK_HELPER_ROOT:-}" ] && echo "$MTK_HELPER_ROOT/scripts/learnings.sh" || ([ -f scripts/learnings.sh ] && echo scripts/learnings.sh || echo "${CLAUDE_PLUGIN_ROOT}/scripts/learnings.sh"))" query --phase spec --files "<comma-separated paths from initial scope>" --max 8` (falls back to reading `tasks/lessons.md`; resolve it from the main worktree when in a worktree).
2. Surface assumptions before planning — runtime, architecture, storage, auth, boundaries. Do not silently fill in major gaps.
3. Classify scope: `internal-refactoring` · `new-feature` · `breaking-change`.
3b. **Dirty-worktree step.** Run `git status --porcelain`. Every modified or untracked path not in this change manifest goes under **Risks** as a `dirty-worktree` entry and into `out_of_scope` in the sidecar, so the `plan-gap-reviewer` can reject any batch that touches it.
4. Read 2-3 nearby files that represent the local pattern to follow.
5. **Ambiguity gate (BEFORE drafting).** Detect whether the task has genuine ambiguity that would change the spec. Trigger if **any** of:
   - Two or more plausible designs exist and the request doesn't pick one (e.g., reflection vs source-gen, sync vs async, single vs split package).
   - Scope edges are undefined (e.g., "users" — authenticated only? including service accounts? soft-deleted?).
   - An architectural choice is unresolved (e.g., new boundary, new persistence target, cross-slice contract).
   - A success criterion would be untestable as stated.

   If triggered: stop and call `AskUserQuestion` with one question per ambiguity (max 4). Each question presents 2–4 concrete options with the tradeoff in the description. Wait for answers, then proceed to drafting with answers folded into the spec — do not defer them to "Open questions" in the spec body.

   **Interview mode (Socratic, one question per round).** Switch from the batched form above to a structured interview when **either**: three or more ambiguities triggered, or the request is one or two sentences for clearly multi-file scope (the ask is underspecified relative to its blast radius). In interview mode:

   - Ask **one** question per `AskUserQuestion` round, starting with the highest-leverage ambiguity — the one whose answer most reshapes the spec (usually the success definition or the architectural boundary, not the naming choice).
   - Probe **intent**, not just option preference: lead with what the engineer is trying to achieve or avoid ("what should happen to in-flight payments when this flag flips?"), then offer the 2–4 concrete options informed by that framing.
   - After each answer, **re-derive the remaining ambiguities** before asking the next question — answers routinely resolve later questions or surface new ones; a pre-computed question list goes stale after round one.
   - Cap at **5 rounds**. Anything still open after the cap is written into the spec as an explicit assumption with the chosen default and its rationale — never as a silent guess.

   Batched mode remains the default for one or two independent ambiguities — don't stretch a two-question gate into an interview.

   If `AskUserQuestion` is deferred, load it via `ToolSearch` with `select:AskUserQuestion`. If the harness doesn't expose it, print the questions as a numbered list and stop until the engineer answers.

   Skip the gate when: the engineer's request already specifies the approach, the task follows an obvious existing pattern, or only one viable design fits the constraints. Document the skip in one line ("ambiguity gate skipped: <reason>") so it's visible in the session log.

   **When an ambiguity is version-sensitive** — the right answer depends on current external best-practice, the installed package version's behavior, or a recent migration path rather than a preference — first follow `.claude/skills/research-context/SKILL.md` to produce a grounded, cited brief, then fold its recommendation into the options you present at the `AskUserQuestion` gate. Resolve "which design" from current information, not training-cutoff memory.
6. Produce a spec with these sections: Summary · Success criteria · Architecture and design · Security and compliance impact · Change manifest · Test manifest · Implementation batches · Risks and assumptions · Open questions.
7. **Security impact, honestly.** Map each `change_manifest` path against the trust boundaries: auth, payments, audit, secrets, PII, IAM, financial state. If any path touches one, `security_impact` is not `none` — state the level and a one-line justification. A mis-classified impact is the one spec error that silently removes reviewers later (it feeds the rigor floor and the drift check).
8. Elegance check: reduce file count, new abstractions, and moving parts if a simpler design exists.
9. **Prior-work check** — run `prior-work-check` once against the draft. A BLOCKED verdict (an existing implementation the spec would duplicate) holds the approval gate until the spec is revised. Append its output under `## Prior Work Check` in the spec.
10. Persist the spec to disk:
   - **Resolve the artifact root first:** `bash scripts/resolve-artifact-root.sh "<a path the change touches>"`. Every `docs/specs/...` path below is relative to **that** root, not automatically the repo root. In a polyglot repo a subtree that owns its artifacts (its own `docs/specs/` plus a `CLAUDE.md`) keeps them — writing to the repo root instead would scatter one project's specs across two locations. A repo with no such subtree resolves to the repo root, so single-project repos are unaffected.
   - Create `docs/specs/` under the resolved root if it does not exist.
   - Compute the base target: `<artifact-root>/docs/specs/YYYY-MM-DD-<feature-slug>` (no extension yet).
   - **Version detection:** Check whether `docs/specs/YYYY-MM-DD-<feature-slug>.md` already exists.
     - If it does not exist → write to `docs/specs/YYYY-MM-DD-<feature-slug>.md` (no suffix).
     - If it DOES exist → find the highest existing `-vN` suffix:
       ```bash
       ls docs/specs/YYYY-MM-DD-<slug>*.md 2>/dev/null | grep -oE '\-v[0-9]+' | sort -V | tail -1
       ```
       If a `-vN` suffix is found, write as `-v(N+1)`. If the file exists but no `-vN` variants do, write as `-v2`.
     - The JSON sidecar gets the **same version suffix** (e.g., `docs/specs/YYYY-MM-DD-<slug>-v2.json`).
     - Emit one line before writing: `Writing spec → docs/specs/<final-filename>.md` so the engineer can confirm the version chosen.
   - **Also emit a machine-parseable sidecar** at `docs/specs/<final-filename>.json` with the schema in **Machine-Parseable Manifest** below. This sidecar drives `spec-drift-detection` after implementation.
   - This enables session recovery, human review outside chat, and reuse across sessions.
   - Add `docs/specs/*` to `.gitignore` with the negations `!docs/specs/baseline/` and `!docs/specs/baseline/**`: per-feature specs are working artifacts, an extended-mode baseline is committed.
11. **Publish the spec artifact (additive, capability-gated).** After the spec is on disk, follow `.claude/references/artifact-publishing.md` to create the workflow's Claude Artifact from the spec — this is the first section of a single browsable URL that later phases (plan, handoff, health) update in place. Publishing is additive: disk is the source of truth and the step is a silent no-op when the `Artifact` tool is unavailable or `MTK_ARTIFACT_PUBLISH=0`. Never publish anything not already written to disk.
12. Always stop for approval before implementation. When invoked from the implement workflow, this means handing control back to Phase 2.5 approval gate (which uses `AskUserQuestion`). Do not silently continue to implementation.

**Approval is sealed, not asserted.** On approval, the implement gate records a SHA-256 **approval seal** over the approved spec/plan bodies — the two scope-encoding artifacts (`scripts/workflow-artifact.sh seal`). The todo is deliberately *not* sealed: it is progress state designed to mutate as batches complete, so sealing it would flip the seal STALE on the first checkbox tick. Because the seal binds the exact approved bytes, editing an approved spec or plan afterward invalidates the approval deterministically — `verification-before-completion` re-checks it with `verify-seal` (refusing completion on a STALE seal) and the `spec-approval-trigger.sh` hook re-queues the gate, rather than trusting a stale `status: approved` marker. This is why moving a success-criterion goalpost post-approval requires re-opening Phase 2.5: the seal will not match.

## Extended Spec Mode

Only when the engineer asks for it, or at rigor MAX. Each item is added to the spec before the Phase 2.5 gate.

1. **Requirements in EARS.** A `## Requirements` section where every bullet uses one template: *Ubiquitous* "The system shall …" · *Event-driven* "When <trigger>, the system shall …" · *State-driven* "While <state>, the system shall …" · *Optional* "Where <feature>, the system may …" · *Unwanted* "If <trigger>, then the system shall …". **ANT check:** if you cannot describe a counter-example for a bullet ("shall be reliable", "handle errors gracefully", "where appropriate"), rewrite or drop it.
2. **EARS lint.** `bash scripts/lint-ears.sh docs/specs/<file>.md` must return zero violations before the gate; record the spec path in the same call (`&& "$WFA" set "$MTK_WF_UUID" results.spec_path=…`). It checks only the `## Requirements` section.
3. **INVEST+C score** against `.claude/references/claude-ready-checklist.md`. Any failing +C item is fixed before the gate; ≤13/16 goes back to draft. Cite failing item numbers.
4. **Constitution Check.** Run `bash scripts/constitution-digest.sh`, then list in a `## Constitution Check` section every Critical Rule or principle that constrains this design, cited by id, with one line on how the design satisfies it. A bent rule is an explicit exception with rationale; an `[EXTRACTED]` violation normally means redesign. `spec-drift-detection` verifies what is cited here.
5. **Delta against a baseline.** Set `baseline_area` (and `delta.adds/modifies/removes` when known; removals are always explicit) so Phase 7.5 can archive it — see `.claude/references/delta-spec-model.md`.

## Machine-Parseable Manifest (JSON Sidecar)

Every spec is accompanied by `docs/specs/<date>-<slug>.json`, validated against
`.claude/schemas/handoff.schema.json`. It is the source of truth for drift detection
and for the `plan` / `implement` sections downstream skills append. Required top-level
keys: `slug`, `date`, `scope`, `change_manifest[]` (`path`, `action`, `purpose`,
`mechanical`), `public_contracts[]` (`kind`, `signature`, `change`, `surface`),
`success_criteria[]` (`id`, `description`, `verification`, `evidence_channel`,
`observable`), `test_manifest[]`, `out_of_scope[]`, `security_impact`, `assumptions[]`,
`risks[]`; `baseline_area` + `delta` in extended mode only;
`coverage_claims[]` and `conditional_descopes[]` when they apply. Every `change_manifest`
path must exist or be marked `create`; an `[ASSUMED]` entry or an unverified coverage
claim is an open decision and blocks `MTK_AUTO_PROCEED`.

**Read `.claude/references/spec-sidecar-manifest.md`** for the full field reference,
allowed values, and the worked example before writing or amending a sidecar.

## Verification

- [ ] Spec is self-contained and scope still matches the original request
- [ ] Every file and test file appears in the manifest; the JSON sidecar matches the markdown's change_manifest, test_manifest, success_criteria, and security_impact
- [ ] Success criteria are specific and testable; assumptions are explicit
- [ ] `security_impact` honestly reflects touched trust boundaries (step 7)
- [ ] Ambiguity gate ran or its skip was stated in one line
- [ ] `prior-work-check` ran once with no BLOCKED verdict (step 9)
- [ ] Extended mode only: `lint-ears.sh` returns 0, +C score > 13/16 recorded, Constitution Check present, `baseline_area` set
- [ ] Spec artifact published (or gate correctly closed) per `.claude/references/artifact-publishing.md`, disk written first

Versions

RepositoryScoreLicence
This page · moberghr/mtk-agent-toolkit100MIT
magnus919/agent-skills100MIT
lucasouzadev/agent-kit-skill100MIT
FrancoStino/opencode-skills-collection100MIT
DanielCryer/spec-workflow100MIT
ctoforaday/special-circumstances100MIT
krzysztofsurdy/code-virtuoso100MIT
rafidone/agent-skills100MIT
sickn33/agentic-awesome-skills100MIT

Database snapshot: 13.11.2026 · package version bfee9c1edc27 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100spec-driven-dev
    Use when starting any non-trivial feature, refactor, or new project that will touch more than one file. Drives an AI coding agent through a gated Spec → Plan → Build → Test → Review → Ship lifecycle so work is specified before it is built, verified before it is reviewed, and…
  • 90spec-driven
    Guide spec-driven development workflow (Requirements → Design → Tasks → Implementation) with approval gates between phases. Use when user wants structured feature planning or says "use spec-driven" or "follow the spec process".
  • 98overfit-spec
    Spec-driven development for the Overfit engine. Use when starting a new feature, model/op/kernel/loader/runtime change, or any change touching multiple files — writes an Overfit-native spec (architecture path, AOT / zero-alloc / parity gates, git-read-only boundary) and a gated…
  • 100spec
    Research a change against this codebase, then write it up as requirements plus a phased plan in docs/ before any code is written. Use for "plan this", "deeply analyse then plan", "audit this and tell me what we need", "what do we need for X", or before starting any new feature…
  • 86spec-driven-coding
    Use for multi-file coding needing a spec, plan, or proof.
  • 96test-driven-development
    Use when implementing any feature or bugfix, before writing implementation code

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.