Skip to content

💫 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.md
index 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.md
new file mode 100644
index 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.md
index 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.md
index 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 rules
diff --git a/docs/toc.yml b/docs/toc.yml
index d6996640d..7548ba95f 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -15,6 +15,8 @@
href: installation.md
- name: Quick Start
href: quickstart.md
+ - name: Existing Projects
+ href: guides/existing-projects.md
- name: Upgrade
href: upgrade.md
- name: Install uv