Baike.dev
Log in
Back to tool/Back to issues
#4551·spec-kit

[Bug]: preset-provided scripts are never resolved — `type: script` and `$CORE_SCRIPT` have no effect

Author: pavel-neumannCreated Sep 12, 2026Updated Sep 16, 2026
Labelsbug-assessseverity-lowneeds-triageauthor-awaitingtriage-nice-to-have

Bug Description

The preset reference documents scripts as a first-class layer of the resolution stack:

"Presets can provide command files, template files (like plan-template.md), and script files. Templates and scripts are looked up from the stack when Spec Kit needs them. Scripts support replace and wrap; script wrappers use $CORE_SCRIPT as the placeholder."

and lists the project-local override location as .specify/templates/overrides/scripts/.

None of this takes effect. A preset may declare type: script, and specify preset add accepts and installs it without complaint, but nothing ever asks the resolver for a script, so the file that actually runs is always the core one.

Three independent places in the shipped code show why:

  1. No caller requests the script type. The only production call into preset composition determines the type as template_type = "command" if is_command else "template" (specify_cli/presets/_commands.py:495). The value "script" is never passed, so PresetResolver.resolve() / collect_all_layers() are never invoked for scripts — even though both handle template_type == "script" (specify_cli/presets/__init__.py:5524, 5531, 5613, and the $CORE_SCRIPT substitution at :6168).
  2. The Bash runtime resolves only .md. resolve_template() in core_pack/scripts/bash/common.sh:509 looks for "$base/overrides/${template_name}.md", and every subsequent tier appends .md as well. There is no .sh branch and no overrides/scripts/ lookup anywhere in the file.
  3. The Python twin mirrors that. core_pack/scripts/python/common.py:308 documents its order as "mirrors resolve_template in scripts/bash/common.sh" and resolves overrides/f"{template_name}.md" only. So the composition engine for scripts exists and is reachable by unit test, but is not wired to anything that runs.

This looks like the script half of #2132 / #2133 never landed on the runtime side, while #3143 documented it as shipped. I could not find an existing report: no open issue or PR with "script" in the title covers it (#1964 is adjacent but is about extensions and has been open since March 2026), and #4443 / #4445 concern PyYAML availability, not resolution. runs the command. Suggestion. Either wire a caller for template_type="script" and add .sh resolution to common.sh and its Python twin, or — if scripts are not meant to be resolvable yet — adjust docs/reference/presets.md and have preset.yml validation reject type: script so the declaration fails loudly instead of silently.

Steps to Reproduce

# 1. Scaffold a project
mkdir demo && cd demo && git init
specify init . --integration claude --script sh --force
 
# 2. Record the core script's hash
sha256sum .specify/scripts/bash/setup-plan.sh
 
# 3a. Try the documented project-local override
mkdir -p .specify/templates/overrides/scripts
printf '#!/usr/bin/env bash\necho "OVERRIDE RAN"\n' \
  > .specify/templates/overrides/scripts/setup-plan.sh
chmod +x .specify/templates/overrides/scripts/setup-plan.sh
 
# 3b. Or try a preset that provides the script
mkdir -p /tmp/p/scripts
cat > /tmp/p/preset.yml <<'YAML'
schema_version: "1.0"
preset:
  id: "gate"
  name: "Gate"
  version: "1.0.0"
  description: "Wraps setup-plan."
requires:
  speckit_version: ">=1.0.0"
provides:
  templates:
    - type: "script"
      name: "setup-plan"
      file: "scripts/setup-plan.sh"
      strategy: "wrap"
YAML
printf '#!/usr/bin/env bash\necho "BEFORE"\n$CORE_SCRIPT "$@"\n' > /tmp/p/scripts/setup-plan.sh
specify preset add --dev /tmp/p
 
# 4. Re-scaffold and compare
specify init . --integration claude --script sh --force
sha256sum .specify/scripts/bash/setup-plan.sh

Expected Behavior

.specify/scripts/bash/setup-plan.sh is composed from the stack, so the wrapper runs first and delegates to the core script through $CORE_SCRIPT — matching the documented behaviour that "templates and scripts are looked up from the stack when Spec Kit needs them".

Actual Behavior

The hash in step 4 is identical to step 2 and still matches .specify/integrations/speckit.manifest.json. The override file and the preset-provided script are never read. specify preset add reports success and specify preset list shows the preset as enabled, so there is no signal that the declared script is inert.

Tried additionally, all without effect: strategy: replace as well as wrap, specify integration upgrade, specify init --here --force. Same result on 1.0.1.

Specify CLI Version

1.0.6

AI Agent

Claude Code

Operating System

macOS 26.6.2

Python Version

Python 3.11.15

Error Logs

# There is no error output — that is part of the problem.
# A preset declaring a script installs cleanly and is reported as active:
 
$ specify preset add --dev /tmp/p
Installing preset from /tmp/p...
✓ Preset 'Gate' v1.0.0 installed (priority 10)
 
$ specify preset list
Installed Presets (in resolution order — highest precedence first)
 
  Gate (gate) v1.0.0 — enabled — priority 10
    Wraps setup-plan.
    Templates: 1
 
# …while the script it provides is never resolved or executed.

Additional Context

Why this matters. The documented mechanism is the natural way to add a step in front of a core script: the preset wraps setup-plan.sh, the core script stays untouched underneath, and Spec Kit maintains the relationship. Any preset that needs to run a check, a fetch, or a validation before the command body reads its inputs wants exactly this.

Current workaround, for anyone hitting the same wall. Override the command instead of the script. A preset providing speckit.plan with strategy: "wrap" and a five-line body:

---
scripts:
  sh: scripts/bash/setup-plan-wrapper.sh --json
---
{CORE_TEMPLATE}

points the materialised command at a project-owned script, which ends with exec "$ROOT/.specify/scripts/bash/setup-plan.sh" "$@". This works and survives upgrades, because {CORE_TEMPLATE} keeps pulling the command body from core.

It has two costs that the documented mechanism would remove:

  • two artefacts instead of one. The script cannot travel inside the preset, so it lives beside it as a separate committed file, and it needs a distinct filename because it cannot replace setup-plan.sh.
  • nothing validates the link. A preset whose frontmatter names a script that does not exist installs without any warning and is listed as healthy; the dead path only surfaces when a user runs the command. Suggestion. Either wire a caller for template_type="script" and add .sh resolution to common.sh and its Python twin, or — if scripts are not meant to be resolvable yet — adjust docs/reference/presets.md and have preset.yml validation reject type: script so the declaration fails loudly instead of silently.

Source: github/spec-kit

View original on GitHubView discussion on GitHub