You probably have hung out utilizing AI coding brokers — GitHub Copilot, Claude Code, Gemini CLI — you could have 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” strategy can work for fast prototypes however turns into much less dependable when constructing mission-critical functions or working with present codebases. The problem, as GitHub frames it, isn’t the coding agent’s means — it’s the strategy. Builders 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-Equipment — a toolkit designed to convey Spec-Pushed Improvement (SDD) to AI coding workflows. The venture at the moment has 90k+ stars and 8k+ forks on GitHub, and has develop into one of many faster-growing developer tooling repositories in current reminiscence.
What’s Spec-Pushed Improvement?
Spec-Pushed Improvement inverts the normal energy construction of software program growth. Specs don’t serve code — code serves specs. The Product Necessities Doc (PRD) isn’t a information for implementation; it’s the supply that generates implementation.
In observe, this implies you write a structured specification first — describing what you need 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, check, and validate code. The result’s much less guesswork, fewer surprises, and higher-quality code.
That is distinct from “documentation-first” as historically practiced. SDD isn’t about writing exhaustive, dry necessities paperwork that no one reads. It’s not about waterfall planning or attempting to foretell the longer term by means of in depth planning workouts. 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, fairly than filed away after venture kickoff.
What Spec-Equipment Really Consists of
Spec-Equipmenthas two key parts: the Specify CLI, a helper command-line software that bootstraps initiatives for SDD by downloading official templates for the coding agent and platform of your selection; and a set of templates and helper scripts that set up the muse for the SDD expertise — defining what a spec seems to be 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+. Set up through uv is the really useful technique:
uv software set up specify-cli --from git+https://github.com/github/[email protected]
specify init As soon as 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 rules/speckit.specify— captures what you need to construct, targeted 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 job checklist/speckit.taskstoissues— converts the generated job checklist into GitHub points for monitoring and execution/speckit.implement— executes these duties utilizing the AI coding agent
There are additionally three elective instructions for enhanced high quality and validation:
/speckit.make clear— surfaces underspecified areas by means of 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 necessary addition is structure.md. Within the SDD context, a structure doc establishes a set of non-negotiable rules for a venture — testing conventions, CLI-first necessities, organizational design system requirements. These are captured as soon as and referenced all through each subsequent growth section.
Learn how to Use GitHub Spec Equipment: A Step-by-Step Information
Spec-Pushed Improvement (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 — Conditions
Be sure to have the precise instruments put in
Earlier than putting in the Specify CLI, you want 4 issues in your machine. Spec Equipment is cross-platform and works on Linux, macOS, and Home windows.
- Python 3.11+ — obtain from python.org
- uv (really useful) or pipx for bundle 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 software installations globally, retains them in your PATH, and makes upgrading simple with uv software checklist, uv software improve, and uv software uninstall. It’s the formally really useful technique.
Step 2 — Set up
Set up the Specify CLI from GitHub
The one official Spec Equipment bundle is revealed instantly from the GitHub repository. Don’t set up from PyPI — any bundle there with the identical identify isn’t maintained by the Spec Equipment group.
uv software set up specify-cli –from git+https://github.com/github/spec-kit.git@vX.Y.Z
pipx set up git+https://github.com/github/spec-kit.git@vX.Y.Z
specify model
Test the Releases web page for the most recent tag (e.g.
v0.8.4). Putting in from essential could embody unreleased modifications.
One-time utilization (no set up): Run
uvx --from git+https://github.com/github/[email protected] specify init to attempt with out a persistent set up.
Step 3 — Initialize
Bootstrap your venture with specify init
Navigate to your venture folder and run specify init. The CLI detects which AI coding agent you could have put in and units up the precise listing construction, templates, and instructions robotically.
specify init my-photo-app
specify init . –integration claude
specify init . –integration codex –integration-options=”–abilities”
specify examine
After this, your venture will include a .specify/ listing with reminiscence/, scripts/, specs/, and templates/ subdirectories.
Expertise mode: Claude Code, Codex CLI, Kimi Code, Devin, and several other different brokers use a skills-based set up — recordsdata go into agent-specific directories (e.g. .claude/abilities/) as an alternative of slash-command immediate recordsdata. Run specify integration checklist to see which mode every agent makes use of.
Step 4 — Structure
Set venture rules with /speckit.structure
The primary command you run inside your agent is /speckit.structure. This creates a structure.md file containing non-negotiable governing rules the agent follows all through each subsequent section. Run this as soon as per venture.
/speckit.structure Create rules targeted on:
– Code high quality and check protection requirements
– Person expertise consistency throughout all screens
– Efficiency necessities for image-heavy interfaces
– No third-party picture add companies — native storage solely
This writes to .specify/reminiscence/structure.md. Consider it as standing directions — issues like “at all times use TypeScript,” “by no means introduce breaking API modifications,” or “observe our inside design system.”
Step 5 — Specification
Describe what to construct with /speckit.specify
Now describe what you need to construct — focus totally on the “what” and “why.” Don’t point out the tech stack at this stage. The agent produces a spec.md with consumer tales and useful necessities.
/speckit.specify Construct an software 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. Inside every album, images are previewed in a
tile-like interface. Customers can rename and delete albums however
can’t delete particular person images from inside an album view.
Don’t point out tech stack right here. Mixing “what to construct” with “how you can 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 robotically.
Step 6 — Non-compulsory High quality Instructions
Make clear and validate your spec earlier than planning
Earlier than producing the technical plan, two elective instructions assist floor gaps and validate your specification. Each are really useful, and might be skipped for fast spikes or exploratory prototypes.
/speckit.make clear
Structured, sequential questioning that data solutions instantly in a Clarifications part of the spec. Reduces rework downstream. Run earlier than /speckit.plan.
/speckit.guidelines
Generates customized high quality checklists that validate necessities completeness, readability, and consistency — described within the README as “unit checks for English.” Run after clarification.
/speckit.make clear
/speckit.guidelines
Throughout clarification, the agent may ask issues like:
- Ought to albums assist a number of choice for batch operations?
- Is there a most variety of images per album?
- Ought to drag-and-drop work on cellular, 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.
Step 7 — Technical Plan
Outline 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.
Hold third-party libraries to a minimal. Photographs will not be uploaded
wherever — metadata is saved in a neighborhood SQLite database through
a light-weight Categorical backend. Drag-and-drop makes use of the native
HTML5 Drag and Drop API.
Your listing after this step:
.specify/specs/001-photo-app/
├── spec.md
├── plan.md
├── data-model.md
├── analysis.md
└── quickstart.md
Test analysis.md to confirm the right tech stack was chosen. If a rapidly-changing framework is concerned, ask the agent to analysis the particular put in model earlier than shifting ahead.
Step 8 — Process Breakdown
Generate duties with /speckit.duties and /speckit.taskstoissues
Run /speckit.duties to supply a duties.md with the complete implementation roadmap. Duties are organized by consumer story, dependency-ordered, and annotated with parallel execution markers.
/speckit.duties
## Person Story: Album Administration
– [ ] Create SQLite schema: albums, images tables
– [ ] [P] Construct Categorical GET /albums endpoint
– [ ] [P] Construct Categorical 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. Every consumer story part ends with a Checkpoint to validate that section’s performance works independently earlier than the following begins. Optionally, convert duties to GitHub Points:
/speckit.taskstoissues
Step 9 — Cross-Artifact Evaluation
Validate consistency with /speckit.analyze
After producing duties and earlier than working implementation, run the elective /speckit.analyze command. It performs a cross-artifact consistency and protection examine throughout the spec, plan, knowledge mannequin, and duties to make sure the whole lot is aligned.
/speckit.analyze
The agent will flag points similar to:
- A consumer story in
spec.mdwith no corresponding job induties.md - The plan referencing a database desk that’s undefined within the knowledge mannequin
- A behaviour described within the spec that has no job assigned to implement it
This can be a read-only command — it produces a findings report with out modifying any recordsdata. Repair flagged points earlier than working /speckit.implement to stop cascading errors throughout code technology.
Step 10 — Implementation
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.
/speckit.implement
Native CLI instruments have to be put in. The agent will run instructions like npm, dotnet, or python instantly in your machine. Be sure that all required runtimes can be found earlier than working this command.
Including a brand new function? Skip /speckit.structure (runs as soon as per venture) and begin from /speckit.specify for every subsequent function.
✅ Full Spec Equipment Workflow — Fast Reference
- Set up:
uv software set up specify-cli --from git+https://github.com/github/[email protected] - Init venture:
specify init--integration - Set rules:
/speckit.structure— run as soon as per venture - Write spec:
/speckit.specify— describe what to construct, not how - Make clear gaps:
/speckit.make clear(elective, really useful earlier than plan) - Validate spec:
/speckit.guidelines(elective, after make clear) - Generate plan:
/speckit.plan— specify tech stack and structure - Break into duties:
/speckit.duties+ elective/speckit.taskstoissues - Test consistency:
/speckit.analyze(elective, after duties, earlier than implement) - Construct it:
/speckit.implement
The Improvement Phases
Spec-Equipment helps three broad growth situations. 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 job breakdowns organized by consumer story, dependency ordering (so fashions are applied earlier than companies, companies earlier than endpoints), parallel execution markers tagged [P], actual file path specs, and checkpoint validation between phases.
Agent Compatibility and Extensibility
The Specify CLI helps a variety of AI coding brokers. If you run specify init, the CLI units up the suitable command recordsdata, context guidelines, and listing buildings in your chosen AI coding agent. Spec-Equipment at the moment 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 — together with a Generic integration for any agent not on the checklist.
An necessary distinction: for a number of brokers, Spec-Equipment installs agent abilities fairly than slash-command immediate recordsdata. Claude Code, for instance, makes use of a skills-based integration that locations recordsdata beneath .claude/abilities/. Codex CLI equally makes use of abilities invoked as $speckit-. For these integrations, go --integration-options="--skills" throughout specify init to put in in abilities mode.
The toolkit can be prolonged by means of two mechanisms. Extensions introduce new instructions and templates — for instance, Jira or Azure DevOps integration, post-implementation code overview, OWASP LLM menace modeling, or V-Mannequin check traceability. Presets override present templates and instructions to implement organizational or regulatory requirements with out including new capabilities. There are at the moment over 70 community-contributed extensions within the catalog, overlaying classes together with docs, code, course of, integration, and visibility, every flagged as both Learn-only or Learn+Write in impact.
Key Takeaways
- GitHub’s Spec-Equipment is an open supply toolkit that introduces a structured Spec-Pushed Improvement (SDD) workflow for AI coding brokers, shifting away from ad-hoc prompting.
- The core workflow runs by means of six instructions:
/speckit.structure→/speckit.specify→/speckit.plan→/speckit.duties→/speckit.taskstoissues→/speckit.implement, with three extra elective instructions for validation. - Spec-Equipment 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 fairly than slash instructions.
- A rising ecosystem of 70+ group extensions provides integrations with instruments like Jira, Azure DevOps, and GitHub Points, plus high quality gates for safety, testing, and drift detection.
- The venture is self-described as an experiment and is greatest fitted to greenfield builds and enormous function work fairly than small bug fixes.
Take a look at the GitHub Repo right here. Additionally, be happy to observe us on Twitter and don’t overlook to hitch our 150k+ ML SubReddit and Subscribe to our E-newsletter. Wait! are you on telegram? now you may be a part of us on telegram as effectively.
Must companion with us for selling your GitHub Repo OR Hugging Face Web page OR Product Launch OR Webinar and so on.? Join with us
