Skip to main content
skill CX Codex

flow-next-qa — Claude Code skill: what it does, how to install

flow-next-qa drives a running app through scenarios pulled from the spec and logs P0/P1/P2 findings backed by captured evidence. Finishes with a ship verdict, yes or no.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What flow-next-qa does

The skill turns the spec's acceptance criteria into test scenarios, maps R-IDs into a coverage table, and treats the boundaries section as a list of what not to test. It drives the app through flow-next-drive, and when a project has .flow/features/, it uses that for navigation between screens.

A ship verdict can only rest on evidence pulled from the live run: screenshots, console output, observed state. Marking something a pass after just reading the source code is explicitly off-limits; with no reachable app or no driver, the outcome is blocked rather than a pass. Reading source to explain a failure already caught on the live app is fine.

It's triggered by /flow-next:qa with a spec id, or runs as the optional pipeline.qa stage inside flow --auto (off by default). It sits alongside CI, staging and manual QA rather than replacing them, and it doesn't touch product code — only files findings and hands them off. That stage is worth turning on only where /flow-next:prime has confirmed the app is ready for QA: seeded data, a documented dev login, a surface that can actually be driven.

What it helps with

  • run a finished feature through scenarios built from acceptance criteria
  • log P0/P1/P2 findings backed by evidence from a live app
  • get a ship-or-not verdict before make-pr
  • check R-ID coverage against real test scenarios
  • wire a first-pass QA check into an autonomous flow --auto pipeline

Example prompts for the agent

  • Run /flow-next:qa against spec SPEC-042
  • Use /flow-next:qa to QA the current feature and show me the verdict
  • Turn on the pipeline.qa stage in flow --auto and check it with /flow-next:qa

How to install flow-next-qa

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

This installs the whole flow-next plugin with all its skills

2Skills CLI (Vercel)

npx skills add gmickel/flow-next --skill flow-next-qa -a claude-code

3Manually: put the files in place

~/.claude/skills/flow-next-qa/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/flow-next-qa/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about flow-next-qa

How do I install flow-next-qa in Claude Code?

Run /plugin marketplace add gmickel/flow-next, then /plugin install flow-next@flow-next.

What does flow-next-qa do?

It drives a running app, checks scenarios derived from the spec, and logs P0/P1/P2 findings with captured evidence, ending in a ship verdict of yes or no.

Can flow-next-qa pass something just by reading the code?

No, that's explicitly forbidden: the verdict relies only on evidence from the running app, and without a reachable app or driver the run is blocked instead.

Source text

SKILL.md · MIT
---
name: flow-next-qa
description: Live-app real-user QA pass derived from the spec. Drives the running app via flow-next-drive, derives scenarios from the spec's AC / R-IDs / boundaries, files structured P0/P1/P2 findings with evidence, and ends with a YES/NO ship verdict receipt. Consumes `.flow/features/` navigation when present. Triggers on /flow-next:qa with a spec id. Runs user-invoked OR as the optional `pipeline.qa` stage of `flow --auto` (default off). Augments — never replaces — CI/staging/manual QA. FORBIDDEN from marking PASS by reading source — the verdict rests on captured evidence from the live app, never on agent narration.
user-invocable: false
allowed-tools: AskUserQuestion, Read, Bash, Grep, Glob, Write, Edit, Task
---

# /flow-next:qa — live-app real-user QA pass

Drive the running app the way an unforgiving real user would, with scenarios taken from the spec,
file P0/P1/P2 findings with captured evidence, and end with a YES/NO ship verdict written as a
`qa_verdict` receipt. The spec is the source of intent: acceptance criteria become scenarios,
R-IDs become the coverage table, boundaries say what not to test, decision context says what the
app should do.

QA is a cheap first live pass over the finished build. It does not replace CI, staging or manual
QA, and it does not fix product code: it files, surfaces and hands off. Findings are advisory; the
human reviewer and the land gate decide.

It runs when the user invokes it, or as the optional `pipeline.qa` stage (`off | on | auto`,
default `off`) that `/flow-next:flow` runs after all tasks are done and before make-pr. When
setting or reading that key, read [gate-selection.md](../flow-next-flow/references/gate-selection.md);
[`flowctl.md`](../../docs/flowctl.md) has the config row. Enable the stage only where
`/flow-next:prime` reports the app is QA-ready (seeded data, a documented dev login, a drivable
surface, readable runtime evidence); otherwise every run ends BLOCKED.

Read [working-rules.md](../../references/working-rules.md) first unless you already have this run; it holds for every step.

## The hard rule

**SHIP rests on evidence captured from the running app** (screenshots, console output, observed
state). A SHIP reached by reading the source or the diff, from narration, or from "the code looks
right" has broken this. With no reachable app or no driver, the outcome is BLOCKED, never a pass.
Reading source to explain a failure you already captured is fine.

## Preamble

flowctl is bundled, not on `PATH`. Define it once; later blocks here and in `workflow.md` use `$FLOWCTL`:

```bash
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
```

This skill runs inline on the host (not forked) so it can ask the user for undocumented facts.

## Arguments

The first non-flag token is the spec id. `--target <url>`, `--receipt <path>` and `--base <ref>`
take a value (as `--flag value` or `--flag=value`). `mode:autonomous` turns on autonomous mode.

```bash
SPEC_ID=""; PREV=""
# No positional parameters: the host rewrites them inside skill code blocks.
# Quote the pasted arguments once so a URL's `&` or `;` stays data.
RAW_ARGS="$ARGUMENTS"
for ARG in $RAW_ARGS; do
  case "$PREV" in
    --target)  QA_TARGET_URL="$ARG"; PREV=""; continue ;;
    --receipt) QA_RECEIPT_OVERRIDE="$ARG"; PREV=""; continue ;;
    --base)    QA_BASE_REF="$ARG"; PREV=""; continue ;;
  esac
  case "$ARG" in
    --target|--receipt|--base) PREV="$ARG" ;;
    --target=*)  QA_TARGET_URL="${ARG#--target=}" ;;
    --receipt=*) QA_RECEIPT_OVERRIDE="${ARG#--receipt=}" ;;
    --base=*)    QA_BASE_REF="${ARG#--base=}" ;;
    mode:autonomous) QA_AUTONOMOUS=1 ;;
    -*) echo "Unknown flag: $ARG (ignored)" >&2 ;;
    *)  [[ -z "$SPEC_ID" ]] && SPEC_ID="$ARG" ;;
  esac
done
[[ -n "$PREV" ]] && echo "Flag $PREV given without a value (ignored)" >&2
[[ "${FLOW_AUTONOMOUS:-}" == "1" ]] && QA_AUTONOMOUS=1
NO_PROMPT=0
[[ "${QA_AUTONOMOUS:-}" == "1" || "${AUTONOMOUS:-}" == "1" ]] && NO_PROMPT=1
export QA_TARGET_URL QA_RECEIPT_OVERRIDE QA_BASE_REF QA_AUTONOMOUS NO_PROMPT
```

**Autonomous mode** (`NO_PROMPT=1`; `flow --auto` dispatches with `mode:autonomous`) asks
nothing. Each fact the interactive run would ask for is resolved from the spec, config or
environment; when it cannot be, the run writes a BLOCKED receipt and exits cleanly. The one
exception is an unresolvable spec id, which is an error (non-zero exit, message on stderr).

Now follow [workflow.md](workflow.md): discover, derive, prepare, execute, file, verdict.

© Gordon Mickel · MIT · gmickel/flow-next

Similar skills

All skills for Testing and QA →

From the same set70

The whole set →
workflow-scout workflow-scout scans repository CI/CD configs, PR and issue templates, automated review bots, and release tooling for readiness checks. CX Codex ★ 730repo stars tooling-scout tooling-scout scans projects for linters, formatters, type checkers and hooks. It is invoked by /flow-next:prime and should not be called directly. CX Codex ★ 730repo stars flow-next-resolve-pr flow-next-resolve-pr coordinates resolution of GitHub PR review feedback, dispatches resolver agents across threads, and closes discussions via GraphQL. CX Codex +1 ★ 730repo stars build-scout build-scout scans project build setup, run commands, CI, and output files. It works through /flow-next:prime, not as a standalone command. CX Codex ★ 730repo stars env-scout env-scout scans your repository for environment templates, Docker files, devcontainers, and bootstrap documentation. Used internally by flow-next. CX Codex ★ 730repo stars testing-scout The testing-scout subagent inspects a project’s test setup, coverage configuration, and CI. It runs through /flow-next:prime, not as a direct invocation. CX Codex ★ 730repo stars why-scout why-scout — a subagent that searches git, PRs, and memory to find why code is structured a certain way. Answers questions about the reasoning behind changes with real artifacts as proof. CX Codex ★ 730repo stars docs-scout docs-scout finds version-matched documentation and inline API signatures for a feature. Helps prep technical context before coding. CX Codex ★ 730repo stars

Project sponsors

Companies that keep this analytics open