docs: update quickstart.md #1238
Conversation
- 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 github#906, github#472 Generated-by: GitHub Copilot <github.copilot@github.com> Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This pull request improves the quickstart documentation by expanding the workflow from 4 to 6 steps, introducing new slash commands, and providing clearer guidance for new users. The changes emphasize context awareness, provide explicit examples for each step, and improve the overall structure and navigability of the guide.
Key Changes:
- Expanded the process from 4 steps to 6 steps, adding constitution definition, specification clarification, and checklist validation as separate steps
- Introduced new slash commands (
/speckit.constitution,/speckit.clarify,/speckit.checklist,/speckit.analyze,/speckit.implement) with clear usage examples - Enhanced the detailed example with the new 6-step workflow and improved clarity about where each command should be executed
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```text | ||
| implement specs/002-create-taskify/plan.md | ||
| ```bash |
There was a problem hiding this comment.
The code block is marked as bash but contains a slash command that should be used in the chat interface. Change the language identifier from bash to markdown to be consistent with the pattern used in other steps (lines 36, 44, 60, 68, 74, 80).
| ```bash | |
| ```markdown |
| Use the `/speckit.plan` command to provide your tech stack and architecture choices. | ||
| **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. | ||
|
|
||
| ```bash |
There was a problem hiding this comment.
The code block is marked as bash but contains a slash command that should be used in the chat interface (not terminal). Change the language identifier from bash to markdown to match the pattern used in other steps (lines 36, 44, 60, 68, 74, 80).
| ```bash | |
| ```markdown |
| ```bash | ||
| /speckit.clarify I want to clarify the task card details. For each task in the UI for a task card, you should be able to change the current status of the task between the different columns in 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. | ||
| ``` | ||
| Also validate the specification checklist: | ||
| You can continue to refine the spec with more details using `/speckit.clarify`: | ||
| ```text | ||
| 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. | ||
| ```bash | ||
| /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. | ||
| ``` |
There was a problem hiding this comment.
The code block is marked as bash but contains slash commands that should be used in the chat interface. Change the language identifier from bash to markdown to be consistent with other steps (lines 36, 44, 60, 68, 74, 80).
| Validate the specification checklist using the `/speckit.checklist` command: | ||
| ```bash |
There was a problem hiding this comment.
The code block is marked as bash but contains a slash command that should be used in the chat interface. Change the language identifier from bash to markdown to be consistent with the pattern used in other steps (lines 36, 44, 60, 68, 74, 80).
| ```bash | |
| ```markdown |
| 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. | ||
| ```bash |
There was a problem hiding this comment.
The code block is marked as bash but contains a slash command that should be used in the chat interface. Change the language identifier from bash to markdown to be consistent with the pattern used in other steps (lines 36, 44, 60, 68, 74, 80).
| ```bash | |
| ```markdown |
| Now I want you to go and audit the implementation plan and the implementation detail files. | ||
| Read through it with an eye on determining whether or not there is a sequence of tasks that you need | ||
| to be doing that are obvious from reading this. Because I don't know if there's enough here. | ||
| ```bash |
There was a problem hiding this comment.
The code block is marked as bash but contains a slash command that should be used in the chat interface. Change the language identifier from bash to markdown to be consistent with the pattern used in other steps (lines 36, 44, 60, 68, 74, 80).
| ```bash | |
| ```markdown |
| I want five users in two different categories, one product manager and four engineers. Let's create three | ||
| different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do," | ||
| "In Progress," "In Review," and "Done." There will be no login for this application as this is just the very | ||
| first testing thing to ensure that our basic features are set up. For each task in the UI for a task card, |
There was a problem hiding this comment.
I really didn't remove as much as it seems here, I reorganized and repurposed what was here to populate the missing /clarify text. 😇
2 participants
This pull request updates the
docs/quickstart.mdguide to make it clearer and more actionable for new users. The most important changes are a reorganization of the workflow from a 4-step to a 6-step process, introduction of new slash commands, and improved contextual guidance. The documentation now emphasizes context awareness, provides explicit instructions for both Bash and PowerShell automation scripts, and includes example usages for each step.Workflow and Process Improvements:
/speckit.constitution,/speckit.clarify,/speckit.checklist,/speckit.analyze,/speckit.implement) and updated examples for each step, making the process more interactive and modular. [1] [2]Context and Guidance Enhancements:
Documentation Quality and Navigation:
Copilot helped generate these changes as noted in commit attribution.