97 lines
4.8 KiB
Markdown
97 lines
4.8 KiB
Markdown
# 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).
|