In case you have hung out utilizing AI coding brokers — GitHub Copilot, Claude Code, Gemini CLI — you’ve gotten most likely run into this case: 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 problem, as GitHub frames it, shouldn’t be the coding agent’s potential — it’s the method. Builders have been treating coding brokers like 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-Package — a toolkit designed to carry Spec-Pushed Improvement (SDD) to AI coding workflows. The mission at present has 90k+ stars and 8k+ forks on GitHub, and has change into one of many faster-growing developer tooling repositories in latest reminiscence.
What’s Spec-Pushed Improvement?
Spec-Pushed Improvement inverts the standard energy construction of software program growth. 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 follow, 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 shouldn’t be about writing exhaustive, dry necessities paperwork that no person reads. It’s not about waterfall planning or making an attempt to foretell the long run by intensive 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, somewhat than filed away after mission kickoff.
What Spec-Package Truly Consists of
Spec-Packagehas 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 alternative; and a set of templates and helper scripts that set up the inspiration 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+. Set up by way of uv is the really helpful methodology:
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 mission’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 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-compulsory instructions for enhanced high quality and validation:
- /speckit.make clear — surfaces underspecified areas by structured, sequential questioning earlier than a technical plan is created (really helpful earlier than /speckit.plan to scale back rework downstream)
- /speckit.analyze — runs cross-artifact consistency and protection evaluation after /speckit.duties and earlier than /speckit.implement
- /speckit.guidelines — generates customized high quality checklists that validate necessities completeness, readability, and consistency
An vital addition is structure.md. Within the SDD context, a structure doc establishes a set of non-negotiable rules for a mission — 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 Package: A Step-by-Step Information
Spec-Pushed Improvement (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
Be sure 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 (really helpful) 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 software installations globally, retains them in your PATH, and makes upgrading simple with uv software listing, uv software improve, and uv software uninstall. It’s the formally really helpful methodology.
Step 2 — Set up
Set up the Specify CLI from GitHub
The one official Spec Package package deal is printed straight from the GitHub repository. Don’t set up from PyPI — any package deal there with the identical title shouldn’t be maintained by the Spec Package crew.
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 primary might embrace unreleased adjustments.
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 mission with specify init
Navigate to your mission folder and run specify init. The CLI detects which AI coding agent you’ve gotten put in and units up the precise listing construction, templates, and instructions routinely.
specify init my-photo-app
specify init . –integration claude
specify init . –integration codex –integration-options=”–expertise”
specify examine
After this, your mission will comprise 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 a substitute of slash-command immediate information. Run specify integration listing to see which mode every agent makes use of.
Step 4 — Structure
Set mission 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 mission.
/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 adjustments,” or “comply with our inner design system.”
Step 5 — Specification
Describe what to construct with /speckit.specify
Now describe what you need to construct — focus completely 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 utility that organizes pictures 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, pictures are previewed in a
tile-like interface. Customers can rename and delete albums however
can not delete particular person pictures from inside an album view.
Don’t point out tech stack right here. Mixing “what to construct” with “tips on how 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.
Step 6 — Non-obligatory High quality Instructions
Make clear and validate your spec earlier than planning
Earlier than producing the technical plan, two non-compulsory instructions assist floor gaps and validate your specification. Each are really helpful, and might be skipped for fast spikes or exploratory prototypes.
/speckit.make clear
Structured, sequential questioning that information solutions straight 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 exams 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 pictures 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.
Maintain third-party libraries to a minimal. Photos should not uploaded
anyplace — 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
Test 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.
Step 8 — Activity Breakdown
Generate duties with /speckit.duties and /speckit.taskstoissues
Run /speckit.duties to supply a duties.md with the total 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, pictures 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 subsequent 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 non-compulsory /speckit.analyze command. It performs a cross-artifact consistency and protection examine throughout the spec, plan, knowledge mannequin, and duties to make sure all the pieces is aligned.
/speckit.analyze
The agent will flag points equivalent to:
- A consumer story in spec.md with no corresponding process in duties.md
- The plan referencing a database desk that’s undefined within the knowledge mannequin
- A behaviour described within the spec that has no process assigned to implement it
This can be a read-only command — it produces a findings report with out modifying any information. Repair flagged points earlier than operating /speckit.implement to forestall cascading errors throughout code era.
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 straight in your machine. Ensure all required runtimes can be found earlier than operating this command.
Including a brand new characteristic? Skip /speckit.structure (runs as soon as per mission) and begin from /speckit.specify for every subsequent characteristic.
✅ Full Spec Package Workflow — Fast Reference
- Set up: uv software set up specify-cli –from git+https://github.com/github/[email protected]
- Init mission: specify init –integration
- Set rules: /speckit.structure — run as soon as per mission
- Write spec: /speckit.specify — describe what to construct, not how
- Make clear gaps: /speckit.make clear (non-compulsory, really helpful earlier than plan)
- Validate spec: /speckit.guidelines (non-compulsory, after make clear)
- Generate plan: /speckit.plan — specify tech stack and structure
- Break into duties: /speckit.duties + non-compulsory /speckit.taskstoissues
- Test consistency: /speckit.analyze (non-compulsory, after duties, earlier than implement)
- Construct it: /speckit.implement
The Improvement Phases
Spec-Package 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 process breakdowns organized by consumer story, dependency ordering (so fashions are applied earlier than providers, providers 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. While 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 present 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 listing.
An vital distinction: for a number of brokers, Spec-Package installs agent expertise somewhat 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, move –integration-options=”–skills” throughout specify init to put in in expertise mode.
The toolkit will also be prolonged by two mechanisms. Extensions introduce new instructions and templates — for instance, Jira or Azure DevOps integration, post-implementation code evaluate, OWASP LLM risk 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 present over 70 community-contributed extensions within the catalog, protecting 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 Improvement (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 further non-compulsory instructions for validation.
- Spec-Package 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 somewhat 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 mission is self-described as an experiment and is greatest fitted to greenfield builds and huge characteristic work somewhat than small bug fixes.
Take a look at the GitHub Repo right here. Additionally, be at liberty to comply with 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 possibly can be part of us on telegram as properly.
Have to accomplice with us for selling your GitHub Repo OR Hugging Face Web page OR Product Launch OR Webinar and so on.? Join with us
