QA Checklist

A cross-harness skill for LLM agents: analyzes git changes and prepares a manual testing checklist for the QA team. Supports Claude Code, Codex, and Cursor from a single shared core.

Invocation

/qa-checklist            # asks for the comparison base
/qa-checklist develop    # directly against the develop branch
/qa-checklist HEAD~3     # against the given ref
/qa-checklist main..feature

If the base is not passed as an argument, the skill offers a choice: base branch (auto-detected develop → main → master), last commit, uncommitted changes, or a custom ref/range.

Example output

A finished checklist looks like the template below. It is written in English by default, grouped by application surface, with one checkbox per user-observable change. The Inspiration block is on by default — add without inspiration to the invocation to omit it.

# QA checklist: feature/dark-mode compared to develop

## Summary of changes

This branch adds a dark-mode toggle to the settings page and validates discount
codes before payment in the checkout flow.

## Inspiration

Night falls on the page,
each code weighed before it pays —
ship calm, all is well.

## Checklist

### Settings

- [ ] **Dark-mode toggle**
  - **Before / after:** Settings had no theme option; a dark-mode toggle is now available.
  - **Expected behavior:** Toggling switches the theme immediately and the choice persists across reloads.
  - **How to verify:** Open Settings, toggle dark mode, reload the page, and confirm the theme is retained.

### Checkout

- [ ] **Discount code validation**
  - **Before / after:** Discount codes were applied without a validity check; they are now validated before payment.
  - **Expected behavior:** An invalid code shows an error and is not applied; a valid code reduces the order total.
  - **How to verify:** At checkout, enter an invalid code then a valid one, and confirm the messages and totals.

## Low risk / internal (manual testing not required)
- Internal refactor of the price-formatting helper (no user-visible change).

How it works

1. scripts/detect-base.sh determines the repository state and the base branch.
2. The user chooses the comparison base (via the harness adapter).
3. scripts/collect-diff.sh collects the diff for the chosen mode.
4. The shallow subagent reads the whole diff, groups changes by "application surface", and writes the summary; the orchestrator keeps only the compact map.
5. The deep subagents (one per user-facing group) fetch their own diff slice and return checklist items.
6. The orchestrator assembles the final markdown in English (or the language the user explicitly requested), prints it to the chat, and on request saves it to docs/qa/<date>-checklist.md.

Structure

• skills/qa-checklist/SKILL.md — shared workflow core
• skills/qa-checklist/references/ — subagent instructions (English)
• skills/qa-checklist/adapters/ — harness specifics (asking the user, spawning subagents)
• skills/qa-checklist/scripts/ — git logic (bash)

The heavy logic (scripts, references, SKILL.md) is shared across all harnesses; only the thin adapters differ.

Installation

Claude Code

No local clone needed — install straight from GitHub. Add the repository as a plugin marketplace and install the plugin:

/plugin marketplace add TuiKiken/qa-checklist
/plugin install qa-checklist@qa-checklist-dev

/plugin marketplace add accepts the owner/repo GitHub shorthand, a full Git URL, or a local path to a clone. Manifest: .claude-plugin/marketplace.json (plugin qa-checklist, source: ./). Claude discovers the skill in skills/qa-checklist/ automatically.

Codex

Codex installs from a local clone, so clone the repository first:

git clone https://github.com/TuiKiken/qa-checklist.git
cd qa-checklist

Then symlink the skill into Codex's skills directory:

ln -s "$PWD/skills/qa-checklist" ~/.codex/skills/qa-checklist
# or repo-local:
ln -s "$PWD/skills/qa-checklist" .agents/skills/qa-checklist

Subagent registration is not needed — the skill spawns Codex's built-in agents (explorer/default) ad-hoc with an inline instruction pointing at the reference files.

Cursor

Cursor installs from a local clone, so clone the repository first:

git clone https://github.com/TuiKiken/qa-checklist.git
cd qa-checklist

Then symlink the skill into Cursor's skills directory:

ln -s "$PWD/skills/qa-checklist" ~/.cursor/skills/qa-checklist
# or repo-local:
ln -s "$PWD/skills/qa-checklist" .agents/skills/qa-checklist

Tests

bash tests/run.sh

Unit tests for the deterministic shell layer (detect-base.sh, collect-diff.sh) run against temporary git fixture repositories and are bash 3.2 compatible.

Releasing (version bump)

The plugin version lives in four manifests and must stay in sync: .claude-plugin/plugin.json, .claude-plugin/marketplace.json, .codex-plugin/plugin.json, .cursor-plugin/plugin.json. Bumping it is what makes harnesses pick up an update, so every change published to main needs a new version.

Enable the guard hook once per clone:

git config core.hooksPath .githooks

Then bump and push:

scripts/bump-version.sh patch     # 0.1.0 -> 0.1.1  (also: minor | major | X.Y.Z)
git push --follow-tags

bump-version.sh rewrites all four manifests, commits chore: release vX.Y.Z, and creates a vX.Y.Z tag. You can also raise the version by hand (e.g. a major bump) — that works too.

The .githooks/pre-push hook does not auto-bump. It only blocks a push to main when the version was not raised above what is already on the remote, so a manual bump is never double-bumped and forgetting to bump is caught. Pushes to other branches are not gated.