Spec-Driven Feature Development

Tech Lead's Club - Spec-Driven Development

Plan and implement features with precision. Granular tasks. Clear dependencies. Right tools. Zero ceremony.

┌──────────┐   ┌──────────┐   ┌─────────┐   ┌─────────┐
│ SPECIFY  │ → │  DESIGN  │ → │  TASKS  │ → │ EXECUTE │
└──────────┘   └──────────┘   └─────────┘   └─────────┘
   required      optional*      optional*     required

* Agent auto-skips when scope doesn't need it

Critical Rules (read before acting)

Loading this skill's files. Reference files live under references/ in this skill's own directory (where this SKILL.md resides). Resolve them relative to the skill directory - never the workspace root - and load them through the active skill by name; never assume a fixed install path. When a step tells you to read a reference, read it completely (to EOF) before acting - never act on a partial/truncated read.

Running this skill's scripts. Every scripts/*.py shipped with this skill lives under that same skill directory. Resolve the skill directory first, then invoke python3 <skill-dir>/scripts/<name>.py .... Never run python3 scripts/... from the consuming project root - that looks for a project-local scripts/ tree that is not this skill. Project data under .specs/ is still read/written relative to the project root (pass --root when the cwd is elsewhere). Below, <skill-dir> means the directory that contains this SKILL.md.

Execution contract - every task, non-negotiable (holds even if you do not open the reference files):

1. Tests derive from the spec's acceptance criteria and assert spec-defined outcomes - they never mirror the implementation.
2. The gate must pass (tests pass) before a task is done - the test runner decides, not self-assessment.
3. One atomic commit per task. Mark the task complete in tasks.md (and update spec traceability when used) before that commit, and include those updates in the same commit. Never batch tasks; never weaken, skip, or delete tests to make them pass.
4. After the LAST task, a fresh Verifier always runs automatically (author ≠ verifier) - spec-anchored outcome check + discrimination sensor. It is never optional and never prompted. See Sub-Agent Delegation.
5. Blast radius: approving a spec or tasks authorizes local implementation and local commits only. git push, force-push, deploy, production DB changes, and other remote / externally visible / destructive operations require an explicit go-ahead for that action.

Deterministic gates run before human review - not from memory. The structural gates for the spec and tasks are enforced by scripts in this skill's scripts/ directory, so they cannot silently drift when the model forgets a step:

• Before confirming a spec: python3 <skill-dir>/scripts/validate_spec.py <spec-path-or-feature> (closure gate: EARS-shaped ACs, filled assumptions, well-formed requirement IDs, required sections).
• Before presenting tasks for approval: python3 <skill-dir>/scripts/validate_tasks.py <tasks-path-or-feature> (granularity smell, diagram-vs-Depends on parity within a phase, no forward-phase dependency, every task carries Tests + Gate).
• On each commit: python3 <skill-dir>/scripts/check_commit.py --message "<msg>" (Conventional Commits). Optionally wire it as a git commit-msg guard (git only, no agent dependency) - see implement.md.
• Before declaring a feature done: python3 <skill-dir>/scripts/validate_state.py <feature> (completion gate: the Verifier's validation.md exists, its verdict is filled to PASS, and it cites file:line evidence - a missing, FAIL, placeholder, or evidence-free report fails). The closing step of Execute runs this automatically, the same way the lessons layer runs at distillation; it is not a manual step.

A non-zero exit means STOP and fix before proceeding. Skip a script only when no code-execution tool is available; then perform the same checks by reading the artifact.

Before Execute: read implement.md completely and run <skill-dir>/scripts/validate_tasks.py; if a formal tasks.md packs into more than one task-budgeted batch (> ~8 tasks), present the sub-agent offer first (see Sub-Agent Delegation).

Auto-Sizing: The Core Principle

The complexity determines the depth, not a fixed pipeline. Before starting any feature, assess its scope and apply only what's needed:

Rules:

• Specify and Execute are always required - you always need to know WHAT and DO it
• Design is skipped when the change is straightforward (no architectural decisions, no new patterns)
• Tasks is skipped when there are ≤3 obvious steps (they become implicit in Execute)
• Discuss is triggered within Specify when the agent detects ambiguous gray areas that need user input, or when the feature has any implicit-requirement dimension present (persistence/state, external calls, auth, payments, concurrency, state transitions)
• Interactive UAT is triggered within Execute only for user-facing features with complex behavior

Safety valve: Even when Tasks is skipped, Execute ALWAYS starts by listing atomic steps inline (see implement.md). If that listing reveals >5 steps or complex dependencies, STOP and create a formal tasks.md - the Tasks phase was wrongly skipped.

.specs Structure

.specs/
├── STATE.md            # Project memory: Decisions log (AD-NNN) + Handoff snapshot
├── LESSONS.md          # Self-improving lessons playbook (rendered by scripts/lessons.py - do not hand-edit)
├── lessons.json        # Canonical lessons state (machine-owned)
└── features/           # Feature specifications
    └── [feature]/
        ├── spec.md         # Requirements with traceable IDs
        ├── context.md      # User decisions for gray areas (only when discuss is triggered)
        ├── design.md       # Architecture & components (only for Large/Complex)
        ├── tasks.md        # Atomic tasks with verification (only for Large/Complex)
        └── validation.md   # Verifier report: PASS/FAIL, per-AC evidence, sensor result, diff range

Create artifacts lazily. Write each file only when its phase actually produces content - never scaffold empty context.md, design.md, or tasks.md up front. An empty file signals a phase happened when it did not; absence is the correct state for a skipped phase. The deterministic validators (scripts/validate_spec.py, scripts/validate_tasks.py, scripts/check_commit.py, scripts/validate_state.py) ship inside this skill's own scripts/ directory, alongside lessons.py.

Workflow

New feature:

1. Specify → (Design) → (Tasks) → Execute (depth auto-sized)

Resume work:

1. Read .specs/STATE.md (Handoff + Decisions).
2. Reconcile Handoff against git (branch, status --porcelain, recent commits) and tasks.md - evidence wins over a stale snapshot. Full procedure: memory.md.
3. Propose the reconciled next step before writing code.

Context Loading Strategy

On-demand load (only what the current task needs):

• .specs/STATE.md - Decisions section (read at Design, re-read on resume); Handoff section (read on resume only)
• confirmed lessons - load at Specify and Design via python3 <skill-dir>/scripts/lessons.py list --status confirmed (lessons.md); confirmed only, never candidates
• spec.md (when working on a specific feature)
• context.md (when designing or implementing from user decisions)
• design.md (when implementing from design)
• tasks.md (when executing tasks)

Never load simultaneously:

• Multiple feature specs
• Multiple architecture docs

Target: <40k tokens total context **Reserve:** 160k+ tokens for work, reasoning, outputs **Monitoring:** Display status when >40k (see context-limits.md)