When you have hung out utilizing AI coding brokers — GitHub Copilot, Claude Code, Gemini CLI — you’ve got in all probability run into this example: you describe what you need, the agent generates a block of code that appears appropriate, 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 difficulty, as GitHub frames it, shouldn’t be the coding agent’s capability — it’s the method. 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-Kit — a toolkit designed to carry Spec-Pushed Growth (SDD) to AI coding workflows. The challenge at the moment 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’s Spec-Pushed Growth?
Spec-Pushed Growth inverts the standard energy construction of software program improvement. Specs don’t serve code — code serves specs. The Product Necessities Doc (PRD) shouldn’t be a information for implementation; it’s the supply that generates implementation.
In apply, 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 fact 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 shouldn’t be about writing exhaustive, dry necessities paperwork that no one reads. It’s not about waterfall planning or attempting to foretell the longer term by in depth planning workout routines. And it isn’t about creating extra forms that slows engineering groups down. The spec stays a residing artifact — up to date as necessities evolve, slightly than filed away after challenge kickoff.
What Spec-Package Really Consists of
Spec-Packagehas two key elements: the Specify CLI, a helper command-line instrument 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 inspiration 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 by way of uv is the beneficial technique:
uv instrument 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 challenge’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 record/speckit.taskstoissues— converts the generated job record into GitHub points for monitoring and execution/speckit.implement— executes these duties utilizing the AI coding agent
There are additionally three optionally available instructions for enhanced high quality and validation:
/speckit.make clear— surfaces underspecified areas by structured, sequential questioning earlier than a technical plan is created (beneficial earlier than/speckit.planto cut 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 challenge — testing conventions, CLI-first necessities, organizational design system requirements. These are captured as soon as and referenced all through each subsequent improvement part.
The best way to Use GitHub Spec Package: A Step-by-Step Information
Spec-Pushed Growth (SDD) with AI coding brokers — from putting in the CLI to operating your first implementation. Follows the official workflow from the github/spec-kit repository.
Step 1 — Stipulations
Ensure you have the precise instruments put in
Earlier than putting in the Specify CLI, you want 4 issues in your machine. Spec Package is cross-platform and works on Linux, macOS, and Home windows.
- Python 3.11+ — obtain from python.org
- uv (beneficial) 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 instrument installations globally, retains them in your PATH, and makes upgrading simple with uv instrument record, uv instrument improve, and uv instrument uninstall. It’s the formally beneficial technique.
Step 2 — Set up
Set up the Specify CLI from GitHub
The one official Spec Package bundle is printed instantly from the GitHub repository. Don’t set up from PyPI — any bundle there with the identical identify shouldn’t be maintained by the Spec Package crew.
uv instrument 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
Verify the Releases page for the most recent tag (e.g.
v0.8.4). Putting in from most important could embrace unreleased modifications.
One-time utilization (no set up): Run
uvx --from git+https://github.com/github/[email protected] specify init to strive with out a persistent set up.
Step 3 — Initialize
Bootstrap your challenge with specify init
Navigate to your challenge folder and run specify init. The CLI detects which AI coding agent you’ve got 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=”–expertise”
specify verify
After this, your challenge will include a .specify/ listing with reminiscence/, scripts/, specs/, and templates/ subdirectories.
Expertise 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 an alternative of slash-command immediate information. Run specify integration record to see which mode every agent makes use of.
Step 4 — Structure
Set challenge 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 part. Run this as soon as per challenge.
/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 providers — 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 inner design system.”
Step 5 — Specification
Describe what to construct with /speckit.specify
Now describe what you need to construct — focus solely on the “what” and “why.” Don’t point out the tech stack at this stage. The agent produces a spec.md with person tales and practical necessities.
/speckit.specify Construct an utility that organizes images into albums.
Albums are grouped by date and may 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 “easy methods 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 robotically.
Step 6 — Elective High quality Instructions
Make clear and validate your spec earlier than planning
Earlier than producing the technical plan, two optionally available instructions assist floor gaps and validate your specification. Each are beneficial, and may 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 would possibly 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 might 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.
Maintain third-party libraries to a minimal. Pictures aren’t uploaded
wherever — metadata is saved in an area SQLite database by way of
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
Verify analysis.md to confirm the proper 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 — Job Breakdown
Generate duties with /speckit.duties and /speckit.taskstoissues
Run /speckit.duties to provide a duties.md with the total implementation roadmap. Duties are organized by person 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 person story part ends with a Checkpoint to validate that part’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 operating implementation, run the optionally available /speckit.analyze command. It performs a cross-artifact consistency and protection verify throughout the spec, plan, knowledge mannequin, and duties to make sure every part is aligned.
/speckit.analyze
The agent will flag points similar to:
- A person 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
It is a read-only command — it produces a findings report with out modifying any information. Repair flagged points earlier than operating /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 should be put in. The agent will run instructions like npm, dotnet, or python instantly in your machine. Make sure that all required runtimes can be found earlier than operating this command.
Including a brand new characteristic? Skip /speckit.structure (runs as soon as per challenge) and begin from /speckit.specify for every subsequent characteristic.
✅ Full Spec Package Workflow — Fast Reference
- Set up:
uv instrument set up specify-cli --from git+https://github.com/github/[email protected] - Init challenge:
specify init --integration - Set rules:
/speckit.structure— run as soon as per challenge - Write spec:
/speckit.specify— describe what to construct, not how - Make clear gaps:
/speckit.make clear(optionally available, beneficial earlier than plan) - Validate spec:
/speckit.guidelines(optionally available, after make clear) - Generate plan:
/speckit.plan— specify tech stack and structure - Break into duties:
/speckit.duties+ optionally available/speckit.taskstoissues - Verify consistency:
/speckit.analyze(optionally available, after duties, earlier than implement) - Construct it:
/speckit.implement
The Growth Phases
Spec-Package helps three broad improvement 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 person story, dependency ordering (so fashions are carried out 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. Once you run specify init, the CLI units up the suitable command information, context guidelines, and listing buildings to your chosen AI coding agent. Spec-Package 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 record.
An necessary distinction: for a number of brokers, Spec-Package 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-. For these integrations, cross --integration-options="--skills" throughout specify init to put in in expertise mode.
The toolkit can be prolonged by two mechanisms. Extensions introduce new instructions and templates — for instance, Jira or Azure DevOps integration, post-implementation code evaluation, 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, masking 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-Package is an open supply toolkit that introduces a structured Spec-Pushed Growth (SDD) workflow for AI coding brokers, shifting away from ad-hoc prompting.
- The core workflow runs by six instructions:
/speckit.structure→/speckit.specify→/speckit.plan→/speckit.duties→/speckit.taskstoissues→/speckit.implement, with three extra optionally available instructions for validation. - Spec-Package helps 29 named AI coding agent integrations plus a Generic choice; 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 Points, plus high quality gates for safety, testing, and drift detection.
- The challenge is self-described as an experiment and is finest fitted to greenfield builds and enormous characteristic work slightly than small bug fixes.
Take a look at the GitHub Repo here. Additionally, be happy to observe us on Twitter and don’t overlook to affix our 150k+ ML SubReddit and Subscribe to our Newsletter. Wait! are you on telegram? now you can join us on telegram as well.
Must companion with us for selling your GitHub Repo OR Hugging Face Web page OR Product Launch OR Webinar and many others.? Connect with us
