# Eng Spec Driven

> Spec-driven development workflow for planning before coding with Factory

- Skill: `tjboudreaux/eng-spec-driven` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tjboudreaux/eng-spec-driven`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tjboudreaux/eng-spec-driven/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tjboudreaux (https://skillmd.com/u/tjboudreaux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tjboudreaux/eng-spec-driven

---


# Spec-Driven Development Skill

Expert guidance for planning and documenting before implementation.

## When to Use

- Before implementing new features
- When requirements are unclear
- For complex architectural decisions
- When multiple implementation paths exist
- Before major refactoring efforts

## Spec-Driven Workflow

### Overview

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  1. Gather  │ ──▶ │  2. Analyze │ ──▶ │  3. Specify │ ──▶ │ 4. Implement│
│ Requirements│     │    Risks    │     │   & Approve │     │    (TDD)    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
```

### Phase 1: Gather Requirements

Use `thinking-socratic` skill to clarify requirements:

**Questions to Ask:**
- What problem are we solving?
- Who are the users/stakeholders?
- What are the success criteria?
- What are the constraints (time, tech, budget)?
- What existing systems are affected?
- What are the non-functional requirements?

**Output:**
```markdown
## Requirements Summary

### Problem Statement
[Clear description of the problem]

### Users/Stakeholders
- Primary: [who]
- Secondary: [who]

### Success Criteria
1. [Measurable outcome]
2. [Measurable outcome]

### Constraints
- Technical: [constraints]
- Timeline: [deadline]
- Dependencies: [systems]
```

### Phase 2: Analyze Risks

Use `thinking-pre-mortem` skill to identify risks:

**Pre-Mortem Exercise:**
> "Imagine this feature has failed spectacularly. What went wrong?"

**Risk Categories:**
- Technical risks (complexity, unknown tech)
- Integration risks (APIs, databases, services)
- Performance risks (scale, latency)
- Security risks (auth, data exposure)
- Operational risks (deployment, monitoring)

**Output:**
```markdown
## Risk Analysis

### High Priority Risks
| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| [risk] | High | Medium | [strategy] |

### Assumptions
1. [assumption to validate]
2. [assumption to validate]

### Open Questions
1. [question needing answer]
```

### Phase 3: Write Specification

**Spec Document Structure:**

```markdown
# Feature: [Name]

## Overview
[1-2 paragraph summary]

## Requirements
- [REQ-1] [Description]
- [REQ-2] [Description]

## Technical Design

### Architecture
[Diagram or description of component interactions]

### API Design
```
POST /api/resource
Request:
{
  "field": "value"
}
Response:
{
  "id": "123",
  "field": "value"
}
```

### Database Schema
```sql
CREATE TABLE resource (
    id SERIAL PRIMARY KEY,
    field VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);
```

### Components
1. **Component A** - [responsibility]
2. **Component B** - [responsibility]

## Test Plan
- Unit: [what to test]
- Integration: [what to test]
- E2E: [what to test]

## Implementation Plan
1. [ ] Step 1 - [description]
2. [ ] Step 2 - [description]
3. [ ] Step 3 - [description]

## Rollout Plan
- [ ] Deploy to staging
- [ ] QA verification
- [ ] Deploy to production (% rollout)

## Metrics & Monitoring
- [Metric to track]
- [Alert to set up]

## Timeline
| Milestone | Date |
|-----------|------|
| Spec approved | [date] |
| Implementation complete | [date] |
| QA complete | [date] |
| Production release | [date] |
```

### Phase 4: Review & Approve

Use `ExitSpecMode` tool to present spec for approval:

```
The spec is ready for review. Key decisions:

1. **API Design**: REST vs GraphQL → Chose REST for simplicity
2. **Database**: PostgreSQL for ACID compliance
3. **Auth**: JWT tokens with refresh mechanism

Options to consider:
- Option A: [approach] - Pros: [x], Cons: [y]
- Option B: [approach] - Pros: [x], Cons: [y]

Recommendation: Option A because [reason]
```

### Phase 5: Implement with TDD

After approval, use `eng-tdd` skill:

1. **Red**: Write failing test
2. **Green**: Write minimal code to pass
3. **Refactor**: Improve code quality

## Spec Templates

### API Endpoint Spec

```markdown
# API: [Endpoint Name]

## Endpoint
`POST /api/v1/resources`

## Purpose
[What this endpoint does]

## Authentication
- Required: Yes
- Method: Bearer token

## Request
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer {token} |
| Content-Type | Yes | application/json |

### Body
```json
{
  "name": "string (required, 1-100 chars)",
  "description": "string (optional, max 500 chars)",
  "category_id": "integer (required)"
}
```

## Response

### Success (201 Created)
```json
{
  "id": 123,
  "name": "Resource Name",
  "description": "Description",
  "category_id": 1,
  "created_at": "2024-01-15T12:00:00Z"
}
```

### Errors
| Code | Description |
|------|-------------|
| 400 | Invalid request body |
| 401 | Unauthorized |
| 404 | Category not found |
| 422 | Validation error |

## Business Rules
1. Name must be unique within category
2. User must have write permission
3. [Other rules]

## Test Cases
- [ ] Create with valid data → 201
- [ ] Create with missing name → 400
- [ ] Create without auth → 401
- [ ] Create with invalid category → 404
- [ ] Create duplicate name → 422
```

### Database Migration Spec

```markdown
# Migration: [Name]

## Purpose
[Why this migration is needed]

## Changes

### New Tables
```sql
CREATE TABLE feature_flags (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) UNIQUE NOT NULL,
    enabled BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT NOW()
);
```

### Altered Tables
```sql
ALTER TABLE users
ADD COLUMN last_login_at TIMESTAMP;
```

### Indexes
```sql
CREATE INDEX idx_users_last_login ON users(last_login_at);
```

## Data Migration
```sql
UPDATE users SET last_login_at = created_at WHERE last_login_at IS NULL;
```

## Rollback Plan
```sql
ALTER TABLE users DROP COLUMN last_login_at;
DROP TABLE feature_flags;
```

## Impact
- Downtime required: No
- Estimated duration: < 1 minute
- Affected services: [list]
```

### Feature Spec

```markdown
# Feature: [Name]

## User Story
As a [user type]
I want to [action]
So that [benefit]

## Acceptance Criteria
- [ ] Given [context], when [action], then [outcome]
- [ ] Given [context], when [action], then [outcome]

## UI/UX
[Mockup link or description]

## Technical Approach

### Frontend
- Components: [list]
- State management: [approach]
- API calls: [list]

### Backend
- Endpoints: [list]
- Services: [list]
- Models: [list]

### Database
- Tables affected: [list]
- New migrations: [list]

## Dependencies
- [ ] [Dependency 1]
- [ ] [Dependency 2]

## Out of Scope
- [What's NOT included]
```

## Integration with Factory

### Using Thinking Skills

```markdown
## Before Writing Spec

1. **Clarify with Socratic Method** (thinking-socratic)
   - What assumptions am I making?
   - What would happen if this failed?
   - Who else needs to be involved?

2. **Identify Risks** (thinking-pre-mortem)
   - What could go wrong?
   - What are we overlooking?

3. **Consider Second-Order Effects** (thinking-second-order)
   - How will this affect other systems?
   - What behavior will this incentivize?

4. **Debias Your Thinking** (thinking-debiasing)
   - Am I anchored to one solution?
   - Am I overconfident?
```

### Spec Mode in Factory

```bash
# Enter spec mode for a feature
/spec Add user authentication

# Factory will:
# 1. Activate spec mode
# 2. Use thinking skills to clarify requirements
# 3. Draft specification
# 4. Present with ExitSpecMode for approval
```

## Best Practices

1. **Spec before code** - Always document before implementing
2. **Keep specs updated** - Update when requirements change
3. **Link to issues** - Reference GitHub issues/Jira tickets
4. **Include diagrams** - Visual architecture aids understanding
5. **Define done** - Clear acceptance criteria
6. **Consider edge cases** - Error handling, empty states
7. **Plan for rollback** - Always have a backout plan
8. **Get early feedback** - Share drafts before finalizing
9. **Time-box speculation** - Don't over-engineer specs
10. **Test the spec** - Review with stakeholders

## Anti-Patterns to Avoid

- **Analysis paralysis** - Spending too long on specs
- **Waterfall specs** - Not iterating on specs
- **Missing stakeholders** - Not involving the right people
- **Undocumented decisions** - Losing context over time
- **Gold plating** - Over-specifying implementation details
- **No validation** - Not checking assumptions