Spec-Driven Development

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

When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.

Scope and existing artifacts

Use the actual repository scripts and installed tool versions; commands below are examples, not verified prerequisites. Preserve supplied specs/plans when the user asks to execute them without edits, and use existing acceptance criteria rather than creating duplicate process documents. Explicit user/repository workflow constraints control required checkpoints and commits. A written spec supports review but is not proof of correctness.