skilld
All skills
n8n-io avatar

/spec-driven-development

@fe98bef official
by n8n - Workflow Automationn8n-io/n8n206k stars
60,960

Keeps implementation and specs in sync. Use when working on a feature that has a spec in .agents/specs/, when the user says /spec, or when starting implementation of a documented feature. Also use when the user asks to verify implementation against a spec or update a spec after changes.

Ask your Agent

Use this Skill: https://skilld.dev/gh/n8n-io/n8n/spec-driven-development

This session only. Nothing lands on disk.

SKILL.md

≈78 tokens always: the name and description. ≈721 when used: this file.

Spec-Driven Development

Specs live in .agents/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

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

Before Starting Work

  1. Find the spec. Search .agents/specs/ for files matching the feature:
ls .agents/specs/

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

  2. 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:
    - [x] ~~OpenRouter proxy~~ → Direct execution: nodes call OpenRouter directly

After Completing Work

Run a spec verification pass:

  1. Re-read the spec alongside the implementation.
  2. 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?
  3. 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
  4. 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 .agents/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"

  1. Read all relevant specs.
  2. Read all implementation files.
  3. 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)
  4. Fix drift, update specs, report gaps to the user.

Source: SKILL.md on GitHub

Third-party checks

No alerts6mo4 checks · Risk SAFE
  • Gen Agent Trust Hub6mo

    This skill is safe and facilitates a specification-driven development workflow by helping the agent synchronize implementation with design documents stored in the local workspace. No malicious patterns or unauthorized external communications were detected.

  • Socket6mo

    No alerts

  • Snyk6mo

    Risk: LOW · No issues

  • Runlayer6mo

    1 file scanned · No issues

Provenance

Signed by skilld at fe98bef. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 16 hours ago.

Activeupdated 4 months ago

Topics

  • Documentation
  • n8n
  • spec-driven
  • development-workflow
  • verification
  • architecture
  • api-design
  • implementation

README badge

README badge for n8n-io/n8n/spec-driven-development

What it does

Keeps implementation and specs in sync by treating `.claude/specs/` markdown files as source of truth for architecture and API contracts. Use when starting a feature with an existing spec, when the user requests `/spec`, or when verifying implementation matches documented design. Includes a core loop for reading specs, implementing, verifying alignment, and updating specs or code as needed.

Generated from the current SKILL.md.

Frequently asked

When should I use this skill?
Use this skill when working on a feature that has a spec in .claude/specs/, when the user says /spec, or when starting implementation of a documented feature. Also use it to verify implementation against a spec or update a spec after changes.
What happens if I diverge from the spec during implementation?
Update the spec immediately in the same session to reflect the divergence. Do not leave spec and code out of sync — they are both sources of truth.
What should I do after completing work?
Run a spec verification pass: re-read the spec alongside implementation, check each section for drift (API endpoints, config vars, module structure, types), update the spec for any drift found, and flag unresolved gaps to the user.
What if no spec exists for the feature?
If the task is non-trivial (new module, new API, architectural change), ask the user whether to create a spec first before implementation.
How should I track progress in the spec?
Use `## Implementation TODO` sections with checkboxes, marking items as complete (`- [x]`) and striking through deliberately skipped items with a brief reason for the change.

Generated from the current SKILL.md. These answers refresh after source changes.