docs: add existing project adoption guide - #4263
Merged
Merged
Conversation
Add a safe brownfield onboarding path and connect it to the docs homepage, quick start, navigation, and spec maintenance guidance. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 663b4e07-d79f-4bd1-aa86-8aeea21a2643
mnriem
force-pushed
the
mnriem-docs-site-improvement
branch
from
August 21, 2026 19:11
9aa385e to
d0730ec
Compare
mnriem
requested
a balanced review from Copilot
and removed request for
Copilot
August 21, 2026 19:12
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a brownfield adoption guide for safely introducing Spec Kit into existing codebases.
Changes:
- Documents initialization, guardrails, bounded changes, workflow planning, and spec persistence.
- Adds navigation links across primary documentation entry points.
- Connects adoption guidance with existing maintenance and community resources.
Show a summary per file
| File | Description |
|---|---|
docs/guides/existing-projects.md |
Adds the adoption guide. |
docs/guides/evolving-specs.md |
Links pre-adoption readers to the new guide. |
docs/index.md |
Adds a homepage navigation card. |
docs/quickstart.md |
Directs existing-project users to tailored guidance. |
docs/toc.yml |
Adds the guide to the documentation navigation. |
Review details
馃挕 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Files reviewed: 5/5 changed files
- Comments generated: 0
- Review effort level: Balanced
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Description
Add a focused onboarding guide for adopting Spec Kit in an existing codebase. The guide covers safe in-place initialization, evidence-based project guardrails, choosing a bounded first change, planning against existing architecture, and selecting a spec persistence model.
The new page is linked from the docs homepage, table of contents, Quick Start, and evolving-specs guide. This addresses the brownfield documentation portion of #1173 without closing the issue's separate custom-agent request.
Testing
Documentation-only change.
uv run specify --help(not applicable)uv sync && uv run pytest(not applicable)AI Disclosure
This PR was authored autonomously by GitHub Copilot (GPT-5.6 Sol) on behalf of @mnriem. Copilot assessed the documentation gap, wrote the guide and navigation updates, and performed the documented validation.