From 513c66f8d6d4d6b6116f934a93703c1e93c4d1f6 Mon Sep 17 00:00:00 2001 From: root Date: Tue, 9 Jun 2026 13:12:18 +0800 Subject: [PATCH 1/2] docs: document evolving specs in existing projects --- README.md | 2 ++ docs/concepts/sdd.md | 2 ++ docs/upgrade.md | 20 ++++++++++++++++++++ 3 files changed, 24 insertions(+) diff --git a/README.md b/README.md index 0a0b4119b2..bb44d7fbfc 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 [Upgrade Guide](./docs/upgrade.md#keeping-specs-current-in-existing-projects) 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..a966de13fe 100644 --- a/docs/concepts/sdd.md +++ b/docs/concepts/sdd.md @@ -24,6 +24,8 @@ those artifacts over time. | **Creative Exploration** | Parallel implementations | | | **Iterative Enhancement** ("Brownfield") | Brownfield modernization | | +In brownfield work, Spec Kit is not a one-time scaffold. Treat project-file updates and feature artifact updates as separate loops: refresh managed commands and templates when you upgrade Spec Kit, and evolve `specs/` artifacts when product behavior changes. See the [upgrade guide](../upgrade.md#keeping-specs-current-in-existing-projects) for the existing-project workflow. + ## Experimental Goals Our research and experimentation focus on: diff --git a/docs/upgrade.md b/docs/upgrade.md index 026279e340..bb7ec8832b 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -111,6 +111,26 @@ These files are **never touched** by the upgrade—the template packages don't e The `specs/` directory is completely excluded from template packages and will never be modified during upgrades. +### Keeping specs current in existing projects + +For brownfield projects, separate two loops: + +- **Spec Kit project-file updates** refresh managed commands, scripts, templates, and shared memory files. +- **Feature artifact evolution** keeps your repository-specific `specs/` artifacts aligned with the code and product behavior you intend to ship. + +When you add another feature to an existing project, create a new feature spec through your installed `/speckit.specify` command and continue through `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement`. The new feature gets its own directory under `specs/`, while previous feature directories remain as historical project artifacts. + +When you extend or correct an existing feature, update that feature's current artifacts instead of regenerating the whole project: + +1. Start from a clean working tree or a dedicated branch so you can review every generated change. +2. Decide whether the work changes the feature's intended behavior or only fixes the implementation. +3. If the intended behavior changes, revise the existing `spec.md` with `/speckit.clarify` or an explicit edit, then rerun `/speckit.plan` and `/speckit.tasks` so the downstream artifacts match the revised spec. +4. If only the code changed, compare the implementation against the existing `spec.md`, `plan.md`, and `tasks.md`; update those artifacts only when they no longer describe the behavior you want to preserve. +5. Run `/speckit.analyze` before implementation resumes to catch gaps between the spec, plan, and tasks. +6. Run `/speckit.implement` with the updated artifacts, then review the resulting code and artifact diffs together. + +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 any customized files under `.specify/templates/` or `.specify/scripts/`. Your `specs/` directory is not part of the template package, but those shared project files can be overwritten by a forced refresh. + ### Update command Run this inside your project directory: From 15c46be6862d32a5bb9d45bc75e60cf847273866 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 10 Jun 2026 10:12:51 +0800 Subject: [PATCH 2/2] docs: reframe evolving specs guide around persistence models --- README.md | 2 +- docs/concepts/sdd.md | 7 ++- docs/docfx.json | 2 +- docs/guides/evolving-specs.md | 88 +++++++++++++++++++++++++++++++++++ docs/toc.yml | 2 + docs/upgrade.md | 20 -------- 6 files changed, 95 insertions(+), 26 deletions(-) create mode 100644 docs/guides/evolving-specs.md diff --git a/README.md b/README.md index bb44d7fbfc..9af501982d 100644 --- a/README.md +++ b/README.md @@ -254,7 +254,7 @@ 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 [Upgrade Guide](./docs/upgrade.md#keeping-specs-current-in-existing-projects) describes the recommended brownfield loop. +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 diff --git a/docs/concepts/sdd.md b/docs/concepts/sdd.md index a966de13fe..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 @@ -24,8 +25,6 @@ those artifacts over time. | **Creative Exploration** | Parallel implementations | | | **Iterative Enhancement** ("Brownfield") | Brownfield modernization | | -In brownfield work, Spec Kit is not a one-time scaffold. Treat project-file updates and feature artifact updates as separate loops: refresh managed commands and templates when you upgrade Spec Kit, and evolve `specs/` artifacts when product behavior changes. See the [upgrade guide](../upgrade.md#keeping-specs-current-in-existing-projects) for the existing-project workflow. - ## Experimental Goals Our research and experimentation focus on: 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 diff --git a/docs/upgrade.md b/docs/upgrade.md index bb7ec8832b..026279e340 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -111,26 +111,6 @@ These files are **never touched** by the upgrade—the template packages don't e The `specs/` directory is completely excluded from template packages and will never be modified during upgrades. -### Keeping specs current in existing projects - -For brownfield projects, separate two loops: - -- **Spec Kit project-file updates** refresh managed commands, scripts, templates, and shared memory files. -- **Feature artifact evolution** keeps your repository-specific `specs/` artifacts aligned with the code and product behavior you intend to ship. - -When you add another feature to an existing project, create a new feature spec through your installed `/speckit.specify` command and continue through `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement`. The new feature gets its own directory under `specs/`, while previous feature directories remain as historical project artifacts. - -When you extend or correct an existing feature, update that feature's current artifacts instead of regenerating the whole project: - -1. Start from a clean working tree or a dedicated branch so you can review every generated change. -2. Decide whether the work changes the feature's intended behavior or only fixes the implementation. -3. If the intended behavior changes, revise the existing `spec.md` with `/speckit.clarify` or an explicit edit, then rerun `/speckit.plan` and `/speckit.tasks` so the downstream artifacts match the revised spec. -4. If only the code changed, compare the implementation against the existing `spec.md`, `plan.md`, and `tasks.md`; update those artifacts only when they no longer describe the behavior you want to preserve. -5. Run `/speckit.analyze` before implementation resumes to catch gaps between the spec, plan, and tasks. -6. Run `/speckit.implement` with the updated artifacts, then review the resulting code and artifact diffs together. - -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 any customized files under `.specify/templates/` or `.specify/scripts/`. Your `specs/` directory is not part of the template package, but those shared project files can be overwritten by a forced refresh. - ### Update command Run this inside your project directory: