Skip to main content
command CX Codex

publish-speckit-ext — Claude Code command: release the extension

publish-speckit-ext — a command to publish the spec-kit extension to a GitHub release. Lets other developers install the extension via catalog without cloning the repository.

MIT ★ 110 updated 2026-11-10

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/publish-speckit-ext.md
Open on GitHub

What publish-speckit-ext does

The command packages the companion extension into a ZIP archive with the correct directory structure and creates a GitHub release with a prefixed tag speckit-ext-v<X.Y.Z>. This is separate from VS Code extension publishing—the result can be installed via specify extension add companion --from <url>.

The full workflow bumps the version, updates CHANGELOG, builds the archive (runtime files only: manifest, commands, workflows, scripts, license—no docs or source), creates a tagged release, and updates the stable companion-latest asset for a permanent install URL. Before publishing, it verifies that all commands listed in extension.yml provides.commands exist, LICENSE is present, and the description is under 100 characters.

What it helps with

  • create a prefixed release tag without triggering VS Code Marketplace automation
  • pack the extension as a ZIP with the structure the installer expects
  • maintain a stable download URL across releases
  • enforce that all commands are registered before packaging

Example prompts for the agent

  • Prepare and release version 2.1.0 of the SpecKit Companion extension
  • Run /publish-speckit-ext and verify the archive is available from the stable link
  • After bumping the version, execute the command to create a GitHub release

How to install publish-speckit-ext

Manually: put the files in place

.claude/commands/publish-speckit-ext.md

Call it with /publish-speckit-ext. For all projects use ~/.claude/commands/

Questions about publish-speckit-ext

How do I install publish-speckit-ext?

In Claude Code, open the alfredoperez/speckit-companion repository. The command loads from .claude/commands/publish-speckit-ext.md. In Codex, copy it to ~/.codex/prompts/publish-speckit-ext.md.

What does publish-speckit-ext do?

Creates a GitHub release of the spec-kit extension ready for catalog installation. Packages files into a ZIP, creates a prefixed tag speckit-ext-v<version>, and updates the stable download URL.

Why use a prefixed tag speckit-ext-v instead of just v?

A bare v* tag triggers the release.yml automation and publishes to the VS Code Marketplace instead of the extension catalog. The prefix prevents this collision and ensures the release reaches only the catalog.

Source text

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

Similar slash commands

All slash commands for DevOps and infrastructure →

From the same set83

The whole set →
speckit.plan The speckit.plan subagent turns a feature specification into research and design artifacts. Use it when you’re ready to plan implementation. CX Codex +1 ★ 110repo stars speckit.taskstoissues speckit.taskstoissues turns the task list from tasks.md into numbered GitHub issues while keeping dependency order. Handy when the plan is already broken into tasks but the tracker is empty. CX Codex +1 ★ 110repo stars submit-catalog-update submit-catalog-update is a Claude Code skill that generates and files an Extension Submission issue for the companion extension in spec-kit. It is used for minor and major version updates. CX Codex +1 ★ 110repo stars feature-clip feature-clip builds SpecKit Companion looping clips through capture, composition, rendering, and media sync for the site and documentation. CX Codex +1 ★ 110repo stars speckit.constitution speckit.constitution is a Claude Code subagent that creates and updates the project constitution at .specify/memory/constitution.md based on team principles. CX Codex +1 ★ 110repo stars ship-ticket The ship-ticket command takes an implemented ticket from branch review through PR creation and merge. Use it when the code is already built in SpecKit Companion. CX Codex +1 ★ 110repo stars speckit.tasks speckit.tasks turns a feature into tasks.md: reads plan.md and spec.md from the feature folder and lays out the work per user story with dependencies. CX Codex +1 ★ 110repo stars speckit.clarify speckit.clarify pins down underspecified details in your feature spec with up to five targeted questions, saving choices directly to disk. CX Codex GP ChatGPT ★ 110repo stars

Project sponsors

Companies that keep this analytics open