publish-speckit-ext — команда для Claude Code: релиз расширения
Команда publish-speckit-ext для публикации расширения spec-kit в релиз на GitHub. Позволяет другим разработчикам устанавливать расширение через каталог без локального клона репозитория.
MIT ★ 110 обновлён 2026-11-10
.claude/commands/publish-speckit-ext.mdЧто делает publish-speckit-ext
Команда упаковывает расширение companion в ZIP-архив с правильной структурой и создаёт GitHub-релиз с тегом вида speckit-ext-v<X.Y.Z>. Это отдельный процесс от публикации VS Code расширения — здесь результат можно установить командой specify extension add companion --from <url>.
Полный цикл включает проверку версии, обновление CHANGELOG, сборку архива (только runtime-файлы: manifest, команды, workflows, скрипты, лицензия — без документации и исходников), создание тегированного релиза и обновление стабильного asset companion-latest для постоянной ссылки установки. Перед публикацией команда проверяет gates: все команды в extension.yml должны быть перечислены в provides.commands, LICENSE-файл на месте, описание короче 100 символов.
Какие задачи решает
- создать префиксный тег для расширения без срабатывания VS Code Marketplace публикации
- упаковать расширение в ZIP с правильной структурой для installer
- обновить стабильную ссылку релиза при выпуске новой версии
- проверить, что все команды зарегистрированы перед упаковкой
Примеры запросов агенту
- Подготовь и опубликуй версию 2.1.0 расширения SpecKit Companion
- Запусти
/publish-speckit-extи убедись, что архив скачивается по стабильной ссылке - После bump версии запусти команду, чтобы создать релиз на GitHub
Как установить publish-speckit-ext
Вручную: положить файлы
.claude/commands/publish-speckit-ext.mdВызов — /publish-speckit-ext. Для всех проектов — ~/.claude/commands/
Вручную: положить файлы
~/.codex/prompts/publish-speckit-ext.mdВызов — /prompts:publish-speckit-ext. В Codex этот формат помечен устаревшим, замена — скиллы
Вручную: положить файлы
.github/prompts/publish-speckit-ext.prompt.mdВручную: положить файлы
.gemini/commands/publish-speckit-ext.tomlGemini хранит команды в TOML: текст запроса — в поле prompt
Вопросы о publish-speckit-ext
Как установить publish-speckit-ext?
В Claude Code откройте папку репозитория alfredoperez/speckit-companion. Команда загружается из файла .claude/commands/publish-speckit-ext.md. В Codex скопируйте файл в ~/.codex/prompts/publish-speckit-ext.md.
Что делает publish-speckit-ext?
Создаёт GitHub-релиз с расширением spec-kit, готовым для установки через каталог расширений. Упаковывает файлы в ZIP, создаёт префиксный тег speckit-ext-v<версия> и обновляет стабильную ссылку для скачивания.
Почему нужен префиксный тег speckit-ext-v, а не просто v?
Голый тег v* срабатывает автоматизацию release.yml и публикует VS Code расширение вместо companion. Префиксный тег speckit-ext-v* избегает конфликта и гарантирует, что релиз попадёт только в каталог расширений.
Исходный текст
publish-speckit-ext.md · MIT
---
allowed-tools: Bash(git *), Bash(gh *), Bash(zip *), Bash(tar *), Bash(specify *), Bash(node:*), Bash(python3:*), Read, Edit
description: Release the spec-kit extension (companion) to a GitHub release for catalog/--from install
---
## Context
- spec-kit ext version: !`grep -A4 '^extension:' apps/speckit-extension/extension.yml | grep 'version:' | tr -d ' "' | sed 's/version://'`
- Latest spec-kit-ext tags: !`git tag --list 'speckit-ext-v*' --sort=-version:refname | head -3`
- Git status: !`git status --porcelain | head`
## Your task
Release the **spec-kit extension** (`apps/speckit-extension/`, `id: companion`) so people can install it without a local clone. This is **separate from `/publish`** (that's the VS Code extension → Marketplace). Full reference: `apps/speckit-extension/docs/publishing.md`.
### ⚠️ Hard-won rules (do not skip)
1. **Tag namespace** — use a **prefixed** tag `speckit-ext-v<X.Y.Z>`. A bare `v*` tag triggers `release.yml` and would publish the WRONG thing to the VS Code Marketplace.
2. **Archive must be a `.zip`** (the installer rejects `.tar.gz` with `BadZipFile`), with a **single top-level dir** `companion-<X.Y.Z>/` containing `extension.yml` at its root (mirrors the GitHub source-archive layout the CLI expects).
3. **Every command must be registered** in `extension.yml` `provides.commands` — a command markdown that exists but isn't listed is silently skipped by the installer (this bit us once).
4. **Install command needs the name arg**: `specify extension add companion --from <https-url>` (not just `--from`). The URL must be **HTTPS**. A raw-URL install shows a one-time "untrusted source" prompt (expected until the catalog lists it).
### Steps
0. **QA gate.** Apply the Release gate in `.claude/commands/release-qa.md` before anything else: a `QA Report*.md` in the vault for the current HEAD with `verdict: ship` and no open FAIL. If it does not pass, stop and tell the user to run `/release-qa`; continue only on their explicit override. Skip it when `/publish-all` already ran it in its preflight.
1. **Bump** `apps/speckit-extension/extension.yml` `extension.version` (semver). Confirm the target version with the user.
2. **Update** `apps/speckit-extension/CHANGELOG.md` — add a dated section for the new version. The file keeps `[Unreleased]` and the two latest releases: cut every older section and paste it, unchanged, at the top of `apps/website/src/data/changelog-archive-speckit.md` (a test fails on a third release). End-user-friendly entries in the format in `.claude/commands/changelog-entry.md` ("Changelog voice"): highlights under `### Highlights`, one-line bullets with their PR link for the rest.
3. **Readiness checklist** (the catalog guide's gates):
- `id` lowercase-hyphen; `description` **< 100 chars**; `homepage` present; `license` field **and** a `LICENSE` file in `apps/speckit-extension/`; `tags` 2–5.
- **Every `provides.commands[].file` exists** AND every command markdown under `apps/speckit-extension/commands/` is listed in `provides.commands`.
- README is current (it's the catalog listing page).
4. **Commit + push** to `main` (`chore(speckit-ext): release v<X.Y.Z>`).
5. **Build the archive** — **allow-list, runtime files only**. Copy just what the installed extension runs (manifest, dispatched commands, the workflow, the runtime scripts, license). Do NOT ship docs, CHANGELOG, ROADMAP, README, `examples/`, or the build-only `nodes/`+`presets/` sources — the catalog renders README/CHANGELOG from GitHub blob URLs, not the zip. (Don't "restore" a `tar --exclude` deny-list here: an allow-list is what keeps future doc/source additions out of the package.)
```bash
V=<X.Y.Z>
rm -rf /tmp/cb && mkdir -p /tmp/cb/companion-$V/scripts
cd apps/speckit-extension
cp extension.yml LICENSE /tmp/cb/companion-$V/
cp -R commands workflows /tmp/cb/companion-$V/
python3 scripts/package-manifest.py --copy-to /tmp/cb/companion-$V/scripts
cd - >/dev/null
( cd /tmp/cb && zip -rq companion-$V.zip companion-$V )
```
**Never hand-type the script list here.** `scripts/package-manifest.py` is the single source of truth; `--copy-to` fills the archive from it and refuses to copy from a failing list. Hand-enumerating the scripts here is what shipped an archive missing five of them (#432). If a command starts calling a new script, CI fails until the manifest carries it — there is nothing to update in this file.
6. **Cut the release** (prefixed tag, attach the version-named zip for archival):
```bash
gh release create speckit-ext-v$V /tmp/cb/companion-$V.zip \
--title "SpecKit Companion spec-kit extension v$V" \
--notes-file <[X.Y.Z] section of apps/speckit-extension/CHANGELOG.md> --target main
```
7. **Refresh the stable `companion-latest` asset** — this is what the README/install docs point users at, so the install/update URL never changes between releases. Force-replace the **stable-named** `companion.zip` on a reusable `companion-latest` **prerelease** with the *same* build:
```bash
cp /tmp/cb/companion-$V.zip /tmp/cb/companion.zip
if gh release view companion-latest >/dev/null 2>&1; then
gh release upload companion-latest /tmp/cb/companion.zip --clobber
else
gh release create companion-latest /tmp/cb/companion.zip \
--title "SpecKit Companion (latest)" \
--notes 'Rolling stable download for the spec-kit extension. Always serves the newest `companion` build. Install/update: `specify extension add companion --from https://github.com/alfredoperez/speckit-companion/releases/download/companion-latest/companion.zip --force`' \
--prerelease --target main
fi
gh release edit companion-latest --prerelease # idempotent — re-asserts prerelease every run so a mis-marked prior release can't become /releases/latest
```
- **`--prerelease` is mandatory.** It keeps `companion-latest` out of the repo's `/releases/latest` (which resolves across BOTH products — a `v*` VS Code release would otherwise hijack it). The stable URL `…/releases/download/companion-latest/companion.zip` resolves by **tag**, so it's immune to the `v*`/`speckit-ext-v*` interleaving. The trailing `gh release edit … --prerelease` re-asserts the flag on every run (the create path sets it, but an existing release that lost the flag would otherwise stay a normal release). Never document `…/releases/latest/download/…` for this repo.
- The `companion-latest` tag is non-`v*`, so it does **not** trigger `release.yml` (the VS Code Marketplace publish).
8. **Verify the deployed install** (simulate a user) in a scratch dir — install from the **stable** URL, the same one users run:
```bash
mkdir -p /tmp/sk-verify/.specify/extensions && cd /tmp/sk-verify
yes | specify extension add companion --from https://github.com/alfredoperez/speckit-companion/releases/download/companion-latest/companion.zip --force
specify extension list # → SpecKit Companion (vX.Y.Z), all commands listed
```
- Run the scratch install with a CLI at or above `requires.speckit_version`: `uvx -q --from git+https://github.com/github/spec-kit.git@v<latest> specify …` in a bash function (zsh does not word-split a command held in a variable). The local `specify` may be older than the floor this release just raised.
- If a prior local install left **inconsistent emission dirs** (`.{claude,cursor,agents}/skills/speckit-companion-*`, `.{gemini,qwen}/commands/speckit.companion.*`, etc.), the install can throw `FileNotFoundError`. Nuke all companion emission artifacts first, then retry.
- **Expected non-error output** (don't flag these as failures): a raw-URL install shows a one-time `⚠ Untrusted Source` prompt; a pre-existing install aborts with `already installed … retry with --force` (remove first or use `--force`); a stale `✗ companion (v0.1.0) ⚠️ Corrupted extension` must be removed before installing; and a clean install ends with an **informational** `⚠ Configuration may be required / Check: .specify/extensions/companion/` — no manual config is actually needed.
9. **Confirm** neither the prefixed tag nor `companion-latest` triggered `release.yml`: `gh run list --workflow=release.yml --limit 2` (no new run — both tags are non-`v*`).
10. **Refresh the community-catalog entry — MINOR or MAJOR releases only; skip for patches.** A patch (`x.y.Z`) does not touch the catalog: catalog users stay on the current minor and patch fixes ride the rolling `companion-latest` URL. **Do NOT open a PR against `extensions/catalog.community.json`** — direct catalog PRs are rejected (github/spec-kit#3937 was closed with "Updates to extensions must use the extension submission issue template"). Both first listings and version updates go through the **[Extension Submission] issue**. Run **`/submit-catalog-update`**: it renders the issue body from the live upstream issue-form template so our headings cannot drift from theirs, gates on the pinned asset returning 200 and on the minor/major cadence, refuses to file a duplicate, and creates the issue with `gh`. It needs two human-authored inputs — Key Features and Example Usage — and one attestation confirmation.
11. **Report** the release URL + the **stable** install command (`…/releases/download/companion-latest/companion.zip`, re-runnable with `--force` to update), and — on a minor/major — the **catalog submission issue URL** from `/submit-catalog-update`. Maintainers apply the `extension-submission` label at triage, which starts automated catalog validation; there is no follow-up PR.
12. **Retire the old-path stub.** Once a `/submit-catalog-update` issue lands with `homepage` pointing at `apps/speckit-extension`, delete the root-level `speckit-extension/` redirect stub (`README.md` + `CHANGELOG.md`) in a follow-up commit. Skip this on a patch release, since step 10 does too.
Update version references (README badge, `publishing.md`) to the new version; keep the documented install/update URL pointed at the stable `companion-latest/companion.zip`. Never commit a VS Code `package.json` version bump as part of this.
© alfredoperez · MIT · alfredoperez/speckit-companion