docs: Add missing prompt commands + existing project walkthrough #937
Conversation
- Add comprehensive guide for integrating Spec-Kit into existing codebases - Include step-by-step workflow from installation to implementation - Update documentation table of contents to include new guide - Provide troubleshooting section and cross-references to other docs Generated-by: ChatGPT <[email protected]> Co-authored-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
- Add step-by-step explanations for each phase of the workflow - Include constitution step in detailed example for complete process - Add cross-references to related documentation guides - Improve navigation between new project and existing project workflows Generated-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
- Add detailed usage, inputs, and examples for the /speckit command suite. - Improve example workflow and timing estimates to reflect added commands. - Clarify expected outputs and propagation behavior to templates and memory. - Minor editorial and formatting fixes in spec-driven.md. Generated-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation improvements to make Spec-Kit more accessible for both new and existing projects, expanding the command reference and establishing clearer user workflows.
- Enhanced documentation with detailed command descriptions, usage examples, and expected inputs/outputs
- Added a new Existing Project Guide for integrating Spec-Kit into established codebases
- Separated workflows between new projects (quickstart) and existing projects with distinct guides
Reviewed Changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/existing-project-guide.md | New comprehensive guide for adding Spec-Kit to existing projects with step-by-step workflow |
| docs/quickstart.md | Updated to focus on new projects, added constitution step, enhanced examples and next steps |
| docs/toc.yml | Added navigation entry for the new Existing Project Guide |
| spec-driven.md | Greatly expanded command documentation with detailed descriptions, benefits, usage examples, and expected inputs for all major commands |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
- Replace non-standard hyphens in title, workspace sentence, and troubleshooting table - Improve consistency with repository docs Assisted-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 10 comments.
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
- Replace non-breaking hyphens with standard hyphens in `docs/existing-project-guide.md`. - Fix spacing and punctuation for the "10-minute guide" phrasing. - Keep changes minimal and localized to documentation style. Assisted-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
|
@anchildress1 I like the direction of this, thank you for the contribution. Let's make sure that references to "Spec-Kit" are replaced with "Spec Kit". |
localden
added
merge-candidate
- Normalize product name to 'Spec Kit' in `CONTRIBUTING.md` and `docs/existing-project-guide.md`. - Fix minor formatting: blockquote spacing, list indentation, and trailing newline. Commit-generated-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
- Add a minimal Copilot Code Review instruction that references existing `AGENTS.md` files - Add `docs/AGENTS.md` for docs-specific agent guidance (tone, capitalization, argument formats) - The `copilot-instructions.md` file is designed to support auto-Copilot Code Reviews in GitHub - Existing `AGENTS.md` files remain unchanged and the authoritative source for project conventions Co-authored-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
|
Hey @localden — hope you don't mind, Copilot was driving me insane so I added in a |
- Correct timing for spec-driven development eliminating confusion - Minor wording improvements for clarity in existing-project-guide Co-authored-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
|
@anchildress1 there actually isn't a need for |
|
@localden I added it for the automated code reviews that trigger Copilot once a PR is opened, which is one place that does not yet support If it would help, I can add an explicit comment there to indicate its overall purpose. I left it out originally since Copilot reads the entire file into context. So comment or not that directive would still be considered by the agent. For what it is though, it's not likely to have a significant impact anyway. So, your call. |
Agreed — bringing in a third party would just add overhead. Copilot should take care of this on its own, so we can keep the spec-kit simple. |
|
@aurexav I'm not sure what you mean by "bringing in a third party".... or was I mistaken when I saw Copilot already set up to automatically review PRs when opened in this repo? I suppose it's possible it came from my end of user settings, but I still thought it was based on the repo itself whether or not to execute that action. I do know there's 31 very confusing and some outright incorrect comments from Copilot posted in this one PR. I have no problem pulling the file back out if you and @localden can confirm that's the desired behavior? Because this functionality, from GitHub.com PR triggers(like if I were to click the below button to request a re-review) is not considering 
... although, I wonder if it would limit itself if it just had a simple constraint that says only use this file when actively reviewing a PR? Because, if |
…-guide and upgrade in docs toc
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /speckit.implement 001-checkout-apply-coupon --dry-run # optional: shows planned changes without executing | ||
| /speckit.implement 001-checkout-apply-coupon # execute the implementation |
There was a problem hiding this comment.
[nitpick] Inconsistent command syntax: The implement command shows --dry-run as a flag option, but this doesn't match the established pattern where other commands in the documentation use natural language after the command. For consistency with other commands like /speckit.specify and /speckit.plan, consider documenting this as /speckit.implement 001-checkout-apply-coupon (show changes without executing) or similar natural language, unless the command actually accepts CLI-style flags.
| /speckit.implement 001-checkout-apply-coupon --dry-run # optional: shows planned changes without executing | |
| /speckit.implement 001-checkout-apply-coupon # execute the implementation | |
| /speckit.implement 001-checkout-apply-coupon (show changes without executing) # optional: shows planned changes without executing | |
| /speckit.implement 001-checkout-apply-coupon # execute the implementation |
|
|
||
| This breaks down your plan into a step-by-step checklist of individual coding tasks. | ||
|
|
||
| **Taskify** once your plan feels right. |
There was a problem hiding this comment.
Spelling error: "Taskify" should be "Generate tasks" or similar. In the context of this documentation, "Taskify" appears to be used as a verb meaning "to create tasks," but this is non-standard usage and may confuse readers. Consider using "Generate tasks" or "Create tasks" instead.
| **Taskify** once your plan feels right. | |
| **Generate tasks** once your plan feels right. |
| # Step 2: Clarify ambiguities (5 minutes) | ||
| /speckit.clarify | ||
| # Asks: "What latency defines 'real-time'?", "How long should message history persist?" | ||
| # Updates: spec.md with clarification section | ||
|
|
||
| # Step 3: Validate requirement quality (5 minutes) | ||
| /speckit.checklist security | ||
| /speckit.checklist api | ||
| # Generates: checklists/security.md, checklists/api.md | ||
| # Tests: requirement clarity, completeness, measurability | ||
|
|
||
| # Step 4: Generate implementation plan (5 minutes) | ||
| /speckit.plan | ||
| # Creates: plan.md with WebSocket architecture, PostgreSQL schema, Redis caching strategy | ||
|
|
||
| # Step 5: Generate executable tasks (5 minutes) |
There was a problem hiding this comment.
Documentation inconsistency: The step numbering shows "Step 2" appearing twice in the example workflow. Line 367 introduces "Step 2: Generate implementation plan" but line 369 also shows "Step 2: Clarify ambiguities". The subsequent steps should be renumbered accordingly (Step 3 for clarify, Step 4 for checklist, etc.).
| # Step 2: Clarify ambiguities (5 minutes) | |
| /speckit.clarify | |
| # Asks: "What latency defines 'real-time'?", "How long should message history persist?" | |
| # Updates: spec.md with clarification section | |
| # Step 3: Validate requirement quality (5 minutes) | |
| /speckit.checklist security | |
| /speckit.checklist api | |
| # Generates: checklists/security.md, checklists/api.md | |
| # Tests: requirement clarity, completeness, measurability | |
| # Step 4: Generate implementation plan (5 minutes) | |
| /speckit.plan | |
| # Creates: plan.md with WebSocket architecture, PostgreSQL schema, Redis caching strategy | |
| # Step 5: Generate executable tasks (5 minutes) | |
| # Step 3: Clarify ambiguities (5 minutes) | |
| /speckit.clarify | |
| # Asks: "What latency defines 'real-time'?", "How long should message history persist?" | |
| # Updates: spec.md with clarification section | |
| # Step 4: Validate requirement quality (5 minutes) | |
| /speckit.checklist security | |
| /speckit.checklist api | |
| # Generates: checklists/security.md, checklists/api.md | |
| # Tests: requirement clarity, completeness, measurability | |
| # Step 5: Generate implementation plan (5 minutes) | |
| /speckit.plan | |
| # Creates: plan.md with WebSocket architecture, PostgreSQL schema, Redis caching strategy | |
| # Step 6: Generate executable tasks (5 minutes) |
| Simplicity gate: max 3 projects per feature | ||
|
|
||
| # Step 1: Create the feature specification (5 minutes) | ||
| /speckit.specify Real-time chat system with message history and user presence |
There was a problem hiding this comment.
[nitpick] Inconsistent command example format: Line 359 shows the /speckit.specify command followed by a feature description on the same line without a line break, while other command examples in the same section (like lines 370-372, 375-378, 381-382) show commands on one line followed by explanatory comments on subsequent lines. This inconsistency may confuse users about the proper command format.
| /speckit.specify Real-time chat system with message history and user presence | |
| /speckit.specify | |
| # Real-time chat system with message history and user presence |
| - The correct syntax for this project is "Spec Kit" (two words, capital S and K). Never use any other variation outside of code snippets. | ||
| - Use active voice and present tense where possible. | ||
| - Write for an audience familiar with AI and programming concepts, but new to Spec Kit. | ||
| - Ensure an informal narrative, teaching voice: give a one-line "why" plus a one-line "how" and a minimal, copy‑pastable example/command when helpful. |
There was a problem hiding this comment.
Inconsistent punctuation: Line 8 contains an en dash (–) instead of a standard hyphen or em dash. For consistency with standard markdown conventions, consider using either a hyphen (-) or an em dash (—).
Merge upstream/main changes into fork main; includes upstream v0.0.85 changes and documentation updates.
…t Guide and Upgrade
…ate-user-guide-docs
3 participants
This addresses in part these issues: #472, #458, #472
I added a new
Existing Project Guidethat is originally written by ChatGPT, but later iterated with Copilot for a broader audience and more generic examples. I have a few more docs in mind for future PRs, Including a more detailed walkthrough, diagrams, and contributor flows. If there's anything else you can think of lmk!Copilot's Summary
This pull request introduces comprehensive improvements to the Spec-Kit documentation and methodology, making it easier for users to adopt Spec-Driven Development in both new and existing projects. The changes include a new guide for integrating Spec-Kit into existing codebases, clearer separation of workflows for new and existing projects, expanded documentation for all major commands, and enhanced navigation in the docs.
Documentation additions and workflow separation:
existing-project-guide.mdwith a step-by-step, rollback-friendly process for integrating Spec-Kit into existing repositories. This guide details initialization, constitution setup, specification, planning, task breakdown, analysis, implementation, commit strategy, troubleshooting, and next steps.quickstart.mdto clarify its focus on new projects, added references to the new existing project guide, and expanded each step with more actionable instructions and example usage. [1] [2] [3] [4] [5] [6]Expanded command documentation:
spec-driven.mdto provide detailed explanations, expected inputs, minimal usage examples, and core values for all major Spec-Kit commands (/speckit.constitution,/speckit.specify,/speckit.clarify,/speckit.checklist,/speckit.plan,/speckit.tasks,/speckit.analyze,/speckit.implement). This makes it easier for users to understand the purpose and workflow of each command. [1] [2]Navigation and organization:
toc.yml) to include the new Existing Project Guide, improving discoverability and navigation between guides for different workflows.User guidance and troubleshooting:
References: [1] [2] [3] [4] [5] [6] [7] [8] [9] [10]