spec driven development

Engineering Community

Skill notes

Overview

Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.

When to Use

Starting a new project or feature Requirements are ambiguous or incomplete The change touches multiple files or modules You're about to make an architectural decision The task would take more than 30 minutes to implement

The Gated Workflow

Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.

Phase 1: Specify

Start with a high-level vision. Ask the human clarifying questions until requirements are concrete. Surface assumptions immediately. Before writing any spec content, list what you're assuming: Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding. Write a spec document covering these six core areas:

Phase 2: Plan

With the validated spec, generate a technical implementation plan: Identify the major components and their dependencies Determine the implementation order (what must be built first) Note risks and mitigation strategies Identify what can be built in parallel vs. what must be sequential

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@addyosmani · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
macOS · Linux · Windows
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1: Specify

Start with a high-level vision. Ask the human clarifying questions until requirements are concrete. Surface assumptions immediately. Before writing any spec content, list what you're assuming: Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding. Write a spec document covering these six core areas:

02
Phase 2: Plan

With the validated spec, generate a technical implementation plan: Identify the major components and their dependencies Determine the implementation order (what must be built first) Note risks and mitigation strategies Identify what can be built in parallel vs. what must be sequential

03
Phase 3: Tasks

Break the plan into discrete, implementable tasks: Each task should be completable in a single focused session Each task has explicit acceptance criteria Each task includes a verification step (test, build, manual check) Tasks are ordered by dependency, not by perceived importance

04
Phase 4: Implement

Execute tasks one at a time following `skills/incremental-implementation/SKILL.md` (`incremental-implementation`) and `skills/test-driven-development/SKILL.md` (`test-driven-development`). Use `skills/context-engineering/SKILL.md` (`context-engineering`) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.