specify init does not copy templates/commands/ to .specify/templates/commands/ — wrap composition strategy fails

[djimit]

specify init does not copy templates/commands/ to .specify/templates/commands/

Problem

During specify init, the install_shared_infra function in shared_infra.py copies template files from the bundled templates/ directory to .specify/templates/. However, it only processes files at the top level (src.is_file() check), skipping subdirectories — specifically templates/commands/.

This means the core command templates (e.g., implement.md, specify.md, plan.md, etc.) are installed directly to the agent directory (e.g., .opencode/commands/speckit.implement.md) via the integration system, but they are not kept in .specify/templates/commands/ for the preset resolver to find.

Impact

Preset authors who use the wrap composition strategy for command overrides (e.g., wrapping speckit.implement with a preamble) cannot resolve the core command as a base layer. The PresetResolver.collect_all_layers() method looks for core commands at:

c = self.templates_dir / "commands" / f"{template_name}.md"  # or stem fallback

Since .specify/templates/commands/ doesn't exist after specify init, the resolver finds no base layer, composition fails, and the command is silently not registered (registered_commands stays empty {}).

Reproduction

specify init --here --integration opencode --script sh --ignore-agent-tools
# .specify/templates/commands/ does NOT exist
# .opencode/commands/speckit.implement.md exists (installed by integration)

# Create a preset with a wrap strategy for speckit.implement
specify preset add --dev /path/to/my-preset
# registered_commands is {} — the wrap composition failed silently

Workaround

Manually copy command templates after init:

mkdir -p .specify/templates/commands
cp <spec-kit-source>/templates/commands/*.md .specify/templates/commands/

Suggested fix

In shared_infra.py, the install_shared_infra function should also copy the templates/commands/ subdirectory (with the same overwrite/manifest logic). Something like:

# After the top-level template files loop:
commands_src = templates_src / "commands"
if commands_src.is_dir():
    dest_commands = dest_templates / "commands"
    if _ensure_or_bucket_dir(dest_commands):
        for src_path in commands_src.iterdir():
            if not src_path.is_file() or src_path.name.startswith("."):
                continue
            dst = dest_commands / src_path.name
            rel = dst.relative_to(project_path).as_posix()
            # ... same overwrite/manifest logic as above ...

Alternatively, the PresetResolver could fall back to reading core commands from the agent directory (e.g., .opencode/commands/speckit.implement.md) when .specify/templates/commands/ doesn't have them.

Environment

• Spec Kit v0.11.3
• macOS Darwin arm64
• Integration: opencode

[github-actions]

Bug assessment — init-commands-dir-missing: Valid · severity medium

---

Bug Assessment: specify init does not populate .specify/templates/commands/

• Slug: init-commands-dir-missing
• Created: 2026-06-22
• Source: issue specify init does not copy templates/commands/ to .specify/templates/commands/ — wrap composition strategy fails #3086
• Verdict: valid
• Severity: medium

Report (summarized)

Reported by @djimit on Spec Kit v0.11.3 (macOS Darwin arm64, opencode integration). During specify init, the install_shared_infra function iterates over the bundled templates/ directory but only processes files, silently skipping subdirectories — specifically templates/commands/. The result is that .specify/templates/commands/ is never created. Preset authors using the wrap composition strategy cannot compose against a core command because PresetResolver.collect_all_layers() looks for the base layer in .specify/templates/commands/ and finds nothing. The reporter observes registered_commands stays {}.

Symptom

After specify init, .specify/templates/commands/ does not exist (even though .opencode/commands/speckit.implement.md etc. are correctly installed by the integration). A preset that declares strategy: wrap for a core command (e.g. speckit.implement) cannot find its base layer, causing composition to fail.

Reproduction

specify init --here --integration opencode --script sh --ignore-agent-tools
# Expect: .specify/templates/commands/ with implement.md, specify.md, plan.md, ...
# Actual: .specify/templates/commands/ does NOT exist

# Create a dev preset with wrap strategy for speckit.implement:
specify preset add --dev /path/to/my-preset
# registered_commands is {} — composition failed

[NEEDS CLARIFICATION: exact Spec Kit build (editable source vs wheel install) — the fallback path (Priority 5) behaves slightly differently in each case.]

Suspected Code Paths

• src/specify_cli/shared_infra.py:440 — if not src.is_file() guard in install_shared_infra skips the commands/ subdirectory. This is the root cause.
• src/specify_cli/shared_infra.py:253 — identical if not src.is_file() guard in refresh_shared_templates. Same omission means commands are also not refreshed on specify upgrade.
• src/specify_cli/presets/__init__.py:3035–3065 — collect_all_layers() checks .specify/templates/commands/ first (Priority 4); only falls through to _find_bundled_core() (Priority 5) when the directory is absent. The fallback exists in current main-branch code but was not present in v0.11.3 (its docstring says it exists specifically "so that collect_all_layers() can locate base layers even when .specify/templates/ doesn't contain the core file" — wording that implies it was added to paper over this gap).
• src/specify_cli/presets/__init__.py:2706–2744 — resolve() also has a matching Priority 5 bundled-core fallback.
• tests/test_presets.py:129–131 — the project_dir fixture manually creates .specify/templates/commands/, masking the real-world absent-directory behavior in all existing preset tests:

  commands_dir = templates_dir / "commands"
  commands_dir.mkdir()

Root Cause Hypothesis

install_shared_infra (and refresh_shared_templates) iterate over the top-level source templates directory with a guard if not src.is_file() that intentionally skips non-files. This was written to avoid copying the vscode-settings.json (explicitly excluded) and presumably to ignore any miscellaneous subdirectories, but it inadvertently excludes the commands/ subdirectory that must be copied to .specify/templates/commands/. The pyproject.toml wheel build maps "templates/commands" → "specify_cli/core_pack/commands" (not under templates/), which means the core_pack layout differs from the source layout — a discrepancy that adds complexity to any fix. Confidence: high — the root cause is directly visible at the stated lines with no ambiguity.

Proposed Remediation

Preferred: Extend install_shared_infra to process the commands/ subdirectory after the top-level template loop, applying the same safe-destination, overwrite-decision, and manifest-recording logic already used for scripts. Extend refresh_shared_templates identically so upgrades keep the copied files current.

Concretely, after the for src in templates_src.iterdir() loop in each function, add:

commands_src = templates_src / "commands"
if commands_src.is_dir():
    dest_commands = dest_templates / "commands"
    if _ensure_or_bucket_dir(dest_commands):   # install_shared_infra spelling
        for src_path in commands_src.iterdir():
            if not src_path.is_file() or src_path.name.startswith("."):
                continue
            dst = dest_commands / src_path.name
            rel = dst.relative_to(project_path).as_posix()
            # ... same overwrite/manifest/bucket logic as top-level templates ...

refresh_shared_templates uses _ensure_safe_shared_directory and _ensure_safe_shared_destination instead of _ensure_or_bucket_dir; it should follow the same pattern already used for its top-level entries.

Alternatives:

• Keep the _find_bundled_core fallback as-is and document that .specify/templates/commands/ is intentionally absent (low risk, but breaks the expected project layout and leaves refresh_shared_templates unable to keep commands current).
• Make PresetResolver.resolve() and collect_all_layers() primary (without copying to .specify/), always reading from the bundled pack. This is a larger refactor that changes the user-facing contract.

Files likely to change:

• src/specify_cli/shared_infra.py (both install_shared_infra and refresh_shared_templates)
• tests/integrations/test_cli.py or a dedicated tests/test_shared_infra.py — add an integration test asserting specify init creates .specify/templates/commands/implement.md (and peers)
• tests/test_presets.py — update project_dir fixture to not manually create commands_dir, or add a separate test that drives real install_shared_infra and verifies the commands directory is populated

Tests to add or update:

• Test that install_shared_infra creates .specify/templates/commands/ and populates it with the bundled command templates.
• Test that refresh_shared_templates updates command files in .specify/templates/commands/ when the bundled source changes.
• Test that specify preset add with a wrap strategy succeeds without requiring .specify/templates/commands/ to be pre-created (exercising the _find_bundled_core path, to lock in the fallback even if the primary path is later added).
• Remove or relax the manual commands_dir.mkdir() in the project_dir fixture to catch regressions.

Risks & Considerations

• Manifest tracking: copied command files must be recorded in speckit.manifest.json so specify upgrade knows they are managed and can refresh them without treating them as user customizations.
• core_pack layout vs source layout: The wheel packages templates/commands/ as specify_cli/core_pack/commands/ (without templates/ prefix). shared_templates_source() already resolves to core_pack/templates/ for wheel installs, so the commands/ subdirectory under templates_src will be core_pack/templates/commands/ — which is the same as templates/commands/ in the source tree. No layout-specific handling needed.
• Overwrite safety: existing user files under .specify/templates/commands/ (placed there via the documented workaround) must be preserved unless --force is given, consistent with the current top-level template behavior.
• No API breakage: the fix is additive; no existing public interfaces change.

Open Questions

• [NEEDS CLARIFICATION: Was _find_bundled_core present in v0.11.3? Confirming this would let us determine whether the reporter's full registered_commands: {} failure (not just a missing directory) is reproducible against current main.]
• [NEEDS CLARIFICATION: Does the reporter use a wheel install or an editable/source install? The _locate_core_pack() / repo-root fallback path differs between the two.]

Generated by 🐛 Assess Bug from Labeled Issue for issue #3086 · 430.8 AIC · ⌖ 29 AIC · ⊞ 31.7K · ◷

[mnriem]

Assessment

The central claim — that wrap-strategy presets fail because specify init doesn't copy templates/commands/ into .specify/templates/commands/ — does not hold as a root cause.

PresetResolver has an explicit Priority‑5 fallback (_find_bundled_core, and the matching tier‑5 branch in resolve()) that locates the core base layer from the bundled core_pack (wheel) or the repo-root templates/ tree (source) precisely when .specify/templates/commands/ is absent. So the missing copy is a layout/cosmetic gap, not a functional one.

Verified empirically:

Install type	core_pack	wrap base layer resolved?
Wheel (pip, e.g. v0.11.3)	present	✅ yes — core (bundled) layer resolves
Source / editable checkout	absent	❌ no

The real bug

There is a genuine failure, but a different one — and it only affects source/editable installs. Both fallbacks computed the repo root as Path(__file__).parent.parent.parent. After presets.py was moved to presets/__init__.py (#2826), that chain is one level short: it resolves to src/ and looks for src/templates/commands/<cmd>.md, which never exists. Result: no base layer, wrap composition silently produces nothing. Wheel installs were unaffected (they take the core_pack branch).

Recommendation

• Don't adopt the suggested fix (copying templates/commands/ into .specify/templates/commands/ during init). It touches the core install/manifest/upgrade flow to solve a non-problem for the common (wheel) case.
• Do fix the off-by-one repo-root fallback — a small, isolated change in the preset resolver that makes source-checkout behave like wheel installs.

PR with the fix + regression tests: mnriem#9 (against a fork; happy to retarget upstream).

Posted on behalf of @mnriem by GitHub Copilot CLI (model: Claude Opus 4.8).

[github-actions]

This issue has been automatically marked as stale because it has not had any activity for 60 days. It will be closed in 30 days if no further activity occurs.