I’ve been writing quite a bit about Spec Kit. Mostly because I can’t get over how effective it is when combined with Copilot. Spec Kit essentially “forces” you into Spec Driven Development best practices.
Spec‑Driven Development (SDD) flips the usual order of product work: start with a clear, testable spec that captures intent, evidence, and acceptance criteria, then drive planning and implementation from that spec. GitHub’s open-source Spec Kit is a practical toolkit for doing SDD consistently. It defines a small set of core phases you’ll use for most features and a fuller, production‑ready flow that adds project‑level setup and quality‑gate steps.
- Constitution (project‑level, once)
- Purpose: Establish project norms, success metrics, maintainers, review cadence, and cross‑team responsibilities. This is a lightweight project manifesto: who’s accountable and how decisions get made.
- Artifact: constitution.md.
- Specify (write the spec)
- As above, but now aligned to the constitution and any project constraints.
- Clarify
- Purpose: Surface and resolve open questions, corner cases, or dependency uncertainties before work begins.
- Artifact: clarify.md or a section in spec.md that records Q&A and owner decisions.
- Outcome: Reduce surprises during implementation; document remaining risks.
- Plan
- As above, but informed by clarified decisions and project constraints.
- Checklist (quality & acceptance gate)
- Purpose: Create explicit acceptance criteria and a quality gate that must be satisfied before merging or releasing.
- Artifact: checklist.md (test cases, performance targets, security/privacy checks).
- Outcome: A clear pass/fail list for reviewers and automated checks.
- Tasks
- As above, often with task owners tied to checklist items and test expectations.
- Analyze
- Purpose: Cross‑artifact checks and risk analysis: are specs, plan, tasks, and checklist consistent? Run dependency analysis, design/architecture review, or automated linting of the spec/artifacts.
- Artifact: analyze.md or automated reports that can be attached to the feature.
- Outcome: Identify gaps, mitigate risks, and confirm readiness to implement.
- Implement
- As above, often with stricter review rules and CI that enforces checklist items.
- Converge
- As above, including a final retrospective to update the spec and constitution where necessary.
How the Spec Kit maps phases to artifacts and tooling
- Each phase produces a Markdown artifact that becomes the input to the next phase (examples: constitution.md, spec.md, plan.md, tasks.md, checklist.md, analyze.md). These artifacts live in the feature directory or repo and become part of the project history and evidence.
- Spec Kit exposes each phase as first‑class commands/agent skills. Common command/agent names include
- /speckit-specify
- /speckit-clarify
- /speckit-plan
- /speckit-tasks
- /speckit-implement
- /speckit-converge
- The short path skips clarify/checklist/analyze for fast progress; the full path uses them as gates and quality controls.
- Spec Kit also provides opt‑in flows for bug‑fixes and idea‑assessment. These are separate entry points that adapt the core SDD workflow to those contexts without forcing the full SDD path.
Why start with a spec?
- Keeps intent explicit: A spec captures the “why” before the “how,” reducing rework and misalignment.
- Enables evidence‑driven decisions: Specs can include data, user research, and acceptance criteria that make tradeoffs explicit.
- Supports better reviews: PRs and code are judged against a known spec, so reviewers focus on deviations and implementation quality.
- Improves knowledge transfer: Markdown artifacts are searchable and persist beyond PRs and tickets.
Tips for integrating Spec Kit into your workflow
- Keep specs concise and testable. Prefer explicit acceptance criteria over vague goals.
- Automate cross‑artifact checks. Use CI jobs to ensure spec.md exists, checklist items map to tests, or tasks correspond to ticketing IDs.
- Use the Clarify phase to resolve dependencies; unresolved questions should block implementation if they affect correctness.
- Treat the spec as living documentation: update it in Converge to reflect decisions made during implementation.
- Embed links between artifacts and PRs so reviewers can quickly find the spec, plan, and checklist from a pull request.
Note: The initial draft of this post was written by BlogWriter and then edited by Jesse Liberty
Illustrations by Copilot. Caution: LLMs make mistakes; this post is offered as is.
