Meet GitHub Spec-Kit: An Open Source Toolkit for Spec-Driven Development with AI Coding Agents
If you’ve got frolicked utilizing AI coding brokers — GitHub Copilot, Claude Code, Gemini CLI — you’ve got most likely run into this example: you describe what you need, the agent generates a block of code that appears right, compiles, after which subtly misses the precise intent. This “vibe-coding” method can work for fast prototypes however turns into much less dependable when constructing mission-critical purposes or working with present codebases. The concern, as GitHub frames it, just isn’t the coding agent’s potential — it’s the method. Developers have been treating coding brokers like search engines like google, when they need to be handled extra like literal-minded pair programmers who excel at sample recognition however nonetheless want unambiguous directions.
To deal with this, GitHub has open sourced Spec-Kit — a toolkit designed to deliver Spec-Driven Development (SDD) to AI coding workflows. The venture presently has 90k+ stars and 8k+ forks on GitHub, and has grow to be one of many faster-growing developer tooling repositories in latest reminiscence.
What is Spec-Driven Development?
Spec-Driven Development inverts the standard energy construction of software program improvement. Specifications don’t serve code — code serves specs. The Product Requirements Document (PRD) just isn’t a information for implementation; it’s the supply that generates implementation.
In follow, this implies you write a structured specification first — describing what you wish to construct and why, with out specifying the tech stack — after which feed that into an AI coding agent as a grounding doc. The spec turns into the supply of reality that instruments and AI brokers use to generate, take a look at, and validate code. The result’s much less guesswork, fewer surprises, and higher-quality code.
This is distinct from “documentation-first” as historically practiced. SDD just isn’t about writing exhaustive, dry necessities paperwork that no person reads. It just isn’t about waterfall planning or making an attempt to foretell the longer term via intensive planning workout routines. And it’s not about creating extra paperwork that slows engineering groups down. The spec stays a dwelling artifact — up to date as necessities evolve, slightly than filed away after venture kickoff.
What Spec-Kit Actually Includes
Spec-Kithas two key elements: the Specify CLI, a helper command-line device that bootstraps initiatives for SDD by downloading official templates for the coding agent and platform of your alternative; and a set of templates and helper scripts that set up the muse for the SDD expertise — defining what a spec seems like, what a technical plan encompasses, and the way it all breaks down into particular person duties that an AI agent can execute.
The CLI is written in Python and requires Python 3.11+. Installation through uv is the really useful technique:
uv device set up specify-cli --from git+https://github.com/github/[email protected]
specify init <PROJECT_NAME>Once initialized, the agent has entry to a set of slash instructions that map on to the SDD workflow. The core instructions are:
/speckit.structure— establishes the venture’s non-negotiable governing ideas/speckit.specify— captures what you wish to construct, centered on the “what” and “why” with out tech stack particulars/speckit.plan— generates the technical implementation plan given your chosen stack/speckit.duties— breaks the plan into an actionable, dependency-ordered process listing/speckit.taskstoissues— converts the generated process listing into GitHub points for monitoring and execution/speckit.implement— executes these duties utilizing the AI coding agent
There are additionally three non-obligatory instructions for enhanced high quality and validation:
/speckit.make clear— surfaces underspecified areas via structured, sequential questioning earlier than a technical plan is created (really useful earlier than/speckit.planto scale back rework downstream)/speckit.analyze— runs cross-artifact consistency and protection evaluation after/speckit.dutiesand earlier than/speckit.implement/speckit.guidelines— generates customized high quality checklists that validate necessities completeness, readability, and consistency
An essential addition is structure.md. In the SDD context, a structure doc establishes a set of non-negotiable ideas for a venture — testing conventions, CLI-first necessities, organizational design system requirements. These are captured as soon as and referenced all through each subsequent improvement section.
GitHub Spec Kit
How to Use GitHub Spec Kit: A Step-by-Step Guide
Spec-Driven Development (SDD) with AI coding brokers — from putting in the CLI to working your first implementation. Follows the official workflow from the github/spec-kit repository.
Step 1 of 10
Make positive you’ve got the best instruments put in
Before putting in the Specify CLI, you want 4 issues in your machine. Spec Kit is cross-platform and works on Linux, macOS, and Windows.
- Python 3.11+ — obtain from python.org
- uv (really useful) or pipx for package deal administration — set up uv from docs.astral.sh/uv
- Git — obtain from git-scm.com
- A supported AI coding agent — Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI, or any of the 29 supported integrations
Why uv? It manages device installations globally, retains them in your PATH, and makes upgrading simple with
uv device listing, uv device improve, and uv device uninstall. It’s the formally really useful technique.
Install the Specify CLI from GitHub
The solely official Spec Kit package deal is revealed straight from the GitHub repository. Do not set up from PyPI — any package deal there with the identical identify just isn’t maintained by the Spec Kit staff.
uv device set up specify-cli –from git+https://github.com/github/spec-kit.git@vX.Y.Z
# Or utilizing pipx
pipx set up git+https://github.com/github/spec-kit.git@vX.Y.Z
# Verify set up
specify model
Check the Releases page for the most recent tag (e.g.
v0.8.4). Installing from essential could embody unreleased adjustments.
One-time utilization (no set up): Run
uvx --from git+https://github.com/github/[email protected] specify init <PROJECT> to attempt and not using a persistent set up.
Bootstrap your venture with specify init
Navigate to your venture folder and run specify init. The CLI detects which AI coding agent you’ve got put in and units up the best listing construction, templates, and instructions routinely.
specify init my-photo-app
# Initialize inside an present listing
specify init . –integration claude
# Skills mode for Claude Code and Codex CLI
specify init . –integration codex –integration-options=”–expertise”
# Check all required instruments are current
specify examine
After this, your venture will include a .specify/ listing with reminiscence/, scripts/, specs/, and templates/ subdirectories.
Skills mode: Claude Code, Codex CLI, Kimi Code, Devin, and a number of other different brokers use a skills-based set up — information go into agent-specific directories (e.g.
.claude/expertise/) as a substitute of slash-command immediate information. Run specify integration listing to see which mode every agent makes use of.
Set venture ideas with /speckit.structure
The first command you run inside your agent is /speckit.structure. This creates a structure.md file containing non-negotiable governing ideas the agent follows all through each subsequent section. Run this as soon as per venture.
/speckit.structure Create ideas centered on:
– Code high quality and take a look at protection requirements
– User expertise consistency throughout all screens
– Performance necessities for image-heavy interfaces
– No third-party picture add providers — native storage solely
This writes to .specify/reminiscence/structure.md. Think of it as standing directions — issues like “all the time use TypeScript,” “by no means introduce breaking API adjustments,” or “observe our inside design system.”
Describe what to construct with /speckit.specify
Now describe what you wish to construct — focus fully on the “what” and “why.” Do not point out the tech stack at this stage. The agent produces a spec.md with person tales and useful necessities.
/speckit.specify Build an utility that organizes images into albums.
Albums are grouped by date and might be re-organized by dragging
and dropping on the primary web page. Albums are by no means nested inside
different albums. Within every album, images are previewed in a
tile-like interface. Users can rename and delete albums however
can’t delete particular person images from inside an album view.
Do not point out tech stack right here. Mixing “what to construct” with “the best way to construct it” at this stage results in over-constrained specs. The tech stack is available in Step 7.
The output goes into .specify/specs/001-photo-app/spec.md and a brand new Git department is created routinely.
Clarify and validate your spec earlier than planning
Before producing the technical plan, two non-obligatory instructions assist floor gaps and validate your specification. Both are really useful, and might be skipped for fast spikes or exploratory prototypes.
/speckit.plan./speckit.make clear
# Then validate spec completeness and readability
/speckit.guidelines
During clarification, the agent would possibly ask issues like:
- Should albums help a number of choice for batch operations?
- Is there a most variety of images per album?
- Should drag-and-drop work on cell, or desktop solely?
If deliberately skipping clarification, explicitly inform the agent — in any other case it could block ready on lacking clarifications earlier than permitting you to proceed to planning.
Define the stack with /speckit.plan
Now specify the tech stack and structure. The agent generates a plan.md, a data-model.md, a analysis.md, and a quickstart.md.
/speckit.plan Use Vite with vanilla HTML, CSS, and JavaScript.
Keep third-party libraries to a minimal. Images usually are not uploaded
anyplace — metadata is saved in an area SQLite database through
a light-weight Express backend. Drag-and-drop makes use of the native
HTML5 Drag and Drop API.
Your listing after this step:
├── spec.md
├── plan.md
├── data-model.md
├── analysis.md
└── quickstart.md
Check
analysis.md to confirm the proper tech stack was chosen. If a rapidly-changing framework is concerned, ask the agent to analysis the precise put in model earlier than shifting ahead.
Generate duties with /speckit.duties and /speckit.taskstoissues
Run /speckit.duties to supply a duties.md with the complete implementation roadmap. Tasks are organized by person story, dependency-ordered, and annotated with parallel execution markers.
# duties.md output construction (instance excerpt):
## User Story: Album Management
– [ ] Create SQLite schema: albums, images tables
– [ ] [P] Build Express GET /albums endpoint
– [ ] [P] Build Express POST /albums endpoint
– [ ] [P] Implement album rename PUT /albums/:id
## Checkpoint: Validate album CRUD independently
The [P] marker signifies duties that may run in parallel. Each person story part ends with a Checkpoint to validate that section’s performance works independently earlier than the subsequent begins. Optionally, convert duties to GitHub Issues:
Validate consistency with /speckit.analyze
After producing duties and earlier than working implementation, run the non-obligatory /speckit.analyze command. It performs a cross-artifact consistency and protection examine throughout the spec, plan, information mannequin, and duties to make sure every little thing is aligned.
The agent will flag points reminiscent of:
- A person story in
spec.mdwith no corresponding process induties.md - The plan referencing a database desk that’s undefined within the information mannequin
- A behaviour described within the spec that has no process assigned to implement it
This is a read-only command — it produces a findings report with out modifying any information. Fix flagged points earlier than working
/speckit.implement to stop cascading errors throughout code era.
Execute with /speckit.implement
With all artifacts in place, run /speckit.implement. The agent first validates that structure.md, spec.md, plan.md, and duties.md are all current, then executes duties so as — respecting dependencies and [P] parallel markers.
# The agent will:
# 1. Validate all prerequisite artifacts exist
# 2. Parse duties.md for the proper execution order
# 3. Execute duties, respecting [P] parallel markers
# 4. Report progress and deal with errors at every step
Local CLI instruments have to be put in. The agent will run instructions like
npm, dotnet, or python straight in your machine. Make positive all required runtimes can be found earlier than working this command.
Adding a brand new function? Skip
/speckit.structure (runs as soon as per venture) and begin from /speckit.specify for every subsequent function.
Full Spec Kit Workflow — Quick Reference
- Install:
uv device set up specify-cli --from git+https://github.com/github/[email protected] - Init venture:
specify init <PROJECT> --integration <agent> - Set ideas:
/speckit.structure— run as soon as per venture - Write spec:
/speckit.specify— describe what to construct, not how - Clarify gaps:
/speckit.make clear(non-obligatory, really useful earlier than plan) - Validate spec:
/speckit.guidelines(non-obligatory, after make clear) - Generate plan:
/speckit.plan— specify tech stack and structure - Break into duties:
/speckit.duties+ non-obligatory/speckit.taskstoissues - Check consistency:
/speckit.analyze(non-obligatory, after duties, earlier than implement) - Build it:
/speckit.implement
The Development Phases
Spec-Kit helps three broad improvement eventualities. For greenfield initiatives, you begin with high-level necessities, generate specs, and plan implementation earlier than writing any code. For iterative enhancement on present codebases (“brownfield”), you add options incrementally with out discarding prior context. For legacy modernization, the place the unique intent is commonly misplaced to time, you seize important enterprise logic in a contemporary spec, design a recent structure within the plan, and let the AI rebuild the system with out carrying ahead inherited technical debt.
The /speckit.duties command produces a duties.md file with process breakdowns organized by person story, dependency ordering (so fashions are applied earlier than providers, providers earlier than endpoints), parallel execution markers tagged [P], precise file path specs, and checkpoint validation between phases.
Agent Compatibility and Extensibility
The Specify CLI helps a variety of AI coding brokers. When you run specify init, the CLI units up the suitable command information, context guidelines, and listing buildings for your chosen AI coding agent. Spec-Kit presently helps 29 named integrations — together with Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI, Qwen Code, Kiro CLI, Goose, Mistral Vibe, Devin for Terminal, Roo Code, and IBM Bob — alongside with a Generic integration for any agent not on the listing.
An essential distinction: for a number of brokers, Spec-Kit installs agent expertise slightly than slash-command immediate information. Claude Code, for instance, makes use of a skills-based integration that locations information below .claude/expertise/. Codex CLI equally makes use of expertise invoked as $speckit-<command>. For these integrations, move --integration-options="--skills" throughout specify init to put in in expertise mode.
The toolkit can be prolonged via two mechanisms. Extensions introduce new instructions and templates — for instance, Jira or Azure DevOps integration, post-implementation code evaluation, OWASP LLM risk modeling, or V-Model take a look at traceability. Presets override present templates and instructions to implement organizational or regulatory requirements with out including new capabilities. There are presently over 70 community-contributed extensions within the catalog, overlaying classes together with docs, code, course of, integration, and visibility, every flagged as both Read-only or Read+Write in impact.
Key Takeaways
- GitHub’s Spec-Kit is an open supply toolkit that introduces a structured Spec-Driven Development (SDD) workflow for AI coding brokers, shifting away from ad-hoc prompting.
- The core workflow runs via six instructions:
/speckit.structure→/speckit.specify→/speckit.plan→/speckit.duties→/speckit.taskstoissues→/speckit.implement, with three extra non-obligatory instructions for validation. - Spec-Kit helps 29 named AI coding agent integrations plus a Generic possibility; some brokers (together with Claude Code and Codex CLI) use a skills-based set up mode slightly than slash instructions.
- A rising ecosystem of 70+ neighborhood extensions provides integrations with instruments like Jira, Azure DevOps, and GitHub Issues, plus high quality gates for safety, testing, and drift detection.
- The venture is self-described as an experiment and is greatest suited for greenfield builds and enormous function work slightly than small bug fixes.
Check out the GitHub Repo here. Also, be at liberty to observe us on Twitter and don’t overlook to hitch our 150k+ ML SubReddit and Subscribe to our Newsletter. Wait! are you on telegram? now you can join us on telegram as well.
Need to accomplice with us for selling your GitHub Repo OR Hugging Face Page OR Product Release OR Webinar and many others.? Connect with us
The put up Meet GitHub Spec-Kit: An Open Source Toolkit for Spec-Driven Development with AI Coding Agents appeared first on MarkTechPost.
