prep/auto/implement ship without review: pinned review extension fails to install on spec-kit 1.0.x

[iddocohen]

Summary

The review companion extension pinned in our install docs cannot be installed on spec-kit 1.0.x. Users who follow the README end up without the speckit-review-run skill, so /speckit.opsmill.prep, /speckit.opsmill.auto, and /speckit.opsmill.implement lose their review tail. critique is unaffected and installs normally.

Reported against specify-cli 1.0.5, reproducible on v1.0.1 and main of the review extension.

$ specify extension add review \
    --from https://github.com/ismaelJimenez/spec-kit-review/archive/refs/tags/v1.0.1.zip

Validation Error: Invalid script name 'detect-changed-files.sh': must be lowercase alphanumeric with hyphens only

Severity: high, publicly broken

This is not an internal inconvenience. Both of our public spec-kit extensions document a flow that cannot be completed today on a current spec-kit:

• opsmill/opsmill-speckit README, Companion extensions, tells every user to run specify extension add review --from .../v1.0.1.zip. That command exits with a validation error on spec-kit 1.0.x.
• opsmill/infrahub-speckit README presents opsmill-speckit/auto as a primary entry point for the Infrahub workflow, so the Infrahub story inherits the same break.

Anyone installing either extension from our published instructions on a current spec-kit lands in one of two states:

1. They notice the error, and our documented install is visibly wrong on first contact.
2. They miss it in the install output, and prep / auto / implement then run without any review pass. The commands do not fail loudly, they just skip the review tail, so an autonomous auto run silently ships unreviewed code. That is the worse of the two.

There is no fallback: spec-kit aborts before registering any command or hook, so the speckit-review-run skill is simply absent rather than degraded.

The fix is not in our hands, it is upstream and already submitted (below). What we own is that our published docs currently point users at a broken install, and that auto degrades quietly instead of announcing the missing skill.

Cause

Upstream bug in ismaelJimenez/spec-kit-review, not in this repo. Its extension.yml puts the file name in provides.scripts[].name:

  scripts:
    - name: "detect-changed-files.sh"
      file: "scripts/bash/detect-changed-files.sh"

spec-kit 1.0.0 started validating provides.scripts / provides.templates entries in ExtensionManifest._validate_provided_artifacts (src/specify_cli/extensions/__init__.py). name must match ^[a-z0-9-]+$, since it is a logical slug and the path belongs in file:. Earlier CLIs never checked that section, which is why the pinned v1.0.1 used to install cleanly. Validation fails before any command or hook is registered, so the extension is not partially installed, it is simply absent.

critique declares no provides.scripts section, so it is unaffected.

Upstream fix

• Issue: specify extension add review fails on spec-kit 1.0.x: script names in extension.yml include file extensions ismaelJimenez/spec-kit-review#4
• PR: Fix provides.scripts names rejected by Spec Kit 1.0.x manifest validation ismaelJimenez/spec-kit-review#5

The PR renames the two entries to detect-changed-files / detect-changed-files-powershell, releases as v1.0.2, and extends the upstream validate-manifest CI job to catch this class of manifest error. Script paths and command frontmatter are unchanged, so behaviour is identical.

Verified on specify-cli 1.0.5 and 0.8.5: install succeeds, all 7 speckit-review-* skills are generated, and the after_implement hook registers.

Impact here

README.md (Companion extensions section) pins:

specify extension add review \
  --from https://github.com/ismaelJimenez/spec-kit-review/archive/refs/tags/v1.0.1.zip

That command fails for anyone on spec-kit 1.0.x. Commands affected: prep, auto, implement.

Workaround until upstream tags v1.0.2

git clone https://github.com/iddocohen/spec-kit-review -b fix/script-name-slugs
specify extension add ./spec-kit-review --dev

Action for this repo

• Wait for upstream PR add speckit.opsmill.qa extension #5 to merge and a v1.0.2 tag to be cut
• Bump the pinned URL in README.md to v1.0.2
• Add a short troubleshooting note for this error, matching the existing companion-extension guidance
• If upstream goes quiet, reconsider whether review should stay an external pin or be vendored
• Interim: update README.md now with the workaround, rather than leaving users on a pin that fails
• Make the missing speckit-review-run skill a loud failure in prep / auto / implement instead of a silent skip, so a broken companion install can never pass for a completed review

[iddocohen]

Companion tracking issue for the Infrahub side, which inherits this through opsmill-speckit/auto: opsmill/infrahub-speckit#6

[iddocohen]

Hardening PR for the silent-skip half of this: #17

It does not fix the upstream manifest bug, it makes a missing companion extension a reported, non-silent outcome instead of an invisible gap:

• prep Phase 3 and implement Phase 0 resolve a provider from the filesystem: extension / fallback / none
• fallback runs a reduced built-in critique/review in a clean-context subagent, so auto still delivers a reviewed change
• none forces STATUS: INCOMPLETE
• Both values ride on the machine-readable status line (CRITIQUE: / REVIEW:) and auto must surface them in its summary

That covers the last two action items in the list above. The remaining item, re-pinning the README to v1.0.2, still waits on upstream.