docs: document evolving specs in existing projects (#2902)

* docs: document evolving specs in existing projects

* docs: reframe evolving specs guide around persistence models

* docs: address evolving specs guide feedback

* docs: address evolving specs review feedback

* docs: require explicit integration in evolving specs update command

---------

Co-authored-by: root <kinsonnee@gmail.com>

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 Goals
 
 Our research and experimentation focus on:

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 Phases
 

docs/docfx.json

@@ -7,6 +7,7 @@
           "toc.yml",
           "community/*.md",
           "concepts/*.md",
+          "guides/*.md",
           "reference/*.md",
           "install/*.md"
         ]
@@ -78,4 +79,3 @@
     }
   }
 }
-

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.

docs/toc.yml

@@ -51,6 +51,8 @@
   items:
     - name: Local Development
       href: local-development.md
+    - name: Evolving Specs
+      href: guides/evolving-specs.md
 
 # Community
 - name: Community