💫 Toolkit to help you get started with SDD or any other process!
docs: add existing project adoption guide (#4263)
Manfred Riem214e5104b641
diff --git a/docs/guides/evolving-specs.md b/docs/guides/evolving-specs.mdindex e2941f08b..17a91298e 100644--- a/docs/guides/evolving-specs.md+++ b/docs/guides/evolving-specs.md@@ -1,5 +1,9 @@# Evolving Specs in Existing Projects+If the repository has not been initialized with Spec Kit yet, start with+[Adopting Spec Kit in an Existing Project](existing-projects.md). This page+covers how to maintain artifacts after adoption.+Existing projects need two separate maintenance loops:- **Spec Kit project-file updates** refresh managed commands, scripts,diff --git a/docs/guides/existing-projects.md b/docs/guides/existing-projects.mdnew file mode 100644index 000000000..479715546--- /dev/null+++ b/docs/guides/existing-projects.md@@ -0,0 +1,106 @@+# Adopting Spec Kit in an Existing Project++You do not need to recreate an existing system from specifications before using+Spec Kit. Initialize the repository in place, capture the rules that matter,+and use the workflow for the next bounded change.++## 1. Start from a Reviewable Baseline++Before initialization, commit or stash existing work and create a branch for the+adoption. This makes every generated file visible in a normal code review.++Choose the [integration key](../reference/integrations.md) for the coding agent+you use. Then run the command from the repository root:++```bash+specify init --here --force --integration <key>+```++`--here` targets the current directory. `--force` allows initialization in a+non-empty directory and may replace files at conflicting managed paths, so use+it only after creating a reviewable baseline. It does not delete the rest of+your application.++Review the resulting diff before continuing. Initialization adds the shared+`.specify/` project files and the command or skill files required by your+selected integration. It does not rewrite your application or infer+specifications for existing behavior.++> [!NOTE]+> Git initialization and feature branches are optional and are managed by the+> **git** extension. Add it with `specify extension add git` if you want that+> workflow.++## 2. Capture Project Guardrails++Run `/speckit.constitution` with principles that are already true for the+repository or that the team has explicitly agreed to adopt:++```text+/speckit.constitution Preserve public API compatibility. Follow the existing+service boundaries. Every database migration must include a rollback plan.+Run the repository's established unit and integration test suites.+```++Use the repository's README, architecture decisions, contribution guide, and+CI configuration as evidence. Do not invent standards merely to fill the+constitution template. The constitution governs later planning and analysis,+so unrealistic rules create noise instead of useful constraints.++## 3. Choose a Bounded First Change++Start with a feature, bug fix, or modernization slice that can be reviewed+independently. Do not make "document the entire existing system" your first+feature unless that inventory is itself the intended deliverable.++Describe both the requested outcome and the compatibility boundaries that must+remain intact:++```text+/speckit.specify Add CSV export to the existing orders page. Preserve current+filters and authorization behavior. Export only the rows visible to the signed-in+user, and do not change the existing JSON API response.+```++The codebase remains implementation context. The new `spec.md` defines the+change you intend to make, not a retroactive specification of every existing+behavior.++## 4. Plan Against the Repository++Continue through the normal workflow:++1. Run `/speckit.clarify` to resolve uncertain behavior and compatibility+ requirements.+2. Run `/speckit.plan` and verify that the proposed design reuses the existing+ architecture, dependencies, and test conventions.+3. Run `/speckit.tasks`, then `/speckit.analyze` to check consistency before+ implementation.+4. Run `/speckit.implement` and review code and artifact changes together.+5. Run `/speckit.converge` to find remaining gaps. If it adds tasks, repeat+ implementation and convergence until the feature is complete.++For command details and optional quality gates, see the+[Quick Start Guide](../quickstart.md) and+[Agentic SDD reference](../reference/agentic-sdd.md).++## 5. Decide How Specs Will Age++After the first change, agree on how the team will maintain completed feature+artifacts:++- Keep each feature directory as an immutable historical record.+- Maintain `spec.md` as a living contract and regenerate downstream artifacts.+- Allow discoveries to flow back from code, tasks, or plans, then reconcile the+ full artifact set.++The [Spec Persistence Models](../concepts/spec-persistence.md) page compares+these choices. The [Evolving Specs guide](evolving-specs.md) provides the+maintenance loop for each model.++## Existing-Project Examples++The [community walkthroughs](../community/walkthroughs.md) include brownfield+examples across .NET, Java, and Go/React codebases. Community extensions for+architecture discovery and brownfield bootstrapping are listed in the+[extension catalog](../community/extensions.md).diff --git a/docs/index.md b/docs/index.mdindex d1007aed8..5e8b25f86 100644--- a/docs/index.md+++ b/docs/index.md@@ -124,6 +124,10 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a<strong>Getting Started</strong><span>Install, configure, and run your first SDD workflow</span></a>+ <a href="guides/existing-projects.md" class="nav-card">+ <strong>Existing Projects</strong>+ <span>Adopt Spec Kit safely in an established codebase</span>+ </a><a href="reference/overview.md" class="nav-card"><strong>Reference</strong><span>Core commands, integrations, extensions, presets, and workflows</span>diff --git a/docs/quickstart.md b/docs/quickstart.mdindex 2813118b5..fb2ecc2f7 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -47,6 +47,9 @@ specify init taskify # or: specify init . to use the current directory> [!NOTE]> Prefer `pipx`, one-time `uvx` runs, a pinned release, or an offline/air-gapped setup? See the [Installation Guide](installation.md) for all supported methods.+> Adding Spec Kit to a repository that already contains code? Follow+> [Adopting Spec Kit in an Existing Project](guides/existing-projects.md) before+> starting the workflow below.### Step 1: `/speckit.constitution` — set the ground rulesdiff --git a/docs/toc.yml b/docs/toc.ymlindex d6996640d..7548ba95f 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -15,6 +15,8 @@href: installation.md- name: Quick Starthref: quickstart.md+ - name: Existing Projects+ href: guides/existing-projects.md- name: Upgradehref: upgrade.md- name: Install uv