Activity

1. jeffstoner-scilo

   added

   needs-triage

   bug

   on Oct 16, 2026
2. mnriem

   added

   triage-must-haveVerdict: high-value, important work for Spec Kit — do firstVerdict: high-value, important work for Spec Kit — do first

   bug-assess

   and removed

   needs-triage

   on Oct 17, 2026
3. github-actions commented on Oct 17, 2026

   

   github-actionsbot

   on Oct 17, 2026 – with GitHub Actions

   Contributor

   More actions

   Bug assessment — init-cli-template-mismatch: Valid · severity high

   ---

   Bug Assessment: Can't initialize project

   • Slug: init-cli-template-mismatch
   • Created: 2026-10-17T12:56:23Z
   • Source: issue [Bug]: Can't initialize project #4994
   • Verdict: valid
   • Severity: high

   Report (summarized)

   The reporter installed specify-cli and followed the published getting-started instructions. With CLI 0.1.6 and Template 1.2.0 on Ubuntu 24.04.5 / Python 3.12.3, the documented specify init my-project --integration claude option is rejected as unknown. The CLI help instead exposes --ai. Retrying with specify init my-project --ai claude reaches initialization but fails with No matching release asset found for claude (expected pattern: spec-kit-template-claude-sh) and reports no available assets. Interactive selection of Claude and sh fails the same way. No comments supplied additional context.

   Symptom

   A fresh installation cannot create a project for Claude Code: the documented option is not recognized, and the legacy option cannot find the template asset required to scaffold the project. The expected behavior is creation of a new project directory with the selected integration.

   Reproduction

   1. Install the reported specify-cli release and follow the getting-started/installation documentation.
   2. Run specify init my-project --integration claude.
   3. Observe No such option: --integration.
   4. Run specify init my-project --ai claude, or select Claude and sh through the prompts.
   5. Observe No matching release asset found for claude (expected pattern: spec-kit-template-claude-sh) and no project directory.

   [NEEDS CLARIFICATION: Confirm the exact package index/source and installer command used, because the report identifies CLI and template versions but not the distribution URL or install command.]

   Suspected Code Paths

   • v0.1.6:src/specify_cli/__init__.py:703-712 — the released CLI constructs the asset name spec-kit-template-{ai_assistant}-{script_type} and fails when no matching release asset is returned. This directly matches the reported error text and expected asset name.
   • v0.1.6:src/specify_cli/__init__.py:1217-1218 — the released command registers --ai and --ai-commands-dir, explaining why --integration is rejected by CLI 0.1.6.
   • v0.1.6:src/specify_cli/__init__.py:1242-1254 — released help/examples document the --ai interface, while the report followed documentation using the newer --integration spelling.
   • src/specify_cli/command_init.py:335-363 — the current checkout uses --integration and documents bundled, offline scaffolding, rather than the old release-asset lookup.
   • src/specify_cli/command_init.py:711-732 — the current checkout creates an IntegrationManifest and invokes the registered integration setup after preparing the project, consistent with the newer initialization flow.
   • pyproject.toml:30-59 — the current package explicitly force-includes templates, scripts, extensions, workflows, presets, and catalogs under specify_cli/core_pack, removing the old dependency on per-agent release assets.
   • src/specify_cli/_assets.py:13-25 — current asset resolution expects a package-bundled core_pack in wheel installs, with source-tree fallback for editable/source installations.
   • src/specify_cli/integrations/claude/__init__.py:43-52 — Claude is a registered claude integration with its own skills setup, so Claude support exists in the current architecture.

   Root Cause Hypothesis

   High confidence: this is a release/documentation and asset-contract mismatch. CLI 0.1.6 predates the --integration command interface and still downloads an agent/script-specific release asset. The reported Template 1.2.0 release does not expose the expected spec-kit-template-claude-sh asset, so both the legacy command and the documented command fail for different reasons. The current checkout shows the likely post-migration design—--integration, package-bundled core assets, and registered integrations—but that does not repair an already published 0.1.6 installation.

   Proposed Remediation

   Preferred: Publish a compatible Specify CLI release and update the installation/getting-started documentation atomically. The release should use the same initialization contract as the docs (--integration) and include the bundled core_pack assets required by specify init; Claude should be resolved through the registered integration rather than a spec-kit-template-claude-sh release asset. Ensure the published wheel/sdist contains the force-included assets and that the release metadata/template version is internally consistent. Add a release smoke test that installs the built artifact in a clean environment and runs specify init <dir> --integration claude --script sh (including the non-interactive path).

   If 0.1.6 must remain supported, alternatively publish the exact legacy assets for every advertised AI/script combination and either restore a compatibility alias for --integration or correct the documentation to target --ai for that release. This is a temporary compatibility measure and risks continuing two divergent initialization contracts.

   Files likely to change:

   • pyproject.toml — verify wheel/sdist inclusion of initialization assets and release packaging.
   • src/specify_cli/command_init.py — only if compatibility aliases or release-specific migration handling are required.
   • src/specify_cli/_assets.py — only if packaged-asset resolution fails in the built artifact.
   • src/specify_cli/integrations/claude/__init__.py — only if Claude setup needs release smoke-test fixes.
   • README.md and installation/reference documentation — keep the documented option and supported release aligned.
   • Release workflow/configuration — publish the CLI and template/package artifacts from the same compatible revision.
   • tests/ — add clean-artifact initialization coverage and legacy/modern option compatibility coverage if an alias is retained.

   Tests to add or update:

   • Build the wheel in CI, install it into a clean virtual environment, and assert specify init help exposes the documented option.
   • Run a fresh, offline Claude initialization with --integration claude --script sh; assert the project directory, bundled templates/scripts, and Claude skills are created.
   • Assert a mismatched or missing asset/package fails with an actionable version/install message rather than an unexplained empty asset list.
   • If backward compatibility is intended, assert --ai claude either remains a supported alias or produces a clear migration message.

   Risks & Considerations

   • Publishing docs and CLI from different revisions will reproduce the option mismatch even if either side is correct in isolation.
   • Removing the old release-asset contract without a compatibility window may break automation pinned to --ai.
   • Incorrect wheel force-inclusion can make source/editable installs pass while end-user wheels fail; artifact-level tests are required.
   • Release assets and package metadata should be checked for version skew so a newer template cannot be paired with an older CLI contract.
   • The failure blocks first-project creation for affected fresh installs, but the blast radius is limited to the incompatible release/version combination rather than existing projects.

   Open Questions

   • [NEEDS CLARIFICATION: Which exact installation command and package source produced CLI 0.1.6?]
   • [NEEDS CLARIFICATION: Was the documentation page read from the repository default branch or from a versioned release page?]
   • [NEEDS CLARIFICATION: Does the 1.2.0 release intentionally omit all spec-kit-template-* assets, or was the release artifact incomplete?]

   Generated by 🐛 Assess Bug from Labeled Issue for #4994 · copilot · gpt52codex · 2.72 AIC · ⌖ 0.605 AIC · ⊞ 22.3K · ◷
4. github-actions

   added

   severity-high

   on Oct 17, 2026