[Bug]: `specify preset add` no longer scaffolds commands — backward compatibility break for presets that previously created commands

[nicolehaugen]

Bug Description

specify preset add currently only overrides the templates used to generate command content and is applied at init time. It does not scaffold commands/skills the way extensions and bundles do.

This is a backward-compatibility break for presets (and users) that previously relied on specify preset add to create commands — those presets now silently produce incomplete results (templates present, but no corresponding command/skill scaffolded).

Behavior is documented in the speckit-preset skill in github/spec-kit-copilot:

"Unlike extensions/bundles, specify preset add does not scaffold skills — a preset overrides the templates used to generate command content and is applied at init time."

Source: https://github.com/github/spec-kit-copilot/blob/main/skills/speckit-preset/SKILL.md

Steps to Reproduce

1. Take a preset that previously (in an earlier Spec Kit version) resulted in commands being scaffolded via specify preset add.
2. On a current version of specify, run specify preset add <id> against an already-initialized project.
3. Observe that no commands/skills are scaffolded; only template overrides apply, and only at specify init time.

Expected Behavior

Presets that previously scaffolded commands should remain backward compatible. Options:

1. Detect legacy-style presets that include command definitions and scaffold the corresponding commands/skills, matching prior behavior.
2. Emit a clear deprecation/migration warning when specify preset add is invoked against a preset that appears to define commands, pointing users to convert those to an extension or bundle.
3. Update Spec Kit docs to explicitly describe the preset vs. extension/bundle boundary and the supported migration path.

Actual Behavior

specify preset add only overrides templates used to generate command content, and only at init time. Presets authored against earlier versions expecting command scaffolding produce no commands, with no migration warning.

Specify CLI Version

0.16.0

AI Agent

GitHub Copilot

Operating System

Win 11

Python Version

python 3.12.0

Error Logs

Additional Context

Related skill docs in github/spec-kit-copilot (skills/speckit-preset/SKILL.md) will need a follow-up update once the core behavior is finalized here.

Filed from a conversation reviewing the speckit-preset skill notes; the underlying preset resolution and init-time template application are owned by the core spec-kit CLI, so tracking here rather than in the Copilot skills repo.

[github-actions]

Bug assessment — preset-add-no-scaffold: Likely valid, needs reproduction · severity medium

---

Bug Assessment: specify preset add silent no-scaffold on command-type templates

• Slug: preset-add-no-scaffold
• Created: 2026-08-12T17:51:00Z
• Source: issue [Bug]: specify preset add no longer scaffolds commands — backward compatibility break for presets that previously created commands #4076
• Verdict: likely valid, needs reproduction
• Severity: medium

Report (summarized)

Reporter (@nicolehaugen) observes that specify preset add installs a preset but does not scaffold any commands or skills into the active agent's directory. Only template overrides are applied, and only during a subsequent specify init. Presets authored for earlier Spec Kit versions that expected commands to be scaffolded immediately on preset add now produce no command/skill files with no migration warning. Reported against v0.16.0, Python 3.12.0, Windows 11, GitHub Copilot agent.

The report cites documentation from github/spec-kit-copilot (skills/speckit-preset/SKILL.md), which states presets "do not scaffold skills — a preset overrides the templates used to generate command content and is applied at init time." The reporter treats this as documenting a regression, not intended design.

The external URL (https://github.com/github/spec-kit-copilot/blob/main/skills/speckit-preset/SKILL.md) is a public GitHub URL; fetch was not performed because it is a private repository reference outside this codebase and not needed for code analysis.

Symptom

Running specify preset add <id> on an already-initialized project produces no command or skill files in the active agent's directory. Expected: command/skill files from the preset's type: command templates are scaffolded immediately, as they were in earlier Spec Kit versions.

Reproduction

1. Initialize a project: specify init my-project --integration <agent>
2. Install a preset that declares type: command templates: specify preset add <preset-id>
3. Inspect the active agent's command/skill directory (e.g., .claude/skills/, .gemini/commands/)
4. Observe that no new command/skill files were written — only template overrides are staged

[NEEDS CLARIFICATION: Exact preset used, its preset.yml content, and whether the commands are core (speckit.specify), extension-scoped (speckit.<ext>.<cmd>), or brand-new names not in core Spec Kit]

Suspected Code Paths

• src/specify_cli/presets/__init__.py:845 — _register_commands(): the primary scaffolding function; code review shows it IS called during install_from_directory (line 3599), so silent no-op must come from a guard inside.
• src/specify_cli/presets/__init__.py:873–881 — extension-installed filter: commands with a speckit.<ext-id>.<cmd> pattern are dropped entirely when the named extension is not installed in the project. If the preset's commands follow this naming pattern and the extension is absent, filtered becomes empty and the function returns {}.
• src/specify_cli/presets/__init__.py:946–976 — single-active rule (Extension commands aren't rendered as skills for non-active skills-mode agents on add/install/upgrade #2948): resolve_active_agent_for_registration is called; if init-options.json exists but the "ai" key resolves to None (corrupt, empty, or unknown agent key), line 950 returns {} immediately — zero commands registered, zero console output, no error.
• src/specify_cli/agents.py:1171–1173 — should_register guard: registration is only attempted when agent_dir_existed is True. If the expected agent directory does not exist (e.g., .claude/ missing after a non-standard init), all commands are silently skipped.
• src/specify_cli/presets/_commands.py:79–284 — preset_add command handler: the success message at line 221/229 reports the preset was "installed" without indicating whether any commands were actually scaffolded. A no-op scaffold is indistinguishable from a successful one in the CLI output.

Root Cause Hypothesis

Confidence: medium.

The most likely causes of silent no-scaffold are the extension-qualified name filter (lines 873–881) and the single-active rule early-return (lines 946–976), not a missing call to _register_commands. The code clearly calls _register_commands during install_from_directory, so the issue is a guard inside that function returning {} silently.

The two most plausible triggers:

1. Extension-scoped commands without the extension installed: if the preset's commands are named speckit.<ext-id>.<cmd> but the extension <ext-id> is not installed, _extension_installed_for_command returns False for every command, the filtered list is empty, and _register_commands returns {} — no files written, no warning.
2. init-options.json present but "ai" value unresolvable: resolve_active_agent_for_registration returns None (not MISSING_INIT_OPTIONS_FILE) when the file exists but the recorded agent key doesn't match any registrar config. Line 950 returns {} with no output.

A secondary contributor is that the CLI success message ("Preset '...' installed") gives no indication of whether commands were scaffolded — leaving users unable to distinguish a correct install from a silent failure. The external skill doc ("presets do not scaffold") may have been written to describe the template-override mechanism rather than command scaffolding, but it now matches the user-observed behavior, suggesting the no-scaffold path is being hit in practice.

Proposed Remediation

Preferred: Add explicit console feedback when _register_commands / _register_skills returns empty for a preset that declares type: command templates.

• When filtered is empty due to the extension filter (_extension_installed_for_command), emit a [yellow]Warning[/yellow] listing which commands were skipped and why (extension not installed).
• When the single-active rule returns {} because resolved_agent is None, emit a [yellow]Warning[/yellow] that no commands were registered because the active integration could not be resolved, and suggest running specify integration use <agent> first.
• After install_from_directory, if registered_commands == {} and the preset has type: command templates, print a summary note: "No commands scaffolded — run specify integration use <agent> to scaffold them for the active integration."

Alternative:

• Guard at the preset_add command level: after manager.install_from_directory(...), check manifest.templates for type: command entries and compare against the returned registered_commands; if a gap exists, warn the user and print the remediation step.

Files likely to change:

• src/specify_cli/presets/__init__.py — add warnings inside _register_commands at the two early-return points (lines ~880, ~950)
• src/specify_cli/presets/_commands.py — add post-install scaffolding status message in preset_add

Tests to add or update:

• tests/test_presets.py — test that preset_add prints a warning when all command templates are filtered by the extension guard
• tests/test_presets.py — test that a warning is printed when init-options.json has an unresolvable agent and commands are silently dropped
• tests/integrations/test_cli.py (or similar) — integration test: preset add on a project with no active agent emits a "no commands scaffolded" notice

Risks & Considerations

• Adding warnings is non-breaking; changing the success message may affect existing output-parsing tests.
• The _extension_installed_for_command filtering is intentional (prevents orphan extension command files). Any fix must preserve this guard and only add visibility, not bypass it.
• The single-active rule (Extension commands aren't rendered as skills for non-active skills-mode agents on add/install/upgrade #2948) is intentional. The fix should make its effect visible, not revert multi-agent registration.
• If the external spec-kit-copilot skill doc accurately reflects intended behavior (presets are template-only, no scaffolding), then this is a documentation/UX clarity issue, not a code bug. Clarification from a maintainer on the intended contract is needed before any code change.

Open Questions

• [NEEDS CLARIFICATION: What is the exact preset.yml of the preset used to reproduce? Specifically: are the type: command entries using extension-scoped names like speckit.<ext>.<cmd>, or plain core names like speckit.specify?]
• [NEEDS CLARIFICATION: Does .specify/init-options.json exist in the project where reproduction was attempted? If so, what is the value of the "ai" key?]
• [NEEDS CLARIFICATION: Was the behavior that "previously scaffolded" from a spec-kit version before the single-active rule was introduced (PR Extension commands aren't rendered as skills for non-active skills-mode agents on add/install/upgrade #2948)?]
• [NEEDS CLARIFICATION: The external skill doc (spec-kit-copilot) says presets do not scaffold — is this the intended design or an outdated description of an old limitation?]

Generated by 🐛 Assess Bug from Labeled Issue for issue #4076 · 395.4 AIC · ⌖ 23.1 AIC · ⊞ 34.1K · ◷