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.
Core SDD phases (short path)
The minimal, “core” Spec Kit flow (good for small features and quick iterations) includes five phases:
- Specify
- Goal: Write the spec—a concise, evidence‑backed description of intent, user impact, acceptance criteria, risks, and open questions.
- Artifact: spec.md (Markdown).
- Who: feature owner, product manager, and any SMEs who clarify requirements.
- Outcome: A single source of truth describing what success looks like and how to validate it.
- Plan
- Goal: Define a high‑level approach and milestones for delivering the spec.
- Artifact: plan.md.
- Who: engineering leads, tech PM, or the feature owner collaborating with implementers.
- Outcome: A roadmap and sequencing that make the work estimable and schedulable.
- Tasks
- Goal: Break the plan into actionable work items, ideally small and testable.
- Artifact: tasks.md (task list, tickets, or issues).
- Who: engineers and project managers.
- Outcome: A set of concrete tasks ready to be picked up, with owners and rough estimates.
- Implement
- Goal: Write the code, tests, and necessary infra changes that fulfill the spec and tasks.
- Artifact: code, PRs, feature branches; the spec + tasks continue to serve as the reference.
- Who: engineers, reviewers, and CI.
- Outcome: Working changes submitted as pull requests.
- Converge
- Goal: Verify the work against the spec, iterate as needed, and finalize the implementation (merge, deploy, and close feedback loops).
- Artifact: verification notes, post‑merge checklist, release notes.
- Who: reviewers, QA, product, and observability owners.
- Outcome: Feature is released (or scheduled) and the spec reflects any final decisions or learnings.
Full (recommended) flow for production‑grade work
For larger efforts or production features, the Spec Kit recommends a fuller, gated flow that adds project setup, clarification, and quality checks. The typical “full” path is:
- 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.
