spec-kit/README.md

speckit

A fully local Spec-Driven Development (SDD) workflow CLI — a rebuild of the idea behind github/spec-kit in a single zero-dependency Python file.

Instead of prompting an AI agent (or yourself) ad hoc, every feature walks a gated artifact pipeline:

constitution  →  specify  →  clarify  →  plan  →  tasks  →  implement  →  converge
(principles)     spec.md    resolve      plan.md   tasks.md   check off     gap check
                            markers                            boxes

Gates are mechanical: plan refuses to run without spec.md, tasks without plan.md, and check validates section structure, clarification markers (cap: 3) and checklist state. No accounts, no API keys, no network — just files.

Requirements

Python 3. Nothing else at runtime (pytest only for developing speckit itself).

Quickstart

python3 speckit.py init myproject --agent claude   # scaffold (drop --agent for plain)
cd myproject
python3 ../speckit.py specify "pantry meal planner" # → specs/001-pantry-meal-planner/spec.md
#   (or: specify prompt.txt --name "pantry planner" — reads the brief from the file)
# ... fill spec.md: stories, requirements, success criteria, assumptions ...
python3 ../speckit.py clarify                       # list open [NEEDS CLARIFICATION: …] markers
python3 ../speckit.py plan                          # → plan.md   (gate: spec.md exists)
python3 ../speckit.py tasks                         # → tasks.md  (gate: plan.md exists)
python3 ../speckit.py status                        # phases + task progress per feature
python3 ../speckit.py check                         # validate current feature (exit 0/1)

A worked example lives in examples/pantry-planner/ — a real feature driven through the entire pipeline.

Commands

Command	What it does
init <name> [--agent claude]	Scaffold <name>/ with .speckit/ state + templates, memory/constitution.md, empty specs/; --agent claude also installs /speckit.* command prompts into .claude/commands/
specify <description or file> [--name "…"] [--timestamp]	Create specs/NNN-slug/spec.md and make it the current feature. The argument can be a quoted description or a path to a file containing the prompt (e.g. specify prompt.txt). Slug = first 4 words (sequential 001, 002, … or YYYYMMDD-HHMMSS- prefix); --name overrides it
switch <NNN or slug>	Re-point the current feature
plan	Seed plan.md for the current feature — refuses while spec.md is missing
tasks	Seed tasks.md — refuses while plan.md is missing
status	All features, per-phase artifact presence, * current marker, N done / M open task counts
check	Validate the current feature: required sections, marker cap (>3 fails), checklist warnings; exit 0 clean / 1 findings
clarify	List every [NEEDS CLARIFICATION: …] marker with file:line
checklist <name>	Seed a reviewer-owned quality checklist into checklists/<name>.md; unchecked items make check warn (never fail)
converge	Append-only gap check: spec stories missing from tasks.md get new checkboxes under ### Convergence; idempotent
constitution [--amend "…" [--major]]	Show the constitution version, or append a dated amendment with a semver bump

Global: --color {auto,always,never} (before the subcommand) — colors only on a real terminal by default.

All commands except init find the project by walking up from the current directory to the nearest .speckit/ — they work from anywhere inside a project (exit 2 outside one).

Working with an AI agent

init --agent claude installs four prompt files into .claude/commands/, so a Claude Code session inside the project gets /speckit.specify, /speckit.plan, /speckit.tasks and /speckit.implement — each prompt tells the agent to run the CLI, fill the seeded artifact properly, and respect the phase gates (implement additionally: work tasks.md top-to-bottom, test-first, check boxes only after verification). The same files work as a howto if you drive the workflow by hand.

Scaffolded project layout

myproject/
  .speckit/state.json        # project name, current feature, feature list
  .speckit/templates/        # your copy of the 5 templates (edit freely)
  .claude/commands/          # agent prompts (with --agent claude)
  memory/constitution.md     # standing principles, semver-versioned
  specs/001-some-feature/
    spec.md  plan.md  tasks.md  checklists/*.md

Developing speckit itself

python3 -m pytest -q        # 51 tests, run from the repo root

Everything lives in speckit.py (stdlib only); document templates in templates/, agent prompts in templates/commands/, tests in tests/test_speckit.py (strictly TDD).