docs: Add new docs page covering upgrade for Specify CLI #1135
+442
−3
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add upgrading-spec-kit.md with detailed upgrade instructions and troubleshooting - Update table of contents to include upgrading guide in Getting Started section - Update documentation index and README links - Address user questions about updating initialized projects from GitHub discussions Co-authored-by: GitHub Copilot <github.copilot@github.com> Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
- Remove link to non-existent existing project guide from README Commit-generated-by: GitHub Copilot <github.copilot@github.com> Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
- Remove outdated links section from docs/upgrading-spec-kit.md - Remove outdated section from README and docs/index Commit-generated-by: GitHub Copilot <github.copilot@github.com> Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
- Rename docs/upgrading-spec-kit.md to docs/upgrade.md for brevity - Update README and documentation index links to point to new upgrade guide - Update table of contents to use shorter "Upgrade" title - Simplify section headers in upgrade guide - Add Getting Started section back to docs/index.md with upgrade guide link Commit-generated-by: GitHub Copilot <github.copilot@github.com> Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR adds a comprehensive upgrade guide for Spec Kit and makes minor documentation improvements. The guide helps users understand how to upgrade both the CLI tool and project files while preserving their customizations.
- New upgrade guide covering CLI and project file updates with detailed scenarios and troubleshooting
- Updated README with link to upgrade guide and corrected constitution file path
- Added upgrade guide to documentation table of contents
Reviewed Changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/upgrade.md | Comprehensive new upgrade guide with CLI and project update instructions, common scenarios, and troubleshooting |
| docs/toc.yml | Added upgrade guide entry to documentation navigation |
| docs/index.md | Added upgrade guide link to main documentation index |
| README.md | Updated upgrade text with link to detailed guide, fixed constitution path reference, and removed trailing space |
| .gitignore | Added *.tmp pattern to ignore temporary files |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/upgrade.md
Outdated
| specify init --here --force --ai <your-agent> | ||
| ``` | ||
|
|
||
| Replace `<your-agent>` with your AI assistant: `claude`, `gemini`, `copilot`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `auggie`, `codebuddy`, `roo`, `kilocode`, or `q`. |
There was a problem hiding this comment.
The list of supported AI agents is duplicated in multiple places in the documentation. Consider maintaining this list in a single location and referencing it to avoid inconsistencies when agents are added or removed.
README.md
Outdated
|
|
||
| >[!NOTE] | ||
| >Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan. | ||
| >Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan. |
There was a problem hiding this comment.
The constitution file path should be .specify/memory/constitution.md for consistency with the rest of the documentation and the actual file structure. The path memory/constitution.md may work as a relative link from the repository root but is inconsistent with references elsewhere (e.g., line 383, 424, 485 in README.md and throughout upgrade.md).
Suggested change
| >Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan. | |
| >Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](.specify/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan. |
- Fix broken constitution.md link in detailed process section - Add reference to supported AI agents list in upgrade guide Commit-generated-by: GitHub Copilot <github.copilot@github.com> Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds documentation to cover concerns discussed in #879
Generated with GitHub Copilot. Attribution in commit history.
This pull request updates documentation to improve clarity and navigation around upgrading Specify, and fixes a broken link. The most important changes include updating upgrade instructions, adding an Upgrade Guide to the documentation, and correcting a reference to the constitution file.
Upgrade documentation improvements:
README.mdto direct users to a new, dedicated Upgrade Guide instead of providing inline instructions.docs/index.mdanddocs/toc.yml, making it easier for users to find upgrade information. [1] [2]Documentation link fixes:
README.mdfrombase/memory/constitution.mdtomemory/constitution.mdto resolve a broken reference.