-
Notifications
You must be signed in to change notification settings - Fork 3.5k
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 our terms of service and privacy 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 docs Generated-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 workflows Generated-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 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 <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 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 <github.copilot@github.com> Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
@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 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 <github.copilot@github.com> Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
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 <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 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. |
This addresses in part these issues: #472, #458, #472
I added a new
Existing Project Guide
that 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.md
with 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.md
to 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.md
to 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]