Transcript
[00:00] GitHub’s SpecKit introduced the world to spec-driven development, which in a nutshell solves a problem where coding agents have a tendency to turn unstated assumptions into code. Since then, there’s been a ton of libraries and frameworks that emulate or are derivative of SpecKit, but SpecKit’s still kind of the king at a whopping 11 months old today. In this video, we’re going to cover what SpecKit is, how to install it, how to use it to build an application from scratch, and we’ll look at the pros and cons of using it for AI-assisted development.
[00:34] First, let’s get SpecKit onto the machine, open a terminal, and run the one-liner UVTool install specify CLI. So to get started with our project, we’re going to need two things. The first thing is a constitution, which is exactly what it sounds like. It’s a set of guiding principles our agents should follow, and a spec, which describes the application or feature we’re working on. For our constitution, I’ll list some generic principles I’d like to follow, and then some app-specific rules.
[01:06] Next, we need to add the actual specification. So this is our first spec, and that means we need to explain what the application actually does. In general, you should structure your spec as though it were a feature, even when starting a new project. Now we’ll start a fresh project. Type specify init, and then the name of the directory where you want to create your application. In my case, it’s going to be focus app. I’ll pick open code for this demo, but you could use copilot, Gemini, Claude, whatever you want to use. There’s a giant list of agents you can install this for. I’ll also choose shell as my script type. This is for the scripts that spec kit’s going to create inside of our project.
[01:46] We’ll CD into that directory, and I like to get init at this point.
[01:52] And now we’ll jump into our coding agent, so I’ll load up open code. Now, since this is a new project, we’ll run the constitution command, and you only ever need to do this once in a project. So I’ll grab our constitution, and we will paste that guy in there, and we’ll run that. So when this is wrapped up the first time, I like to have the agent commit the changes. It’s probably just me, but I feel like it sets a tone, and I get more consistent commits afterwards.
[02:19] So now we’re going to run our spec by doing spec kit dot specify. We’re going to grab our spec, and we’re going to paste that guy in. Now spec kit’s going to parse the input and create a structured specification for us, and stores that for the next phase. So here’s the code base, and we can see we have our constitution describing all of our guiding principles. And in our spec folder, we have our first spec outlining the features as I described it. So with our spec in place, we want the agent to challenge the spec. So we’re going to run spec kit clarify. And what this is going to do, it’s going to review our spec and see if it jives with our constitution or other specs we’ve implemented in the past. Or if there are gaps in our feature set. And here it came back with a clarifying question.
[03:07] So how should the task be ordered in the main task by default? And it gives me some options. And I’m just going to go ahead and go with the recommended option a
[03:22] So now that our spec has been properly vetted, we can create our plan with spec kit dot plan. If we take a look in our project, our spec documents have exploded. And now we have research, decision tracking, scopes, user stories, success criteria, and functional requirements. And once our plan is in place, we can break that into manageable tasks with spec kit tasks. This tool reads the plan document and generates a list of tasks in phases with references to elements created in the plan and implementation strategies. So now we get to the heavy lifting and this is going to be spec kit dot implement.
[04:06] So spec kit’s going to work in a feature branch for our spec and streams each task to the AI agent, which writes the corresponding code files and commits them. And as the changes are made, we can see directories, code tests all being updated and created and committed as it goes along.
[04:24] So this is a step that a lot of folks like to skip, but trust me, you want to run this guy. So after all the tasks are completed, run spec kit converge. And this is very much like the clarify step, except it’s going to go back and it’s going to evaluate all the completed work and identify any gaps that we may want to reconsider. And if it comes back with any suggested changes, it’ll create appended tasks to our existing task lists that we can run spec kit implement again on.
[04:57] So now we can see our app is ready. We’ve got a beautiful, uh, get commit history here. Now we can run NPM dev to explore the application and here’s our app and it’s super ugly, but everything here is functioning. Um, I can create a task with a description, set a due date, create a tag and hit add task. And now it’s in the list down here.
[05:21] I can update its status. I can edit it, delete it, whatever. Everything’s here.
[05:26] I’ve got a light and dark mode. Like I said, it looks kind of shitty, but I didn’t describe any design in this and I usually would not. So let’s take a quick look and make sure all of our tests are passing. So along the way, spec kit did write a bunch of tests for us. Groovy, 70 tests are passing.
[05:47] Now, as far as design at this point, I don’t really think you need to worry about it, but I do like to run a little minimalist UI skill on this guy, uh, just to clean things up, but that’s entirely optional at this stage.
[06:06] So as far as further development, uh, we just create a new spec here. I made one for moving the task form into a model and we follow the exact same steps. Spec kit specify creates our spec. We dropped that in there. Spec kit clarify is going to challenge our spec. Spec kit plan is going to define all of our requirements and spec kit task is going to generate manageable tasks for our agent. And we’re going to run spec kit implement, which is going to implement all the tasks. And we’ll follow that up with spec kit converge. And now I have the task form in a modal functioning as I described.
[06:40] And after running a few more specs, my app is really starting to come together. I’ve got a calendar view where I can drag them all around. I have tasks that recur or have dependencies or subtasks.
[06:57] And that’s the core workflow, uh, install, init, set a constitution, write a clear spec plan, split into tasks, implement and verify. So the overall benefit from using spec kit or spec driven development is you can turn vague requirements into a working application while staying in control of every step and persist a clear history of every decision ever made. But that’s sort of a double edged sword because all of this planning and documentation takes time, it makes it slower and more verbose than trying to one-shot vibe code and application. However, the patience you put into using AI to develop like this will pay off down the road when you can actually generate meaningful information or bug reports from the documentation and history that spec kit created for you.
Installation
uv install specifiy-cliInitialize a project
specify init <folder-name>During this process you can choose a specific harnesss (opencode, etc) that you want to set up integrations for. you can always add more integrations later.
Constitution
Our project’s Constitution is a set of guiding principles our agents should follow, I’ll list some generic principles I’d like to follow, and then some app-specific rules.
- Features should be independently testable.- Business logic should be represented explicitly and tested.- Prefer simple, maintainable solutions over unnecessary abstractions. - Use TypeScript with strict type checking.- The UI should remain responsive and keyboard accessible.- Keep the application local-first with no required backend.and we’ll initialize the constitution with the following in our coding agent
/speckit.constitution <paste constitution here>Our agent will now reference the constitution to ensure any specifications going forward comply with the rules we set here.
Specification
In general, you should structure your specification as though it were a feature, even when starting a new project.
Here is the specification I used in the video:
Build a personal task management application called Focus App.
Users can create, edit, complete, and delete tasks.
Each task has:- title- description- priority: low, medium, high- status: todo, in-progress, completed- optional due date- tags
The main interface should show a list of tasks.
Users should be able to:- create a task- edit a task- mark a task complete- delete a task- filter tasks by status- filter tasks by priority- filter tasks by tag- search tasks by title and description
Tasks should persist locally so that data survives application restarts.
The application should have a clean desktop-first interface and support dark and light themes.We can kick off this project by running the following in our coding agent:
/speckit.specify <paste spec here>The Spec-Driven Workflow
Specify
We’ve already looked at how to kick things off with
/speckit.specifyClarify
We follow the specify step with clarify to follow up with the agent on any open questions or to confirm any assumptions it may have made.
/speckit.clarifyIn this process the agent may ask questions you’ll need to respond to.
Plan
Now that our spec has been properly vetted, we can create our plan with speckit.plan. This tool will produce research, decision tracking, scopes, user stories, success criteria, and functional requirements.
/speckit.planTasks
Next we create the tasks with spekkit.tasks. This tool reads the plan document and generates a list of tasks in phases with references to elements created in the plan and implementation strategies.
/speckit.tasksImplement
Next we implement the feature(s). speckit.implement. Spec kit’s going to work in a feature branch for our spec and stream each task to the AI agent, which writes the corresponding code files and commits them.
/speckit.implementConverge
Finally we converge. speckit.converge. This is very much like the clarify step, except it’s going to go back and it’s going to evaluate all the completed work and identify any gaps that we may want to reconsider. And if it comes back with any suggested changes, it’ll create appended tasks to our existing task lists.
/speckit.convergeIf the converge step produces any new tasks we cycle from implement to converge as many times as needed.
Additional specs I ran from the video:
Spec #2:
Update the task creation and editing experience in Focus.
The Add Task and Edit Task forms should be presented in a modal dialog rather than as inline or dedicated-page forms.
When the user selects "Add Task", open an empty task form in a modal.
When the user selects an existing task to edit, open the same form in a modal populated with the task's current values.
The modal should contain all fields currently supported by the task model:- title- description- priority- status- due date- tags
The modal should provide:- Save button- Cancel button- close button
Saving should validate the form and persist the task.
Canceling or closing the modal should discard unsaved changes.
If the user attempts to close the modal while there are unsaved changes, the application should ask for confirmation before discarding them.
The modal should:- appear above the current application view- prevent interaction with the underlying page while open- trap keyboard focus within the modal- close with the Escape key- return keyboard focus to the control that opened it after closing- be usable entirely with the keyboard
The same modal component and form implementation should be reused for both creating and editing tasks.Spec #3:
Add a calendar view to Focus App.
- Users should be able to switch between the existing task-list view and a calendar view.- The calendar should support month, week, and day views.- Tasks with due dates should appear on the calendar.- Users should be able to drag a scheduled task to another date, which changes its due date.- Users should be able to click a calendar task to open its task details.- Tasks without a due date should not appear on the calendar.- The current date should be visually distinguished.Spec #4:
Add recurring tasks to Focus App.
Users should be able to configure a task to repeat:- daily- weekly- monthly- on selected days of the week
Users should be able to specify an optional end date.
When a recurring task is completed, focus-app should create the next occurrence according to its recurrence rule.
Completing one occurrence must not mark future occurrences as completed.
Users should be able to edit either:- the current occurrence- the entire recurring series
Users should be able to stop a recurring series.
Recurring tasks should appear correctly on the calendar.Spec #5
Add subtasks to Focus App.
A task can contain multiple subtasks.
Users can create, edit, reorder, complete, and delete subtasks.
The parent task should display its completion progress.
A parent task should not automatically become completed when all subtasks are completed.
Instead, when all subtasks are completed, the user should be prompted to complete the parent task.
Completing a parent task should complete all of its incomplete subtasks.
Subtasks should inherit the parent's tags but may have their own due date and priority.