SDD stands for Spec-Driven Development, a four-phase process (specify, plan, tasks, implement) that must be completed before any code is written.

Why can't I write code before the spec?

Because the phases ensure aligned requirements, architecture, and testability, reducing rework and miscommunication. Per §2 Phase 1, a spec must be generated first.

What happens to a spike code request?

A spike can be used for prototypes, but spike code must never be merged without completing the full SDD workflow afterward.

What if a phase is skipped?

Skipping is not allowed. All four phases must be executed sequentially to ensure a complete, reviewable plan and tests before implementation.

What outputs are produced in each phase?

Specifies a Markdown doc for review, Plan documents the technical approach and dependencies, Tasks provides a Markdown checklist of work units with acceptance tests, and Implement follows test-driven coding with Red-Green-Refactor.

sdd-workflow

Scanned

npx machina-cli add skill theinterneti/TTA.dev/sdd-workflow --openclaw

Files (1)

SKILL.md

2.0 KB

Spec-Driven Development Workflow (TTA.dev)

No implementation code may be written before completing the SDD phases.

The 4 Phases

Execute these phases sequentially. No phase may be skipped.

/specify — Functional Specification (The "What")
- User journeys, edge cases, success criteria, out-of-scope
- Output: Markdown document for user review and approval
/plan — Technical Plan (The "How")
- Which packages are affected (tta-dev-primitives, tta-observability-integration, etc.)
- New modules, classes, functions to create
- How the feature composes with existing primitives (>>, |)
- External dependencies with justification
- Observability strategy (traces, metrics, logs)
/tasks — Task Breakdown
- Isolated, testable work units
- Each task includes acceptance test description
- Numbered by dependency (topological sort)
- Format: Markdown checklist
/implement — Test-Driven Implementation
- Red: Write failing test encoding acceptance criteria
- Green: Minimal implementation to pass the test
- Refactor: Clean up while tests stay green
- Run quality gate before marking task complete

Exceptions

/spike: User explicitly requests prototype code. Spike code must never be merged without going through the full SDD workflow afterward.

Enforcement

If the user asks for code without a spec, initiate /specify first and explain the SDD process.
Reference this constitution by section (e.g., "Per §2 Phase 1, I need to generate a spec first.").

Deep Reference

For the complete SDD Constitution with all tables and detailed guidance, see docs/agent-guides/sdd-constitution.md.

Source

git clone https://github.com/theinterneti/TTA.dev/blob/main/.claude/skills/sdd-workflow/SKILL.mdView on GitHub

Overview

SDD enforces a four-phase workflow before coding: specify, plan, tasks, implement. It ensures user journeys, edge cases, and acceptance criteria are captured, mapped to a technical plan, and broken into testable units. This alignment reduces rework by requiring a reviewable spec prior to any implementation.

How This Skill Works

Phases execute sequentially: /specify captures functional requirements and edge cases; /plan outlines the technical approach, affected primitives, modules, dependencies, and observability; /tasks breaks work into testable units with acceptance criteria; /implement follows Test-Driven Implementation (Red, Green, Refactor) and runs a quality gate. If a user requests prototype code, use /spike, but it must later go through the full SDD workflow after review.

When to Use It

You’re asked to build a new feature from scratch and need a documented spec before coding.
Requirements are vague or shifting, and you want a preserved, reviewable plan.
Introducing new primitives, packages, or external dependencies requires formal justification.
You need clear acceptance criteria and testable tasks to align stakeholders.
Developing a critical feature where quality gates and observability are essential.

Quick Start

Step 1: Initiate /specify to document the What—user journeys, edge cases, and acceptance criteria.
Step 2: Create /plan detailing affected primitives, modules, dependencies, and observability strategies.
Step 3: Break into /tasks with acceptance tests, then proceed to /implement using Red-Green-Refactor and pass the quality gate.

Best Practices

Start with a thorough /specify document capturing user journeys, edge cases, success criteria, and out-of-scope items.
Produce Markdown outputs for /specify, /plan, and /tasks to enable reviewer feedback and approval.
Follow the strict sequence: do not begin implementation until all four phases are complete.
In /implement, write failing tests first (Red), then implement minimally to pass (Green), and refactor while keeping tests green.
Use /spike only when explicitly requested for prototype code, and route it through the full SDD workflow afterward.

Example Use Cases

Building a new user authentication flow with explicit success criteria and edge cases in /specify, then mapping dependencies in /plan.
Adding a feature flag controlled UI path where observability (traces/metrics) is planned in /plan and validated in /tasks.
Integrating a third-party API by detailing request/response contracts in /specify and creating isolated, testable tasks in /tasks.
Porting a legacy feature to a new architecture with topological task ordering in /tasks and a test-driven /implement cycle.
Prototyping a dashboard component via /spike, followed by a full SDD cycle to merge into main after review.

Frequently Asked Questions

Add this skill to your agents