Spec Dev

Spec-Driven Development Skill

The Workflow

Think before you build. Every project starts with three documents in sequence. No code until tasks.md is finalized.

.spec-dev/
├── requirements.md   ← What problem are we solving and for whom?
├── spec.md           ← How will we solve it? (decisions, architecture, scope)
└── tasks.md          ← What exactly needs to be built, in what order?

Once all three are done and Harshul signs off, proposals/plans go into Notion.

---

Step 1: requirements.md

The "what and why" — no solutions yet.

# Requirements: [Project/Feature Name]

## Problem Statement
[1-2 sentences: what is broken or missing, and for whom?]
[Be specific. "Engineers waste time X" is better than "the process is inefficient."]

## Goals
- [Goal 1 — measurable if possible]
- [Goal 2]
- [Goal 3]

## Non-Goals (explicitly out of scope)
- [Thing we are NOT building]
- [Edge case we are NOT handling in v1]

## Success Criteria
[How will we know this worked? What metrics, behaviors, or outcomes signal success?]

## Constraints
- [Technical constraint — e.g., "must work with existing Redis setup"]
- [Time constraint — e.g., "needs to ship before X"]
- [Resource constraint]

## Open Questions
- [Things we don't know yet that affect the design]

---

Step 2: spec.md

The "how" — decisions made, architecture chosen, scope locked. Only write this after requirements.md is stable.

# Spec: [Project/Feature Name]

Status: Draft | In Review | Finalized
Last updated: [date]

## Summary
[2-3 sentences: what we're building and the core approach]

## Design Decisions

### Decision 1: [Topic]
**Options considered**: [A], [B], [C]
**Chosen**: [A]
**Why**: [Reasoning — tradeoffs made explicit]

### Decision 2: [Topic]
...

## Architecture / Approach

[Describe the system, flow, or implementation approach.
Use diagrams if helpful (ASCII or mermaid).
Be specific enough that someone else could implement it from this doc.]

## Data Model / Schema (if applicable)
[Tables, fields, types, relationships]

## API / Interface Design (if applicable)
[Endpoints, inputs, outputs, error states]

## Edge Cases and Error Handling
- [Edge case 1 → how handled]
- [Edge case 2 → how handled]

## What's Explicitly Not in v1
[Repeat non-goals from requirements + any new ones discovered during design]

## Dependencies
- [External service or library relied upon]
- [Internal system or team dependency]

## Open Questions (resolved)
- [Q from requirements.md] → [Answer]

---

Step 3: tasks.md

The "what gets built, in what order" — atomic, actionable, sequenced. Only write this after spec.md is finalized.

# Tasks: [Project/Feature Name]

## Status
[ ] Not started  [x] In progress  [✓] Done

## Phase 1: [Phase name — e.g., "Foundation"]
- [ ] [Task 1 — specific enough to know when it's done]
- [ ] [Task 2]
- [ ] [Task 3]

## Phase 2: [Phase name — e.g., "Core feature"]
- [ ] [Task 4]
- [ ] [Task 5]

## Phase 3: [Phase name — e.g., "Testing + cleanup"]
- [ ] Write tests for [X]
- [ ] Update docs / README
- [ ] Code review
- [ ] Deploy / ship

## Blocked by
- [Task X is blocked by Y]

## Notes
- [Any sequencing rationale or implementation notes]

Task quality bar: Each task should be completable in one focused session (2-4 hours max). If a task would take longer, break it down.

---

Step 4: Log to Notion (when finalized)

Once requirements, spec, and tasks are signed off, the project goes into Notion.

Depending on what it is:

If it's a talk/paper proposal: → Create entry in CFP DB (collection://1b4e2e4a-acb4-804e-9047-000bf8dade67) → Tag with conference/event name → Body: paste the abstract + outline from spec.md

If it's a research/learning project: → Create entry in Notes DB (collection://9883f279-86ea-4d45-a916-2fe9f0fc32ad) → Set Status to In progress → Link to Personal projects if it belongs to a project → Body: paste spec summary and key decisions

Use notion-create-pages for either.

---

Workflow Summary

1. requirements.md  →  Harshul reviews  →  approved?
2. spec.md          →  Harshul reviews  →  approved?
3. tasks.md         →  Harshul reviews  →  approved?
4. Build            →  work through tasks.md phase by phase
5. Log to Notion    →  when finalized or shipped

No step can be skipped. If requirements aren't clear, don't write the spec. If the spec has open decisions, don't write tasks. The three docs force clarity before code.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: harshuljain13
• Source: harshuljain13/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.