- Notifications
You must be signed in to change notification settings - Fork4.9k
docs: Add missing prompt commands + existing project walkthrough#937
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
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 docsGenerated-by: ChatGPT <chatgpt@openai.com>Co-authored-by: GitHub Copilot <github.copilot@github.com>Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
- 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 workflowsGenerated-by: GitHub Copilot <github.copilot@github.com>Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
- 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 <github.copilot@github.com>Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 orlearn how to get started.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
- Replace non-standard hyphens in title, workspace sentence, and troubleshooting table - Improve consistency with repository docsAssisted-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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 orlearn how to get started.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
- 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 <github.copilot@github.com>Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
localden commentedOct 19, 2025
@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". |
- 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 <github.copilot@github.com>Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 orlearn how to get started.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
- 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 conventionsCo-authored-by: GitHub Copilot <github.copilot@github.com>Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
anchildress1 commentedOct 19, 2025
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-guideCo-authored-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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 orlearn how to get started.
Uh oh!
There was an error while loading.Please reload this page.
localden commentedOct 21, 2025
@anchildress1 there actually isn't a need for |
anchildress1 commentedOct 22, 2025
@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. |
aurexav commentedOct 25, 2025
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. |
anchildress1 commentedOct 25, 2025
@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? Becausethis functionality, from GitHub.com PR triggers(like if I were to click the below button to request a re-review) isnot 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 |
anchildress1 commentedOct 31, 2025
…-guide and upgrade in docs toc
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 |
CopilotAINov 16, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
[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. |
CopilotAINov 16, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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) |
CopilotAINov 16, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.).
| #Step2: Clarify ambiguities (5 minutes) | |
| /speckit.clarify | |
| #Asks: "What latency defines 'real-time'?", "How long should message history persist?" | |
| #Updates: spec.md with clarification section | |
| #Step3: Validate requirement quality (5 minutes) | |
| /speckit.checklist security | |
| /speckit.checklist api | |
| #Generates: checklists/security.md, checklists/api.md | |
| #Tests: requirement clarity, completeness, measurability | |
| #Step4: Generate implementation plan (5 minutes) | |
| /speckit.plan | |
| #Creates: plan.md with WebSocket architecture, PostgreSQL schema, Redis caching strategy | |
| #Step5: Generate executable tasks (5 minutes) | |
| #Step3: Clarify ambiguities (5 minutes) | |
| /speckit.clarify | |
| #Asks: "What latency defines 'real-time'?", "How long should message history persist?" | |
| #Updates: spec.md with clarification section | |
| #Step4: Validate requirement quality (5 minutes) | |
| /speckit.checklist security | |
| /speckit.checklist api | |
| #Generates: checklists/security.md, checklists/api.md | |
| #Tests: requirement clarity, completeness, measurability | |
| #Step5: Generate implementation plan (5 minutes) | |
| /speckit.plan | |
| #Creates: plan.md with WebSocket architecture, PostgreSQL schema, Redis caching strategy | |
| #Step6: 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 messagehistory and user presence |
CopilotAINov 16, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
[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 |
docs/AGENTS.md Outdated
| - 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. |
CopilotAINov 16, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 (—).
adedb99 tob458ccfCompare- The copilot-instructions file must be used for code reviews- I do not want to hold up doc updates for instruction changes- Will copy these suggestions to a separate PRFixesgithub#906,github#472Authored-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
anchildress1 commentedDec 11, 2025
Hey@localden I'm hoping that taking the copilot-specific changes back out of this branch will get it out of this holding pattern 🤞🏻 Since nobody has objected to making the code review feature pick up |
anchildress1 commentedDec 11, 2025
Instructions moved to#1321 |
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]