Skip to content

💫 Toolkit to help you get started with SDD or any other process!

docs: clarify delivery versus post-delivery spec persistence (#4945)

Manfred Riem60ac84952c75
diff --git a/docs/concepts/spec-persistence.md b/docs/concepts/spec-persistence.md
index dcef44111..9269eca58 100644
--- a/docs/concepts/spec-persistence.md
+++ b/docs/concepts/spec-persistence.md
@@ -1,12 +1,36 @@
# Spec Persistence Models
Spec Kit intentionally leaves teams in control of what happens to `spec.md`,
-`plan.md`, and `tasks.md` after requirements change. The toolkit gives you a
+`plan.md`, and `tasks.md` after a feature is delivered. The toolkit gives you a
repeatable workflow, but it does not force one artifact maintenance strategy.
This page names three common models so teams can make that choice explicit.
None is the default, and none is required by Spec Kit.
+## Shared Delivery, Separate Persistence
+
+All three models use the same feature delivery process:
+specify -> plan -> tasks -> implement -> converge. Repeat implement and
+converge until the agreed feature is complete.
+
+Converge assesses the implementation against the feature's spec, plan, and
+tasks, governed by the constitution. It is append-only: its only possible write
+is adding remaining work to `tasks.md`. It does not select a persistence model,
+rewrite intent to match code, or treat approval of code as agreement with
+documented intent.
+
+Persistence is the team's choice of how to maintain artifacts **after
+delivery**, not an alternative way to deliver or determine completeness.
+Discoveries can occur during implementation, but their timing does not define
+the persistence model. If the team agrees to change the intended contract,
+make that intent explicit in the artifacts and deliver against it.
+
+A later change requiring implementation still goes through the shared delivery
+process and convergence against its explicit intended artifacts, whether those
+artifacts are new or revised. See
+[Evolving Specs in Existing Projects](../guides/evolving-specs.md) for practical
+guidance.
+
## Two Separate Questions
Spec-driven development has a temporal question: how long should the
@@ -21,17 +45,24 @@ frames that lifecycle in three levels:
regenerate implementation artifacts from it.
Spec Kit also exposes a second question: what happens to the artifact set when
-requirements change? The models below describe that mutation strategy.
+requirements change after delivery? The models below describe that maintenance
+strategy.
## Flow-Back Spec
Use flow-back when `spec.md`, `plan.md`, `tasks.md`, and the implementation are
all allowed to inform each other.
-In this model, edits can begin in any artifact. A developer might update
-`tasks.md` during implementation, revise `plan.md` after a technical discovery,
-or adjust `spec.md` after a product clarification. The team then reconciles the
-artifact set manually so the final project history still makes sense.
+After delivery, accepted discoveries can inform maintenance edits to any
+artifact. The team decides what those discoveries mean for intended behavior,
+technical approach, or task breakdown, then manually reconciles `spec.md`,
+`plan.md`, and `tasks.md` with that agreed direction. The implementation is
+evidence for that discussion, not a replacement source of intent.
+
+This is a team-owned maintenance convention, not a requirement for a new core
+amendment command or an artifact-rewriting role for converge. If reconciliation
+identifies implementation work, deliver that change through the shared process
+against the explicit intended artifacts.
Flow-back works well when:
@@ -68,10 +99,10 @@ that make the lineage easy to follow.
Use living spec when `spec.md` is the contract and the other artifacts are
derived from it.
-In this model, teams update `spec.md` first and then regenerate or revise
-`plan.md` and `tasks.md` from that source. The plan and task list are still
-valuable, but they are treated as disposable derivations rather than permanent
-sources of truth.
+After delivery, teams maintain `spec.md` as the contract, updating it first when
+intended behavior changes, then regenerating or revising `plan.md` and
+`tasks.md` from that source. The plan and task list are still valuable, but they
+are treated as disposable derivations rather than permanent sources of truth.
Living spec works well when:
@@ -89,9 +120,9 @@ The model is a team convention, not a CLI setting. A project can even use
different models in different areas, as long as contributors know which one
applies.
-| Model | Mutation rule | Best fit | Watch out for |
+| Model | Post-delivery maintenance rule | Best fit | Watch out for |
|---|---|---|---|
-| Flow-back spec | Edit any artifact, then reconcile | Fast iteration and close collaboration | Silent drift between artifacts |
+| Flow-back spec | Reflect accepted discoveries in any artifact, then reconcile | Fast iteration and close collaboration | Silent drift between artifacts |
| Flow-forward spec | Create a new feature directory for new requirements | Audit trails and historical clarity | Duplicate or fragmented context |
| Living spec | Edit `spec.md`; regenerate derived artifacts | Spec as contract | Lost rationale in regenerated files |
diff --git a/docs/guides/evolving-specs.md b/docs/guides/evolving-specs.md
index 17a91298e..f55928445 100644
--- a/docs/guides/evolving-specs.md
+++ b/docs/guides/evolving-specs.md
@@ -2,35 +2,61 @@
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.
+covers how to maintain feature artifacts after delivery and deliver subsequent
+changes.
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.
+- **Feature artifact evolution** maintains repository-specific `specs/`
+ artifacts according to the team's post-delivery persistence convention.
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.
+files. Use one of the artifact persistence models below to decide how completed
+feature artifacts are maintained when requirements or implementation insights
+change an existing project. None is required or the default.
For the conceptual model definitions, see
[Spec Persistence Models](../concepts/spec-persistence.md).
-## Flow-Forward Spec
+## Shared Feature Delivery Loop
-Use flow-forward when each feature directory should remain a historical record.
+All three persistence models use the same delivery/completeness process:
+specify -> plan -> tasks -> implement -> converge. Repeat implementation and
+convergence until the agreed feature is complete.
-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:
+For a new feature or a later change requiring implementation:
-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.
+1. Make the intended contract explicit in `spec.md`. Use `/speckit.specify` to
+ create a new feature directory under `specs/`, or revise an existing spec
+ according to your team's persistence convention.
+2. Run `/speckit.plan` or revise `plan.md` to define the implementation approach.
+3. Run `/speckit.tasks` or revise `tasks.md` to derive the work breakdown.
+ Run `/speckit.analyze` before implementation to catch cross-artifact gaps.
4. Run `/speckit.implement` and review the resulting code and artifact diffs.
-5. Run `/speckit.converge` to verify completeness and generate tasks for remaining gaps. If tasks are appended, repeat `/speckit.implement` and `/speckit.converge` until the feature is fully complete.
+5. Run `/speckit.converge` to assess implementation against the spec, plan, and
+ tasks, governed by the constitution. If it appends tasks for remaining gaps,
+ repeat `/speckit.implement` and `/speckit.converge` until the agreed feature
+ is complete.
+
+Converge is append-only: its only possible write is adding tasks to `tasks.md`.
+It does not choose a persistence strategy or rewrite the artifacts to accept
+code as a replacement for documented intent.
+
+Discoveries may arise during delivery under any model. If they lead to an
+agreed change of intent, make the revised contract explicit in the artifacts
+and deliver against it. The maintenance choices below apply after delivery;
+they do not replace this loop.
+
+## Flow-Forward Spec
+
+Use flow-forward when each completed feature directory should remain a
+historical record.
+
+After delivery, retain the completed artifacts without changing them. For
+another feature or a follow-up change requiring implementation, create a new
+feature directory and use the shared delivery loop above.
The previous feature directory remains intact for audit, comparison, or
explaining how the project reached its current state. Use clear feature names or
@@ -41,9 +67,9 @@ cross-links when a new directory supersedes or extends earlier work.
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:
+After delivery, maintain `spec.md` as the contract. 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.
@@ -52,10 +78,11 @@ spec:
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.
-7. Run `/speckit.converge` to assess completion and append any remaining work to `tasks.md`. If tasks are appended, repeat `/speckit.implement` and `/speckit.converge` until the feature is fully complete.
+5. Run `/speckit.analyze` to catch gaps between the spec, plan, and tasks.
+
+These steps maintain the artifact set; they do not deliver changed behavior.
+If the revised contract requires implementation, use the shared delivery loop
+above against those explicit intended artifacts.
Preserve important implementation rationale before replacing derived artifacts.
If a plan or task list contains decisions that still matter, carry them forward
@@ -63,12 +90,13 @@ explicitly.
## Flow-Back Spec
-Use flow-back when implementation discoveries are allowed to reshape the
-artifact set.
+Use flow-back when accepted discoveries inform maintenance across the artifact
+set after delivery.
-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:
+A discovery may have originated in `spec.md`, `plan.md`, `tasks.md`, or the
+implementation, including during delivery. For post-delivery maintenance,
+the team decides which discoveries to accept and brings the artifacts into
+alignment with that agreed direction:
1. Capture the discovery in the artifact closest to the work.
2. Decide whether it changes intended behavior, implementation strategy, task
@@ -76,8 +104,12 @@ the artifact set back into alignment:
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.
+
+The implementation provides evidence for the team's decision; accepting code
+does not automatically make it the intended contract. Reconcile the artifacts
+manually, not through converge or a required core amendment command. If the
+agreed direction requires implementation, use the shared delivery loop above
+against explicit intended artifacts.
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