# speckit

A fully local Spec-Driven Development (SDD) workflow CLI — a rebuild of the
idea behind [github/spec-kit](https://github.com/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

```bash
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/`](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

```bash
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).