Spec Driven Development

It emphasizes keeping implementation and specs synchronized through a core loop of reading, implementing, verifying, and updating.

Install

npx promptshop add spec-driven-development

Details

What This Skill Does

This skill guides developers in using a spec-driven development approach, where specifications serve as the source of truth for architectural decisions, API contracts, and implementation scope. It emphasizes keeping implementation and specs synchronized through a core loop of reading, implementing, verifying, and updating. This is useful for software engineers working on complex projects.

When to Use

Before starting work, find and read the relevant spec. When diverging from the spec, update it immediately. After completing work, verify the implementation against the spec. When a task is non-trivial, create a spec first. Reference spec decisions during implementation. Run a spec verification pass after completing work.

Key Features

Provides a core loop for spec-driven development.
Emphasizes the importance of keeping specs and code in sync.
Guides users in finding and reading existing specs.
Provides instructions for updating specs during implementation.
Offers a checklist for verifying implementation against the spec.
Suggests annotating skipped items in the spec with reasons.

Manual Installation

Manual installation## Core Loop

Read spec → Implement → Verify alignment → Update spec or code → Repeat

Before Starting Work

Find the spec.
Search .claude/specs/ for files matching the feature:.

ls .claude/specs/

Read the full spec. Understand scope, decisions, API contracts, and open questions before writing code.

If no spec exists and the task is non-trivial (new module, new API, architectural change), ask the user whether to create one first.

During Implementation

Reference spec decisions — don't re-decide what the spec already settled. When you diverge from the spec (better approach found, user requested change, constraint discovered), update the spec immediately in the same session. Don't leave spec and code out of sync. Tick off TODO checkboxes (- [ ] → - [x]) as items are completed. Strike through or annotate items that were deliberately skipped or replaced, with a brief reason:

~~Open Router proxy~~ → Direct execution: nodes call Open Router directly

After Completing Work

Run a spec verification pass:

Re-read the spec alongside the implementation. Check each section:

Do API endpoints in spec match the controller?
Do config/env vars in spec match the config class?
Does the module structure in spec match the actual file tree?
Do type definitions in spec match @n8n/api-types?
Are all TODO items correctly checked/unchecked? Update the spec for any drift found. Common drift:
New files added that aren't listed in the structure section
API response shapes changed during implementation
Config defaults adjusted
Architectural decisions refined Flag unresolved gaps to the user — things the spec promises but implementation doesn't deliver yet (acceptable for MVP, but should be noted).

Spec File Conventions

One or more markdown files per feature in .claude/specs/. Keep specs concise. Use tables for mappings, code blocks for shapes. Use ## Implementation TODO with checkboxes to track progress. Split into multiple files when it helps (e.g. separate backend/frontend), but don't enforce a rigid naming scheme.

When the User Asks to "Self-Review" or "Verify Against Spec"

Read all relevant specs. Read all implementation files. Produce a structured comparison:

Aligned: items where spec and code match
Drift: items where they diverge (fix immediately)
Gaps: spec items not yet implemented (note as future work) Fix drift, update specs, report gaps to the user. Spec-Driven Development
Specs live in .claude/specs/.
They are the source of truth for architectural. decisions, API contracts, and implementation scope. Implementation and specs must stay in sync — neither leads exclusively.

Core Loop