feat: implement preset wrap strategy

[kennedy-whytech]

Description

• Implements strategy: wrap for preset command/skill overrides — presets can now inject content before and after core commands using a {CORE_TEMPLATE} placeholder without fully replacing them
• Wired into both _register_skills (Claude skills path) and register_commands (all other agents)

Fixes in this branch

{SCRIPT} placeholders broken in wrapped commands — when a preset used strategy: wrap, the core template's scripts/agent_scripts frontmatter was silently discarded after body substitution. Presets that wrap an existing
command (e.g. "use Codex for the following: {CORE_TEMPLATE}") now inherit the core's script metadata so prerequisite check scripts still run.

Extension commands never resolved — _substitute_core_template only searched core-pack and project template directories. Wrapping extension commands like speckit.git.feature now also searches
.specify/extensions//commands/, so {CORE_TEMPLATE} resolves correctly for extension overrides.

Two test hygiene fixes (from code review):

• Restored missing "reinstall" assertion in the bundled preset CLI error test
• Restored AGENT_CONFIGS on the class (not the instance) after test mutation, preventing state leaking across tests

Test plan

• uv run python -m pytest tests/test_presets.py::TestWrapStrategy — all wrap strategy tests pass
• Full suite: uv run python -m pytest — no new failures

End-to-end test with my own presets. The wrapping seems doing good. Also, I feel like "wrap" can cover prepend and append already.

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

AI Disclosure

• I did not use AI assistance for this contribution

• I did use AI assistance (describe below)

  AI assistance disclosure

  This PR was implemented with AI assistance (Claude Code) for code generation,
  test writing, and commit messages. All changes were reviewed and verified
  manually.

[Copilot]

Pull request overview

Adds support for strategy: wrap on preset-provided commands, enabling preset authors to inject pre/post content around an existing “core” command body via a {CORE_TEMPLATE} placeholder during command/skill registration.

Changes:

• Introduces _substitute_core_template() and applies it during preset skill registration (_register_skills) and generic agent command registration (CommandRegistrar.register_commands).
• Extends the self-test preset with a new speckit.wrap-test command and updates docs to mark wrap as implemented for commands.
• Adds unit + E2E-style tests covering placeholder substitution and install behavior.

Show a summary per file

File	Description
tests/test_presets.py	Updates self-test manifest expectations; adds new TestWrapStrategy coverage.
src/specify_cli/presets.py	Adds _substitute_core_template() and wires it into preset skill generation.
src/specify_cli/agents.py	Wires wrap substitution into agent command registration.
presets/self-test/preset.yml	Adds a new wrap-strategy command entry to the self-test preset.
presets/self-test/commands/speckit.wrap-test.md	Adds a wrap command template using {CORE_TEMPLATE}.
presets/README.md	Updates roadmap/docs to reflect wrap implemented for commands/artifacts.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 6/6 changed files
• Comments generated: 1

[mnriem]

Please address Copilot feedback. If not applicable, please explain why

[kennedy-whytech]

@mnriem that makes sense to me. updated.

[Copilot]

Pull request overview

Implements support for strategy: wrap on preset command templates by substituting {CORE_TEMPLATE} with the installed core command template body during installation/registration, enabling presets to extend core commands without copy/paste.

Changes:

• Added _substitute_core_template() helper and applied it when generating skills from preset commands (Claude skills flow).
• Applied the same substitution in CommandRegistrar.register_commands() for non-skill agent command installation.
• Added a self-test preset wrap command + unit/E2E tests, and updated preset strategy documentation.

Show a summary per file

File	Description
src/specify_cli/presets.py	Adds {CORE_TEMPLATE} substitution helper and applies it in the skills generation path for wrap-strategy preset commands.
src/specify_cli/agents.py	Applies {CORE_TEMPLATE} substitution during normal agent command registration when strategy: wrap is set.
tests/test_presets.py	Updates self-test manifest expectations and adds unit + E2E coverage for wrap substitution.
presets/self-test/preset.yml	Registers a new wrap-strategy command in the bundled self-test preset.
presets/self-test/commands/speckit.wrap-test.md	New wrap command template containing {CORE_TEMPLATE} placeholder.
presets/README.md	Updates roadmap/docs to reflect wrap being implemented for commands/artifacts (not scripts).

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 6/6 changed files
• Comments generated: 2

[mnriem]

Please address Copilot feedback

[Copilot]

Pull request overview

Adds a new preset composition option (strategy: wrap) for command/skill overrides, allowing presets to inject content around the existing core command by substituting a {CORE_TEMPLATE} placeholder, rather than fully replacing the command.

Changes:

• Implement _substitute_core_template helper to resolve and substitute {CORE_TEMPLATE} from project core templates, bundled core pack, and installed extensions.
• Wire wrap substitution into both preset skill generation (_register_skills) and agent command registration (register_commands).
• Extend self-test preset + add comprehensive tests for wrap behavior, extension resolution, and script placeholder hygiene.

Show a summary per file

File	Description
src/specify_cli/presets.py	Introduces {CORE_TEMPLATE} substitution + merges core scripts/agent_scripts into wrapped skill frontmatter.
src/specify_cli/agents.py	Enables wrap substitution during agent command registration.
tests/test_presets.py	Adds TestWrapStrategy coverage and updates self-test manifest expectations.
presets/self-test/preset.yml	Adds a self-test wrap command entry.
presets/self-test/commands/speckit.wrap-test.md	New wrap-strategy command template used for end-to-end testing.
presets/README.md	Updates documentation to reflect wrap is implemented for commands/artifacts (scripts TBD).

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 6/6 changed files
• Comments generated: 1

[Copilot]

When strategy: wrap is used here, _substitute_core_template returns the wrapped core template’s frontmatter as the second tuple element, but it’s discarded. For SKILL-target agents that call resolve_skill_placeholders (e.g. codex/kimi), any {SCRIPT}/{AGENT_SCRIPT} placeholders coming from the substituted core body will remain unresolved unless scripts/agent_scripts are inherited into frontmatter (similar to what _register_skills now does). Consider merging scripts and agent_scripts from the core frontmatter when the preset frontmatter doesn’t define them, before _adjust_script_paths runs so paths get normalized too.

Suggested change

	body, _ = _substitute_core_template(body, cmd_name, project_root, self)
	body, core_frontmatter = _substitute_core_template(
	body, cmd_name, project_root, self
	)
	for key in ("scripts", "agent_scripts"):
	if key not in frontmatter and key in core_frontmatter:
	frontmatter[key] = deepcopy(core_frontmatter[key])

[mnriem]

Please address Copilot feedback

[Copilot]

Pull request overview

Adds support for a new preset composition mode (strategy: wrap) so preset command/skill overrides can inject content around an existing command body via a {CORE_TEMPLATE} placeholder, instead of fully replacing it.

Changes:

• Introduces _substitute_core_template() and wires it into preset skill generation and agent command registration for strategy: wrap.
• Extends command registration to merge missing scripts / agent_scripts from the wrapped “core” template and resolves placeholders for TOML command output.
• Adds wrap-strategy tests plus a self-test preset command and updates preset documentation.

Show a summary per file

File	Description
src/specify_cli/presets.py	Adds core-template substitution helper and applies wrap behavior when generating SKILL.md overrides.
src/specify_cli/agents.py	Applies wrap substitution and frontmatter inheritance during command registration; resolves placeholders for TOML output.
tests/test_presets.py	Adds wrap-strategy test suite and adjusts self-test preset expectations; modifies bundled preset CLI error assertions.
presets/self-test/preset.yml	Registers a new self-test command entry for wrap strategy coverage.
presets/self-test/commands/speckit.wrap-test.md	Adds a wrap-strategy self-test command file using {CORE_TEMPLATE}.
presets/README.md	Updates documentation to reflect that command/template wrapping is implemented (scripts wrap not yet).

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (2)

tests/test_presets.py:3299

• Same AGENT_CONFIGS leakage issue here: the test mutates registrar.AGENT_CONFIGS[...] (class-level) and then restores with registrar.AGENT_CONFIGS = original (instance-level assignment). This can leave test-agent in the class-level configs for subsequent tests. Restore on CommandRegistrar.AGENT_CONFIGS (class) or patch the dict in a context manager.

        registrar = CommandRegistrar()
        original = copy.deepcopy(registrar.AGENT_CONFIGS)
        registrar.AGENT_CONFIGS["test-agent"] = {
            "dir": str(agent_dir.relative_to(project_dir)),
            "format": "markdown",
            "args": "$ARGUMENTS",
            "extension": ".md",
            "strip_frontmatter_keys": [],
        }
        try:
            registrar.register_commands(
                "test-agent",
                [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],
                "test-preset",
                project_dir / "preset",
                project_dir,
            )
        finally:
            registrar.AGENT_CONFIGS = original

tests/test_presets.py:3347

• Same AGENT_CONFIGS leakage issue in the TOML agent test: registrar.AGENT_CONFIGS is mutated (class-level) but restored via instance assignment (registrar.AGENT_CONFIGS = original). This can leak test-toml-agent into other tests. Restore via CommandRegistrar.AGENT_CONFIGS = original or patch the dict with patch.dict/monkeypatch.

        registrar = CommandRegistrar()
        original = copy.deepcopy(registrar.AGENT_CONFIGS)
        registrar.AGENT_CONFIGS["test-toml-agent"] = {
            "dir": str(toml_dir.relative_to(project_dir)),
            "format": "toml",
            "args": "{{args}}",
            "extension": ".toml",
            "strip_frontmatter_keys": [],
        }
        try:
            registrar.register_commands(
                "test-toml-agent",
                [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],
                "test-preset",
                project_dir / "preset",
                project_dir,
            )
        finally:
            registrar.AGENT_CONFIGS = original

• Files reviewed: 6/6 changed files
• Comments generated: 4

[Copilot]

_substitute_core_template currently only looks for the core file at .specify/templates/commands/{short_name}.md. This won’t resolve wrapped extension commands (e.g. speckit.git.feature) because their “core” source lives under .specify/extensions/<ext-id>/commands/ (and may not match the {short_name}.md naming). Consider detecting extension command names and resolving via the installed extension manifest (.specify/extensions/<ext-id>/extension.yml) to find the correct command file path, then substitute from that file; fall back to .specify/templates/commands/ for core commands.

[Copilot]

For strategy: wrap, short_name is derived by stripping speckit. (so extension commands become e.g. git.feature) and then passed to _substitute_core_template(), which looks for .specify/templates/commands/{short_name}.md. This prevents {CORE_TEMPLATE} substitution for extension overrides. A more reliable approach is to pass the full command name into the resolver and have it locate the core source either in .specify/templates/commands/ (core) or .specify/extensions/<ext-id>/commands/ (extension), ideally via the installed extension manifest.

[Copilot]

The bundled-preset CLI error test no longer asserts that the output includes the reinstall guidance. The CLI code paths for missing bundled presets print a “Try reinstalling …” message, so dropping this assertion reduces coverage for the intended recovery hint (and conflicts with the PR description that says it was restored). Re-add an assertion that the output contains "reinstall" (or the specific reinstall command string).

[Copilot]

This test mutates registrar.AGENT_CONFIGS (a class-level dict) but restores it via registrar.AGENT_CONFIGS = original, which only sets an instance attribute and leaves the class-level dict permanently mutated (leaking state into other tests). Restore on the class (CommandRegistrar.AGENT_CONFIGS = original) or use a patching helper (e.g. monkeypatch/patch.dict) to avoid cross-test leakage.

This issue also appears in the following locations of the same file:

• line 3280
• line 3328