spec-first

Generate spec.md, todo.md, and decisions.md before coding.

5|Updated Dec 25, 2025
One-click install
npx skills add https://github.com/rohunvora/my-claude-skills --skill spec-first
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spec-first
Source: https://github.com/rohunvora/my-claude-skills/tree/main/.claude/skills/spec-first
Command: npx skills add https://github.com/rohunvora/my-claude-skills --skill spec-first

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Spec-first development enforces a deliberate spec/planning loop for non-trivial tasks. By creating spec.md, todo.md, and decisions.md before coding, teams reduce "looks right" failures and ship with robust tests.

Core Features & Use Cases

  • Stage A: Frame the Problem
  • Stage B: Write spec.md (freeze decisions)
  • Stage C: Generate todo.md (planning)
  • Stage D: Execute Changes (small diffs, frequent verification)
  • Stage E: Verify and Review (adversarial mode)
  • Stage F: Decide What Lasts (policy vs mechanism)

Quick Start

  • Frame the problem and surface tradeoffs; surface constraints; frame minimal version; generate spec.md; create a stepwise plan in todo.md; implement changes in small, testable steps; verify with adversarial review and tests.

Frequently Asked Questions about spec-first

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent 'looks right' failures when building new features?

Spec-first development prevents 'looks right' failures by enforcing explicit planning before coding. Write spec.md to freeze decisions, create todo.md for stepwise execution, and document tradeoffs in decisions.md. This delays implementation until requirements and constraints are clear, reducing costly rework on non-trivial projects.

What's the best way to plan and document multi-file software changes?

Create a spec-first workflow: frame the problem and surface constraints, generate spec.md to capture decisions, build todo.md with testable steps, then execute in small diffs with frequent verification. This produces durable artifacts for diffing, re-use, and adversarial review before shipping.

When should I use spec-first planning instead of starting to code immediately?

Use spec-first planning for new features, projects, or changes spanning 3+ files with unclear requirements or explicit tradeoffs. It's essential for non-trivial software development where decisions need to be frozen upfront and tests drive implementation.

How does spec-first prevent bugs and reduce verification overhead?

Spec-first treats the implementation phase as executing a junior engineer's clear interfaces and tests. By planning and documenting decisions upfront, you catch ambiguities before coding, enable adversarial review, and ensure robust test coverage reduces rework and post-release failures.

Can I use spec-first for small changes or single-file edits?

Spec-first applies to non-trivial efforts requiring explicit tradeoffs, typically 3+ files or unclear requirements. Small, straightforward changes or single-file edits don't require the full planning loop; reserve it for projects where decisions and constraints justify documented specs and stepwise execution.