Spec-Driven Development

Spec-driven development workflow inspired by github/spec-kit .

Phases

1. Research

Understand the landscape before building.

What exists? How do others solve this?
Best practices and patterns
Trade-offs between approaches

Output: Research document (can be stored separately)

2. Spec

Document what we’re building. Each feature gets a directory with three files:


specs/<feature>/
├── spec.md    # What: goals, scope, API surface, requirements
├── plan.md    # How: implementation strategy, file structure, code examples
└── tasks.md   # Work: issues, dependencies, checklists, acceptance criteria

spec.md

Overview and goals
Success criteria
Architecture / components
Scope (in/out)
API surface
Non-functional requirements
Risks and mitigations

plan.md

Implementation strategy and approach
Detailed phases with file structures
Code examples / pseudocode
Dependencies between components
Estimates
Testing strategy

tasks.md

Task breakdown with issue templates
Dependencies graph
Implementation checklists
Acceptance criteria per task
Progress tracking

3. Tickets

Create GitHub Issues from tasks.md.

Principle: Specs Are Source of Truth


specs/<feature>/tasks.md  ← Detailed requirements, checklists, code examples
         ↓
GitHub Issues  ← Lightweight tracking: "Did we do tasks X, Y, Z?"

Don’t duplicate details into issues. Issues should reference the spec.

Issue Structure

Keep issues minimal:


## [Issue Title]
 
**Spec**: `specs/<feature>/`
**Tasks**: [X, Y, Z] from `tasks.md`
**Effort**: ~[N] hours
**Depends on**: #[issue]
 
### Progress
- [ ] Task X: [Name]
- [ ] Task Y: [Name]
- [ ] All tests passing
- [ ] PR reviewed & merged
 
See `specs/<feature>/tasks.md` for detailed acceptance criteria.

Bundling Tasks

Group related tasks into issues (3-7 hours each):

Foundation: Setup + Models + Storage
Business Logic: Manager + Unit Tests
API Layer: Routes + Middleware + Integration Tests
Polish: Documentation + Manual Testing

See individual feature tasks.md for specific bundling recommendations.

Labels

Feature name (e.g., auth, billing)
Type (e.g., enhancement, bug, refactor)

4. Implement

Build it.

One PR per ticket
CI must pass
PR merged to main triggers deploy

Directory Structure


specs/           # Specifications (committed)
├── feature-name/
│   ├── spec.md      # What: User stories, acceptance criteria
│   ├── plan.md      # How: Technical implementation
│   └── tasks.md     # When: Task breakdown
examples/            # Usage examples
tests/               # Test files
src/                 # Source code

Naming Convention

Spec directories: <feature>/