Skip to main content
command CX Codex

release-qa — Claude Code command: QA before publish

release-qa is a Claude Code command that checks code before release. It compares the last version tag, runs automated and manual checks, and blocks /publish until all checks pass.

MIT ★ 110 updated 2026-10-19

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

What release-qa does

The release-qa command gates a release in one run. It reads the diff from the last v* tag, executes automated gates (tests, linters), then reviews paths listed in surface-map.yml by hand. The result is a vault report with a verdict—ship if all checks pass, or fix-first with a list of FAIL items. This report is mandatory: /publish* commands refuse to tag without it.

After fixes, call with recheck to run only the checks that ended FAIL or BLOCKED in the latest report, skipping ones already verified. All automated gates run again regardless. Evidence and artifacts (logs, screenshots) go to a local sandbox under $EVIDENCE_DIR, configured by .claude/sandboxes-env.sh.

What it helps with

  • Gate a release: confirm code is ready to ship before tagging
  • Verify changed paths against a checklist map
  • Collect evidence from manual checks into one report
  • Block publish if any FAIL checks remain
  • Re-verify only broken checks after fixes

Example prompts for the agent

  • Run the full baseline QA before the first release: /release-qa
  • After fixes, re-run only the failed checks: /release-qa recheck
  • Review the verdict and open items in Projects/speckit companion/QA Report <YYYY-MM-DD>.md

How to install release-qa

Manually: put the files in place

.claude/commands/release-qa.md

Call it with /release-qa. For all projects use ~/.claude/commands/

Questions about release-qa

How do I install release-qa in Claude Code?

Copy .claude/commands/release-qa.md into your project. The command loads automatically when the project context is set up.

What does release-qa do?

It gates a release by diffing code from the last version tag, running automated checks and manual verification against a path map, then writing a report. The report must say ship and have zero FAIL items for /publish* commands to proceed.

When should I use the recheck argument?

After fixing issues, run /release-qa recheck to re-verify only the checks that failed in the last report, without repeating passes, and generate a new verdict against the current code.

Source text

release-qa.md · MIT
---
allowed-tools: Bash(git:*), Bash(npm:*), Bash(node:*), Bash(python3:*), Bash(code:*), Bash(specify:*), Bash(claude:*), Bash(awk:*), Bash(cp:*), Bash(mkdir:*), Bash(ls:*), Bash(date:*), Bash(open:*), Read, Write, Edit, Skill, TaskCreate, TaskUpdate
description: Release-scoped QA of SpecKit Companion, run once after a batch of fixes. Scopes itself from the diff since the last v* tag, runs automated gates first, spends desktop time on what needs eyes, and writes one vault report with a ship / fix-first verdict. Gates /publish.
argument-hint: "[recheck]"
---

## What this does

QA for a release, once, at the end of a batch. It is issue-agnostic: it reads what is being released (the diff since the last `v*` tag and the `## [Unreleased]` sections of both changelogs), not a ticket list. It is step 3 of `/release-loop` (and `recheck` is step 6); every `/publish*` command refuses to tag without its report.

## Run

Load the `release-qa` skill and follow it in order: Step 0 scope, Step 1 automated gates, Step 2 scripted and desktop checks, Step 3 report. The skill owns the flow, `.claude/skills/release-qa/surface-map.yml` owns which paths need which checks, and the helper scripts next to it do the mechanical work.

`$ARGUMENTS`:
- empty: the full run, baseline included.
- `recheck`: after fixes. Repeats the automated gates and only the checks that ended FAIL or BLOCKED in the latest report, and writes a new report against the new HEAD.

The result is one note, `Projects/speckit companion/QA Report <YYYY-MM-DD>.md` in the vault. Raw evidence stays in the sibling `speckit-sandboxes` checkout, under `$EVIDENCE_DIR/<date>-release-qa/` (and `$EVIDENCE_DIR/<date>-qa-<name>/` for what `qa-stage.sh` stages); `. .claude/sandboxes-env.sh` sets `$EVIDENCE_DIR`.

## Release gate

The publish commands run this before they tag. The gate passes only when all three hold:

1. The newest `Projects/speckit companion/QA Report*.md` in `~/dev/GitHub/obsidian-vault` exists.
2. Its `head` frontmatter equals `git rev-parse --short HEAD`, or every commit in `git log <head>..HEAD --format=%s` is a release commit (`chore: bump version to …`, or `chore(speckit-ext): release …`, `chore(claude-mod): release …` or `chore(canvas): release …`). Anything else means the report is for other code.
3. It says `verdict: ship` and `fails: 0`.

When it does not pass, stop and say why in one line: no report, a report for another sha (name both), or the open FAIL checks. The fix is `/release-qa` (or `/release-qa recheck` after fixes).

Only an explicit instruction in the conversation to skip QA for this release overrides the gate. Say `QA gate overridden` in the release report.

## Guardrails

- QA never edits the repo, files issues, or fixes anything. Every FAIL is a fix candidate in the report, and the next batch picks it up.
- Never run it per ticket, and never on a dirty tree.
- Nothing is repeated: a check runs once however many surfaces ask for it, and a screenshot is shot once and reused as evidence and as a docs candidate.
- A changed path with no surface in the map is reported as `no QA mapping`, never given a guessed check.

© alfredoperez · MIT · alfredoperez/speckit-companion

Similar slash commands

All slash commands for Testing and QA →

From the same set83

The whole set →
speckit.companion.living-show speckit.companion.living-show is a Claude Code command that prints requirement headings, one complete requirement, or rules tied to a file. Run it to inspect a specific part of a living spec without opening the whole document. CX Codex +1 ★ 110repo stars speckit.companion.status speckit.companion.status — a command for Claude Code and Codex reads .spec-context.json and reports the active spec’s step, status, decisions, and next action. It is read-only. CX Codex +1 ★ 110repo stars speckit.plan speckit.plan runs an implementation planning workflow from a feature spec, generating research.md, data models, and API contracts. CX Codex GP ChatGPT ★ 110repo stars sandbox This command builds throwaway SpecKit sandboxes from recipes or lists available recipes and existing folders. It works with Claude Code and Codex. CX Codex +1 ★ 110repo stars install-local The install-local command for Claude Code builds and installs local speckit-companion VS Code and spec-kit extensions, bumping the patch version to trigger an editor reload banner. CX Codex +1 ★ 110repo stars speckit.companion.living-drift speckit.companion.living-drift finds capability files that changed after their living spec was last committed. Use it to spot project changes that have not made it back into the spec. CX Codex +1 ★ 110repo stars speckit.companion.resume speckit.companion.resume is a command for Claude Code that resumes spec-driven development after a pause. It carries recorded decisions forward and starts the next pipeline step. CX Codex +1 ★ 110repo stars speckit.git.commit speckit.git.commit is a Claude Code command that stages and commits changes after Spec Kit commands, according to project configuration. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open