SDD Workflow

Spec Driven Development treats specs as living development contracts. Every phase of implementation is gated by clearly defined criteria, validated automatically at each transition.

The Lifecycle

clarify → create_spec → DoR check → implement (PLAN.md) → validate → drift detection → done

Each arrow is a gate. You can't move forward without satisfying the previous phase's Definition of Done.

Phase 1 — Clarify

Tools: clarify_requirements, reality_check

Before writing a single line of spec, surface the ambiguities.

Prompt: "Use specforge to clarify requirements for [feature] in project [id]"

clarify_requirements generates a targeted list of questions — scope boundaries, edge cases, non-functional requirements, external dependencies — so the spec starts with clean, unambiguous intent.

reality_check evaluates whether the requirements are feasible given the current project context. It catches "impossible by Friday" situations before they become tech debt.

Phase 2 — Create the Spec

Tools: create_spec, design_schema, define_ui_contract, generate_adr

Prompt: "Create a spec for [feature] in project [id]"

create_spec generates a structured HU.md with:

Section	What it contains
User Story	Who, what, why
Acceptance Criteria	Testable, unambiguous criteria
DoR Checklist	Definition of Ready gates
Database Schema hints	Tables, columns, relations
UI Contracts	Component contracts, state management
ADR hints	Architecture Decision Records
PLAN.md	Step-by-step execution plan

When the project has AI-native architecture detected, the spec also generates:

• Latency budgets and fallback chains
• Prompt versioning criteria
• LLM observability requirements

Phase 3 — DoR Check

Tools: check_readiness, detect_contradictions

Before implementation starts, verify the spec is actually ready.

Prompt: "Check if spec SPEC-003 is ready for implementation in project [id]"

check_readiness evaluates:

• Completeness of acceptance criteria
• Criteria quality (testable, unambiguous)
• Dependency status (blocking specs resolved?)
• Constitution compliance

detect_contradictions scans all specs for semantic conflicts — catches situations where SPEC-A says "users can delete their account" and SPEC-B says "accounts are immutable."

Phase 4 — Implement

Tools: generate_execution_plan, package_handoff, generate_tests

Prompt: "Generate an execution plan for spec SPEC-003 in project [id]"

generate_execution_plan produces a PLAN.md with:

• RED/GREEN/VERIFY cycle steps
• Parallelizable steps identified
• File ownership per step
• Estimated effort per step

package_handoff bundles the spec into a structured handoff package for an AI agent — objective, criteria, file list, constraints — ready for autonomous implementation.

generate_tests produces a test plan and test file stubs from the spec's acceptance criteria.

Phase 5 — Validate

Tools: validate, audit, security_check

After implementation, verify coverage:

Prompt: "Validate spec SPEC-003 against the code at /path/to/src"

validate checks:

• Which acceptance criteria are covered by code
• Which are missing or partially implemented
• Overall spec coverage percentage

audit scores the implementation 0–100 for:

• SOLID principles
• Clean code
• Architecture compliance
• Constitution violations

security_check runs the spec through OWASP Top 10 and scans code for insecure patterns, generating a security score (A–F).

Phase 6 — Drift Detection

Tools: detect_drift, reconcile_spec

As requirements evolve, keep specs and code aligned:

Prompt: "Detect drift in spec SPEC-003 for project [id]"

detect_drift reports:

• Criteria that no longer match the code
• Constitution violations introduced since last check
• Downstream impact: which other specs are affected by the drift

When drift is intentional (the spec needs updating):

Prompt: "Reconcile spec SPEC-003 with the implementation changes in project [id]"

reconcile_spec presents each change for per-change approval and checks Constitution compliance before saving.

The Project Constitution

The Constitution is a set of immutable architectural principles extracted from your CLAUDE.md, .cursorrules, or other AI agent config files.

Prompt: "Initialize the constitution for project [id] from CLAUDE.md"

Once set, the Constitution is automatically enforced in create_spec, audit, and detect_drift. Violations are flagged before they reach code review.

Status Transitions

Status	Description
draft	Spec created, not yet ready
ready	Passed DoR check
in_progress	Implementation started
review	Implementation complete, pending validation
done	Validated and accepted
blocked	Blocked by dependency

Prompt: "Update status of spec SPEC-003 to in_progress in project [id]"

Each transition runs DoR/DoD validation. You can't mark a spec done without meeting the DoD criteria.