The way developers work with artificial intelligence is evolving rapidly. Tools like GitHub Copilot have normalised the idea that code can be written interactively in collaboration with an AI partner. Yet as anyone who has experimented with these assistants knows, the biggest source of frustration is not syntax but intent. If you tell Copilot “build me a dashboard,” it will do exactly that, but rarely the dashboard you imagined. GitHub’s Spec Kit is an attempt to move the locus of intent into explicit artefacts, specifications, plans, tasks, and constitutions that guide not only the humans but also the AI systems involved. Below I want to explore what that looks like in practice, why it matters, and how it can be adapted to real world development.
Spec Kit is a command line tool and a set of conventions. You start by initialising a new project with specify init, which sets up a folder structure with placeholders for specifications, plans, tasks and a constitution. The constitution is the first unusual concept. It is not code, not requirements, but a statement of principles and constraints. Imagine a project where every developer, whether human or AI, is expected to follow the same rules about architecture, security, and style. The constitution becomes the anchor for those rules. A very simple example might look like this:
# constitution.md
## Principles
- All backend services must be implemented in .NET 8 with minimal APIs.
- Every external dependency must be logged and approved before use.
- Unit test coverage must remain above 80%.
- All endpoints must be protected by Azure AD authentication.
## Constraints
- Database must remain PostgreSQL 16, hosted in Azure Database for PostgreSQL Flexible Server.
- Response times for critical endpoints must remain below 500ms at P95.
- Deployment must be via Azure Container Apps, not raw containers.
Although it looks like documentation, this file now guides every subsequent step. When you or your AI assistant later generate a plan or break down tasks, these principles are fed into the prompts and prevent drift from agreed architectural standards.
Once the constitution exists, you move on to specifications. The specify command opens an interactive session where you describe the feature or project you want to build. Suppose we need a real time chat widget for an e-commerce admin dashboard. A specification for that might be written like this:
# specs/chat-widget.md
## Overview
Build a chat support widget embedded in the Admin Dashboard. Logged in admins can communicate in real time with support agents. Messages may include text or file attachments.
## User Stories
- Admin users can send messages and view replies in real time.
- Support agents can see incoming chats in their queue and reply immediately.
- Unread messages are clearly indicated in the UI.
- File attachments must be limited to 5MB and restricted to image and PDF formats.
## Error States
- If the network drops, messages queue locally and retry when connection resumes.
- If a file upload fails due to size or format, the user sees an inline error and can retry.
- If the server returns an error, the client logs it and displays a non blocking message.
## Non-Functional Requirements
- End to end latency must remain under 200ms for message delivery.
- All data must be encrypted in transit and at rest.
Notice how this is not pseudo code but a set of declarative statements. It is more precise than a product brief but less prescriptive than a design document. The magic lies in what happens next. You can run specify plan specs/chat-widget.md and the tool, usually backed by an AI assistant, will generate a technical plan that respects both the specification and the constitution. A fragment of such a plan might look like this:
# plans/chat-widget-plan.md
## Architecture
The frontend will be React 18 with a dedicated ChatWidget component using Socket.IO for WebSocket communication. The backend will be a Node.js 20 Express service integrated into the existing API gateway. Messages will be stored in PostgreSQL with an append-only table design. Attachments will be uploaded to Azure Blob Storage with client side pre signed URLs.
## Security
Authentication will piggyback on the existing JWT issued by Azure AD. Every message insert checks role claims. File uploads are virus-scanned asynchronously before being marked available.
## Deployment
Backend services will be deployed into the `ci-chat` container app environment. CI pipeline must include integration tests for WebSocket event flow.
Already you can see how much friction is removed. Instead of a vague idea being turned into half formed code, we have a specification, a plan, and still no single line of production code. When we finally generate tasks, they are derived from this plan. The command specify tasks plans/chat-widget-plan.md might give us something like:
# tasks/chat-widget-tasks.md
- Create database migration for `messages` and `attachments` tables.
- Implement backend WebSocket handlers for `sendMessage` and `receiveMessage`.
- Add REST endpoint for retrieving chat history (`GET /chats/:id/messages`).
- Implement file upload API with pre-signed URL generation.
- Create React ChatWidget component with responsive layout.
- Add read/unread indicators to the UI.
- Write unit tests for backend handlers and integration tests for message flows.
We can now pick up these tasks individually, commit against them, and reviewers have a clear reference. Importantly, if Copilot or another AI assistant is involved, you can feed it a specific task and the relevant part of the plan, keeping context tight and the output aligned with the overall vision.
One of the most interesting challenges with Spec Kit is drift. As projects evolve, specifications and plans become outdated. The only way to keep them useful is to treat them as first class citizens in version control. A change in code that contradicts the specification should trigger either an update to the spec or a rollback of the change. For instance, if the team later decides to switch from Socket.IO to SignalR, the plan must be amended and the tasks regenerated. This discipline prevents the slow decay of documentation that plagues many long running projects.
A second challenge is scale. It is one thing to write a single specification and plan, but in a mature codebase you may have dozens. Here Spec Kit encourages modularity. Each feature or subsystem can live in its own folder with its own specification, plan, and tasks. A naming convention such as specs/001-chat-widget.md, specs/002-notifications.md helps order them. Over time, patterns emerge, and you can even maintain templates for common types of features. For example, if you frequently add new CRUD modules, you can create a crud-template.md specification with placeholders, making it easier to scaffold the next one.
What does this look like in a legacy environment? Imagine a monolithic insurance application written a decade ago. Management wants an audit trail of every user action, both for compliance and for internal monitoring. Without Spec Kit, the request might land as a Jira ticket that says “add audit trail,” leaving developers to guess scope and implementation. With Spec Kit, the constitution reminds the team of non negotiables such as database technology and encryption standards. The specification spells out what events must be logged, how long data should be retained, what the UI for reviewing logs must show. The plan then grapples with the hard reality of the existing architecture: do we piggyback on the current logging system, create new tables, or stream events to a service bus? The task breakdown can then be spread across multiple teams, ensuring incremental progress. The difference is night and day in clarity and predictability.
Spec Kit also shines in distributed teams. When developers are scattered across time zones, ambiguity multiplies. By insisting on a shared constitution and written specifications, teams create a common language. Even if half the work is assisted by AI, everyone understands the guardrails. A junior developer in Dublin can implement a task knowing that a senior reviewer in Bermuda will check it against the same specification. An AI assistant generating boilerplate knows that the constitution forbids unreviewed external dependencies, so it won’t casually pull in a random package.
For those interested in automation, Spec Kit integrates naturally with CI pipelines. Nothing prevents you from writing a simple job that verifies each pull request touching a feature folder has an up to date specification and plan. You could even go further and build a linter that checks whether the constitution’s principles are violated in code. Imagine a pre commit hook that rejects changes if test coverage drops below the constitution’s threshold. In that way the documents stop being passive and become active constraints.
Of course, no tool is without costs. Writing detailed specifications and plans requires discipline and time. For small bug fixes it is overkill. For greenfield projects it can feel like slowing momentum when everyone is excited to just start coding. Yet the payoff arrives later when features interact, when new members join, and when stakeholders demand accountability. Without specifications you have arguments; with them you have agreements.
GitHub’s Spec Kit is all about the philosophy - specifications first, implementation second. It recognises that AI is powerful but also literal, and that humans are often vague and contradictory. By putting a layer of explicit documents between intent and code, it ensures both humans and AI move in the same direction. The examples above, from chat widgets to audit trails, demonstrate how this looks in practice, with snippets showing the tangible artefacts you create along the way. Whether you are running a startup experimenting with real time features or an enterprise trying to update a monolith, Spec Kit offers a way to reduce ambiguity, capture decisions, and make AI a more reliable collaborator.
