Spec-Driven Development with GitHub Spec Kit: A Practical Workflow

Spec-driven development is a way of building software where a written specification, not a chat prompt, is the source of truth that a coding agent implements against. Instead of describing a feature in a throwaway message and hoping the agent guesses the rest, you write down what to build and why, refine it through structured phases, and hand the agent a document it can execute. The specification stays in version control, evolves with the feature, and gives everyone on the team a single artifact to review.

GitHub Spec Kit is the open-source toolkit that puts this method into practice. It has grown past 120,000 stars on GitHub and works with more than 30 coding agents, including Claude Code, GitHub Copilot, Cursor, Gemini CLI, and Codex CLI. Spec Kit does not replace your agent. It gives the agent a repeatable pipeline of commands that turn a one-line idea into a spec, a technical plan, an ordered task list, and finally working code.

This guide walks the workflow one command at a time: install, constitution, specify, plan, tasks, and implement. Each phase produces a markdown artifact that feeds the next, so the agent always has structured context. At the end we cover the one step Spec Kit deliberately leaves to you: proving that the code the agent wrote actually satisfies the spec.

What GitHub Spec Kit is

Spec Kit is a command-line tool plus a set of agent prompts and templates. The CLI, called specify, bootstraps a project with the folders and templates the workflow needs, and the prompts install as slash commands in your coding agent, so the whole loop runs from inside the editor or terminal you already use.

The design idea is simple. Large language models are good at writing code but bad at holding a large, fuzzy intent across many steps. Spec Kit breaks the intent into explicit documents, each reviewed before the next begins, so the agent works from a stable contract rather than a growing pile of chat history. This is the same shift we describe in turning tribal knowledge into executable specs: move the knowledge out of people's heads and into artifacts a machine can act on.

The Spec Kit workflow, step by step

Step 1: Install the specify CLI

Spec Kit installs through uv, the Python package runner. The fastest path is a single command that fetches the tool from the repository and initializes a project:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

During init you choose your coding agent, and Spec Kit writes the matching prompt files into the project (a .specify/ directory of templates plus agent-specific command files). Open the project in Claude Code, Copilot, Cursor, or any supported agent, and the slash commands are ready. To scaffold several projects, install the CLI persistently with uv tool install specify-cli.

Step 2: Set the constitution

The workflow opens with /speckit.constitution, which writes a constitution.md capturing the non-negotiable principles for the project: coding standards, architectural constraints, testing expectations, and any rule the agent must never break. Every later phase reads the constitution, so a plan that violates a stated principle gets caught early. These are the guardrails the agent carries through the rest of the loop.

Step 3: Specify what to build

Next comes /speckit.specify, the heart of the method. You give it a plain-language description of the feature, and it produces a spec.md focused on the "what" and the "why": user stories, functional requirements, and acceptance criteria. The spec deliberately excludes technical choices like frameworks or database engines, describing behavior the way a product owner would, so it stays readable across engineering, product, and QA. If parts of the request are ambiguous, /speckit.clarify asks targeted questions and folds the answers back in before you commit to a plan, which is far cheaper than discovering unknowns halfway through implementation.

Step 4: Plan the technical approach

With an approved spec, /speckit.plan generates plan.md, the "how." This is where technology decisions live: the language and framework, data model, external services, and the architecture that will satisfy the requirements. Because the plan is grounded in both the spec and the constitution, it stays consistent with your principles rather than drifting toward whatever the model would pick by default. This mirrors the discipline of moving from product requirements to living end-to-end coverage: the requirement and the proof of it should trace to the same source.

Step 5: Break the plan into tasks

/speckit.tasks turns the plan into tasks.md, an ordered, dependency-aware checklist. Tasks are grouped by user story and sequenced so foundations come before the things that depend on them: models before services, services before endpoints. Independent tasks are marked so the agent can parallelize them. The result is a work breakdown the agent executes in small, verifiable increments instead of one large, opaque generation. Optional commands add rigor here: /speckit.analyze checks the spec, plan, and tasks for cross-artifact consistency, /speckit.checklist generates custom quality gates, and /speckit.taskstoissues converts tasks into GitHub issues.

Step 6: Implement

Finally, /speckit.implement executes the task list. The agent works through tasks.md in order, writing code, wiring components, and checking off items as it goes. Because every decision traces back to a reviewed spec and plan, the output is far more predictable than an open-ended "build me this" prompt. The agent builds from a contract, not a guess.

Step 7: Verify against the spec

Here is where the Spec Kit loop stops. The toolkit takes you from idea to running code, but it does not confirm the running code does what spec.md promised. As Microsoft's own walkthrough of Spec Kit notes, the method is silent on validation once implementation finishes. You are left to check the acceptance criteria by hand, or to trust that green unit tests mean the feature works in a browser. For anything with a user interface, they do not: a passing test suite and a broken signup form coexist all the time.

Closing the verification gap

The spec already contains the answer to "is this done." Every user story and acceptance criterion in spec.md is a statement about observable behavior, which is exactly what an end-to-end test proves. The missing piece is a step that reads those criteria and checks them against the rendered application.

That is the step Shiplight adds. Shiplight installs into the same coding agent you drive Spec Kit with, as a Model Context Protocol server plus a set of skills, with a one-line install for Claude Code, Cursor, Codex, VS Code, and 40 or more agents. Once connected, the agent gains eyes and hands in a real browser. After /speckit.implement finishes, you run /shiplight verify, and the agent opens the app, walks the flows the spec describes, and confirms the acceptance criteria hold against the actual UI, not a mock.

The second move is durability. Running /shiplight create-yaml-tests has the agent turn those same acceptance criteria into end-to-end tests, authored from intent rather than brittle selectors. The tests are readable YAML that lives in your git repository, next to the specs that produced them, so the spec and its proof travel together. They run locally with npx shiplight test, stay Playwright-compatible, and self-heal in a real browser when the UI shifts, with any healed step surfacing as a reviewable pull request diff instead of a silent rewrite. This is the executable-intent approach applied to the artifacts Spec Kit generates.

The effect is concrete. The constitution sets the rules, spec.md states the intent, the agent implements it, and a maintained test suite keeps proving that intent holds on every future change. Teams reach reliable coverage far faster than hand-writing scripts: one Head of QA moved from spending most of their time maintaining Playwright tests to near zero within a month, because the tests are authored from intent and heal themselves. The specification stops being a document you wrote once and becomes a contract that stays enforced.

For the format those tests use, see YAML-based testing. For the broader method, see what spec-driven development is and how it pairs with AI coding agents.

Key Takeaways

• Spec Kit is a command pipeline, not an agent. It scaffolds a project with the specify CLI, then runs inside Claude Code, Copilot, Cursor, and 30 or more other agents.
• Each phase produces a reviewed artifact. /speckit.constitution, /speckit.specify, /speckit.plan, and /speckit.tasks create constitution.md, spec.md, plan.md, and tasks.md, and /speckit.implement builds from them.
• The spec is written as behavior, so it stays readable across product, engineering, and QA.
• Spec Kit stops at implementation. It does not verify that the built software satisfies the spec, especially in the UI.
• Verification closes the loop. Shiplight plugs into the same agent to check the running app against the acceptance criteria and turn them into maintained YAML tests that live next to the specs.

Frequently Asked Questions

How do I use GitHub Spec Kit?

Install the specify CLI with uvx --from git+https://github.com/github/spec-kit.git specify init my-project, choose your coding agent during init, then run the slash commands in order: /speckit.constitution to set project rules, /speckit.specify to write the spec, /speckit.plan for the technical approach, /speckit.tasks to break it into work, and /speckit.implement to build. Each command produces a markdown file the next one reads.

What is the GitHub Spec Kit workflow?

It is a five-stage pipeline: constitution, specify, plan, tasks, and implement. Constitution sets non-negotiable principles, specify captures requirements as spec.md, plan turns them into a technical plan.md, tasks generates an ordered tasks.md, and implement has the agent write the code. Optional commands like /speckit.clarify and /speckit.analyze add checks between stages.

What artifacts does Spec Kit produce?

Spec Kit generates four markdown documents: constitution.md (project principles), spec.md (requirements and user stories), plan.md (technical design), and tasks.md (an ordered, dependency-aware task list). These live in the repository so the whole team can review them and the agent can reload them as context.

Does Spec Kit verify that the code matches the spec?

No. Spec Kit takes you from idea to working code but does not confirm the implementation satisfies the specification, and it says nothing about testing the user interface. Shiplight fills this gap by having your agent check the running app against the spec's acceptance criteria in a real browser, then author maintained end-to-end tests from those same criteria.

Which coding agents work with Spec Kit?

Spec Kit supports more than 30 agents, including Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, and Windsurf. You pick one during specify init and can switch later without rewriting your specs, since the artifacts are plain markdown.

Related Reading

• What is spec-driven development
• Spec-driven development with AI coding agents
• From tribal knowledge to executable specs
• From requirements to living E2E coverage
• The executable intent playbook
• YAML-based testing

References: GitHub Spec Kit repository, Spec Kit documentation, Diving into Spec-Driven Development with Spec Kit (Microsoft for Developers), spec-driven.md (github/spec-kit), Model Context Protocol