[Feature]: Let a preset declare a required extension in `requires.extensions`

[Yash-Chindam]

Problem Statement

A preset cannot declare that it depends on an extension, so a preset that is useless without one installs silently and appears broken.

@mnriem identified this in #4164 (comment) while reviewing the speckit-inventory / inventory-alignment pair, and suggested tracking it separately rather than blocking that submission:

One genuine gap worth noting: preset.yml's requires: only declares speckit_version, so there's no formal "requires extension X" dependency to guarantee the extension is installed alongside the preset. That's a small, separable core enhancement I'd track on its own issue rather than block this on.

Filing it as suggested. There are three concrete parts to the gap:

1. The manifest cannot express it. PresetManifest validation requires requires.speckit_version and validates nothing else in that section, so there is no supported key for an extension dependency. ExtensionManifest has the same limitation.

2. The catalog already expresses it anyway. Three community presets in presets/catalog.community.json currently carry a requires.extensions array:

Preset	requires.extensions
aide-in-place	["aide"]
inventory-alignment	["speckit-inventory"]
mde	["mde"]

So the field is already a de-facto convention in the catalog, and the preset submission template even has a "Required Extensions (optional)" input that feeds it. But it exists only as catalog metadata — it cannot be declared in the preset package itself, which means it is absent when a preset is installed with --dev or --from <url>, i.e. exactly the paths that bypass the catalog.

3. Nothing enforces it. I could not find any code path that reads requires.extensions to gate or warn on installation. It appears to be purely descriptive.

The user-visible result: install one of those three presets without its extension and the install succeeds, the templates resolve, and the command overrides register — but the parts that call into the extension quietly do nothing. The workflow still runs correctly, so nothing errors; the feature just appears not to work, with no signal pointing at the missing extension.

Proposed Solution

Make the dependency declarable in the manifest and checked at install time.

Schema. Accept an optional requires.extensions in preset.yml, mirroring the shape already used in the catalog:

requires:
  speckit_version: ">=0.9.0"
  extensions:
    - id: speckit-inventory
      version: ">=0.1.0"   # optional
      required: true        # optional, default true

A plain list of id strings (extensions: ["speckit-inventory"]) should also be accepted, since that is what the three existing catalog entries use.

Validation. Validate the section like speckit_version is validated today: reject non-list values, non-string/non-mapping members, and ids that do not match the existing ^[a-z0-9-]+$ id pattern. #3980 ("reject non-string requires.speckit_version") is the precedent for the strictness level here.

Install-time check. On specify preset add, compare declared dependencies against installed extensions and:

• if a required: true dependency is missing, warn clearly and name the extension plus the exact specify extension add command that would satisfy it;
• if a version constraint is unsatisfied, warn with both the required and installed versions.

I would suggest warn, not hard-fail, at least initially. These preset overrides are written to degrade safely — without the extension, the core workflow runs unchanged — so blocking the install would be harsher than the situation warrants, and would break the three catalog entries above for anyone who deliberately wants the preset alone. A --force-style escape hatch would be needed if it ever became a hard failure.

Extensions too, if desired. extension.yml has the identical limitation. Extending both keeps the two manifest schemas symmetric, though the preset side is where the demonstrated need is.

Alternatives Considered

Document the pairing in the README and stop there. This is the current workaround, and what the inventory-alignment and aide-in-place READMEs do. It fails because the person who needs the warning is the one who did not read the README — and nothing in the install output points at the problem.

Enforce from the catalog entry only. The data is already there for three presets, so this is the smallest change. But it does nothing for --dev and --from <url> installs, which is how presets are tested and how anything not yet listed is installed. The dependency belongs with the package that has it.

Hard-fail the install on a missing dependency. Cleaner semantics, but it would immediately break installs of the three presets already declaring the field, and it overrides an author who deliberately designed for safe degradation. Better as a later opt-in (required: true already leaves that door open) than as the initial behavior.

Leave it to a package manager. #2566 proposed a community package manager with conflict detection and was closed. Dependency declaration is a manifest concern and much smaller in scope than that proposal.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

All agents

Use Cases

1. A read-only primitive plus the preset that wires it in. This is the shape @mnriem recommended in #4164 and that speckit-inventory + inventory-alignment now implement: an extension provides the capability, and a preset overrides core commands to call it. The preset is inert alone. Same shape as aide-in-place + aide and mde + mde.

2. Testing a pair locally before submitting. With --dev installs the catalog is not consulted at all, so an author gets no feedback that they have installed half of their own pair — the case most likely to produce a confused bug report.

3. Maintainer vetting. The submission template collects "Required Extensions" today, but nothing downstream can verify the claim against the package. A manifest field makes it checkable.

Acceptance Criteria

• preset.yml accepts an optional requires.extensions, in both the id-string-list and the mapping form.
• Invalid shapes are rejected with a clear message, consistent with the existing requires.speckit_version validation.
• Omitting requires.extensions remains valid; every existing preset continues to install unchanged.
• specify preset add warns when a declared required: true dependency is not installed, naming the extension and the command that installs it.
• specify preset add warns when a declared version constraint is unsatisfied, showing required vs installed.
• The warning appears for --dev, --from <url>, and catalog installs alike.
• Unit tests cover: valid declaration in both forms, each invalid shape, dependency satisfied, dependency missing, and version mismatch.
• presets/PUBLISHING.md and the preset schema docs document the new field.
• Decide whether the three catalog entries already carrying requires.extensions should be reconciled with the manifests in their source repos, or whether catalog and manifest are allowed to state it independently.

Additional Context

I ran into this as the author of the inventory-alignment preset (#4227, merged in #4229). The robot that added my catalog entry had to patch the dependency back in by hand — its follow-up commit reads "Restore the required speckit-inventory dependency and pin the submitted release archive SHA-256" — which is itself a small sign that the information wants to live somewhere more reliable than a catalog entry assembled from an issue form.

I searched open and closed issues for this and did not find an existing report; the closest is #2566, which was closed and much broader in scope. Happy to be pointed at a duplicate if I missed one.

I am willing to implement this if the approach and the warn-versus-fail decision are acceptable — please confirm the direction before I open a PR, and let me know if you would prefer the extension.yml side included or left out of the first change.

AI disclosure. Filed on behalf of @Yash-Chindam by Claude Code (model: Claude Opus 5), acting autonomously. Per CONTRIBUTING, this used AI assistance for research and drafting: Claude Code inspected the preset and extension manifest validation, searched for prior issues, surveyed the community catalogs for existing requires.extensions usage, and wrote this issue. I reviewed it before filing.

[github-actions]

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

Idea Intake: Preset Extension Dependency Declaration

• Slug: preset-extension-dependency
• Created: 2026-08-20
• Source: GitHub issue [Feature]: Let a preset declare a required extension in requires.extensions #4231
• Type: improvement

Idea (as captured)

A preset cannot declare that it depends on an extension, so a preset that is useless without one installs silently and appears broken. [...] Make the dependency declarable in the manifest and checked at install time.

The issue proposes: (1) adding an optional requires.extensions field to preset.yml (and optionally extension.yml), validated like requires.speckit_version; (2) checking at specify preset add time whether declared required: true extension dependencies are installed, and warning (not hard-failing) when they are not.

Restated

Presently, preset.yml has no supported key for declaring which extensions it depends on, so installing a preset without its companion extension produces a silently broken experience. This improvement would add schema support for requires.extensions, validate it, and surface a warning at install time when the dependency is absent.

Origin & Context

• Raised by: @Yash-Chindam
• Trigger: @mnriem identified the gap while reviewing the speckit-inventory / inventory-alignment preset submission ([Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164), and suggested it be tracked as a separate issue. Filed by the author of inventory-alignment after that merge.

First-Glance Unknowns

• [NEEDS CLARIFICATION: Should extension.yml gain the same requires.extensions field in the same PR, or be a follow-on?]
• [NEEDS CLARIFICATION: Should the check be a warning or a hard-fail initially? (Issue proposes warn; the opt-in required: true flag could later enable hard-fail.)]
• [NEEDS CLARIFICATION: Should specify preset add --dev/--from <url> also check extension versions, or only presence?]
• [NEEDS CLARIFICATION: How should the three existing catalog entries that already carry requires.extensions be reconciled — should each preset's source preset.yml also declare it, or is catalog/manifest independence acceptable?]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6), acting autonomously.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4231 · 654.8 AIC · ⌖ 17 AIC · ⊞ 36.4K · ◷

[github-actions]

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

Idea Research: Preset Extension Dependency Declaration

• Slug: preset-extension-dependency
• Created: 2026-08-20
• Evidence confidence (overall): high

Users & Demand

• The author of inventory-alignment (@Yash-Chindam) encountered this gap directly while building and submitting a preset that requires the speckit-inventory extension. First-hand user signal from a community contributor. (confidence: high, cited: issue [Feature]: Let a preset declare a required extension in requires.extensions #4231)
• @mnriem identified the gap during code review of [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164 and explicitly requested it be tracked separately. Maintainer call-out during review is strong signal the gap was already known before a user hit it. (confidence: high, cited: [Feature]: Stop grep-based spec alignment, structured IDs + context packs #4164 comment in issue body)
• Three of 33 community presets (9%) already declare requires.extensions in catalog.community.json (aide-in-place, inventory-alignment, mde), yet no code reads this field for enforcement. The field exists as a de-facto convention. (confidence: high, cited: presets/catalog.community.json)

Prior Art

• requires.speckit_version — Both PresetManifest and ExtensionManifest already validate a version constraint at install time (_validate() + check_compatibility()). The precedent for typed, validated, install-time requires checking is firmly established. (cited: src/specify_cli/presets/__init__.py:360–382, src/specify_cli/extensions/__init__.py:343–368)
• requires.tools and requires.mcp in BundleManifest — The bundle layer's Requires dataclass accepts tools and mcp string lists alongside speckit_version. A parallel extensions list in the preset manifest follows the same pattern. (cited: src/specify_cli/bundler/models/manifest.py:50–53)
• Issue [Feature]: Spec Kit Package Manager — community CLI for extension/preset discovery, install, version pinning, and conflict detection #2566 (closed) — A broader community package manager with conflict detection was proposed and closed. This request is explicitly narrower: manifest-level declaration + install-time warning only. (cited: issue [Feature]: Let a preset declare a required extension in requires.extensions #4231 body)
• Issue fix(manifests): reject non-string requires.speckit_version #3980 — Established the precedent of "reject non-string requires.speckit_version" with strict type validation. The proposed feature follows the same strictness philosophy. (cited: CHANGELOG.md, tests/test_presets.py:421–436)
• Preset submission template — already has a "Required Extensions (optional)" input that feeds requires.extensions in the catalog. The concept is accepted convention; it just lacks implementation. (cited: issue [Feature]: Let a preset declare a required extension in requires.extensions #4231 body)

Market & Context

• Alternative today: preset authors document the dependency in their README. This fails exactly the user who did not read the README — the common case.
• Cost of doing nothing: users install presets silently, find features non-functional, file bug reports, never discovering the missing extension. Each of the three catalog presets is a latent silent-failure.

Data & Constraints

• 33 community presets in the catalog; 3 already declare requires.extensions (unenforced). (cited: presets/catalog.community.json)
• PresetManifest._validate() currently validates only requires.speckit_version; any extra keys (including requires.extensions) are silently ignored. (cited: src/specify_cli/presets/__init__.py:360–382)
• CatalogEntry.from_dict() reads requires.speckit_version from catalog JSON but does not store or expose requires.extensions. (cited: src/specify_cli/bundler/models/catalog.py:188–189)
• The preset add command calls install helpers; none check extension deps at any install path (--dev, --from, catalog). (cited: src/specify_cli/presets/_commands.py:89–128)
• ExtensionManifest._validate() has the identical limitation — only requires.speckit_version checked. (cited: src/specify_cli/extensions/__init__.py:343–368)

Evidence Against the Idea

• Warn-only may be too weak: a warning that can be ignored is arguably insufficient if the preset is useless without the extension. The issue author argues for warn first, with required: true leaving a door open for future hard-fail. Reasonable initial posture.
• Scope creep risk: extending extension.yml symmetrically increases PR scope. Change is straightforward in both places but the decision should be explicit.
• Catalog/manifest duplication: having requires.extensions in both catalog JSON and preset.yml creates two places to keep in sync with no automatic reconciliation.

Gaps & Open Questions

• [NEEDS CLARIFICATION: Should extension.yml be included in the first change?]
• [NEEDS CLARIFICATION: Should version constraints on extension deps be enforced at install time in v1, or only presence?]
• [NEEDS CLARIFICATION: How should catalog vs. manifest duplication of requires.extensions be handled — independent, authoritative-manifest, or reconciled?]

Sources

• [Feature]: Let a preset declare a required extension in requires.extensions #4231 (host: github.com, policy: allowlisted)
• Local checkout: presets/catalog.community.json, src/specify_cli/presets/__init__.py, src/specify_cli/extensions/__init__.py, src/specify_cli/bundler/models/manifest.py, src/specify_cli/presets/_commands.py, CHANGELOG.md

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6), acting autonomously.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4231 · 654.8 AIC · ⌖ 17 AIC · ⊞ 36.4K · ◷

[github-actions]

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

Problem Definition: Preset Extension Dependency Declaration

• Slug: preset-extension-dependency
• Created: 2026-08-20
• Inputs used: intake.md | research.md

Problem Statement

When a community preset requires a companion extension to function, there is no supported way to declare that dependency in preset.yml, so specify preset add installs the preset silently even when the extension is absent — leaving users with a workflow that appears to run but silently does nothing.

Affected Users & Stakeholders

• Users: any Spec Kit user who installs a community preset that pairs with an extension (inventory-alignment + speckit-inventory, aide-in-place + aide, mde + mde). They experience features that silently do nothing with no actionable error.
• Preset authors: community contributors building preset+extension pairs. Currently forced to rely on README documentation; no way to make the CLI surface the dependency at install time.
• Maintainers: @mnriem and the core team, who manually inspect whether a catalog entry's requires.extensions matches the package's actual dependencies.

Goals

• Enable a preset author to declare requires.extensions in preset.yml, in both string-list form and the richer mapping form (with optional version and required keys), validated like requires.speckit_version today.
• Have specify preset add warn clearly — naming the extension and the install command — when a declared required: true dependency is missing or version-unsatisfied, across all install paths (--dev, --from <url>, catalog).
• Validate the field shape strictly (type, id pattern ^[a-z0-9-]+$, non-string rejection) so malformed manifests fail with a clean PresetValidationError.

Non-Goals

• Hard-failing the install — out of scope for the initial change; warn-only.
• Resolving requires.extensions from the catalog entry alone — dependency must travel with the package.
• Full package-manager conflict detection (issue [Feature]: Spec Kit Package Manager — community CLI for extension/preset discovery, install, version pinning, and conflict detection #2566 scope) — explicitly out of scope.
• Automatically installing missing extensions — out of scope.

Success Metrics

• All three existing catalog presets can carry requires.extensions in their preset.yml without breaking existing installs. (baseline: field is accepted but silently ignored today)
• Installing one without the declared extension produces a warning naming the extension and the specify extension add <id> command. (baseline: no warning today)
• Installing with the extension already present produces no new output. (baseline: n/a)
• Unit tests cover: valid declaration (both forms), each invalid shape, dependency satisfied, dependency missing, version mismatch.
• (qualitative) Community preset authors adopt the field by default for extension-paired presets.

Cost of Inaction

Three community presets already carry requires.extensions in the catalog with no enforcement. Every user who installs one without its companion extension gets a silently broken workflow. As more extension+preset pairs are submitted (an explicitly encouraged pattern), the problem grows proportionally.

Open Questions

• [NEEDS CLARIFICATION: Should extension.yml gain the same field in the same PR for schema symmetry?]
• [NEEDS CLARIFICATION: Should version constraint checking on extension deps be included in v1 or deferred?]
• [NEEDS CLARIFICATION: Policy on catalog vs. manifest independence — duplication acceptable, or should one be authoritative?]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6), acting autonomously.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4231 · 654.8 AIC · ⌖ 17 AIC · ⊞ 36.4K · ◷

[github-actions]

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

Concept: Preset Extension Dependency Declaration

• Slug: preset-extension-dependency
• Created: 2026-08-20
• Recommended option: B — Validate schema + warn at install time

Options

Option A — Document-only (status quo + policy)

• Sketch: Codify the existing README convention as official guidance in presets/PUBLISHING.md. No code change. The three catalog entries continue to carry requires.extensions as unenforced metadata.
• Appetite: small (hours)
• Trade-offs: Zero risk of breaking existing installs. No benefit to users who skip the README, which is the entire failure mode described in this issue.
• Rabbit holes: None.

Option B — Validate schema + warn at install time (recommended)

• Sketch: Add requires.extensions as an optional, validated field to PresetManifest._validate(), accepting both the id-string-list form and the richer mapping form (with version and required keys). On specify preset add — across all install paths (--dev, --from <url>, catalog) — compare declared deps against installed extensions and emit a warning (not an error) for each missing or version-unsatisfied required: true dep, naming the extension and the specify extension add <id> command. Optionally extend ExtensionManifest symmetrically. Validation strictness follows the requires.speckit_version precedent (fix(manifests): reject non-string requires.speckit_version #3980): reject non-list values, non-string/non-mapping members, ids failing ^[a-z0-9-]+$.
• Appetite: medium (days–week). Validation change is small; install-time check requires touching all three install paths consistently.
• Trade-offs: Directly solves the problem for all install paths. Warn-only is safe — no existing installs break. ExtensionRegistry.get_extension() already provides installed-extension lookup.
• Rabbit holes: Keeping --dev, --from <url>, and catalog paths in sync. Catalog JSON requires.extensions vs. preset.yml can diverge; a policy decision is needed (not enforced in v1).

Option C — Hard-fail on missing required deps

• Sketch: Same schema change as B, but required: true deps cause specify preset add to abort, requiring --force to override.
• Appetite: medium (similar to B, plus --force flag)
• Trade-offs: Cleaner semantics but immediately breaks installs for users who want the preset without the extension — a valid use case. Better as a later opt-in.
• Rabbit holes: Breaking change risk for any user who has scripted specify preset add <id> without the companion extension.

Recommendation

Option B — Validate schema + warn at install time.

The problem is real, well-evidenced (3 of 33 community presets affected; maintainer-identified pattern), and the solution fits cleanly into the existing requires.speckit_version validation architecture. Warn-not-fail respects preset authors who design for safe degradation, matches the issue author's explicit preference, and avoids breaking any existing install.

Out of Scope (for Option B)

• Hard-failing the install on a missing dep (future opt-in)
• Automatically installing missing extensions
• Reconciling catalog JSON requires.extensions with package manifest (policy, not code)
• Full dependency conflict detection ([Feature]: Spec Kit Package Manager — community CLI for extension/preset discovery, install, version pinning, and conflict detection #2566 scope)

Assumptions to Validate

• ExtensionRegistry.get_extension(extension_id) is accessible from the preset install code paths without major refactor. [NEEDS CLARIFICATION]
• Policy on catalog/manifest independence for requires.extensions — accepted duplication, or one authoritative? [NEEDS CLARIFICATION: maintainer decision]
• Whether extension.yml is in scope for the same PR. [NEEDS CLARIFICATION: maintainer decision]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6), acting autonomously.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4231 · 654.8 AIC · ⌖ 17 AIC · ⊞ 36.4K · ◷

[github-actions]

Feature assessment — preset-extension-dependency · Stage 5/5: Decision — verdict go

Decision: Preset Extension Dependency Declaration

• Slug: preset-extension-dependency
• Decided: 2026-08-20
• Verdict: go
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	Real, demonstrated failure mode: 3 of 33 community presets carry requires.extensions in the catalog with zero enforcement; maintainer and author both independently identified the gap. Silent install + broken feature = strong problem signal.
Evidence strength	adequate	Direct user signal (preset author hit the bug), maintainer call-out during review, codebase verification of the gap in PresetManifest._validate() and all install paths. Three concrete affected presets confirmed by reading catalog.community.json. No user telemetry, but the structural gap is unambiguous from code inspection.
Value vs. inaction	strong	Every install of the three affected presets without the companion extension is a latent silent failure. The extension+preset pattern is actively encouraged, so the problem grows. The fix is bounded and directly targeted.
Feasibility / appetite	strong	Implementation follows established patterns: requires.speckit_version validation (#3980) is the direct precedent; ExtensionRegistry.get_extension() provides installed-extension lookup; all install paths are already in scope of preset add. Medium appetite with clear scope.
Strategic fit	strong	Symmetrical with requires.speckit_version; consistent with the bundle layer's requires.tools/requires.mcp. The preset submission template already collects the field — this brings the manifest up to the convention the catalog already uses.
Risk posture	strong	Warn-only approach means no existing install breaks. required: true flag design leaves a door open for future hard-fail. Validation strictness bounded by the ^[a-z0-9-]+$ id pattern and type checks established by #3980.

Verdict & Rationale

go. The problem is structurally confirmed in code, has immediate real-world impact on three existing community presets, and the recommended solution (Option B: schema validation + install-time warning) fits the existing architecture cleanly. Evidence strength is adequate: the gap is unambiguous from code inspection and catalog data, even without broad user telemetry. The warn-not-fail posture removes breaking-change risk. Three open questions remain (extension.yml scope, version-constraint enforcement in v1, catalog/manifest duplication policy) but none blocks implementation — they are scope decisions to resolve at the PR stage, not gate conditions.

Handoff to /speckit.specify

• Problem: preset.yml has no supported key for declaring extension dependencies, so specify preset add installs silently when a required extension is absent, producing a broken workflow with no diagnostic output.
• Chosen approach: Option B — add requires.extensions as an optional, validated field to PresetManifest (and optionally ExtensionManifest); emit a clear warning at specify preset add time when declared required: true deps are missing or version-unsatisfied, across all install paths.
• In scope: preset.yml schema (requires.extensions, both string-list and mapping forms), PresetManifest._validate() validation (strict, matching fix(manifests): reject non-string requires.speckit_version #3980), specify preset add install-time check (all paths: --dev, --from <url>, catalog), presets/PUBLISHING.md documentation update, unit tests covering valid/invalid shapes + dep satisfied/missing/version-mismatch.
• Out of scope: hard-fail on missing dep, automatic extension installation, full dependency conflict detection ([Feature]: Spec Kit Package Manager — community CLI for extension/preset discovery, install, version pinning, and conflict detection #2566), mechanical catalog/manifest reconciliation.
• Success metrics: existing installs unaffected; missing-dep warning appears for all install paths; unit tests cover all new validation branches.
• Carried-forward open questions:
  • [NEEDS CLARIFICATION: Should extension.yml be in scope for the same PR?]
  • [NEEDS CLARIFICATION: Should version constraint checking on extension deps be enforced in v1?]
  • [NEEDS CLARIFICATION: Policy on catalog vs. manifest duplication of requires.extensions.]
  • [NEEDS CLARIFICATION: Confirm ExtensionRegistry.get_extension() is accessible from preset install code paths without major refactor.]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6), acting autonomously.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4231 · 654.8 AIC · ⌖ 17 AIC · ⊞ 36.4K · ◷