Skip to content

Conversation

anchildress1
Copy link

This PR was generated using both GitHub Copilot and ChatGPT. Attribution is defined in each commit according standards defined in this blog post.

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:

  • Added a new 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.
  • Updated 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:

  • Greatly expanded the methodology documentation in 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:

  • Updated the documentation table of contents (toc.yml) to include the new Existing Project Guide, improving discoverability and navigation between guides for different workflows.

User guidance and troubleshooting:

  • Added troubleshooting sections and next steps to both guides, helping users resolve common issues and find further resources. [1] [2]

References: [1] [2] [3] [4] [5] [6] [7] [8] [9] [10]

anchildress1 and others added 3 commits October 16, 2025 04:33
- 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>
@Copilot Copilot AI review requested due to automatic review settings October 18, 2025 01:44
Copy link
Contributor

@Copilot Copilot AI left a 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>
@Copilot Copilot AI review requested due to automatic review settings October 18, 2025 02:00
Copy link
Contributor

@Copilot Copilot AI left a 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>
@localden
Copy link
Collaborator

@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 localden added merge-candidate Reasonable change that is going to be merged after a review. documentation Improvements or additions to documentation labels Oct 19, 2025
@localden localden self-assigned this Oct 19, 2025
@Copilot Copilot AI review requested due to automatic review settings October 19, 2025 17:57
- 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>
Copy link
Contributor

@Copilot Copilot AI left a 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>
@anchildress1
Copy link
Author

Hey @localden — hope you don't mind, Copilot was driving me insane so I added in a .github/copilot-instructions.md file that should redirect it to the existing ./AGENTS.md plus a new ./docs/AGENTS.md with a couple highlights specific to the published docs. Hopefully that's enough to calm my friend down a bit over here. 🤣🤞

 - 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>
@Copilot Copilot AI review requested due to automatic review settings October 19, 2025 21:56
Copy link
Contributor

@Copilot Copilot AI left a 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.

@localden
Copy link
Collaborator

@anchildress1 there actually isn't a need for copilot-instructions.md since Copilot (VS Code and the CLI) both respect AGENTS.md as-is.

@anchildress1
Copy link
Author

@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 AGENTS.md. The relative links to AGENTS.md should allow those files to be loaded into context within GitHub and it can easily be deleted without affecting anything after support for is enabled for reviews.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation merge-candidate Reasonable change that is going to be merged after a review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants