{"id":50415513,"url":"https://github.com/bzdvdn/speckeep","last_synced_at":"2026-05-31T05:31:08.517Z","repository":{"id":350939107,"uuid":"1207877976","full_name":"bzdvdn/speckeep","owner":"bzdvdn","description":"strict lightweight SDD for brownfield\\greenfield agent workflow","archived":false,"fork":false,"pushed_at":"2026-05-14T18:37:07.000Z","size":3952,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-14T20:33:33.266Z","etag":null,"topics":["agentic-workflows","ai","ai-agents","brownfield","claude","codex","context-engineering","developer-tools","develpoment","golang","greenfield","kilocode","llm","sdd","spec","spec-driven-development","windsurf"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bzdvdn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-11T14:24:58.000Z","updated_at":"2026-05-14T18:37:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bzdvdn/speckeep","commit_stats":null,"previous_names":["bzdvdn/speckeep"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/bzdvdn/speckeep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdvdn%2Fspeckeep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdvdn%2Fspeckeep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdvdn%2Fspeckeep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdvdn%2Fspeckeep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bzdvdn","download_url":"https://codeload.github.com/bzdvdn/speckeep/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzdvdn%2Fspeckeep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33720897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflows","ai","ai-agents","brownfield","claude","codex","context-engineering","developer-tools","develpoment","golang","greenfield","kilocode","llm","sdd","spec","spec-driven-development","windsurf"],"created_at":"2026-05-31T05:31:08.380Z","updated_at":"2026-05-31T05:31:08.510Z","avatar_url":"https://github.com/bzdvdn.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# speckeep\n\n[![ci](https://github.com/bzdvdn/speckeep/actions/workflows/ci.yml/badge.svg)](https://github.com/bzdvdn/speckeep/actions/workflows/ci.yml)\n[![release-build](https://github.com/bzdvdn/speckeep/actions/workflows/release-build.yml/badge.svg)](https://github.com/bzdvdn/speckeep/actions/workflows/release-build.yml)\n\nРусская версия: [README.ru.md](README.ru.md)\n\n`speckeep` is a lightweight project context kit for development agents and humans.\n\nIt keeps project intent, specifications, feature artifacts, and task breakdowns in simple files without introducing a rigid process engine.\n\nSpecKeep is the successor to DraftSpec (archived). If you are migrating an existing DraftSpec workspace, start with `speckeep migrate`.\n\nSpecKeep is intentionally optimized for low overhead and real-world usage: narrow default context, minimal required artifacts, strict workflow discipline without heavyweight orchestration, and branch-based collaboration that works cleanly for both solo and team development.\n\n## Positioning\n\nSpecKeep is a strict lightweight SDD kit for real codebases.\n\nIt is designed for teams that want more discipline than a loose planning layer, but do not want the workflow surface, artifact overhead, or orchestration weight of a heavier SDD system.\n\n- stricter than OpenSpec in phase discipline and artifact alignment\n- lighter than Spec Kit in default context, workflow surface, and artifact overhead\n- optimized for agent-first workflows with narrow context loading\n- designed to keep strictness in templates, entrypoints, and readiness checks rather than heavyweight orchestration\n- built for brownfield repositories where context must stay narrow, local, and reviewable\n\nIn short: SpecKeep aims to maximize discipline per token: strong phase boundaries, low artifact drag, and enough structure to keep agents and humans aligned in everyday work.\n\n## SpecKeep vs OpenSpec vs Spec Kit\n\n| Dimension                | SpecKeep                              | OpenSpec                             | Spec Kit                         |\n| ------------------------ | -------------------------------------- | ------------------------------------ | -------------------------------- |\n| Workflow style           | Strict phase chain with narrow context | Fluid artifact-guided workflow       | Thorough multi-step SDD workflow |\n| Default context size     | Smallest by default                    | Moderate                             | Largest                          |\n| Artifact overhead        | Low                                    | Medium                               | High                             |\n| Phase discipline         | High                                   | Medium                               | Highest                          |\n| Brownfield ergonomics    | High                                   | High                                 | Medium                           |\n| Team collaboration model | Branch-first, feature-local artifacts  | Change-folder oriented               | Branch and workflow heavy        |\n| Shared mutable state     | Avoided by design                      | Low                                  | Varies by setup                  |\n| Best fit                 | Lean strict SDD on real codebases      | Flexible SDD-lite for fast iteration | Full-featured rigorous SDD       |\n\nIn short, SpecKeep aims to sit between OpenSpec and Spec Kit: stricter than OpenSpec, lighter than Spec Kit, and optimized for branch-based collaboration with minimal default context.\n\n## Where SpecKeep Stands Out\n\n- Narrow context by default. Each phase is designed to load the smallest useful scope.\n- Code reading should stay phase-local and targeted: enough to remove guesswork, not enough to recreate full-repository context.\n- Strict workflow chain. Constitution, spec, optional inspect, plan, tasks, and implementation stay aligned.\n- `inspect` is a real quality gate, not a loose suggestion before planning.\n- Lightweight traceability. Stable IDs and cheap readiness checks reduce prompt bloat.\n- Brownfield-friendly workflow. SpecKeep works well in existing repositories without forcing a heavyweight process layer.\n- Branch-first collaboration. Active feature state stays local to the feature instead of spreading through shared mutable memory.\n- `inspect` is optional before planning: run it when the spec is ambiguous, high-risk, or needs a formal quality gate. If an inspect report exists, it must be valid and non-blocking.\n- Optional workflow commands available at any phase: `/speckeep.challenge` (adversarial review — finds weak assumptions and untestable criteria), `/speckeep.handoff` (compact session handoff document so a new session can resume without re-reading all artifacts), `/speckeep.hotfix` (emergency fix outside the standard phase chain — for well-understood fixes touching ≤ 3 files), `/speckeep.scope` (quick scope boundary check, inline only, no file written).\n\nOpenSpec is more flexible by design and works well when teams want a looser artifact-guided workflow.\n\nSpec Kit provides a broader and more thorough workflow surface, but usually at the cost of more artifacts, more context, and more process overhead.\n\nSpecKeep is optimized for discipline per token: strong workflow boundaries, minimal default context, explicit quality gates, and enough structure to keep agents aligned without making the workflow heavy.\n\n## Documentation\n\nExtended documentation lives in [`docs/`](docs/README.md):\n\n- [English docs](docs/en/index.md)\n- [Русская документация](docs/ru/index.md)\n\n## Public CLI\n\n```text\nspeckeep init [path]\nspeckeep refresh [path]\nspeckeep add-agent [path]\nspeckeep list-agents [path]\nspeckeep remove-agent [path]\nspeckeep cleanup-agents [path]\nspeckeep add-skill [path]\nspeckeep list-skills [path]\nspeckeep remove-skill [path]\nspeckeep install-skills [path]\nspeckeep skills-restore [path]\nspeckeep sync-skills [path]\nspeckeep skills install [path]\nspeckeep skills restore [path]\nspeckeep skills sync [path]\nspeckeep doctor [path]\nspeckeep doctor [path] --json\nspeckeep dashboard [path]\nspeckeep feature \u003cslug\u003e [path]\nspeckeep feature repair \u003cslug\u003e [path]\nspeckeep features [path]\nspeckeep migrate [path]\nspeckeep list-specs [path]\nspeckeep show-spec \u003cname\u003e [path]\nspeckeep check \u003cslug\u003e [path]\nspeckeep check \u003cslug\u003e [path] --json\nspeckeep check [path] --all\nspeckeep check [path] --all --json\nspeckeep trace [slug] [path]\nspeckeep demo [path]\nspeckeep export \u003cslug\u003e [path]\nspeckeep export \u003cslug\u003e [path] --output \u003cfile\u003e\nspeckeep list-archive [path]\nspeckeep list-archive [path] --status \u003cstatus\u003e\nspeckeep list-archive [path] --since \u003cYYYY-MM-DD\u003e\nspeckeep list-archive [path] --json\n```\n\n## Workflow\n\n```text\nconstitution -\u003e spec -\u003e [inspect, optional] -\u003e plan -\u003e tasks -\u003e implement -\u003e verify -\u003e archive\n```\n\n## Key Points\n\n- The constitution is the highest-priority project document.\n- Feature artifacts keep `plan.md`, `tasks.md`, `data-model.md`, `verify.md`, `contracts/`, and optional `research.md` together under one slug directory.\n- Lean artifact mode is now the default for generated workspaces: canonical active artifacts are `spec.md`, optional `inspect.md`, `plan.md`, `tasks.md`, `data-model.md`, `contracts/`, and `verify.md`; older `summary.md`, `spec.digest.md`, and `plan.digest.md` are legacy optional artifacts.\n- `data-model.md` and `contracts/` are intentionally compact but structured: entities should capture fields, invariants, and lifecycle; contracts should capture boundary IO, failures, and delivery assumptions.\n- Specs use canonical `Given / When / Then` markers across documentation languages.\n- SpecKeep prefers stable IDs and explicit references over repeated narrative summaries: `RQ-*` for requirements, `AC-*` for acceptance criteria, `DEC-*` for plan decisions, and phase-scoped `T*` task IDs.\n- Agent workflows are designed to load only the minimum context required.\n- Strictness comes from phase entrypoints, templates, stable artifact structure, and readiness checks rather than large default prompts.\n- `inspect` now treats helper-script output as the primary structural evidence layer: readiness checks can emit categorized findings such as `structure`, `traceability`, `ambiguity`, `consistency`, and `readiness`, which the agent should preserve and only deepen when necessary.\n- Agent-facing `/speckeep.spec` is branch-first: it should work from `feature/\u003cslug\u003e`, support `--name` with optional `--slug` / `--branch`, and still prefer explicit `name:` / `slug:` metadata for prompt files.\n- `speckeep init` requires an explicit `--shell` and generates one script family: `sh` or `powershell`. Supported agent targets: `claude`, `codex`, `copilot`, `cursor`, `kilocode`, `opencode`, `trae`, `windsurf`, `roocode`, `aider`.\n- Generated workspaces include `.speckeep/scripts/run-speckeep.*` as the stable CLI launcher for agents; it resolves `DRAFTSPEC_BIN` first and falls back to `speckeep` from `PATH`.\n- Generated `.speckeep/scripts/*` wrappers compute the project root from the script location and pass it via `--root`, so they can be executed from any working directory.\n- `speckeep feature repair` and `speckeep migrate` provide safe canonicalization for legacy artifacts such as old inspect report paths.\n- Existing projects may keep legacy `summary.md`, `spec.digest.md`, and `plan.digest.md` during transition; `refresh` no longer expects them, and new generated guidance does not depend on them.\n- `speckeep check \u003cslug\u003e` shows artifact presence, inspect and verify verdict, task progress, the exact next slash command, and a compact readiness summary from structured checks; exits with code 1 when blocked; supports `--json` for CI use. `--all` shows a readiness table across all features.\n- `speckeep demo [path]` creates a demo workspace pre-populated with an example feature at the implement phase — spec, inspect report, plan, tasks, and data model are all populated.\n- `speckeep export \u003cslug\u003e` bundles all feature artifacts into one markdown document for sharing with a reviewer or new agent session; supports `--output` to write to a file.\n- `speckeep list-archive` lists archived features from `specs/archived/`; shows one entry per slug (most recent snapshot) with status, date, and reason; supports `--status` to filter by archive status, `--since \u003cYYYY-MM-DD\u003e` to filter by date, and `--json` for automation.\n- `/speckeep.plan` supports `--research`: enters research-first mode — agent identifies concrete unknowns, writes `research.md`, then asks \"Research complete — proceed to full plan?\" before producing `plan.md`.\n- `/speckeep.plan` includes `## Incremental Delivery`: guides agents to define MVP (smallest testable increment) and plan iterative expansion steps with AC traceability — avoids monolithic implementations and enables early validation.\n- `/speckeep.spec` supports `--amend`: targeted edit mode — update one section or add one criterion without rewriting the spec or invalidating an existing inspect report.\n- `/speckeep.handoff` without a slug generates handoff documents for all active features at once.\n- `/speckeep.hotfix`: emergency fix workflow — writes a minimal hotfix spec (fix, root cause, risk, verification, touches) before any code change, implements, verifies inline, then archives; skips inspect, plan, and tasks phases; use only when the root cause is known and the fix touches ≤ 3 files.\n- `doctor` warns when the same stable ID (`AC-*`, `RQ-*`) appears across multiple specs.\n- **Traceability by design**. Agents are instructed to annotate code with `// @sk-task \u003cID\u003e (\u003cAC_ID\u003e)` during implementation. Use `speckeep trace \u003cslug\u003e` to scan and verify these links between code and requirements.\n- Generated docs and prompts support English and Russian.\n\n- **Greenfield-friendly**. While SpecKeep is optimized for brownfield, it works great for from-scratch projects using a \"Foundation-first\" approach.\n\n## Quick Start (Greenfield)\n\nIf you are starting a project from scratch:\n\n1.  **Init**: `speckeep init . --lang en --shell sh`\n2.  **Establishment**: Define the tech stack, architecture, and rules via `/speckeep.constitution --foundation`. This creates a unified document for project rules and technical foundation.\n3.  **First Feature**: Once the baseline is established, move to the first functional specification via `/speckeep.spec`.\n\n## Skills Quickstart\n\n`--ref` is required for git sources to keep skill installs reproducible and avoid floating branch drift.\n\nFor git-backed skills, SpecKeep caches the source checkout under `.speckeep/skills/checkouts/\u003cid\u003e` and keeps that path ignored via a managed root `.gitignore` block.\n\n```bash\n# add a local skill\nspeckeep add-skill my-project --id architecture --from-local skills/architecture\n\n# add a git-backed skill (pin with --ref)\nspeckeep add-skill my-project --id openai-docs --from-git https://example.com/skills.git --ref v1.2.3 --path skills/openai-docs\n\n# list configured skills\nspeckeep list-skills my-project\n\n# install skills into agent folders\nspeckeep install-skills my-project\n\n# restore missing git-backed checkouts from manifest.yaml\nspeckeep skills-restore my-project\n\n# sync only skills-managed artifacts\nspeckeep sync-skills my-project\n```\n\n## Usage Example (Brownfield)\n\n```bash\n# try the demo instantly — no project setup required\nspeckeep demo ./my-demo\n\n# init a real project\nspeckeep init my-project --lang en --shell sh --agents claude --agents codex\nspeckeep refresh my-project --shell powershell --dry-run\nspeckeep doctor my-project\nspeckeep check export-report my-project\n```\n\n## Example Feature Cycle\n\nA full workflow for a real feature — \"Add CSV export to the reports page\".\n\n\u003cdetails\u003e\n\u003csummary\u003eSee the full cycle →\u003c/summary\u003e\n\n### 1. Init\n\n```bash\nspeckeep init . --lang en --shell sh --agents claude\n# → .speckeep/ scaffold, AGENTS.md, agent slash-command files written\n```\n\nOptional advanced flags:\n\n- `--specs-dir` overrides where specs are stored (default: `specs/active`)\n- `--archive-dir` overrides where archived artifacts are stored (default: `specs/archived`)\n- `--constitution-file` overrides where the project constitution is stored (default: `CONSTITUTION.md`)\n\n### 2. Write the spec\n\nCall `/speckeep.spec --name \"CSV export for reports\"` in your agent.\n\n`specs/active/csv-export-for-reports/spec.md`:\n\n```markdown\n## Goal\n\nAllow users to download the reports table as a CSV file.\n\n## Acceptance Criteria\n\n**AC-001** Export produces a file\nGiven the Reports page has at least one row\nWhen the user clicks \"Export CSV\"\nThen a .csv file downloads with column headers and all visible rows\n\n**AC-002** Empty state is handled\nGiven the reports table is empty\nWhen the user clicks \"Export CSV\"\nThen a .csv with headers only downloads — no error shown\n```\n\n### 3. Inspect\n\nCall `/speckeep.inspect csv-export-for-reports`.\n\n- `specs/active/csv-export-for-reports/inspect.md` — verdict `pass`, all AC have G/W/T\n- no extra recap file is required; implement and verify will rely on `tasks.md` as the main operational entrypoint\n\n### 4. Plan\n\nCall `/speckeep.plan csv-export-for-reports`.\n\n`specs/active/csv-export-for-reports/plan.md` names the implementation surfaces: `ReportsPage.tsx` (add button), `useReportExport.ts` (new hook, CSV logic), `reports.test.ts` (new tests).\n\n### 5. Tasks\n\nCall `/speckeep.tasks csv-export-for-reports`.\n\n`specs/active/csv-export-for-reports/tasks.md`:\n\n```markdown\n## Surface Map\n\n| Surface                    | Tasks |\n| -------------------------- | ----- |\n| hooks/useReportExport.ts   | T1.1  |\n| components/ReportsPage.tsx | T1.2  |\n| tests/reports.test.ts      | T2.1  |\n\n## Implementation Context\n\n- MVP Goal: export the current visible reports table as CSV\n- Acceptance Boundaries: AC-001, AC-002\n- Key Rules: keep behavior in-browser; no extra export formats; preserve empty-state UX\n- Data/Domain Invariants: exported columns match the visible table; header row is always present\n- Contracts/Protocols: browser download only; no background job or email delivery\n- Proof Signals: CSV file downloads; empty table exports headers only\n- Out of Scope: batch export, scheduled export, XLSX support\n\n## Phase 1: Hook and button\n\n- [ ] T1.1 add `useReportExport` hook — converts `rows[]` to CSV blob and triggers browser download — AC-001 `Touches: hooks/useReportExport.ts`\n- [ ] T1.2 add Export CSV button to ReportsPage — calls hook on click, disabled when rows empty — AC-001, AC-002 `Touches: components/ReportsPage.tsx`\n\n## Phase 2: Tests\n\n- [ ] T2.1 add tests for useReportExport — covers non-empty rows, empty rows, header-only output — AC-001, AC-002 `Touches: tests/reports.test.ts`\n\n## Acceptance Coverage\n\nAC-001 → T1.1, T1.2, T2.1\nAC-002 → T1.2, T2.1\n```\n\n### 6. Implement, verify, archive\n\n```\n/speckeep.implement csv-export-for-reports   # Phase 1 done, stops\n/speckeep.implement csv-export-for-reports   # Phase 2 done, stops\n/speckeep.verify    csv-export-for-reports   # verdict: pass\nspeckeep archive    csv-export-for-reports .\n```\n\n### Check readiness at any point\n\n```bash\nspeckeep check csv-export-for-reports\n# Phase:  tasks → implement\n# Tasks:  0 / 3 done\n# Next:   /speckeep.implement csv-export-for-reports\n```\n\n\u003c/details\u003e\n\n## Demo\n\nA reproducible terminal demo kit lives under [`demo/`](demo/README.md).\n\nBuild the local binary and render the quick terminal demo:\n\n```bash\ngo build -o bin/speckeep ./src/cmd/speckeep\nvhs demo/quick.tape\n```\n\nDemo assets:\n\n- [Quick terminal demo](demo/README.md)\n- [Brownfield walkthrough](demo/brownfield.md)\n- [Self-hosting walkthrough](demo/self-hosting.md)\n\nThe quick tape produces `demo/speckeep-demo.gif` and demonstrates `init`, generated agent files, `AGENTS.md`, and launcher-based `doctor` / `refresh --dry-run`.\n\n## Install\n\nSpecKeep is distributed as a single binary via GitHub Releases.\n\nLinux / macOS:\n\n```bash\nVERSION=v0.3.1\ncurl -fsSL \"https://raw.githubusercontent.com/bzdvdn/speckeep/${VERSION}/scripts/install.sh\" | bash -s -- --version \"${VERSION}\"\n```\n\nWindows (PowerShell):\n\n```powershell\n$version=\"v0.3.1\"\n$env:SPECKEEP_VERSION=$version\npowershell -ExecutionPolicy Bypass -c \"iwr -useb https://raw.githubusercontent.com/bzdvdn/speckeep/$version/scripts/install.ps1 | iex\"\n```\n\nTo also add the install directory to `PATH`:\n\n- Linux: add `--add-to-path` or set `SPECKEEP_ADD_TO_PATH=1`\n- Windows: set `$env:SPECKEEP_ADD_TO_PATH=1` or run the script with `-AddToPath`\n\nFor deeper guidance, use:\n\n- [Overview](docs/en/overview.md)\n- [CLI Reference](docs/en/cli.md)\n- [Workflow Model](docs/en/workflow.md)\n- [Examples](docs/en/examples.md)\n- [Roadmap](docs/en/roadmap.md)\n\nProject contribution and trust docs:\n\n- [Contributing](CONTRIBUTING.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Security Policy](SECURITY.md)\n\n## Development\n\n```bash\ngo test ./...\ngo build -o bin/speckeep ./src/cmd/speckeep\n\n# with version stamp\ngo build -ldflags \"-X speckeep/src/internal/cli.Version=v0.3.1\" -o bin/speckeep ./src/cmd/speckeep\n```\n\nThe repository includes unit tests for config, project lifecycle, doctor checks, specs, templates, agents, and CLI-level behavior.\n\n## License\n\nReleased under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbzdvdn%2Fspeckeep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbzdvdn%2Fspeckeep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbzdvdn%2Fspeckeep/lists"}