diff --git a/README.md b/README.md index 0a0b4119b2..9af501982d 100644 --- a/README.md +++ b/README.md @@ -254,6 +254,8 @@ Spec-Driven Development is a structured process that emphasizes: | **Creative Exploration** | Parallel implementations | | | **Iterative Enhancement** ("Brownfield") | Brownfield modernization | | +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: diff --git a/docs/concepts/sdd.md b/docs/concepts/sdd.md index c5b6d5542c..fd994219c7 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 +brownfield workflow. ## Development Phases diff --git a/docs/docfx.json b/docs/docfx.json index 62869e1d83..e22b394ba0 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.md new file mode 100644 index 0000000000..1c6263129f --- /dev/null +++ b/docs/guides/evolving-specs.md @@ -0,0 +1,88 @@ +# 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 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 + +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 + +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 +`specify init --here --force`, protect any project-specific material that lives +outside `specs/`, especially `.specify/memory/constitution.md` and customized +files under `.specify/templates/` or `.specify/scripts/`. + +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.yml index e5fb07fbba..aac69f57b4 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -49,6 +49,8 @@ items: - name: Local Development href: local-development.md + - name: Evolving Specs + href: guides/evolving-specs.md # Community - name: Community