[Feature]: `specify preset update` — in-place preset update with rollback and single-pass reconciliation

[digimangos]

Summary

There is currently no specify preset update <id> command. The only way to move an installed preset to a new version is preset remove <id> followed by preset add <id>. That workaround has real correctness problems beyond performance, because both remove() and install_from_directory() independently trigger full-stack reconciliation (composed commands/skills, and — when constitution-sync is enabled — memory/constitution.md) whenever the touched preset provides a constitution template. A version bump therefore reconciles the constitution twice: once against the stack with the preset temporarily absent, once against the reinstalled stack — with a real window in between where on-disk state reflects neither the old nor the new version.

This was raised as a valid feature-parity gap in #4415, with a request to open a tracking issue including acceptance criteria for: single/all updates, catalog-only eligibility, preserving priority/enabled state, rollback on failure, and command/skill/constitution reconciliation.

Current behavior (traced in source)

• PresetManager.install_from_directory (presets/__init__.py) refuses to install over an already-installed preset id unless force=True, which itself calls self.remove() first — i.e. there is no in-place update path, only teardown+rebuild.
• PresetResolver.collect_all_layers / resolve_content recompute composed content from the entire installed-preset priority stack on every reconciliation call — never a diff against a single preset's previous version.
• _reconcile_constitution / _materialize_constitution_template unconditionally overwrite .specify/memory/constitution.md (when constitution-sync is enabled and the file is still detected as machine-generated) with no check for whether the resolved content actually changed.
• PresetRegistry stores priority and enabled per installed preset, but neither remove() nor install_from_directory() reads the previous entry back when reinstalling — so a manual remove+add workaround also risks losing an explicit --priority (if omitted, it silently falls back to the default of 10) and always resets enabled to True regardless of whether the preset was previously disabled.
• Neither remove nor add ever holds both the old and new manifest at the same time, so today there's no way to report what an update actually changed.

Proposed command

specify preset update <id> [--from URL | --dev PATH] [--priority N] [--all]

Acceptance criteria

Single-preset update

• specify preset update <id> updates one named, already-installed preset to a new version from a supplied source (--from URL / --dev PATH) or, when eligible (see catalog-eligibility below), by re-resolving from its original catalog source.
• Running preset update against a preset id that is not installed fails with a clear error directing the user to preset add instead — it must not silently fall through to an install path.
• Old vs. new preset.yml manifests are diffed (added / removed / changed template names) before any files are touched, and this diff drives which command/skill files are registered vs. unregistered — not a blind re-register of everything the new manifest declares.

Bulk update (--all)

• specify preset update --all checks every installed preset for a newer compatible version and updates only those that have one; presets already at the latest version are reported as skipped, not reinstalled with identical content.
• A failure updating one preset in a bulk run is isolated to that preset (full rollback per the rollback criteria below) and does not abort or skip processing of the remaining presets.
• Bulk update produces a per-preset outcome summary (updated / already-latest / failed-with-reason / skipped-and-why).
• Behavior for disabled presets under --all is explicitly decided and documented (skip entirely vs. update files but leave disabled) rather than left as an implementation accident.

Catalog-only eligibility

• When no --from/--dev is supplied, automatic re-resolution of "the newer version" is only attempted when the preset's original install source is a catalog entry (or otherwise durably re-resolvable); presets installed via --dev or a one-off --from URL fail with a clear "source not re-resolvable, supply --from/--dev explicitly" error rather than failing silently or guessing.
• Update re-applies the same catalog install-allowed / discovery-only check that preset add already enforces (_install_allowed) — a discovery-only catalog preset cannot be updated any more than it can be freshly installed, if that's still the intended catalog semantics.
• This dovetails with [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 (recording install source/ref for extensions, presets, and workflows installed via --from, to support update) — provenance persisted for that issue should be reused here rather than re-invented per artifact type.

Preserving priority / enabled state

• Omitting --priority on preset update preserves the preset's currently registered priority (read via the existing PresetRegistry.get(pack_id)["priority"]) rather than resetting to the default of 10.
• Passing --priority N explicitly still allows a deliberate reprioritize as part of the same update call.
• A preset's enabled/disabled state (set via preset enable/preset disable) is preserved across an update — updating a disabled preset must not silently re-enable it.

Rollback on failure

• Compatibility/manifest validation failures on the new version occur before any live preset directory or registry entry is modified — a validation failure is a true no-op.
• New content is staged (e.g. presets/<id>.staging/) and validated before being swapped in; if staging or pre-swap validation fails, the previously installed version remains fully installed and functional.
• The swap from old to new content is atomic at the directory level (rename-based, not a recursive file-by-file overwrite), minimizing any window where the preset directory is partial or missing.
• A documented recovery path exists for the rare case of a crash during the swap step itself (e.g. a .bak directory retained, or a preset repair command).
• A reconciliation failure after a successful swap does not roll back the already-successful content/registry update (the new version is genuinely installed) — it surfaces a clear, actionable warning instead of silently succeeding or incorrectly reverting a good install.

Command / skill / constitution reconciliation

• Command and skill registration reconciliation runs exactly once per update, over the union of added/removed/changed names from the manifest diff — not once via an implicit "remove" pass and again via an implicit "add" pass.
• memory/constitution.md reconciliation (when constitution-sync is enabled) runs at most once per update, against the final post-update stack — never against an intermediate stack with the preset transiently absent.
• Reconciliation compares the newly resolved constitution content's hash against the current on-disk content and skips the write entirely when they match, so a version bump that doesn't change the resolved constitution produces zero file changes.
• The existing "don't clobber a hand-edited constitution" guard (_constitution_is_generated, based on the provenance sidecar hash) is reused unchanged by update(), not reimplemented.
• preset update prints a real diff summary (e.g. +2 commands, -1 command, constitution unchanged, priority kept at 10), since it's the first place both the old and new manifest are available together.

Compatibility with existing workflows

• preset add and preset remove continue to behave exactly as they do today; preset update is additive, not a replacement.
• A new preset version that renames the preset id or otherwise restructures its layout in a way a diff can't reconcile causes update to fail clearly and point the user to the remove+add workaround, rather than attempting a partial/corrupt diff-based update.

Implementation

I plan to work on this together with @markuswondrak.

Related

• specify preset update — feature parity with extension update #4415 — originating discussion
• [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 — install source/ref provenance for --from installs, needed for catalog-eligible auto-resolution here
• [Feature]: Resolve constitution-template at /constitution command time; gate install-time seeding behind constitution-sync #3950, feat(presets): add opt-in constitution-sync preset #3873, [bug-fix] Fix init-force-preset-desync: reapply presets/extensions on init --here --force #3995 — constitution-sync design and reconciliation-on-force work this builds on

[github-actions]

Feature assessment — preset-update · Stage 1/5: Intake

Idea Intake: specify preset update

• Slug: preset-update
• Created: 2026-09-03T16:53:35Z
• Source: GitHub issue [Feature]: specify preset update — in-place preset update with rollback and single-pass reconciliation #4427, labeled feature-assess
• Type: improvement

Idea (as captured)

Summary

There is currently no specify preset update command. The only way to move an installed preset to a new version is preset remove followed by preset add. That workaround has real correctness problems beyond performance, because both remove() and install_from_directory() independently trigger full-stack reconciliation (composed commands/skills, and — when constitution-sync is enabled — memory/constitution.md) whenever the touched preset provides a constitution template. A version bump therefore reconciles the constitution twice: once against the stack with the preset temporarily absent, once against the reinstalled stack — with a real window in between where on-disk state reflects neither the old nor the new version.

This was raised as a valid feature-parity gap in #4415, with a request to open a tracking issue including acceptance criteria for: single/all updates, catalog-only eligibility, preserving priority/enabled state, rollback on failure, and command/skill/constitution reconciliation.

Current behavior (traced in source)

• PresetManager.install_from_directory (presets/__init__.py) refuses to install over an already-installed preset id unless force=True, which itself calls self.remove() first — i.e. there is no in-place update path, only teardown+rebuild.
• PresetResolver.collect_all_layers / resolve_content recompute composed content from the entire installed-preset priority stack on every reconciliation call — never a diff against a single preset's previous version.
• _reconcile_constitution / _materialize_constitution_template unconditionally overwrite .specify/memory/constitution.md (when constitution-sync is enabled and the file is still detected as machine-generated) with no check for whether the resolved content actually changed.
• PresetRegistry stores priority and enabled per installed preset, but neither remove() nor install_from_directory() reads the previous entry back when reinstalling — so a manual remove+add workaround also risks losing an explicit --priority (if omitted, it silently falls back to the default of 10) and always resets enabled to True regardless of whether the preset was previously disabled.
• Neither remove nor add ever holds both the old and new manifest at the same time, so today there's no way to report what an update actually changed.

Proposed command

specify preset update <id> [--from URL | --dev PATH] [--priority N] [--all]

Acceptance criteria

Single-preset update

• specify preset update <id> updates one named, already-installed preset to a new version from a supplied source (--from URL / --dev PATH) or, when eligible (see catalog-eligibility below), by re-resolving from its original catalog source.
• Running preset update against a preset id that is not installed fails with a clear error directing the user to preset add instead — it must not silently fall through to an install path.
• Old vs. new preset.yml manifests are diffed (added / removed / changed template names) before any files are touched, and this diff drives which command/skill files are registered vs. unregistered — not a blind re-register of everything the new manifest declares.

Bulk update (--all)

• specify preset update --all checks every installed preset for a newer compatible version and updates only those that have one; presets already at the latest version are reported as skipped, not reinstalled with identical content.
• A failure updating one preset in a bulk run is isolated to that preset (full rollback per the rollback criteria below) and does not abort or skip processing of the remaining presets.
• Bulk update produces a per-preset outcome summary (updated / already-latest / failed-with-reason / skipped-and-why).
• Behavior for disabled presets under --all is explicitly decided and documented (skip entirely vs. update files but leave disabled) rather than left as an implementation accident.

Catalog-only eligibility

• When no --from/--dev is supplied, automatic re-resolution of "the newer version" is only attempted when the preset's original install source is a catalog entry (or otherwise durably re-resolvable); presets installed via --dev or a one-off --from URL fail with a clear "source not re-resolvable, supply --from/--dev explicitly" error rather than failing silently or guessing.
• Update re-applies the same catalog install-allowed / discovery-only check that preset add already enforces (_install_allowed) — a discovery-only catalog preset cannot be updated any more than it can be freshly installed, if that's still the intended catalog semantics.
• This dovetails with [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 (recording install source/ref for extensions, presets, and workflows installed via --from, to support update) — provenance persisted for that issue should be reused here rather than re-invented per artifact type.

Preserving priority / enabled state

• Omitting --priority on preset update preserves the preset's currently registered priority (read via the existing PresetRegistry.get(pack_id)["priority"]) rather than resetting to the default of 10.
• Passing --priority N explicitly still allows a deliberate reprioritize as part of the same update call.
• A preset's enabled/disabled state (set via preset enable/preset disable) is preserved across an update — updating a disabled preset must not silently re-enable it.

Rollback on failure

• Compatibility/manifest validation failures on the new version occur before any live preset directory or registry entry is modified — a validation failure is a true no-op.
• New content is staged (e.g. presets/.staging/) and validated before being swapped in; if staging or pre-swap validation fails, the previously installed version remains fully installed and functional.
• The swap from old to new content is atomic at the directory level (rename-based, not a recursive file-by-file overwrite), minimizing any window where the preset directory is partial or missing.
• A documented recovery path exists for the rare case of a crash during the swap step itself (e.g. a .bak directory retained, or a preset repair command).
• A reconciliation failure after a successful swap does not roll back the already-successful content/registry update (the new version is genuinely installed) — it surfaces a clear, actionable warning instead of silently succeeding or incorrectly reverting a good install.

Command / skill / constitution reconciliation

• Command and skill registration reconciliation runs exactly once per update, over the union of added/removed/changed names from the manifest diff — not once via an implicit "remove" pass and again via an implicit "add" pass.
• memory/constitution.md reconciliation (when constitution-sync is enabled) runs at most once per update, against the final post-update stack — never against an intermediate stack with the preset transiently absent.
• Reconciliation compares the newly resolved constitution content's hash against the current on-disk content and skips the write entirely when they match, so a version bump that doesn't change the resolved constitution produces zero file changes.
• The existing "don't clobber a hand-edited constitution" guard (_constitution_is_generated, based on the provenance sidecar hash) is reused unchanged by update(), not reimplemented.
• preset update prints a real diff summary (e.g. +2 commands, -1 command, constitution unchanged, priority kept at 10), since it's the first place both the old and new manifest are available together.

Compatibility with existing workflows

• preset add and preset remove continue to behave exactly as they do today; preset update is additive, not a replacement.
• A new preset version that renames the preset id or otherwise restructures its layout in a way a diff can't reconcile causes update to fail clearly and point the user to the remove+add workaround, rather than attempting a partial/corrupt diff-based update.

Implementation

I plan to work on this together with @markuswondrak.

Related

• specify preset update — feature parity with extension update #4415 — originating discussion
• [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 — install source/ref provenance for --from installs, needed for catalog-eligible auto-resolution here
• [Feature]: Resolve constitution-template at /constitution command time; gate install-time seeding behind constitution-sync #3950, feat(presets): add opt-in constitution-sync preset #3873, [bug-fix] Fix init-force-preset-desync: reapply presets/extensions on init --here --force #3995 — constitution-sync design and reconciliation-on-force work this builds on

Restated

Add an additive specify preset update workflow that can update one installed preset or eligible presets in bulk without the current remove-and-reinstall gap. It should preserve registry state, validate and stage changes safely, support rollback before the swap, and perform command/skill/constitution reconciliation once against the final preset stack.

Origin & Context

• Raised by: digimangos
• Trigger: A feature-parity gap was identified in specify preset update — feature parity with extension update #4415; the issue requests a tracking implementation for safer single- and bulk-preset updates.

First-Glance Unknowns

• [NEEDS CLARIFICATION: What exact catalog and provenance data will be available when this feature is implemented, especially in relation to [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533?]
• [NEEDS CLARIFICATION: Should --all update disabled presets while preserving their disabled state, or skip them entirely?]
• [NEEDS CLARIFICATION: What is the required crash-recovery mechanism for an interrupted atomic swap?]
• [NEEDS CLARIFICATION: Which preset manifest changes are considered reconcilable versus requiring remove+add?]
• [NEEDS CLARIFICATION: What user-facing confirmation behavior is required for single and bulk updates?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4427 · 286.6 AIC · ⌖ 30 AIC · ⊞ 30.4K · ◷

[github-actions]

Feature assessment — preset-update · Stage 2/5: Research

Idea Research: specify preset update

• Slug: preset-update
• Created: 2026-09-03T16:53:35Z
• Evidence confidence (overall): medium

Users & Demand

• The requester reports a concrete workflow problem for maintainers and users who need to move an installed preset to a newer version, and supplies a detailed acceptance list covering single and bulk updates, state preservation, rollback, and reconciliation — [source: GitHub issue [Feature]: specify preset update — in-place preset update with rollback and single-pass reconciliation #4427] (confidence: medium, cited)
• The issue states that the current workaround is preset remove followed by preset add, and identifies correctness windows and lost registry state as harms. This is stated demand from one issue, not observed usage volume — [source: GitHub issue [Feature]: specify preset update — in-place preset update with rollback and single-pass reconciliation #4427] (confidence: medium, cited)
• Broader demand, frequency of preset updates, and the number of affected projects are not available in the repository or issue — [NEEDS CLARIFICATION: provide usage data, support examples, or additional stakeholder/user signals] (confidence: high, assumption)

Prior Art

• The current CLI exposes list, add, remove, search, resolve, info, set-priority, enable, and disable preset commands, but no update command — [source: src/specify_cli/presets/_commands.py, command registrations] (confidence: high, cited)
• PresetManager.install_from_directory() validates the incoming manifest, rejects an already-installed ID unless force=True, and implements force by calling remove() before copying the new directory. This confirms the current replacement path is teardown plus install rather than in-place update — [source: src/specify_cli/presets/__init__.py, PresetManager.install_from_directory()] (confidence: high, cited)
• The registry already has merge-preserving metadata updates and stores version, enabled, priority, and registered command/skill ownership. It also has get(), list_by_priority(), and restore() primitives that could support state retention and rollback, although no preset update orchestration currently uses them — [source: src/specify_cli/presets/__init__.py, PresetRegistry] (confidence: high, cited)
• The resolver intentionally recomputes the complete preset priority stack. collect_all_layers() gathers preset, extension, and core layers, while resolve_content() composes them according to strategy — [source: src/specify_cli/presets/__init__.py, PresetResolver.collect_all_layers() and resolve_content()] (confidence: high, cited)
• The project has prior source/provenance work for component updates: issue [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 describes recording URL/ref/commit information for --from installs and adding update support across extensions, presets, and workflows. That issue is marked completed, but the current preset install metadata shown in install_from_directory() still records source: "local" and does not visibly include the requested URL/ref/commit fields — [source: GitHub issue [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533; src/specify_cli/presets/__init__.py, install metadata] (confidence: medium, cited)
• Constitution synchronization is an existing opt-in precedent. The architecture documentation says normal preset operations do not materialize the live constitution, while an enabled constitution-sync preset may reconcile it with provenance protection — [source: presets/ARCHITECTURE.md, “Constitution lifecycle”] (confidence: high, cited)

Market & Context

• Presets are documented as stackable, priority-ordered customizations whose command overrides are registered during installation and cleaned up during removal; this makes update behavior cross-cutting rather than a simple directory replacement — [source: presets/README.md, “How It Works” and “Command Overrides”] (confidence: high, cited)
• The repository documents official and community catalogs, with catalog entries carrying an install_allowed policy; community presets are discovery-only by default and may require direct installation from a repository — [source: presets/README.md, “Catalog Management”; src/specify_cli/presets/_commands.py, preset_add()] (confidence: high, cited)
• Users can currently install a preset from a catalog, a local development directory, or an archive URL, but the repository does not provide evidence about competing product behavior or the market size for preset lifecycle management — [source: src/specify_cli/presets/_commands.py, preset_add(); [NEEDS CLARIFICATION: external market/prior-art comparison]] (confidence: medium, cited)

Data & Constraints

• Preset resolution precedence is priority-based: lower numeric priority wins, and disabled presets are excluded from the active stack unless explicitly requested — [source: PresetRegistry.list_by_priority() and presets/ARCHITECTURE.md] (confidence: high, cited)
• Install-time command reconciliation registers commands and skills after the preset is added to the registry; post-install reconciliation covers the affected command names, while failures are surfaced as warnings rather than making the install fail — [source: PresetManager.install_from_directory()] (confidence: high, cited)
• Constitution synchronization checks whether the existing constitution is still generated before materializing the resolved template, and skips authored/modified content. The materializer writes the resolved bytes and provenance sidecar but the inspected path has no content-hash equality short-circuit before writing — [source: src/specify_cli/presets/__init__.py, _reconcile_constitution() and _materialize_constitution_template()] (confidence: high, cited)
• The current removal path gathers registered commands, manifest-declared command aliases, skill ownership, and constitution provenance before deleting the preset, then performs restoration/reconciliation. This is substantial existing behavior that an update must avoid invoking twice through an implicit remove/add sequence — [source: PresetManager.remove()] (confidence: high, cited)
• The issue requires an atomic directory swap and crash recovery, but no existing preset-specific staging/swap/repair mechanism was found in the inspected source — [source: src/specify_cli/presets/__init__.py, install/remove paths; [NEEDS CLARIFICATION: acceptable recovery contract]] (confidence: medium, cited)

Evidence Against the Idea

• The requested behavior spans catalog resolution and policy, provenance, manifest diffing, command and skill registration, constitution synchronization, registry-state preservation, bulk isolation, atomic replacement, and recovery. The scope is substantially larger than adding a CLI alias, so implementation and maintenance cost may exceed the value for low-frequency updates — [source: acceptance criteria in GitHub issue [Feature]: specify preset update — in-place preset update with rollback and single-pass reconciliation #4427; current lifecycle code in src/specify_cli/presets/__init__.py] (confidence: high, cited)
• Existing registry metadata may be insufficient to auto-resolve older non-catalog installations because the inspected install path records only a generic local source. Without durable provenance, automatic update eligibility would be ambiguous and could force explicit --from/--dev inputs — [source: PresetManager.install_from_directory(); GitHub issue [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533] (confidence: high, cited)
• Presets can alter multiple agent-specific representations and compose across a priority stack. A partial or incorrectly ordered reconciliation could leave generated command/skill files inconsistent even if the preset directory swap succeeds — [source: presets/ARCHITECTURE.md; PresetManager.remove() and PresetResolver] (confidence: medium, cited)
• No repository evidence establishes how often users update presets, how costly the current workaround is in practice, or whether users would accept explicit source parameters instead of automatic discovery — [NEEDS CLARIFICATION: quantify the problem before committing to the full bulk/rollback scope] (confidence: high, assumption)

Gaps & Open Questions

• [NEEDS CLARIFICATION: Is the completed [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 implementation present on this revision for presets, or does this issue need to depend on additional provenance work?]
• [NEEDS CLARIFICATION: Should --all process disabled presets and preserve them disabled, or skip them?]
• [NEEDS CLARIFICATION: What exact manifest changes can be reconciled in place, especially ID changes, aliases, file moves, and strategy changes?]
• [NEEDS CLARIFICATION: What confirmation, dry-run, and output contract is required for single and bulk updates?]
• [NEEDS CLARIFICATION: What recovery behavior is required after a process crash during directory swap?]
• [NEEDS CLARIFICATION: What user/project telemetry or support evidence demonstrates update frequency and acceptable performance?]

Sources

• GitHub issue [Feature]: specify preset update — in-place preset update with rollback and single-pass reconciliation #4427 — primary request and acceptance criteria (host: github.com, policy: allowlisted)
• GitHub issue [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 — source/ref/commit provenance and cross-component update context (host: github.com, policy: allowlisted)
• src/specify_cli/presets/__init__.py — PresetRegistry, PresetManager, and PresetResolver implementation (source: repository)
• src/specify_cli/presets/_commands.py — installed preset command surface and catalog install policy (source: repository)
• presets/README.md and presets/ARCHITECTURE.md — documented preset behavior (source: repository)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4427 · 286.6 AIC · ⌖ 30 AIC · ⊞ 30.4K · ◷

[github-actions]

Feature assessment — preset-update · Stage 3/5: Problem

Problem Definition: specify preset update

• Slug: preset-update
• Created: 2026-09-03T16:53:35Z
• Inputs used: intake.md and research.md

Problem Statement

Spec Kit projects that depend on an installed preset cannot move that preset to a newer version through a dedicated lifecycle operation. They must remove and reinstall it, which can temporarily remove the preset from the resolution stack, repeat reconciliation work, and lose or reset registry state such as priority and enabled/disabled status.

Affected Users & Stakeholders

• Users: Spec Kit project maintainers using installed presets — they must assemble a remove/add workaround and may encounter intermediate or incorrect generated command, skill, or constitution state.
• Users: Preset authors and developers installing from local directories or archive URLs — they lack a predictable update path when a source is not catalog-resolvable.
• Stakeholders: Spec Kit maintainers — they own lifecycle behavior, compatibility guarantees, and backward compatibility for preset add and preset remove.
• Stakeholders: Preset authors and catalog maintainers — they depend on stable identity, provenance, compatibility, and install-policy semantics.
• Stakeholders: Teams reviewing generated artifacts — they need reconciliation to avoid unnecessary writes and to protect hand-edited constitutions.
• [NEEDS CLARIFICATION: quantify the population and update frequency for each affected user group.]

Goals

• Provide a safe, explicit way to move an already-installed preset to a compatible newer version without requiring remove-then-add.
• Preserve the preset's intentional registry state, including priority and enabled/disabled status, unless the user explicitly changes it.
• Keep the project’s resolved command, skill, and optional constitution state coherent throughout the update lifecycle.
• Make source eligibility and provenance requirements explicit for catalog, development, and archive-installed presets.
• Give users an understandable outcome and change summary for single and bulk update attempts.
• Preserve existing preset add and preset remove behavior as compatible operations.

Non-Goals

• Replacing preset add or preset remove.
• Changing the general preset resolution precedence or composition semantics.
• Automatically updating presets whose source cannot be safely re-resolved or explicitly supplied.
• Overwriting an authored or hand-edited constitution.
• Defining implementation-level APIs, data models, file layouts, or task breakdowns in this assessment.
• Expanding the request into updates for extensions or workflows beyond the preset-specific behavior, except where shared provenance must be reused.

Success Metrics

• An installed preset can be updated through one explicit operation, while an uninstalled ID fails clearly and directs the user to preset add (baseline: no update command; workaround is remove plus add).
• An update that omits --priority retains the prior priority, and an update preserves enabled/disabled state (baseline: the remove/add workaround can reset both).
• For a successful update, command/skill reconciliation runs once against the final preset stack, and constitution reconciliation runs no more than once when enabled (baseline: remove and install can each trigger reconciliation).
• Validation or pre-swap failure leaves the prior preset directory and registry entry unchanged (baseline: no dedicated update transaction or staging path is present in the inspected preset lifecycle).
• Bulk update reports each preset as updated, already latest, failed with reason, or skipped with reason, without one failure preventing independent items from being considered (baseline: no bulk preset update exists).
• A version change whose resolved constitution bytes are identical produces no constitution file write, while a generated-file guard continues to protect edited content (baseline: the inspected materializer writes resolved bytes without an equality short-circuit).
• [NEEDS CLARIFICATION: establish measurable performance and adoption targets, including acceptable update duration and expected reduction in failed/manual updates.]

Cost of Inaction

Projects continue to use a teardown-and-rebuild workaround that can create an intermediate state with no old or new preset layer, repeat full-stack reconciliation, and reset user-controlled registry state. Users of non-catalog sources remain unable to discover updates automatically, while maintainers must preserve increasingly complex install/remove behavior without a focused update contract. The frequency and business impact of these failures are not quantified.

Open Questions

• [NEEDS CLARIFICATION: Is the completed provenance work from [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 available and sufficient for preset auto-resolution on this revision?]
• [NEEDS CLARIFICATION: Should --all update disabled presets while leaving them disabled, or skip them entirely?]
• [NEEDS CLARIFICATION: Which manifest changes are safely reconcilable in place, and which require remove+add?]
• [NEEDS CLARIFICATION: What confirmation, dry-run, and summary output contract should single and bulk updates provide?]
• [NEEDS CLARIFICATION: What crash-recovery guarantee is required if the process stops during the directory swap?]
• [NEEDS CLARIFICATION: What evidence or threshold justifies the full bulk-update and recovery scope?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4427 · 286.6 AIC · ⌖ 30 AIC · ⊞ 30.4K · ◷

[github-actions]

Feature assessment — preset-update · Stage 4/5: Concept

Concept: specify preset update

• Slug: preset-update
• Created: 2026-09-03T16:53:35Z
• Recommended option: Option A — Focused single-preset update

Options

Option A — Focused single-preset update

+- Sketch: Let a maintainer update one already-installed preset from an explicitly supplied source or a durably catalog-resolvable source. The update keeps the preset’s existing registry state by default, validates the candidate before replacing the installed version, and refreshes affected generated command/skill/constitution state once against the final stack. Bulk updates remain a later extension after provenance and recovery behavior are proven.
+- Appetite: medium
+- Trade-offs: Wins a clear, high-value fix for the reported remove/add correctness gap while limiting the first release to a tractable workflow. Sacrifices --all, cross-preset failure isolation, and the broadest automation until demand and provenance are better established. Main risks are defining safe manifest compatibility and guaranteeing that reconciliation failures are visible without corrupting state.
+- Rabbit holes: Supporting every historical install source, interpreting arbitrary manifest renames as in-place changes, and reconciling all agent representations without invoking existing remove/add behavior twice.

Option B — Full transactional update and bulk management

+- Sketch: Deliver the entire requested lifecycle: single-preset and --all updates, catalog eligibility, durable source provenance, preserved registry state, candidate validation, transactional replacement and recovery, manifest-diff reporting, isolated bulk failures, and single-pass command/skill/constitution reconciliation.
+- Appetite: large
+- Trade-offs: Wins the most complete user experience and directly covers the full acceptance list. Sacrifices near-term delivery speed and increases the amount of behavior that must be specified, tested, documented, and kept compatible with existing agent-specific registration. Risk is high because the repository has no established preset staging/recovery contract and demand volume is unquantified.
+- Rabbit holes: Crash recovery after the swap itself, partial failures across many presets, catalog and archive provenance migrations, disabled-preset policy, and subtle interactions between changed aliases, composition strategies, and constitution provenance.

Option C — Document and harden the existing workaround

+- Sketch: Keep remove-plus-add as the supported update procedure, but document source requirements, warn about priority/enabled-state preservation, and improve diagnostics around reconciliation and authored constitutions. Defer a dedicated update operation until more usage evidence exists.
+- Appetite: small
+- Trade-offs: Wins low implementation risk and can clarify current behavior quickly. Sacrifices the requested atomicity, single-pass reconciliation, state-preserving update semantics, and convenient bulk management; it leaves the reported intermediate-state problem in place.
+- Rabbit holes: Documentation can become an implicit compatibility promise without fixing the underlying lifecycle, and incremental hardening may duplicate work needed for a later update command.

Recommendation

Recommend Option A as a bounded first concept because the repository and issue establish a real lifecycle gap, while evidence for update frequency and the requirements for bulk/crash recovery remain incomplete. It addresses the clearest goals — a dedicated single-preset path, preserved priority/enabled state, explicit source eligibility, pre-replacement validation, and one final reconciliation — without committing to a large automation surface before provenance and recovery questions are answered. Option B should be reconsidered after validating demand and defining the unresolved contracts; Option C is acceptable only as a temporary fallback, not as a resolution of the core problem.

Out of Scope (for the recommended option)

• preset update --all and per-preset bulk outcome aggregation.
• Automatic updates for sources without durable provenance or an explicit --from/--dev source.
• A general preset repair command or a guaranteed recovery workflow for a crash during the replacement step.
• In-place interpretation of preset ID renames, arbitrary file moves, or unreconcilable manifest restructuring; these remain clear remove+add cases.
• Updates to extension and workflow commands, except reuse of already-established shared provenance behavior.
• Changes to normal preset priority, composition, or constitution authorship rules.

Assumptions to Validate

• The completed provenance work associated with [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 is available on the target revision or can be reused without a parallel redesign.
• A single preset can be identified as the same logical preset when its incoming manifest retains the installed ID.
• Existing registry metadata is sufficient to preserve priority and enabled/disabled state when the update does not explicitly override them.
• Existing command, skill, and constitution reconciliation helpers can be invoked once against the final stack without changing preset add or preset remove.
• The majority of immediate value comes from safe single-preset updates; bulk updates can wait for evidence and a defined disabled-preset policy.
• [NEEDS CLARIFICATION: maintainers accept explicit remove+add fallback for unrecognized manifest changes.]
• [NEEDS CLARIFICATION: define the user confirmation and failure-reporting contract for the bounded update.]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4427 · 286.6 AIC · ⌖ 30 AIC · ⊞ 30.4K · ◷

[github-actions]

Feature assessment — preset-update · Stage 5/5: Decision — verdict needs-clarification

Decision: specify preset update

• Slug: preset-update
• Decided: 2026-09-03T16:53:35Z
• Verdict: needs-clarification
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	The issue describes a specific missing lifecycle operation, and repository code confirms that force installation removes an existing preset before copying the replacement.
Evidence strength	weak	The repository and issue substantiate the workflow mechanics, but demand comes from one request; update frequency, affected-project count, and comparative user evidence are absent.
Value vs. inaction	adequate	Avoiding intermediate stack state and accidental registry-state resets is meaningful, but the cost and frequency of the current workaround are unquantified.
Feasibility / appetite	adequate	The focused single-preset option fits a medium appetite and can reuse registry and reconciliation primitives; the full bulk/recovery scope has no established implementation contract.
Strategic fit	strong	The project constitution explicitly includes update in the shared CLI verb vocabulary and requires registry-driven, test-backed, idempotent changes, all of which align with the focused concept.
Risk posture	weak	Provenance availability, reconcilable manifest changes, disabled-preset behavior, confirmation semantics, and crash recovery remain unresolved; command/skill/constitution reconciliation spans several stateful surfaces.

Verdict & Rationale

Needs clarification. The problem is valid and a bounded single-preset concept is plausible, but the evidence is not strong enough for a go: the request does not quantify demand, and the acceptance criteria depend on unresolved provenance, manifest-compatibility, disabled-state, confirmation, and recovery contracts. Revisit research to establish usage and source/provenance facts, then revisit shape to confirm whether the focused option is the right first boundary and to resolve its explicit assumptions. The full bulk-update option should not proceed as scoped until those questions are answered.

If needs-clarification

• Blocking questions:
  • [NEEDS CLARIFICATION: What usage data, support examples, or additional stakeholder signals establish update frequency and the cost of the remove/add workaround?]
  • [NEEDS CLARIFICATION: Is the completed [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 provenance implementation present and sufficient on this revision for catalog and explicit-source preset updates?]
  • [NEEDS CLARIFICATION: Which manifest changes are safely reconcilable in place, and which require the documented remove+add fallback?]
  • [NEEDS CLARIFICATION: Should --all update disabled presets while leaving them disabled, or skip them entirely?]
  • [NEEDS CLARIFICATION: What confirmation, dry-run, failure-reporting, and crash-recovery guarantees are required for the first release?]
    +- Revisit stage: research, then shape

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4427 · 286.6 AIC · ⌖ 30 AIC · ⊞ 30.4K · ◷

[markuswondrak]

Answering the blocking questions:

1. Demand evidence — We're answering this through the feature gap itself rather than usage data (Spec Kit has no telemetry, so quantified demand will never materialize). The concrete correctness problems stand on their own: remove+add reconciles the constitution twice with a real intermediate window, and silently resets priority and enabled. Additionally this is a parity issue — specify extension update exists (including bulk), bundles have update flows, presets don't. Bulk update is explicitly in scope, with semantics identical to extension update: bare specify preset update updates all installed presets, preset update updates one; per-item outcome lines; one failure doesn't abort the rest.

2. [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 provenance — Not a blocker. We mirror extension update's resolution: catalog lookup by preset ID (no durable provenance needed), same _install_allowed enforcement, version compare via PEP 440. Presets installed via --from/--dev fail with a clear "source not re-resolvable — supply --from/--dev explicitly" error, per the existing acceptance criteria. [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 provenance remains a useful follow-up but is not required for this feature.

3. Reconcilable manifest changes — Simple rule: an update proceeds iff the incoming manifest validates and its id matches the installed preset. Everything else inside the manifest (version bump, template changes, composition strategies, aliases, added/removed files) is reconcilable, because the resolver recomputes the full stack from disk anyway. Not reconcilable → clear error pointing at remove+add: ID rename, unparseable/corrupt manifest, missing files.

4. Disabled presets under bulk — Follow extension update semantics: bulk processes all installed presets, preserving each one's registered enabled state (never re-enables a disabled preset). A single preset update on a disabled preset updates its files and keeps it disabled.

5. Confirmation / dry-run / crash-recovery for release 1 — Same contract as extension update: no interactive prompt for a single update; one confirmation prompt for a batch; a --dry-run flag printing the manifest diff and planned actions without touching anything. Recovery reuses the extension-update pattern rather than inventing a new one: validation before any modification, per-item backup under the presets directory, rollback on failure, and a guard ensuring validation failures leave an untouched installation untouched. No dedicated preset repair command.

Net effect on the concept: bulk updates come in version 1 (cheap, since the mechanism is identical to extensions), while the genuinely heavy parts of Option B — durable provenance and a repair command — stay out of scope. Single-pass command/skill/constitution reconciliation and the constitution hash short-circuit from the acceptance criteria remain as specified.

[digimangos]

Changes to original acceptance criteria (from @markuswondrak's clarification-answers comment)

The answers above supersede three specific points from the original acceptance criteria:

• [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 is no longer a dependency. The "Catalog-only eligibility" section originally said provenance persisted for [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 "should be reused here rather than re-invented." That's reversed: catalog-eligible re-resolution works by ID lookup alone (same model as specify extension update), and [Feature]: Record install source (URL / ref / commit) for extensions, presets, and workflows installed via --from, and support them in update #3533 is not required to land first.
• preset repair is no longer an acceptable recovery mechanism. The "Rollback on failure" section originally offered a crash-recovery path as "a .bak directory retained, or a preset repair command" — either was fine. That option is removed: recovery must follow the extension-update backup/rollback pattern only, no dedicated repair command.
• The unreconcilable-restructuring criterion is narrowed. The "Compatibility with existing workflows" section originally left this open-ended — id rename "or otherwise restructures its layout in a way a diff can't reconcile." That's replaced with an exact, closed list: id rename, unparseable/corrupt manifest, or missing referenced files. Nothing else (e.g. a template's type changing, a schema_version bump) is treated as a separate reject reason — it either passes manifest validation or it doesn't.

Everything else in the original criteria stands as specified.

Additional acceptance criteria

Catalog-only eligibility

• Automatic re-resolution mirrors specify extension update's existing model: catalog lookup by preset ID (no durable provenance record needed), the same _install_allowed enforcement, and version comparison via PEP 440.
• Presets installed via --from/--dev (i.e. not resolvable back to a catalog entry) fail update with a clear "source not re-resolvable — supply --from/--dev explicitly" error.

Bulk update (--all)

• Bulk semantics match specify extension update exactly: bare specify preset update (no id) updates all installed presets; preset update <id> updates one. Per-item outcome lines are printed; one item's failure does not abort processing of the rest.
• Bulk update preserves each preset's registered enabled state — a disabled preset's files are still updated, but it is never re-enabled by the bulk run.
• preset update <id> on a disabled preset updates its files and keeps it disabled (single-item case, same rule as bulk).

Reconcilable manifest changes

• An update proceeds if and only if the incoming manifest validates and its id matches the installed preset's id. All other manifest changes — version bump, template additions/removals/content changes, composition strategy changes, alias changes — are reconcilable, since the resolver recomputes the full stack from disk regardless.
• Update fails clearly and points at the remove+add workaround for exactly: preset id rename, an unparseable/corrupt manifest, or missing referenced files.

Confirmation / dry-run / crash-recovery contract (release 1)

• No interactive confirmation prompt for a single-preset update; one confirmation prompt for a bulk (--all) update.
• --dry-run prints the manifest diff and planned actions without modifying any file, directory, or registry entry.
• Recovery reuses the existing specify extension update pattern: validation runs before any modification; a per-item backup is kept under the presets directory during the swap; rollback restores the previous state on failure; a validation failure leaves the existing installation completely untouched.

[digimangos]

The proposed implementation is now available in PR #4441: #4441. It adds single and bulk specify preset update, catalogue/--from/--dev sources, dry-run support, manifest reconciliation, atomic rollback, state preservation, constitution safeguards, and regression coverage. Posted on behalf of @digimangos by GitHub Copilot (model: GPT-5.6 Luna, autonomous).