GitHub Spec Kit Guide: The Standard Workflow for Spec-Driven Coding

If the spec-driven coding movement has a standard, it's GitHub Spec Kit — the open-source toolkit developed by GitHub engineers together with contributors from Microsoft and Anthropic. With over 100k GitHub stars by mid-2026, it's the largest pure spec-driven development project, and its workflow of constitution → specify → plan → tasks → implement has become the model that most other tools measure themselves against.

The core idea is a power reversal: code doesn't define the project, the spec does. "Specifications don't serve code — code serves specifications." Instead of telling an agent what to do in a prompt, you build a chain of versioned artifacts — constitution, spec, plan, tasks — and the agent's job is to make the code conform to them.

This guide covers the full workflow, command by command, and where to go next in our spec-driven coding cluster.

What Spec Kit actually is

Spec Kit is a CLI (specify-cli) plus a set of slash commands. You install it, run specify init, and the tool scaffolds a repository structure with a .specify/ directory, templates, and agent hooks. Then, inside your coding agent — Claude Code, GitHub Copilot, Cursor, Gemini CLI, or any of 25+ supported tools — you drive the workflow with /speckit.* commands.

Installation:

uvx --from git+https://github.com/github/spec-kit.git specify init myproject
# or: pipx install git+https://github.com/github/spec-kit.git

Requirements: Python 3.11+, Git, and a supported AI agent. The CLI is offline-first — bundled assets, lazy network use, hash-tracked file operations — so it works in air-gapped enterprise environments.

The workflow, command by command

The full sequence:

/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan
→ /speckit.checklist → /speckit.tasks → /speckit.analyze → /speckit.implement
→ /speckit.converge

If that looks heavy, there's a lean path for quick experiments: /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement. The optional commands exist to catch problems at the cheapest point in the pipeline.

/speckit.constitution — the project's rulebook

The constitution is constitution.md, stored in .specify/memory/. It sets governing principles: engineering standards, guardrails, required and discouraged patterns, testing expectations, naming conventions, compliance requirements. It's the "north star" every later artifact is checked against.

The constitution is semantically versioned — PATCH for wording changes, MINOR for new principles, MAJOR for removals. When the constitution changes, Spec Kit validates that existing plans, specs, and task templates stay in sync and produces a Sync Impact Report. During planning, compliance gates (simplicity gate, test-first gate) enforce it; a plan that violates the constitution must be revised or carry a documented justification.

/speckit.specify — the what and the why

This generates spec.md — the heart of the method. The spec deliberately stays technology-agnostic: no frameworks, no databases, no API structure. It describes the feature, user problem, functional requirements (numbered, like FR-001), non-functional requirements, scenarios, and success criteria.

Two behaviors are worth knowing:

1. Specify creates a Git feature branch (001-feature-name) and writes the spec to specs/<branch-name>/. The spec is a PR unit: when the branch merges, the spec comes with it. Switching features means switching branches, and commands auto-detect the active feature from the branch.
2. Ambiguity is flagged, not guessed. Where the spec is unclear, the agent inserts [NEEDS CLARIFICATION] markers with up to three structured questions instead of inventing answers.

/speckit.clarify — resolving ambiguity on purpose

An optional structured Q&A loop that resolves the [NEEDS CLARIFICATION] markers before planning starts. Your answers update spec.md in place: markers replaced, assumptions appended, version incremented. This is the stage where "the more specific you are, the better the agent performs" gets its payoff.

/speckit.plan — the how

plan.md is the technical architecture: tech stack, components, data model, API contracts, deployment structure, dependencies. It's checked against the constitution (compliance gates) and the spec (requirement coverage). Depending on scope, the plan can also produce research.md (technology trade-off analysis), data-model.md (entity schemas), and a contracts/ directory (API specifications).

/speckit.checklist — optional validation

Generates quality checklists that validate the spec (before planning) or the plan (before tasks): complete, clear, consistent, requirements covered. Cheap insurance at the cheapest point.

/speckit.tasks — the executable breakdown

tasks.md breaks the plan into ordered, granular, developer-ready tasks. Each task maps to a single logical unit and carries its own acceptance criteria and dependency notes. [P] marks tasks that can run in parallel — the cue for multi-agent execution. A typical order: setup → tests-first (TDD before core implementation) → core implementation → integration → polish.

/speckit.analyze — optional cross-check

A read-only consistency check across spec, plan, and tasks: requirement coverage, constitution alignment, conflicts, missing dependencies. Run before implementation; repeat after.

/speckit.implement — code serves the spec

The agent executes the defined tasks, producing code, tests, and documentation strictly against the earlier artifacts. This is the stage the whole chain exists to make deterministic.

/speckit.converge — close the loop

After implementation, converge verifies the codebase against the plan and appends anything unbuilt as new tasks in tasks.md. Repeat implement/converge until the feature converges — then the PR (with its spec) is ready for human review.

Why teams adopt Spec Kit

• Agent-agnostic: one workflow across Claude Code, Copilot, Cursor, Gemini CLI, and 25+ other agents — the same /speckit.* commands everywhere.
• The spec is the PR unit: reviewable, versioned, and merged with the code it describes. No more PRs that "did something" with no baseline to check against.
• Context-aware: commands read the current branch to know which feature you're working on.
• Constitution enforcement: rules are checked mechanically at plan time, not relied on as vibes.

Known trade-offs

The May 2026 hands-on reviews are honest about friction: Spec Kit generates a lot of artifacts (spec, plan, tasks, research, contracts), and for small changes that's ceremony. Reviewers noted the tool writes tests but doesn't automatically run them, and it produces more files than code in early sessions. It's built for iterative enhancement of a real project — the lean path exists for a reason. Use the lean path for experiments, the full path for features that matter.

Spec Kit vs. the alternatives

If Spec Kit is the "strong spec" school — the spec is the single source of truth — the ecosystem has other philosophies worth knowing:

• OpenSpec is deliberately lighter: no constitution, no clarify phase, four commands, delta specs. Better for quick iteration on existing codebases.
• BMad Method replaces the artifact chain with a virtual agile team of specialist agents, from analyst to QA.
• Superpowers skips formal specs and concentrates on execution discipline: TDD, review gates, subagents.
• Task Master focuses on one stage — turning a PRD into structured tasks.

The full decision matrix is in our Spec Kit vs OpenSpec vs BMad comparison.

Getting started in five minutes

1. Install via uvx --from git+https://github.com/github/spec-kit.git specify init (or pipx) in your project.
2. Run /speckit.constitution and accept the generated rulebook (or argue with it — that's the point).
3. Run /speckit.specify for a small, real feature. Watch for [NEEDS CLARIFICATION] markers — answer them.
4. Run /speckit.plan, /speckit.tasks, then /speckit.implement and see the difference between prompted code and spec-driven code.

Then branch out: the complete spec-driven coding guide explains where Spec Kit fits in the wider ecosystem, and the spec-driven vs vibe coding comparison makes the case for why the ceremony pays off.