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 → challenge_spec → check_readiness → update_status(review)
→ update_status(approved) → update_status(implementing) → validate → update_status(done)
→ drift detection

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 planu 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 spec.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
Execution guidance	Grounded implementation hints, files, and lifecycle metadata

Each spec is a single unified document since SPEC-630:

File	Purpose
spec.md	User story, acceptance criteria, technical detail, file lists, status, history — all in one document with rich frontmatter

Migration note: older Planu projects may still have technical.md, progress.md, or *-report.html files alongside specs. Run heal_spec_docs to merge and clean them up automatically. New specs are created in the unified format.

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 exists but has not passed review gates
review	Spec is being stress-tested and reviewed as a plan
approved	Spec plan is approved and locked for implementation
implementing	Production work is in progress against the approved contract
done	Validation and reviewer evidence passed
blocked	Work is paused by an active blocker

Prompt: "Run validate for SPEC-003, then update_status(done) in project [id]"

Each transition runs lifecycle gates. In particular, done requires a successful validate pass plus fresh reviewer evidence.