43a54bf2d6
* feat(presets): add opt-in constitution-sync preset Follow-up to #3790, which removed the consistency-propagation pass from the core /constitution command in favor of runtime resolution. Teams that treat materialized plan/spec/tasks templates as reviewed, committed artifacts lost the auto-sync of amended constitutional guidance on a non-forced upgrade. Add a bundled, opt-in `constitution-sync` preset that restores that behavior via a wrap-strategy override of speckit.constitution (composes on {CORE_TEMPLATE} so it stays forward-compatible). It only writes into the project's own .specify/templates scaffolds and installed command files, never into stack-owned template layers. - presets/constitution-sync/: preset.yml (requires >=0.14.4), wrap command, README documenting the tension between auto-propagation and the resolution stack - presets/catalog.json: bundled entry - docs/upgrade.md: document the 0.14.4 behavior change and the opt-in - tests/test_presets.py: structural + composition coverage (TestConstitutionSyncPreset) Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * fix(presets): ship constitution-sync in wheel, clarify scope guard, assert composition Address review feedback on #3873: - pyproject.toml: force-include presets/constitution-sync into the wheel's core_pack so `_locate_bundled_preset` resolves it in a released install; the bundled advertisement was otherwise unshippable. - tests/contract/test_wheel_bundled_presets.py: new contract test asserting every bundled preset in presets/catalog.json is force-included (guards lean too). - commands/speckit.constitution.md: explicitly state the propagation section supersedes the core Scope Guard, which otherwise says dependent templates are not modified here. - tests/test_presets.py: assert resolve_content substitutes {CORE_TEMPLATE} and the effective command embeds both the core body and the sync pass. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * test(presets): parse frontmatter as YAML in constitution-sync wrapper test Address review feedback on #3873: assert `strategy: wrap` structurally by parsing the Markdown frontmatter as YAML (instead of a substring match that could false-positive on body text), and assert {CORE_TEMPLATE} in the body section only. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(presets): reframe constitution-sync README around behavior and caveats Rework the preset's user-facing docs to describe what it does, what it does not do, and the caveats you take on — rather than leading with version/origin history. The preset stack is the project's forward direction, so the README no longer positions this as "restoring pre-0.14.4 behavior." Also make the edit-in-place vs. composition conflict explicit and consistent across the wrapper command and docs: propagation into command files/templates that are provided or wrapped by a preset/extension is clobbered on stack reconciliation (integration use/upgrade, preset/extension install/remove), so the wrapper restricts propagation to project-local artifacts the team owns. - README: forward-looking "What it does / does not do / When to use / Caveats" - speckit.constitution.md: step 4 no longer hand-edits composed command files; closing caveat covers command files too - docs/upgrade.md: note the composition-model conflict in the opt-in section - tests: assert the updated closing-caveat wording Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(presets): tweak constitution-sync README default-behavior wording Phrase the default-behavior note as "the current version of Spec Kit" and rewrap the opening paragraph. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(presets): keep emphasis spans on one line in constitution-sync README Avoid **bold** spans broken across soft line breaks (runtime resolution, reviewed committed artifacts) so they render consistently. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(presets): refocus constitution-sync README on what it restores Reframe the intro around what the preset restores and what the user opts into, rather than describing current Spec Kit default behavior. Be honest that propagation was removed deliberately (duplicates the source of truth, fights composition) and this preset knowingly reintroduces it and its tradeoffs. Minor flow fixes (comma splice, terse bullet). Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(upgrade): de-pin version from /constitution behavior-change section The upgrade guide always describes the latest version, so hard-pinning "0.14.4" in the heading and "Starting in 0.14.4" in the body added no value. Keep the #3790 provenance link and the "no longer propagates" framing; the machine-readable version gate stays in preset.yml. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e * docs(upgrade): clarify non-breaking nuance and presets direction Note that the /constitution scope change is only noticeable if you relied on the old edit-in-place behavior, and add the forward-looking framing: presets and extensions — not in-place file edits — are how Spec Kit now governs, versions, and audits shared assets across repositories. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: afa7c1d2-147b-4f62-a6fc-a2cc824cfa3e
6.3 KiB
Constitution Template Sync
An opt-in preset that restores /constitution's ability to propagate amended guidance into your
project's own templates and command files. After you update the constitution, it aligns
plan-template.md, spec-template.md, tasks-template.md, project-local command files, and
guidance docs so they reflect the current principles.
This propagation used to be built into /constitution; it was dropped when the command moved to the
preset model. Installing this preset opts you back into it: you get the guidance materialized into
reviewed, committed artifacts instead of relying on runtime resolution alone.
What you're opting into. Propagation was removed deliberately — it duplicates the constitution as the source of truth and can fight the composition stack (materialized edits get shadowed or clobbered on the next recompose). This preset knowingly reintroduces that behavior, and those tradeoffs, for teams that want it. Read the caveats before installing.
For most projects the default composable stack is the recommended approach, and at organization scale it is usually the stronger governance model. Runtime resolution keeps the live constitution as the single source of truth (nothing to re-sync, so nothing drifts), and the stack composes the entire Spec Kit ecosystem — not just the SDD commands, but every command, template, script and extension — with explicit priority levels, strategies, and independent versioning. It is a capability, not automatic governance: a core team authors its own organizational presets and extensions, then owns, versions, and audits that policy in one place and rolls it across many repositories, instead of scattering frozen, per-repo copies no central team can see. This preset is a supported escape hatch for teams whose workflow depends on reviewing materialized artifacts directly — useful as a bridge, though for org-wide policy the better long-term path is usually a versioned preset a core team maintains.
What it does
Ships a single wrap-strategy override of speckit.constitution. It composes on top of the
current core command (via {CORE_TEMPLATE}), so it stays forward-compatible with core changes, and
appends a propagation pass that, after the constitution is written:
- Aligns
plan/spec/tasks-template.mdin.specify/templates/with the updated principles. - Updates project-local command files and guidance docs to correct stale references.
- Extends the Sync Impact Report in
.specify/memory/constitution.mdwith the files it touched.
What it does not do
- It does not change behavior for anyone who does not install it — the default runtime resolution model is untouched.
- It does not disable runtime resolution.
plan,tasks, andanalyzestill read the live constitution every run; this preset adds materialized copies on top — it does not replace the source of truth. - It does not edit versioned, package-owned files — templates or command files provided or
wrapped by another preset or extension. Those are recomposed from the resolution stack, so it
only ever writes into your project's own
.specify/templates/scaffolds and command files that are not managed by a preset/extension.
When to use it
Install it only if your team treats the materialized templates and commands as
reviewed, committed artifacts — for example, if plan-template.md's Constitution Check is
read in PRs as "here are our current gates" and is expected to track the constitution.
If you rely on the default runtime-resolution model, you do not need this preset: the live constitution is already the single source of truth and there is nothing to sync.
Caveats you take on
The preset resolution stack is how Spec Kit composes templates and commands going forward: they are layered, package-owned artifacts recomposed on demand, not frozen files you edit in place. Propagation is the opposite idea — it materializes guidance into files and freezes it. That tension is the main thing to understand before installing:
-
Materialized copies can drift. Anything propagated is a snapshot; if you amend the constitution and do not re-run
/constitution, the copies fall out of sync. The default runtime model has no drift because it reads the live constitution every run. -
Edits to composed files do not survive reconciliation. If the rest of your SDD flow is preset/extension-managed, the commands it materializes (
speckit.plan,speckit.specify,speckit.tasks,speckit.analyze,speckit.implement, …) are recomputed from the stack. Any guidance propagated into them is clobbered the next time the stack reconciles — onspecify integration use <key>/switch,specify integration upgrade, or any preset/extension install or remove. The same applies to templates owned by another preset/extension. This is why the preset restricts itself to project-local files; propagation is reliable only for artifacts you own outright. -
A pre-filled Constitution Check can bias
/plan. Materializing concrete gates intoplan-template.mdreplaces the runtime pointer, so the first/planpass may anchor on the frozen text. Keep the pointer unless you specifically want committed gates.
Bottom line: this preset fits projects whose governed templates and commands are project-local
artifacts they review, with the rest of the SDD flow on the plain bundled core. If your
plan/specify/tasks/analyze commands or templates come from other presets or extensions,
prefer the default runtime-resolution model.
Installation
# constitution-sync is a bundled preset — no download needed
specify preset add constitution-sync
Development
# Test from local directory
specify preset add --dev ./presets/constitution-sync
# Verify the wrapped command resolves
specify preset resolve speckit.constitution
# Remove when done
specify preset remove constitution-sync
Migrating back to the default
To move back to runtime resolution, reset each materialized ## Constitution Check section in
.specify/templates/plan-template.md to the pointer:
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
[Gates determined based on constitution file]
Then remove this preset. See docs/upgrade.md for details.
License
MIT