[Bug]: EXTENSION-DEVELOPMENT-GUIDE.md still claims specify-cli on PyPI is "a different, unrelated project", contradicting README

[0xE1337]

Bug Description

The troubleshooting section of extensions/EXTENSION-DEVELOPMENT-GUIDE.md still warns that the bare specify-cli package on PyPI is "a different, unrelated project", while both the README and docs/installation.md now document PyPI as an official installation channel. The guide's warning was accurate when it was written (commit ab9c702, 2026-04-29, "fix: include --from git+... in upgrade hint to avoid PyPI squat package"), but it became outdated after the PyPI project was handed over to the spec-kit team (#2908, closed as completed on 2026-06-26) and was never updated.

Where

extensions/EXTENSION-DEVELOPMENT-GUIDE.md line 690 (Troubleshooting → "Extension won't install") — permalink:

Fix: Update spec-kit with uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git. The bare specify-cli package on PyPI is a different, unrelated project — installing it without --from git+... will give you a stub CLI that does not include extension, preset, or other spec-kit commands.

This contradicts:

README.md line 53 — permalink:

Prefer installing from PyPI? The specify-cli package is also published there:

uv tool install specify-cli

docs/installation.md line 14 — permalink:

Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the github/spec-kit GitHub repository (source installs) and the specify-cli package on PyPI.

Expected Behavior

All documents should agree: specify-cli on PyPI is the official Spec Kit CLI, and the troubleshooting entry should not tell users that a PyPI install is an unrelated stub.

Actual Behavior

A user who installs via the README's recommended PyPI route (uv tool install specify-cli) and later hits the "Extension requires spec-kit >=0.2.0" troubleshooting entry is told their installation is "a different, unrelated project" with a stub CLI — which is no longer true and is confusing.

Current PyPI metadata confirms the package is official (specify-cli 0.12.17): "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."

This is the only remaining occurrence of the outdated claim — a repo-wide search for "unrelated project" matches nothing else.

Suggested Fix

Update the troubleshooting entry in extensions/EXTENSION-DEVELOPMENT-GUIDE.md to drop the "unrelated project" claim, e.g.:

Fix: Update spec-kit with uv tool install specify-cli --force (or add --from git+https://github.com/github/spec-kit.git to install the latest development version).

Happy to send a small PR for this if that helps.

[github-actions]

Bug assessment — pypi-unrelated-project-warning: Valid · severity low

---

Bug Assessment: Stale "unrelated project" warning in EXTENSION-DEVELOPMENT-GUIDE.md

• Slug: pypi-unrelated-project-warning
• Created: 2026-07-17T13:27:17Z
• Source: issue [Bug]: EXTENSION-DEVELOPMENT-GUIDE.md still claims specify-cli on PyPI is "a different, unrelated project", contradicting README #3575
• Verdict: valid
• Severity: low

Report (summarized)

The troubleshooting section of extensions/EXTENSION-DEVELOPMENT-GUIDE.md (line 690) still warns that the specify-cli package on PyPI is "a different, unrelated project" that produces a stub CLI. This was accurate when written (commit ab9c702, 2026-04-29) to guard against a PyPI squatter package, but the PyPI name was transferred to the spec-kit team (issue #2908, closed 2026-06-26). README.md and docs/installation.md now both document PyPI as an official, maintained installation channel. The guide is the only remaining document with the old warning.

Symptom

A user who installs via the documented uv tool install specify-cli (README) and later consults the "Extension requires spec-kit >=0.2.0" troubleshooting entry is told their installation is "a different, unrelated project" — which is no longer true and will mislead them into thinking they need to reinstall from GitHub even though their PyPI install is fully supported.

Reproduction

1. Install Spec Kit via PyPI: uv tool install specify-cli
2. Encounter the error Extension requires spec-kit >=0.2.0
3. Open extensions/EXTENSION-DEVELOPMENT-GUIDE.md, Troubleshooting → "Extension won't install"
4. Read line 690: told PyPI package is "a different, unrelated project — installing it without --from git+... will give you a stub CLI"
5. Expected: guidance consistent with README and docs/installation.md (PyPI is official)

Suspected Code Paths

• extensions/EXTENSION-DEVELOPMENT-GUIDE.md:690 — the outdated troubleshooting fix text containing the "different, unrelated project" claim

No source code logic is involved; this is a documentation-only issue. Confirmed via grep that "unrelated project" appears only at this one location in the repository.

Root Cause Hypothesis

The troubleshooting entry was written to protect against a PyPI squatter that previously occupied the specify-cli name. After the package was transferred to the spec-kit team (completing issue #2908), README.md and docs/installation.md were updated to document PyPI as an official channel, but the corresponding warning in the extension guide was not updated. Confidence: high — the evidence is fully traceable (commit reference, issue reference, current file state).

Proposed Remediation

Preferred: Update line 690 of extensions/EXTENSION-DEVELOPMENT-GUIDE.md to remove the "unrelated project" claim and present PyPI as a valid update path, e.g.:

Fix: Update spec-kit with uv tool install specify-cli --force (PyPI) or `uv tool install specify-cli --force --from (github.com/redacted) to install the latest development version.

This keeps both install routes mentioned (PyPI for stable releases, GitHub for bleeding-edge) without mischaracterizing either.

Alternatives:

• Minimal removal: simply drop the "a different, unrelated project...stub CLI" sentence and keep only the --from git+... command with no additional commentary. Slightly less helpful than the preferred fix since it hides the simpler PyPI update path.

Files likely to change:

• extensions/EXTENSION-DEVELOPMENT-GUIDE.md (line 690 only)

Tests to add or update:

• No automated tests cover documentation prose; this fix does not require test changes. A doc linting/link-check CI step could be added in the future to catch cross-document contradictions, but that is out of scope for this fix.

Risks & Considerations

• Documentation-only change with no source code impact — zero risk of regressions.
• The reporter offered to submit a PR; this is a good candidate for a community contribution.
• Care should be taken to keep the development-version install path (--from git+...) visible for users who need unreleased features, not just PyPI stable.

Open Questions

• None — the fix is straightforward and all evidence is present.

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 🐛 Assess Bug from Labeled Issue for issue #3575 · 58.3 AIC · ⌖ 11 AIC · ⊞ 31.8K · ◷