Skip to content

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

docs: distinguish extension reconciliation from core SDD (#4948)

Manfred Riemfe3de81d5b53
diff --git a/docs/concepts/spec-persistence.md b/docs/concepts/spec-persistence.md
index 9269eca58..d6b97ba9e 100644
--- a/docs/concepts/spec-persistence.md
+++ b/docs/concepts/spec-persistence.md
@@ -19,11 +19,21 @@ 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.
+The core workflow has no dedicated command that automatically reconciles
+differences among `spec.md`, `plan.md`, and `tasks.md`. Analyze reports
+inconsistencies without editing artifacts, and converge only appends remaining
+work to `tasks.md`. Teams can reconcile artifacts directly, and extensions can
+provide their own commands or hooks to coordinate reconciliation during or
+after delivery. Extension behavior does not change the responsibilities of the
+core commands.
+
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.
+the persistence model. Reconciliation can also occur during delivery without
+becoming part of the core workflow or the persistence strategy. 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
@@ -55,14 +65,17 @@ all allowed to inform each other.
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.
+technical approach, or task breakdown. The team can reconcile `spec.md`,
+`plan.md`, and `tasks.md` itself or use an extension whose documented behavior
+does so. 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.
+amendment command or an artifact-rewriting role for analyze or converge.
+Extension-provided reconciliation remains extension behavior, whether it runs
+during or after delivery. If reconciliation identifies implementation work,
+deliver that change through the shared process against the explicit intended
+artifacts.
Flow-back works well when:
diff --git a/docs/guides/evolving-specs.md b/docs/guides/evolving-specs.md
index f55928445..1a0cf9db9 100644
--- a/docs/guides/evolving-specs.md
+++ b/docs/guides/evolving-specs.md
@@ -44,10 +44,18 @@ 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.
+Core has no dedicated command that automatically reconciles differences among
+`spec.md`, `plan.md`, and `tasks.md`. `/speckit.analyze` reports inconsistencies
+without changing the artifacts. A team can reconcile them directly, or an
+extension can provide commands or hooks that do so during or after delivery
+according to that extension's documented behavior. Those actions do not change
+the responsibilities of the core commands.
+
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.
+and deliver against it. Reconciliation may occur during delivery, but the
+maintenance choices below describe what the team persists after delivery; they
+do not replace this loop.
## Flow-Forward Spec
@@ -68,17 +76,16 @@ Use living spec when `spec.md` is the contract and `plan.md` and `tasks.md` are
derived from it.
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:
+changes, revise the existing `spec.md` first. Then reconcile downstream
+artifacts so they match the updated spec:
-1. Start from a clean working tree or a dedicated branch so every generated
+1. Start from a clean working tree or a dedicated branch so every artifact
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` to catch gaps between the spec, plan, and tasks.
+2. Update `spec.md` with the intended contract.
+3. Reconcile `plan.md` and `tasks.md` directly or through an extension according
+ to the team's documented convention.
+4. Run `/speckit.analyze` to report any remaining 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
@@ -107,7 +114,8 @@ alignment with that agreed direction:
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
+directly or through an extension. Analyze and converge do not provide automatic
+all-artifact reconciliation, and no core amendment command is required. If the
agreed direction requires implementation, use the shared delivery loop above
against explicit intended artifacts.
diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md
index e39ff9d69..676428a07 100644
--- a/docs/reference/extensions.md
+++ b/docs/reference/extensions.md
@@ -2,6 +2,13 @@
Extensions add new capabilities to Spec Kit — domain-specific commands, external tool integrations, quality gates, and more. They introduce new commands and templates that go beyond the built-in Spec-Driven Development workflow.
+An extension can define commands or hooks that reconcile `spec.md`, `plan.md`,
+and `tasks.md` during or after feature delivery. Any such edits follow the
+extension's documented behavior and the project's governance; they are not
+performed by, or added to the responsibilities of, the core Spec Kit commands.
+The team's persistence model separately determines how artifacts are maintained
+after delivery.
+
## Search Available Extensions
```bash