GitHub Spec Kit: A Practical Guide to AI-Supported Software Development

GitHub Spec Kit is an open-source toolkit for implementing Specification-Driven Development (SDD) using AI coding agents.

Rather than asking an AI agent to write software directly from a prompt, Spec Kit introduces a structured process in which requirements are clarified, technical decisions are made, implementation tasks are generated and the resulting software is verified.

It represents an interesting evolution of ideas developed through Behaviour-Driven Development (BDD) and Acceptance Test-Driven Development (ATDD), where the emphasis was on agreeing what software should do before writing it. The difference is that AI agents can now undertake much of the implementation, testing and documentation.

Spec Kit works with GitHub Copilot and a range of other supported coding agents. It is not tied to a particular cloud platform and can be incorporated into existing Microsoft Azure, AWS or hybrid engineering environments.

1. The Spec Kit lifecycle

Spec Kit organises development around a series of commands, each producing or refining artefacts that inform the next stage.

The sequence is structured, but not rigid. Teams can revisit specifications and plans as they learn more.

The crucial distinction is that the specification describes the intended behaviour, while the plan describes the technical implementation.

This separation helps prevent technical decisions from prematurely determining what the product should do.

2. Getting started

You need Git, Python tooling, uv and a supported AI coding agent. For a Microsoft-oriented development team, GitHub Copilot is a natural starting point.

Install Spec Kit from a terminal:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Create a project configured for Copilot:

specify init my-project --ai copilot
cd my-project

Open the project in your coding environment and start your AI agent.

The commands in the next section are entered into the agent’s chat, not the terminal. Exact command syntax and supported integration options can change between Spec Kit releases.

3. A worked example

Imagine developing a feature for a regulatory compliance platform that allows customers to receive alerts when regulations affecting their business change.

Step 1: Establish engineering principles

/speckit.constitution
Use Azure-native services.
Follow established security and coding standards.
Require automated unit and integration tests.
Use existing APIs and shared components where possible.
All changes must pass CI/CD quality gates.

These principles are intended to apply consistently across subsequent development.

Step 2: Specify the feature

/speckit.specify
Allow customers to subscribe to regulatory
changes affecting selected countries and topics.
Customers must be able to:
- Select countries and regulatory topics
- Choose notification frequency
- View relevant changes
- Unsubscribe at any time
Include measurable acceptance criteria.

The agent creates a structured specification describing the required behaviour.

Step 3: Clarify requirements

/speckit.clarify
Identify ambiguous business rules,
edge cases and missing acceptance criteria.

For example, what happens when a customer subscribes to a topic that has no regulatory updates? How should the system handle a regulatory change affecting multiple countries?

These questions are resolved before implementation, reducing the likelihood of expensive rework.

Step 4: Develop the technical plan

/speckit.plan
Use the existing Azure architecture,
.NET APIs and established authentication.
Reuse existing notification services.

The agent examines the requirements and proposes an implementation approach consistent with the project’s engineering principles.

Step 5: Validate and generate tasks

Run /speckit.checklist to review requirements quality, followed by /speckit.tasks to generate the implementation work breakdown.

The /speckit.analyze command can then identify inconsistencies between the specification, technical plan and implementation tasks.

Step 6: Implement and verify

Run /speckit.implement to build the feature.

The coding agent works through the generated tasks, producing code, tests and supporting documentation.

The team then verifies the implementation against the specification, executes automated tests and resolves any defects or missing functionality.

Importantly, passing the generated tests is not sufficient evidence that the original business requirement has been understood correctly. The product leader and domain expert must still validate the resulting behaviour.

4. What files does Spec Kit create?

Most development artefacts are Markdown files stored alongside the source code.

Not every feature requires every file. Some are generated only when relevant.

The files provide persistent context for agents and an auditable record of the team’s decisions.

They also make it easier for different agents or engineers to continue work without relying entirely on conversational history.

5. How does this relate to BDD and ATDD?

Spec Kit has a particularly interesting relationship with Behaviour-Driven Development and Acceptance Test-Driven Development.

Dan North’s work on BDD and the work Richard Watt and I undertook on ATDD shared an important principle: software development should begin with an agreed understanding of the behaviour the system must exhibit.

The specification should describe what successful software looks like, while executable acceptance tests provide evidence that the implementation satisfies those expectations.

Spec Kit extends this thinking into a structured, AI-supported engineering workflow.

However, Spec Kit does not automatically guarantee the discipline of ATDD.

For example, a requirement might state:

Customers must receive notifications about regulatory changes relevant to their subscriptions.

A useful acceptance scenario would be:

Given a customer subscribes to French
environmental regulations
When a relevant regulation is updated
Then the customer receives a notification
according to their selected frequency
And the notification links to the
regulatory change

These examples can be included in the specification and converted into automated acceptance tests.

For a production team, I would make this an explicit engineering principle: important business behaviour should have agreed acceptance criteria and appropriate automated verification.

There is also a potential weakness in AI-supported development. If the same agent generates the specification, implementation and tests, all three may share the same misunderstanding.

Independent validation of business intent therefore remains important.

6. How should a team use Spec Kit?

For an organisation moving from Scrum towards AI-supported SDD, I would initially retain a small multidisciplinary team with clear responsibilities.

These are responsibilities, not necessarily six separate people.

A product leader might work directly with a domain expert and two engineers, supported by coding agents and shared engineering services.

The team should work iteratively rather than attempting to specify an entire product before implementation begins.

One of the advantages of AI-assisted development is that working software can be produced relatively quickly, allowing the team to refine requirements through observation and feedback.

This should reduce the need for large upfront specifications while preserving the discipline of defining expected behaviour.

7. How does Spec Kit fit with Azure, GitHub and AWS?

Spec Kit is not a replacement for an application lifecycle management platform. It provides a structured, specification-led development workflow that can operate across different cloud environments and engineering toolchains.

Both Microsoft and AWS offer technologies that support AI-assisted software development. Spec Kit itself is cloud-agnostic, although the choice of coding agent, development environment and deployment platform influences how the workflow is implemented.

A practical comparison is:

AWS Kiro

AWS has introduced Kiro, an AI development environment that places specification-driven development at the centre of its approach.

Kiro is particularly relevant because it provides an integrated experience for moving from requirements to technical design, implementation tasks and agent-assisted development.

Where Spec Kit provides an open-source framework that works with different coding agents, Kiro combines specification management and AI-assisted engineering within a dedicated development environment.

Both approaches share the principle that developers should establish what the software needs to do before asking AI agents to implement it.

Measuring and forecasting delivery with Nave

An important part of adopting Spec-Driven Development is understanding whether it genuinely improves the flow of work through the software development lifecycle.

Nave provides flow analytics and probabilistic forecasting, complementing Spec Kit and the underlying development toolchain.

It measures several important aspects of delivery performance:

• Cycle time: How long work takes from starting development to completion.
• Throughput: How many work items are completed over a given period.
• Work in progress: How much work is being undertaken simultaneously.
• Flow efficiency: How much time work spends actively progressing compared with waiting.
• Cumulative flow: How work moves through different stages and where queues develop.

Nave also uses historical delivery data to produce probabilistic forecasts.

Rather than asking developers to estimate precisely how many days a feature will take, product leaders can use observed delivery performance to understand the likelihood of completing work within a particular timeframe.

For organisations transitioning from Scrum to AI-supported SDD, this provides a useful alternative to story points and velocity.

Spec Kit helps structure and execute the development work. Nave helps measure and forecast how that work flows through the delivery process.

Together, they could provide a practical foundation for managing an AI-supported SDLC.

There is one important qualification. Nave measures the flow of work represented in the team’s work management system. If specifications, agent tasks and implementation activities are not reflected appropriately in that system, the measurements may provide an incomplete picture.

Teams therefore need consistent definitions of when work starts, finishes and moves between stages, particularly when AI agents change how development tasks are organised.

Choosing the right toolchain

For an organisation already invested in Microsoft Azure, GitHub and Azure DevOps, Spec Kit with GitHub Copilot is a sensible starting point. It can be introduced incrementally without replacing the existing engineering platform.

For an AWS-oriented organisation, Kiro deserves consideration alongside Spec Kit, particularly where teams want a more integrated specification-to-implementation experience.

For organisations operating across both cloud platforms, Spec Kit offers the advantage of separating the specification-led development process from the underlying cloud infrastructure.

Nave can complement either approach by providing an independent view of delivery performance and forecasting.

The objective is to establish a repeatable, measurable, AI-supported SDLC, not simply to select the most capable coding assistant.

8. What should you measure?

The objective is not to generate more code or specifications. It is to deliver valuable software more quickly, economically and reliably.

For an initial pilot, I would measure five things:

Nave can provide much of the flow-related evidence, while engineering systems provide information about effort, quality and deployment performance.

Product analytics and commercial systems are needed to establish whether the resulting functionality creates business value.

This distinction matters.

A reduction in development cycle time is an operational improvement. Its commercial significance depends on whether it enables valuable functionality to reach customers earlier, whether those customers adopt it and whether adoption influences revenue, retention or cost.

A useful value hypothesis might therefore be:

If SDD reduces the time required to deliver customer-requested functionality by 40%, we expect valuable features to become available earlier. Where customers adopt those features, this should accelerate the associated revenue opportunities and potentially improve retention.

The hypothesis can then be tested using delivery baselines, actual release dates, adoption data and commercial outcomes.

9. A practical first experiment

I would start with a small feature in an existing application, rather than building an entirely new product.

Choose something with genuine business rules, a manageable technical scope and measurable acceptance criteria. Use one domain expert and one or two engineers, supported by coding agents.

Run the complete Spec Kit lifecycle, including clarification, acceptance criteria, automated verification and deployment.

Use Nave, where the existing work management data supports it, to establish a delivery baseline and observe how work progresses through the experiment.

Record the effort involved in specification, implementation, testing, rework and release. Pay particular attention to where humans intervene, how often specifications change and whether the agents create additional verification or rework.

Compare the results against a representative baseline from the existing development process.

The experiment should answer three questions:

1. Speed: Can a small team deliver reliable software faster using SDD?
2. Economics: Does the reduction in implementation effort exceed any additional effort required for specification, verification and agent supervision?
3. Value: Does faster delivery enable valuable functionality to reach customers earlier?

The first two questions can be answered relatively quickly. The third requires observing customer adoption and commercial results over a longer period.

For a PE-backed software business, this distinction is particularly important. A technically successful experiment is useful, but the investment case depends on whether the new development model can produce measurable economic benefits within the available investment horizon.

Spec Kit, coding agents and tools such as Nave provide an increasingly practical foundation for testing that proposition.

The opportunity is not simply to automate software development. It is to redesign the development lifecycle around a much shorter journey from customer need to working software, while retaining the engineering discipline needed to deliver it reliably.

Author: David Fellows

I advise senior management teams on how to use technology to generate value in their business. Chief Digital Officer, Chief Technology Officer, Non Executive Director, Independent Technology Strategy advisor. View all posts by David Fellows