Strict, lightweight spec-driven development for coding agents. speckeep keeps specs, plans, tasks, and traceability in plain files so agents and people stay aligned — without heavy process.
English · Русский · Docs · Roadmap · Releases
- Quick Start
- Why speckeep?
- Workflow
- Positioning
- CLI
- CI
- Install
- Example Feature Cycle
- Documentation
- Development
- License
# 0. Install — npm is the recommended path (or use npx without installing)
npm install -g speckeep@1.2.2
# npx speckeep@1.2.2 demo ./my-demo
# 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 - Module context (
/spk-module-context) — ask the agent to write/refresh a folder'sCONTEXT.md("what/how/why"), indexed fromREPOSITORY_MAP.mdso agents onboarding into a module/app don't lose context
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] [--tests|--files]
speckeep trace --file <path> [path]
speckeep trace init <slug> [path]
speckeep trace rebuild [slug] [path] [--all]
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.
Recommended — npm (current release: v1.2.2). The npm launcher downloads the matching native binary for your OS/arch, so PATH usually just works:
npm install -g speckeep@1.2.2
# or run without a global install
npx speckeep@1.2.2 init my-project --lang en --agents claudeNative installer (Linux / macOS):
VERSION=v1.2.2
curl -fsSL "https://raw.githubusercontent.com/bzdvdn/speckeep/${VERSION}/scripts/install.sh" | bash -s -- --version "${VERSION}"
# --add-to-path registers the install directory in PATHWindows (PowerShell):
npm install -g speckeep@1.2.2
# Native alternative
$version="v1.2.2"
$env:SPECKEEP_VERSION=$version
powershell -ExecutionPolicy Bypass -c "iwr -useb https://raw.githubusercontent.com/bzdvdn/speckeep/$version/scripts/install.ps1 | iex"The native binary is automatically added to PATH on Windows. On Linux, use --add-to-path if the install directory is not already on your PATH.
Other package managers:
- Homebrew:
brew install bzdvdn/speckeep/speckeep(seecontrib/packaging/brew/) - Scoop:
scoop bucket add speckeep https://github.com/bzdvdn/scoop-speckeep && scoop install speckeep(seecontrib/packaging/scoop/) - Go:
go install speckeep@latest
Update the installed binary:
# npm install
npm install -g speckeep@latest
# native install
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=v1.2.2" -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> . # Proof evidence for completed tasks
speckeep trace <slug> . --files # actual changed files mapped to tasks
speckeep trace --file src/handlers/export.go . # reverse lookup across active + archived specsChange attribution is pinned when the feature branch is created (speckeep trace init <slug>) and persisted as changes.json on archive, so trace --file keeps working after merges.
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.
Large multi-project repos (monorepos, or front + backend + mobile clients) are where agents lose context fastest. Two lightweight pieces keep them oriented:
REPOSITORY_MAP.md(/spk-repo-map) is the map: it lists modules/apps and points to each one's context —## Modules & Context(path, role,CONTEXT.mdwhen present, else(no context — run /spk-module-context <path>))./spk-module-context <path>asks the agent to read a folder (e.g.src,ui) and write/refresh<path>/CONTEXT.mdwith prose — Purpose, Responsibilities, How it works, Key files, Public contracts, Gotchas. Invoke it manually, or afterimplementthe agent suggests it when a module was created/restructured.
Agents entering a module read its CONTEXT.md first (and repo-map for the wider picture) instead of re-deriving the architecture by grepping everything.
/spk-repo-map # map: modules & apps -> CONTEXT.md pointers
/spk-module-context src # document the Go/backend app into src/CONTEXT.md
/spk-module-context ui # document the UI into ui/CONTEXT.mdLean by design: no generated graphs, no CLI auto-parsing — the agent gathers and writes facts, and repo-map carries the index.
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.