spec-driven-dev

Core Philosophy: Code is a lossy projection of specifications. Intent, constraints, invariants, and architectural decisions must be captured in the spec BEFORE any code is written. The spec is the product; the code is a byproduct.

Sub-Skills

Component	Purpose
retrofit	Pre-Phase 1: Scan existing project, build BASELINE.md for context
specifier	Phase 1: Gather requirements, business logic, user journeys → SPEC.md
architect	Phase 2: Technical architecture, data models, API contracts → PLAN.md
decomposer	Phase 3: Break plan into atomic, implementable tasks → TASKS.md
toolchain	Post-spec: Discover, install, and configure required tools/MCPs
sync	Post-spec: Push tasks to GitHub Projects, SPEC.md to Linear, configure sync

Dependency Chain:

• Greenfield: specifier → architect → decomposer → toolchain → sync → implement
• Existing project: retrofit → specifier → architect → decomposer → toolchain → sync → implement

The Solution: Front-load ALL thinking into structured specification documents. When the spec is comprehensive and LLM-optimized, implementation becomes mechanical execution — one-shot or close to it.

When FULL SDD is Required:

• New projects (any greenfield work)
• Major features (touching 5+ files or introducing new architectural patterns)
• Significant refactors (changing data models, API contracts, or system boundaries)
• Any work the user explicitly wants to one-shot

When LIGHT SDD Suffices:

• Medium features (3-5 files, clear scope, known patterns)
• Features within an existing well-spec'd project

When NO SDD is Needed:

• Bug fixes (unless systemic)
• Small features (1-3 files, clear scope)
• Documentation, configuration, or styling changes

Maturity Levels (for user awareness, not skill configuration):

1. Spec-first: Spec written, used to guide implementation, then archived
2. Spec-anchored: Spec kept alive for ongoing evolution and maintenance
3. Spec-as-source: Spec is the only human-edited artifact; code is fully generated

STEP 1: Detect project state

CHECK for existing project indicators:
  - package.json, requirements.txt, Cargo.toml, go.mod (package manifest)
  - .git directory with history
  - src/ or app/ directory with code
  - CLAUDE.md or build log
  - specs/BASELINE.md (already retrofitted)

IF existing project detected AND specs/BASELINE.md does NOT exist:
  project_state = EXISTING_NO_BASELINE
ELIF existing project detected AND specs/BASELINE.md EXISTS:
  project_state = EXISTING_WITH_BASELINE
ELSE:
  project_state = GREENFIELD

STEP 2: Determine scope

IF request matches ANY:
  - Keywords: "new project", "build me", "create an app/site/tool/platform"
  - Keywords: "I want to build", "let's build", "start a new"
  - Keywords: "new feature", "add a feature", "build a feature", "implement"
  - Keywords: "I want to add", "add X to", "build X for", "create X in"
  - Keywords: "spec this", "write a spec", "one-shot this"
  - Keywords: "deploy SDD", "add spec-driven", "retrofit", "baseline this"
  - Estimated scope: > 5 files or > 500 lines of new code
  - Introduces new data models, APIs, or architectural patterns
  - User explicitly requests SDD
  - User describes a feature that sounds non-trivial (multiple components,
    database changes, new API endpoints, new pages/routes)
THEN:
  scope = FULL_SDD

ELIF request is medium scope (3-5 files, clear patterns):
  scope = LIGHT_SDD
  RESPOND:
    "This is medium-sized. I'll do a lightweight spec — just enough to
     one-shot it cleanly."
  Execute abbreviated flow:
    - Ask 3-5 clarifying questions about scope, constraints, edge cases
    - Produce mini-spec inline (not a separate file)
    - Proceed to implementation
  EXIT

ELSE:
  scope = NO_SDD
  Proceed with normal implementation
  EXIT

STEP 3: Route based on project state + scope

IF scope == FULL_SDD AND project_state == EXISTING_NO_BASELINE:
  RESPOND:
    "This is an existing project without a baseline. Before we spec new work,
     I need to understand what's already built.

     **I'll run the retrofit process first:**
     - Scan your codebase, build log, git history, and config
     - Create a BASELINE.md capturing your current architecture and state
     - Then we'll flow into the normal spec process for your new feature

     Let me start scanning."
  GOTO Phase 0.5 (Retrofit)

ELIF scope == FULL_SDD AND project_state == EXISTING_WITH_BASELINE:
  RESPOND:
    "I see this project already has a baseline. I'll reference it for context
     as we spec your new work.

     **4 Phases:**
     1. **Specify** — What are we building and why?
     2. **Plan** — How will it be built technically?
     3. **Tasks** — What are the atomic units of work?
     4. **Implement** — Execute against the spec.

     Let's start with Phase 1."
  READ specs/BASELINE.md into context
  GOTO Phase 1

ELIF scope == FULL_SDD AND project_state == GREENFIELD:
  RESPOND:
    "This needs a spec before we build. I'm going to walk you through
     spec-driven development — this is where the real work happens.
     Once the spec is solid, implementation should be close to one-shot.

     **4 Phases:**
     1. **Specify** — What are we building and why?
     2. **Plan** — How will it be built technically?
     3. **Tasks** — What are the atomic units of work?
     4. **Implement** — Execute against the spec.

     Let's start with Phase 1."
  GOTO Phase 1