In the previous tutorials, we ran three commands of GitHub Spec Kit: /constitution, /specify, and /clarify. Constitution helped us define the overall purpose and principles of our project, Specify allowed us to outline detailed specifications for our features, then switch to a feature branch, and Clarify enabled us to refine those specifications by addressing ambiguities and edge cases. Before we proceed to the next commands, this is a good time to actually read the full spec file /specs/<feature>/spec.md that has been generated to confirm the specs meet our expectations. If you want to make any manual changes, now is the time to do it, because the next commands will build upon this spec file.
/plan Command #
After confirming the spec file, we can use the /speckit.plan command. After that command we can add some details as to how we want to plan this feature. This is the step where you outline any technical implementation details such as what CSS framework to use, what UI component library, testing framework or any other third party services or APIs you want to integrate. This planning stage is where you lay that out. Below is the small snippet I provided for my ICS Generator:
Before running the command, let’s check the .github/agents/speckit.plan.agent.md file, so we can get a rough idea on what this command does ahead of time. As previous commands, this file also accepts a $ARGUMENTS variable that replace with what we provide after the command. Then it instructs the agent to run the script setup plan. Then the agent will ask questions from user for any unclarified details. Then agent will read and understand the spec file for the feature. Then it will read the constitution file to ensure the plan aligns with the overall project goals. Then it instructs the agent to start work on the plan file itself by reading through the plan template and executing each stage in order. In this phase the agent should create several files like, research.md, data-model.md, and quickstart.md. Once it does all that, it’s told to verify its own work by making sure everything in this planning stage is completed. Finally, it will report the details back to us in the chat.
If we go to .specify/templates/plan-template.md, This file includes a list of steps that the agent needs to follow to fill out this plan, do its research, make the data models, create contracts and check its own work.
Let’s fire off the /speckit.plan command now. While the agent is working on the plan, you can see in the chat how it’s progressing through each step of the plan template. Once it’s done, it will provide a summary of what it has accomplished in the chat with descriptions of each file it created or updated.
After the command is complete, we can see the new files that were created under /specs/<feature> directory. If we open up plan.md, and look for the Constitution Check section, you can see that the requirements that we defined in the constitution file has been referenced here to ensure that the plan aligns with the overall project goals. If we scroll down further, we can see the project directory structure that was outlined in the plan. These files are not created yet, but this gives us a clear idea of what needs to be done in the implementation phase.
If we open the data-model.md file, in the Entities section, there is a list of different properties that the main entity ICS File will have like title, description, start time, end time, etc. As we chose TypeScript as our programming language, it may also shows TypeScript interfaces for these entities that we can use later during implementation. This makes it really easy during the actual coding phase for the coding agent to look at this and generate code based on these data models.
Read all these created files and make sure everything matches your requirements before proceeding to the next command. Next step is to create a task list for the coding agent to follow during implementation. So we want to make sure that this plan is good enough for the next step.
/tasks Command #
The /speckit.tasks command takes the plan documents and from those makes an actionable set of tasks for the coding agent to work on to implement that plan. In the chat, all we need to do is run the command without any additional details because we have already made the entire plan and this next step is just about turning the plan into a series of tasks for the AI coding agent to follow.
Before running the command, as with previous commands, let’s check the .github/agents/speckit.tasks.agent.md file to see what this command does. Inside this file, we can again see the $ARGUMENTS variable that will be replaced with what we provide after the command. After that it instructs the agent to run the script setup tasks. This script will check the current feature branch, get the paths of plan files etc. Then it outputs the results to the terminal so the agent can read them. Then it instructs the agent those plan documents if they exist. Then it tells the agent to create tasks using the tasks template file located at .specify/templates/tasks-template.md. It says to replace the example tasks in that template with actual tasks. It also outlines some task generation rules down here as well, followed by some guidance on how to order the tasks.
After running the command, it will create a tasks.md file under the /specs/<feature> directory. If you open that file, you can see a list of tasks identified as T001, T002, T003 and so on. There are split into different phases. Phases may also split into different milestones. Some of the tasks have a [P] tag which indicates that those are running parallelly. After the tasks, there will be a section for Dependencies & Execution Order which outlines any dependencies between tasks and the order in which they should be executed.
In the next tutorial, we can start implementing these tasks. However, there is one more optional command we can run which is the /speckit.analyze command. We will cover that in the next tutorial as well before we start implementation.