💫 Toolkit to help you get started with SDD or any other process!
docs: document evolving specs in existing projects (#2902)
WOLIKIMCHENG75df458c3742
diff --git a/README.md b/README.mdindex 0a0b4119b..ae651a2b1 100644--- a/README.md+++ b/README.md@@ -254,6 +254,12 @@ Spec-Driven Development is a structured process that emphasizes:| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> || **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |+For existing projects, keep Spec Kit tooling updates separate from feature+artifact evolution: refresh managed project files when upgrading, and update+`specs/` artifacts when intended behavior changes. The+[Evolving Specs guide](./docs/guides/evolving-specs.md) describes the+recommended brownfield loop.+## 🎯 Experimental GoalsOur research and experimentation focus on:diff --git a/docs/concepts/sdd.md b/docs/concepts/sdd.mdindex c5b6d5542..fe6052c0e 100644--- a/docs/concepts/sdd.md+++ b/docs/concepts/sdd.md@@ -13,8 +13,9 @@ Spec-Driven Development is a structured process that emphasizes:Spec Kit does not prescribe how teams preserve or mutate `spec.md`, `plan.md`,and `tasks.md` after requirements change. See-[Spec Persistence Models](spec-persistence.md) for three common ways to manage-those artifacts over time.+[Spec Persistence Models](spec-persistence.md) for the concepts and+[Evolving Specs in Existing Projects](../guides/evolving-specs.md) for the+existing-project evolution workflows.## Development Phasesdiff --git a/docs/docfx.json b/docs/docfx.jsonindex 62869e1d8..e22b394ba 100644--- a/docs/docfx.json+++ b/docs/docfx.json@@ -7,6 +7,7 @@"toc.yml","community/*.md","concepts/*.md",+ "guides/*.md","reference/*.md","install/*.md"]@@ -78,4 +79,3 @@}}}-diff --git a/docs/guides/evolving-specs.md b/docs/guides/evolving-specs.mdnew file mode 100644index 000000000..feb2c8870--- /dev/null+++ b/docs/guides/evolving-specs.md@@ -0,0 +1,90 @@+# Evolving Specs in Existing Projects++Existing projects need two separate maintenance loops:++- **Spec Kit project-file updates** refresh managed commands, scripts,+ templates, and shared memory files.+- **Feature artifact evolution** keeps repository-specific `specs/` artifacts+ aligned with the code and product behavior you intend to ship.++Use the [upgrade workflow](../upgrade.md) when you need newer Spec Kit project+files. Use one of the artifact persistence models below when requirements or+implementation insights change an existing project.++For the conceptual model definitions, see+[Spec Persistence Models](../concepts/spec-persistence.md).++## Flow-Forward Spec++Use flow-forward when each feature directory should remain a historical record.++When you add another feature or make a substantial follow-up change, create a+new feature spec through your installed `/speckit.specify` command and continue+through the standard flow:++1. Run `/speckit.specify` to create a new feature directory under `specs/`.+2. Run `/speckit.plan` to define the implementation approach.+3. Run `/speckit.tasks` to derive the work breakdown.+4. Run `/speckit.implement` and review the resulting code and artifact diffs.++The previous feature directory remains intact for audit, comparison, or+explaining how the project reached its current state. Use clear feature names or+cross-links when a new directory supersedes or extends earlier work.++## Living Spec++Use living spec when `spec.md` is the contract and `plan.md` and `tasks.md` are+derived from it.++When intended behavior changes, revise the existing `spec.md` first. Then+regenerate or manually revise downstream artifacts so they match the updated+spec:++1. Start from a clean working tree or a dedicated branch so every generated+ change is reviewable.+2. Update `spec.md` with `/speckit.clarify` or an explicit edit.+3. Rerun `/speckit.plan` or revise `plan.md` so the technical approach matches+ the revised spec.+4. Rerun `/speckit.tasks` or revise `tasks.md` so implementation work matches+ the revised plan.+5. Run `/speckit.analyze` before implementation resumes to catch gaps between+ the spec, plan, and tasks.+6. Run `/speckit.implement`, then review the code and artifact diffs together.++Preserve important implementation rationale before replacing derived artifacts.+If a plan or task list contains decisions that still matter, carry them forward+explicitly.++## Flow-Back Spec++Use flow-back when implementation discoveries are allowed to reshape the+artifact set.++In this model, the first useful edit can happen wherever the insight lands:+`spec.md`, `plan.md`, `tasks.md`, or the implementation. After the change, bring+the artifact set back into alignment:++1. Capture the discovery in the artifact closest to the work.+2. Decide whether it changes intended behavior, implementation strategy, task+ breakdown, or only code.+3. Update any other artifacts that now disagree with the accepted direction.+4. Run `/speckit.analyze` to check for gaps across `spec.md`, `plan.md`, and+ `tasks.md`.+5. Continue implementation only after the artifact set describes the behavior+ and approach you want future contributors to trust.++Flow-back is flexible, but it requires discipline. Do not leave a lower-level+change in `tasks.md` or code if `spec.md` still says something different and the+spec is meant to remain trustworthy.++## Before Updating Spec Kit Project Files++Before refreshing Spec Kit project files with the terminal command+`specify init --here --force --integration <your-agent>`, protect any+project-specific material that lives outside `specs/`, especially+`.specify/memory/constitution.md` and customized files under+`.specify/templates/` or `.specify/scripts/`. Use `<your-agent>` for the AI+coding agent integration used by the target project.++Your `specs/` directory is not part of the template package, but shared project+files can be overwritten by a forced refresh.diff --git a/docs/toc.yml b/docs/toc.ymlindex 250120612..aba93ab43 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -51,6 +51,8 @@items:- name: Local Developmenthref: local-development.md+ - name: Evolving Specs+ href: guides/evolving-specs.md# Community- name: Community