Русская версия: README.ru.md
speckeep — a lightweight Spec-Driven Development kit for dev agents and humans. It keeps specs, plans, tasks, and traceability in simple files so agents and people stay aligned without heavy process.
SpecKeep is the successor to DraftSpec (archived). Migrate with speckeep migrate.
# 1. Try it instantly — no project setup needed
speckeep demo ./my-demo
# 2. See what was created
speckeep dashboard ./my-demo
# 3. Init a real project
speckeep init my-project --lang en --shell sh --agents claudeThat's it. You now have a project with constitution, spec, plan, tasks, inspect report, and data model — plus agent prompt files and AGENTS.md.
Teams using AI coding agents face a common problem: agents lose context between sessions, drift from requirements, and produce untestable code.
speckeep solves this with discipline per token — minimal file-based structure that keeps agents and humans on the same page:
- Specs with stable IDs (
AC-*,RQ-*) — agents know exactly what to build and verify - Tasks with surface maps and phase grouping — agents execute in order, one phase at a time
- Traceability (
Proof:entries intasks.md) — prove that every requirement is implemented and tested - 19 agent adapters — Claude Code, Codex, Cursor, Copilot, OpenCode, aider, Amazon Q, Gemini, Jules, Cline, Devin, Goose, Refact, Windsurf, and more (maintenance tiers) — Continue.dev support was dropped after reports the product was discontinued
- Fast closing loop (
/spk.converge) — turn implementation gaps into follow-up tasks and iterate until converged - CI gate (
speckeep guard) — machine-verifiable "is every feature closeable now?" - Express lane — tiny/low-risk features skip
plan.md/data-model.mdand close fromspec.md+tasks.md - One-shot propose (
/spk.propose) — idea →spec.md+tasks.mdin a single pass, straight to implement - Drop-in migration (
speckeep import openspec|speckit) — convert OpenSpec/Spec Kit feature packages into speckeep layout in seconds - Compact archive (
--compact) — keep onlysummary.md+ git pointer instead of copying every artifact
Results in practice: agents produce correct code on first try more often, handoffs between sessions cost less context, and requirements stay reviewable by humans.
constitution → spec → [inspect] → plan → tasks → implement → archive
verify is an optional on-demand audit; archive is allowed once every [x] task carries a Proof: entry (or after verify: pass).
Each phase loads only the minimum context. Optional workflow commands available at any phase: /spk.challenge, /spk.handoff, /spk.hotfix, /spk.scope, /spk.recap.
| Dimension | speckeep | OpenSpec | Spec Kit |
|---|---|---|---|
| Workflow style | Strict phase chain, narrow context | Fluid artifact-guided | Thorough multi-step SDD |
| Default context | Smallest | Moderate | Largest |
| Artifact overhead | Low | Medium | High |
| Brownfield | High | High | Medium |
| Collaboration | Branch-first, feature-local | Change-folder oriented | Branch-heavy |
| Best fit | Lean strict SDD on real codebases | Flexible SDD-lite | Full-featured rigorous SDD |
speckeep init [path]
speckeep refresh [path]
speckeep doctor [path] [--json]
speckeep dashboard [path]
speckeep check <slug> [path] [--json]
speckeep check [path] --all [--json]
speckeep feature <slug> [path]
speckeep features [path]
speckeep list-specs [path]
speckeep show-spec <name> [path]
speckeep trace <slug> [path]
speckeep export <slug> [path] [--output <file>]
speckeep converge <slug> [path] [--json]
speckeep guard [path] [--slug <slug>] [--json]
speckeep import <openspec|speckit> [path] [--json]
speckeep demo [path]
speckeep archive <slug> [path] [--compact]
speckeep list-archive [path] [--status <status>] [--since <YYYY-MM-DD>] [--json]
speckeep self check | self upgrade
speckeep migrate [path]
speckeep add-agent | list-agents | remove-agent | cleanup-agents [path]
Agent support is skills-first: speckeep init --agents opencode,claude lays a composite SpecKeep sdd skill pack (a root SKILL.md plus one self-contained per-phase skill file, each inlining its full phase instructions) into each target's standard skills directory (.opencode/skills/, .claude/skills/, …). The CLI stays the deterministic spine that skills call as gates (check, converge, guard).
Use the bundled GitHub Action to keep every pull request green against the SpecKeep gate:
- uses: bzdvdn/speckeep/.github/actions/speckeep@main
with:
root: .It installs speckeep, detects changed specs/active/<slug>/ features, and runs speckeep guard on each (fails the PR when a touched feature is not closeable). A copy-paste ready workflow lives in contrib/ci/speckeep-guard.yml.
Linux / macOS:
curl -fsSL "https://raw.githubusercontent.com/bzdvdn/speckeep/main/scripts/install.sh" | bash
# add --version v1.0.0 to pin; --add-to-path to register PATHWindows (PowerShell):
powershell -ExecutionPolicy Bypass -c "iwr -useb https://raw.githubusercontent.com/bzdvdn/speckeep/main/scripts/install.ps1 | iex"The binary is automatically added to PATH on Windows. On Linux, use --add-to-path if the install directory is not already on your PATH.
Package managers:
- Homebrew:
brew install bzdvdn/speckeep/speckeep(seecontrib/packaging/brew/) - Scoop:
scoop bucket add speckeep https://github.com/bzdvdn/speckeep && scoop install speckeep(seecontrib/packaging/scoop/) - npm:
npx speckeep initornpm install -g speckeep— a thin launcher that downloads the matching native binary on install (seecontrib/packaging/npm/) - Go:
go install speckeep@latest
Update the installed binary:
speckeep self check # current vs latest release (read-only)
speckeep self upgrade # download, sha256-verify, and replace in placeBuild from source:
go build -ldflags "-X speckeep/src/internal/cli.Version=v0.8.0" -o bin/speckeep ./src/cmd/speckeepFull workflow: "Add CSV export to reports" →
speckeep init . --lang en --shell sh --agents claudeCall /spk.spec --name "CSV export for reports" in your agent.
specs/active/csv-export-for-reports/spec.md:
## Goal
Allow users to download the reports table as a CSV file.
## Acceptance Criteria
**AC-001** Export produces a file
Given the Reports page has at least one row
When the user clicks "Export CSV"
Then a .csv file downloads with column headers and all visible rows
**AC-002** Empty state is handled
Given the reports table is empty
When the user clicks "Export CSV"
Then a .csv with headers only downloads — no error shownCall /spk.inspect csv-export-for-reports. Produces inspect.md with verdict.
Call /spk.plan csv-export-for-reports. Surfaces: ReportsPage.tsx, useReportExport.ts, reports.test.ts.
Call /spk.tasks csv-export-for-reports. Produces tasks.md:
| Surface | Tasks |
|---|---|
| hooks/useReportExport.ts | T1.1 |
| components/ReportsPage.tsx | T1.2 |
| tests/reports.test.ts | T2.1 |
/spk.implement csv-export-for-reports
/spk.verify csv-export-for-reports # verdict: pass
speckeep archive csv-export-for-reports .
speckeep check csv-export-for-reports
# Phase: tasks → implement
# Tasks: 0 / 3 done
# Next: /spk.implement csv-export-for-reportsEach feature lives under specs/<slug>/ with:
spec.md— requirements (RQ-*) and acceptance criteria (AC-*with Given/When/Then)inspect.md(optional) — quality gate before planningplan.md— design decisions (DEC-*) and incremental deliverytasks.md— executable tasks with surface map and phase groupingdata-model.md— entities, fields, invariantscontracts/api.md,contracts/events.md(optional)verify.md— verification evidence
During implementation, record evidence for each completed task as a Proof: line directly below the [x] checkbox in tasks.md:
- [x] T1.1 Add export handler
Proof: code src/handlers/export.go ExportHandler
Proof: test src/tests/export_test.go TestExportFlow
Proof: <kind> <path> [<anchor>], where kind is code|test|docs|chore. A checked task without a Proof: entry is not done — speckeep check and speckeep archive block it. Evidence is read only from tasks.md; there are no trace markers in source code.
Verify with:
speckeep trace <slug> .Supported out of the box: claude, codex, copilot, cursor, kilocode, opencode, trae, windsurf, roocode, aider, amazonq, gemini, jules, cline, devin, goose, refact, codiumate, qwen-code.
speckeep init my-project --agents opencode,claude # lays the sdd skill packThe skills live under the target's skills directory: a lightweight sdd overview skill plus one independent, directly slash-invocable skill per phase:
.<target>/skills/
sdd/
SKILL.md # overview: workflow chain, gates — reach for this when the phase isn't obvious
spk-spec/
SKILL.md # each phase is its own top-level skill: /spk-spec, /spk-plan, /spk-implement, ...
spk-plan/
SKILL.md
...
Each phase skill is its own directory (not nested resource files) so it is directly slash-invocable — e.g. typing /spk-spec in Claude Code — instead of only reachable through the model deciding to open a linked file. Each one inlines the canonical prompt from .speckeep/templates/prompts/ (kept in sync automatically) so an agent gets the full phase instructions from one file, and is gated by speckeep check; closing uses speckeep converge / speckeep guard. aider additionally gets a .aider/CONVENTIONS.md pointer because it has no skill loader.
Extended docs in docs/:
Project:
A reproducible terminal demo is available under demo/:
go build -o bin/speckeep ./src/cmd/speckeep
vhs demo/quick.tapeRequires Go 1.26+.
go test ./...
go vet ./...
go build -o bin/speckeep ./src/cmd/speckeepReleased under the MIT License.