diff --git a/docs/concepts/sdd.md b/docs/concepts/sdd.md index 7f59feb51b..c5b6d5542c 100644 --- a/docs/concepts/sdd.md +++ b/docs/concepts/sdd.md @@ -11,6 +11,11 @@ Spec-Driven Development is a structured process that emphasizes: - **Multi-step refinement** rather than one-shot code generation from prompts - **Heavy reliance** on advanced AI model capabilities for specification interpretation +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. + ## Development Phases | Phase | Focus | Key Activities | diff --git a/docs/concepts/spec-persistence.md b/docs/concepts/spec-persistence.md new file mode 100644 index 0000000000..dcef441116 --- /dev/null +++ b/docs/concepts/spec-persistence.md @@ -0,0 +1,107 @@ +# 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 +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. + +## Two Separate Questions + +Spec-driven development has a temporal question: how long should the +specification matter? One +[overview of SDD tooling](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) +frames that lifecycle in three levels: + +- **Spec-first**: write a spec before coding, then allow it to be discarded. +- **Spec-anchored**: keep the spec after implementation and use it for future + changes. +- **Spec-as-source**: treat the spec as the only human-edited source and + 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. + +## 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. + +Flow-back works well when: + +- the team is small enough to notice and reconcile drift quickly +- implementation discoveries are expected to reshape the original plan +- speed matters more than preserving each intermediate decision as immutable + history + +The main risk is silent divergence. If the team changes lower-level artifacts +without reflecting the decision back into `spec.md`, future contributors may +not know which artifact to trust. + +## Flow-Forward Spec + +Use flow-forward when each feature directory should remain a historical record. + +In this model, completed artifacts are treated as immutable. When requirements +change, the team creates a new feature directory instead of mutating the +existing `spec.md`, `plan.md`, or `tasks.md`. The older directory remains useful +for audit, comparison, or explaining how the project reached its current state. + +Flow-forward works well when: + +- auditability and traceability matter +- features are well-scoped and rarely revisited in place +- the team wants a clear sequence of requirement changes over time + +The main tradeoff is duplication. Related decisions can be spread across +multiple feature directories, so teams need naming, linking, or review habits +that make the lineage easy to follow. + +## Living Spec + +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. + +Living spec works well when: + +- the product contract is stable enough to own the workflow +- the team is comfortable regenerating derived artifacts after spec changes +- consistency between requirements and implementation matters more than keeping + every intermediate plan intact + +The main risk is losing useful implementation rationale if derived artifacts are +discarded without preserving important decisions elsewhere. + +## Choosing a Model + +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 | +|---|---|---|---| +| Flow-back spec | Edit 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 | + +If your team has not chosen a model yet, start by answering two questions: + +1. Should completed feature directories be historical records or editable work + areas? +2. Is `spec.md` the single source of truth, or are `plan.md` and `tasks.md` + allowed to become co-equal sources? + +Once those answers are clear, document the convention in your project +constitution or team onboarding notes so future contributors know how to handle +changes. diff --git a/docs/toc.yml b/docs/toc.yml index ce91339a1b..e5fb07fbba 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -41,6 +41,8 @@ items: - name: What is SDD? href: concepts/sdd.md + - name: Spec Persistence Models + href: concepts/spec-persistence.md # Development workflows - name: Development