In the previous tutorials, we covered the /constitution command to set up the foundational rules for AI agent behavior. In this tutorial, we will explore two additional commands: /specify and /clarify. First let’s understand what /specify command does.
/specify Command #
We are gonna use the /specify command which is use to make a high level specification of a new feature or evenn a whole segment of the application. I found that working on contained features works better than trying to specify a whole application at once. I have noticed some people have success specifying a whole application at once, but I think there is a high chance of models going off track when the scope is too large. It doesn’t mean that the feature you are specifying has to be small, because then the Spec Kit becomes a little bit overkill. To begin with, we’ll give it a fair amount of work to do just to get the main functionality up and running.
In the Copilot Chat interface, you can enter the /specify command followed by a brief description of the feature you want to implement. This outline should be high level and it should focus on what and why instead of how. We shouldn’t get into details about the underlying technologies or the architecture we’ll be using, but instead focus on the user experience. I’m gonna develop a simple web app which users can generate ics calendar files for events. Users can input event details such as title, date, time, and location, and the app will generate a downloadable .ics file that can be imported into calendar applications.
Let’s clarify what happens when we run the /specify command. If you open .github/agents/speckit.specify.agent.md file, you can see the full prompt that is run with the prompt given by us. Like in the constitution command, our prompt is inserted into $ARGUMENTS variable. The prompt also says that the arguments represent the new feature that we are making. It also runs a script which does couple of things, it makes and checks out a new feature branch, it also updates the .github/prompts/speckit.specify.prompt.md file with the new feature description. Finally, it instructs the agent to inform the user with brnch name, spec file path and next steps.
If you want to see the script file that is being run, you can check out .specify/scripts directory. The content of this directory can be based on the OS you are using. In my case, I’m using Mac so I have a bash directory. Inside this directory, you can see the create-new-feature.sh file. You can search for a string like branch name in this file to see how the branch name is being generated. It generates a branch name using a feature number and the first three words of the specify prompt. After that it checks out the new branch.
After running the /specify command, the agent created a new branch called 001-add-ics-generator and checked it out. It also created two new files specs/001-add-ics-generator/spec.md and specs/001-add-ics-generator/checklists/requirements.md. The spec.md file contains a detailed specification of the feature we described in the /specify command. It breaks down the feature into user stories, acceptance criteria, and technical considerations. This was all in the spec template that it used. The requirements.md file contains a checklist of requirements that need to be fulfilled for this feature.
If you open the spec.md file, you can see that it has broken down the feature into multiple user stories. In the Edge Cases section, it has identified potential edge cases that we need to clarify before implementing the feature. In the next command /clarify, we will address and refine these edge cases.
In the requirements.md file, we’ve got Content Quality, Requirement Completeness and Feature Readiness checklists. While the agent is implementing the feature, it will refer to these checklists to ensure that all requirements are met.
/clarify Command #
Now we’ve got the spec created, we can either go right onto the planning stage by running the /plan command, or optionally we can run the /clarify command first. The /clarify command instructs the agent to read through the current spec file and identify any ambiguities, edge cases, or areas that need further clarifications. Then it asks the user for input to refine and update the spec accordingly. This step is not required, but I find it useful to run this command to ensure that the spec is as clear and comprehensive as possible before moving on to planning and implementation.
If you run the /clarify command, it will run the .github/agents/speckit.clarify.agent.md file. Essentially, it looks at our spec file and see if there is any underspecified areas. If there is, it’s going to ask us about them and it will give some options that we can reply with. Once we answered all those questions, it will update the spec file with our answers. I’m gonna run the /clarify command for my project now.
The clarify command has identified a few areas in the spec that need further clarification. It has prompted me with five questions regarding edge cases and user interactions.
As the first question, it is asking how to handle multi-day all-day events, It also gives me three options to choose from.
The second question is about handling recurring events. Again, it provides three options to choose from.
After answering all the questions, the agent has updated the spec file with my answers. If you open the specs/001-add-ics-generator/spec.md file, you can see that it has added new functional requirements and clarifications based on my responses.
The next step after clarifying the spec would be to run the /plan command. The Copilot itself recommends running the /plan command after specifying and clarifying the feature. In the next tutorial, we will explore the /plan command in detail and see how it helps in breaking down the implementation tasks for the specified feature.