Spec-Driven Implementation

Overview

Implement features from validated specifications using Test-Driven Development, with continuous spec compliance checking throughout.

This is the core SDD implementation workflow: Spec → Plan → TDD → Verify.

Critical Rule: Implementation MUST match spec. Any deviation triggers spec evolution workflow.

When to Use

Use this skill when:

• Spec exists and is validated
• Ready to write code
• Starting implementation of new feature

Don't use this skill when:

• No spec exists → Use sdd:spec or sdd:brainstorm first
• Spec/code mismatch exists → Use sdd:evolve
• Debugging existing code → Use systematic-debugging

Technical Prerequisites

Ensure spec-kit is initialized:

{Skill: spec-kit}

If spec-kit prompts for restart, pause this workflow and resume after restart.

Workflow Prerequisites

Before starting implementation:

• Spec exists in specs/features/[feature-name].md
• Spec validated for soundness (sdd:review-spec)
• Spec validated against constitution (if exists)
• No open questions in spec that block implementation

If prerequisites not met: Stop and address them first.

The Process

1. Read and Understand Spec

Load the spec:

cat specs/features/[feature-name].md

Extract key information:

• Functional requirements (what to build)
• Success criteria (how to verify)
• Error handling (what can go wrong)
• Dependencies (what's needed)
• Constraints (limitations)

Validate understanding:

• Summarize spec back to user
• Confirm no ambiguities remain
• Identify any implementation questions

2. Generate Implementation Plan FROM Spec

Use sdd:writing-plans skill to create plan.

The plan MUST:

• Derive directly from spec requirements
• Include all functional requirements
• Cover all error cases
• Address all edge cases
• Reference spec sections explicitly

Plan structure:

# Implementation Plan: [Feature Name]

**Source Spec:** specs/features/[feature-name].md
**Date:** YYYY-MM-DD

## Requirements Coverage

### Functional Requirement 1: [From spec]
**Implementation approach:**
- [ ] Task 1
- [ ] Task 2
...

[Repeat for all functional requirements]

## Error Handling Implementation

[For each error case in spec]
- **Error:** [From spec]
- **Implementation:** [How to handle]

## Test Strategy

[How we'll verify each requirement]

## Files to Create/Modify

[List with file paths]

## Verification Steps

- [ ] All tests pass
- [ ] Spec compliance check passes
- [ ] Code review against spec

Save plan: docs/plans/[date]-[feature]-implementation.md

3. Set Up Isolated Workspace

Use using-git-worktrees (optional but recommended):

git worktree add ../feature-[name] -b feature/[name]
cd ../feature-[name]

Or work in current branch:

• Ensure clean working directory
• Create feature branch if needed

4. Implement with Test-Driven Development

Use test-driven-development skill.

For each requirement in spec:

1. Write test first (based on spec requirement)

   • Test validates spec requirement directly
   • Include error cases from spec
   • Include edge cases from spec

2. Watch it fail

   • Confirms test is testing the right thing
   • Red phase of TDD

3. Write minimal code to pass

   • Implement spec requirement
   • Don't add features not in spec
   • Green phase of TDD

4. Refactor

   • Clean up while keeping tests green
   • Refactor phase of TDD

5. Verify spec compliance

   • Does code match spec requirement?
   • Check implementation against spec section
   • Document any necessary deviations

Track progress with TodoWrite:

• Mark requirements as in_progress/completed
• One requirement at a time
• Don't skip or batch

5. Continuous Spec Compliance Checking

During implementation, regularly check:

# Compare implementation to spec
# For each functional requirement:
# - ✓ Implemented as specified
# - ✗ Deviation detected → document reason

If deviation needed:

• Document WHY spec cannot be followed
• Note what changed and reason
• Will trigger sdd:evolve during review

6. Code Review Against Spec

Use sdd:review-code skill.

Review checks:

• Code implements all spec requirements
• No extra features beyond spec
• Error handling matches spec
• Edge cases covered per spec
• Tests validate spec requirements

Output:

• Compliance score (% of requirements met)
• List of deviations with reasons
• Recommendations: approve or evolve

7. Verification Before Completion

Use sdd:verification-before-completion skill.

Verification steps:

1. All tests pass
2. Spec compliance validation passes
3. No unaddressed deviations
4. All success criteria met (from spec)

If verification fails: Fix issues before claiming completion.

Checklist

Use TodoWrite to track:

• Read and understand spec
• Generate implementation plan from spec
• Set up workspace (worktree or branch)
• For each requirement: TDD cycle (test, fail, implement, pass, refactor)
• Check spec compliance continuously
• Request code review against spec
• Run verification (tests + spec compliance)
• Address any deviations (evolve spec or fix code)
• Commit implementation
• Clean up workspace

Example Flow

User: Let's implement the user profile API from the spec

You: I'm using sdd:implement to build this feature from the spec.

Reading spec: specs/features/user-profile-api.md

The spec defines:
- PUT /api/users/:id/profile endpoint
- Fields: name (2-50 chars), bio (max 500), avatar_url
- Auth: JWT required
- Errors: 401, 403, 404, 422
- Success criteria: authenticated users can update profiles

Generating implementation plan from spec...
[Uses sdd:writing-plans]

Plan created: docs/plans/2025-11-10-user-profile-api-implementation.md

Plan includes:
1. Create route handler (src/api/users/profile.ts)
2. Add validation middleware (src/middleware/validate-profile.ts)
3. Update service layer (src/services/user.ts)
4. Add tests (tests/api/users/profile.test.ts)

Ready to implement with TDD. Starting...

[Uses test-driven-development]

Test 1: Should reject unauthenticated requests (Spec: Error Handling)

Writing test...
```typescript
test('PUT /api/users/:id/profile returns 401 without JWT', async () => {
  const response = await request(app)
    .put('/api/users/123/profile')
    .send({ name: 'Test' });

  expect(response.status).toBe(401);
  expect(response.body.error).toBe('Authentication required');
});

Running test... ❌ FAIL (expected - no auth implemented yet)

Implementing auth middleware... [Adds JWT validation]

Running test... ✅ PASS

Spec compliance check: ✓ Matches spec requirement: "User must be authenticated with valid JWT" ✓ Error message matches spec: "Authentication required"

---

Test 2: Should validate name length (Spec: Functional Requirements #2)

Writing test...

test('PUT /api/users/:id/profile validates name length', async () => {
  const token = generateTestJWT({ sub: '123' });

  // Too short
  let response = await request(app)
    .put('/api/users/123/profile')
    .set('Authorization', `Bearer ${token}`)
    .send({ name: 'A' });

  expect(response.status).toBe(422);

  // Too long
  response = await request(app)
    .put('/api/users/123/profile')
    .set('Authorization', `Bearer ${token}`)
    .send({ name: 'A'.repeat(51) });

  expect(response.status).toBe(422);

  // Valid
  response = await request(app)
    .put('/api/users/123/profile')
    .set('Authorization', `Bearer ${token}`)
    .send({ name: 'Valid Name' });

  expect(response.status).toBe(200);
});

Running test... ❌ FAIL

Implementing validation... [Adds name length validation]

Running test... ✅ PASS

Spec compliance check: ✓ Matches spec: "name: string, 2-50 characters"

---

[Continues through all requirements...]

All requirements implemented ✓

Requesting code review against spec... [Uses sdd:review-code]

Code Review Results: ✓ All functional requirements implemented (6/6) ✓ All error cases handled (4/4) ✓ All edge cases covered (3/3) ✓ Tests validate spec requirements

Spec Compliance: 100%

Deviations detected: 1

• Added updated_at field to response (not in spec) Reason: Standard practice for update endpoints Recommendation: Update spec (minor addition)

Running verification... [Uses sdd:verification-before-completion]

✅ All tests passing (24/24) ✅ Spec compliance validated ⚠️ Minor deviation: updated_at field

Recommendation: Use sdd:evolve to update spec with updated_at field

You: Should I update the spec to include the updated_at field?

## Handling Deviations

**When code deviates from spec:**

1. **Document the deviation** during implementation
2. **Note the reason** (technical constraint, better approach, etc.)
3. **Continue implementation** (don't block on it)
4. **Trigger evolution** during review
5. **Use `sdd:evolve`** to reconcile

**Never:**
- Silently deviate without documentation
- Force-fit code to incorrect spec
- Skip spec compliance checks

## Integration with Superpowers Skills

**This skill orchestrates:**
- `sdd:writing-plans` - Generate plan from spec
- `test-driven-development` - TDD implementation
- `sdd:review-code` - Spec compliance review
- `sdd:verification-before-completion` - Tests + spec validation
- `sdd:evolve` - If deviations need reconciliation

**Also compatible with:**
- `using-git-worktrees` - Isolated workspace
- `systematic-debugging` - If bugs found during implementation

## Success Criteria

**Implementation is complete when:**
- [ ] All spec requirements implemented
- [ ] All tests passing
- [ ] Spec compliance 100% (or deviations reconciled)
- [ ] Code review passed
- [ ] Verification passed
- [ ] All success criteria from spec met

## Common Pitfalls

**Avoid:**
- Implementing features not in spec
- Skipping TDD (spec doesn't mean no tests!)
- Ignoring error cases from spec
- Deviating without documentation
- Claiming completion before verification

**Instead:**
- Implement only what's in spec (YAGNI)
- TDD for every requirement
- Test all error cases from spec
- Document all deviations
- Verify before completing

## Remember

**The spec is your contract.**

- Don't add features not in spec
- Don't skip requirements from spec
- Don't ignore error cases in spec
- Don't deviate silently

**If spec is wrong or incomplete:**
- Document the issue
- Continue implementation
- Use `sdd:evolve` to fix spec

**Quality gates exist for a reason:**
- TDD ensures testability
- Code review ensures compliance
- Verification ensures correctness

**Follow the process. Ship quality code that matches the spec.**