You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: Enhance quickstart guide with admonitions and examples
- Convert blockquotes to GFM admonitions for better visibility
- Add current directory initialization example
- Expand process to 6 steps with clarify, analyze, checklist, implement
- Update example with separate clarify commands
- Add proper links in Next Steps
Fixes#906, #472
Generated-by: GitHub Copilot <[email protected]>
Signed-off-by: Ashley Childress <[email protected]>
Copy file name to clipboardExpand all lines: docs/quickstart.md
+76-51Lines changed: 76 additions & 51 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,16 +2,24 @@
2
2
3
3
This guide will help you get started with Spec-Driven Development using Spec Kit.
4
4
5
-
> NEW: All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`.
5
+
> [!NOTE]
6
+
> All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`.
6
7
7
-
## The 5-Step Process
8
+
## The 6-Step Process
8
9
9
-
### 1. Install Specify
10
+
> [!TIP]
11
+
> **Context Awareness**: Spec Kit commands automatically detect the active feature based on your current Git branch (e.g., `001-feature-name`). To switch between different specifications, simply switch Git branches.
10
12
11
-
Initialize your project depending on the coding agent you're using:
13
+
### Step 1: Install Specify
14
+
15
+
**In your terminal**, run the `specify` CLI command to initialize your project:
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script sh # Force POSIX shell
22
30
```
23
31
24
-
### 2. Define Your Constitution
32
+
### Step 2: Define Your Constitution
25
33
26
-
Use the `/speckit.constitution` command to establish the core rules and principles for your project. This ensures all future code and specifications adhere to your project's standards.
34
+
**In your AI Agent's chat interface**, use the `/speckit.constitution`slash command to establish the core rules and principles for your project. You should provide your project's specific principles as arguments.
27
35
28
-
```bash
29
-
/speckit.constitution
36
+
```markdown
37
+
/speckit.constitution This project follows a "Library-First" approach. All features must be implemented as standalone libraries first. We use TDD strictly. We prefer functional programming patterns.
30
38
```
31
39
32
-
### 3. Create the Spec
40
+
### Step 3: Create the Spec
33
41
34
-
Use the `/speckit.specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
42
+
**In the chat**, use the `/speckit.specify` slash command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
35
43
36
-
```bash
44
+
```markdown
37
45
/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
38
46
```
39
47
40
-
### 4. Create a Technical Implementation Plan
48
+
### Step 4: Refine the Spec
41
49
42
-
Use the `/speckit.plan`command to provide your tech stack and architecture choices.
50
+
**In the chat**, use the `/speckit.clarify` slash command to identify and resolve ambiguities in your specification. You can provide specific focus areas as arguments.
43
51
44
52
```bash
53
+
/speckit.clarify Focus on security and performance requirements.
54
+
```
55
+
56
+
### Step 5: Create a Technical Implementation Plan
57
+
58
+
**In the chat**, use the `/speckit.plan` slash command to provide your tech stack and architecture choices.
59
+
60
+
```markdown
45
61
/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
46
62
```
47
63
48
-
### 5. Break Down and Implement
64
+
### Step 6: Break Down and Implement
49
65
50
-
Use `/speckit.tasks` to create an actionable task list, then ask your agent to implement the feature.
66
+
**In the chat**, use the `/speckit.tasks` slash command to create an actionable task list.
67
+
68
+
```markdown
69
+
/speckit.tasks
70
+
```
71
+
72
+
Optionally, validate the plan with `/speckit.analyze`:
73
+
74
+
```markdown
75
+
/speckit.analyze
76
+
```
77
+
78
+
Then, use the `/speckit.implement` slash command to execute the plan.
79
+
80
+
```markdown
81
+
/speckit.implement
82
+
```
51
83
52
84
## Detailed Example: Building Taskify
53
85
@@ -57,8 +89,8 @@ Here's a complete example of building a team productivity platform:
57
89
58
90
Initialize the project's constitution to set ground rules:
59
91
60
-
```bash
61
-
/speckit.constitution
92
+
```markdown
93
+
/speckit.constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented.
62
94
```
63
95
64
96
### Step 2: Define Requirements with `/speckit.specify`
@@ -70,58 +102,51 @@ let's call it "Create Taskify," let's have multiple users but the users will be
70
102
I want five users in two different categories, one product manager and four engineers. Let's create three
71
103
different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do,"
72
104
"In Progress," "In Review," and "Done." There will be no login for this application as this is just the very
73
-
first testing thing to ensure that our basic features are set up. For each task in the UI for a task card,
74
-
you should be able to change the current status of the task between the different columns in the Kanban work board.
75
-
You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task
76
-
card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick
77
-
from. There will be no password required. When you click on a user, you go into the main view, which displays the list of
78
-
projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns.
79
-
You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are
80
-
assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly
81
-
see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can
82
-
delete any comments that you made, but you can't delete comments anybody else made.
105
+
first testing thing to ensure that our basic features are set up.
83
106
```
84
107
85
108
### Step 3: Refine the Specification
86
109
87
-
After the initial specification is created, clarify any missing requirements:
110
+
Use the `/speckit.clarify` command to interactively resolve any ambiguities in your specification. You can also provide specific details you want to ensure are included.
88
111
89
-
```text
90
-
For each sample project or project that you create there should be a variable number of tasks between 5 and 15
91
-
tasks for each one randomly distributed into different states of completion. Make sure that there's at least
92
-
one task in each stage of completion.
112
+
```bash
113
+
/speckit.clarify I want to clarify the task card details. For each task in the UI fora task card, you should be able to change the current status of the task between the different columnsin the Kanban work board. You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task card, assign one of the valid users.
93
114
```
94
115
95
-
Also validate the specification checklist:
116
+
You can continue to refine the spec with more details using `/speckit.clarify`:
96
117
97
-
```text
98
-
Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not.
118
+
```bash
119
+
/speckit.clarify When you first launch Taskify, it's going to give you a list of the five users to pick from. There will be no password required. When you click on a user, you go into the main view, which displays the list of projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns. You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can delete any comments that you made, but you can't delete comments anybody else made.
120
+
```
121
+
122
+
### Step 4: Validate the Spec
123
+
124
+
Validate the specification checklist using the `/speckit.checklist` command:
125
+
126
+
```bash
127
+
/speckit.checklist
99
128
```
100
129
101
-
### Step 4: Generate Technical Plan with `/speckit.plan`
130
+
### Step 5: Generate Technical Plan with `/speckit.plan`
102
131
103
132
Be specific about your tech stack and technical requirements:
104
133
105
-
```text
106
-
We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use
107
-
Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API,
108
-
tasks API, and a notifications API.
134
+
```bash
135
+
/speckit.plan We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, tasks API, and a notifications API.
109
136
```
110
137
111
-
### Step 5: Validate and Implement
138
+
### Step 6: Validate and Implement
112
139
113
-
Have your AI agent audit the implementation plan:
140
+
Have your AI agent audit the implementation plan using `/speckit.analyze`:
114
141
115
-
```text
116
-
Now I want you to go and audit the implementation plan and the implementation detail files.
117
-
Read through it with an eye on determining whether or not there is a sequence of tasks that you need
118
-
to be doing that are obvious from reading this. Because I don't know if there's enough here.
0 commit comments