/flow-next-spec-completion-review

name: flow-next-spec-completion-review
description: Spec completion review - verifies all spec tasks implement the spec requirements. Triggers on /flow-next:spec-completion-review.
user-invocable: false

Spec Completion Review Mode

**Workflow is backend-split. Read [workflow-common.md](workflow-common.md) for Phase 0 (backend detection + philosophy), then read ONLY the file matching your active backend:**

• `BACKEND=codex` → [workflow-codex.md](workflow-codex.md)
• `BACKEND=copilot` → [workflow-copilot.md](workflow-copilot.md)
• `BACKEND=cursor` → [workflow-cursor.md](workflow-cursor.md)
• `BACKEND=claude` → [workflow-claude.md](workflow-claude.md)
• `BACKEND=host` → [workflow-host.md](workflow-host.md)

Do not load the others — only the active backend's file is needed.

Verify that the combined implementation of all tasks in a spec satisfies the spec requirements. This is NOT a code quality review (that's impl-review's job) — this confirms spec compliance only.

**Role**: Spec Completion Review Coordinator (NOT the reviewer) **Backends**: Codex CLI (codex), GitHub Copilot CLI (copilot), Cursor CLI (cursor), Claude Code CLI (claude), or host-native (`host`)

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

Preamble — execute Phase 0 exactly once

**The executable Phase 0 lives in [workflow-common.md](workflow-common.md) §"Phase 0: Backend Detection" — Read it and execute it ONCE, before any other bash in this skill.** It defines `$FLOWCTL` (bundled — NOT installed globally; `which flowctl` fails, expected), resolves `$BACKEND` via the single `flowctl review-backend` call, and handles the ASK / `none` cases. Never invoke `flowctl review-backend` a second time in the same run.

Exception: a `--review=<backend>` argument wins — when present, set `BACKEND` from the flag and skip Phase 0's `review-backend` call + ASK handling (still run its `$FLOWCTL` setup lines). A value that is not one of the backends below stops as for ASK, naming them.

Backend at a glance

The per-backend summary (models, env vars, `--spec` forms and `FLOW_REVIEW_BACKEND` spec-form examples) and the `backend[:model[:effort]]` spec grammar live in [references/backend-at-a-glance.md](references/backend-at-a-glance.md). Read it **only** when you surface backend guidance to the user (ASK branch, recommendation, override hint) — routing does not need it.

Critical Rules

Per-backend critical rules live in the backend file you route to (`workflow-codex.md`, `workflow-copilot.md`, `workflow-cursor.md`, `workflow-claude.md`) — each opens with its own **Critical rules** section. The host safety invariant and the all-backends rules stay here because they gate routing itself.

**For host backend:** `host` is bare-only. After selection, read [workflow-host.md](workflow-host.md). The review must use a fresh, tool-enforced read-only reviewer from a different model family and fail closed when no cross-family pin is available.

**For all backends:**

• Any failure → output `RETRY: no verdict (backend or transport failure)` and stop; when its

`CLI message:` reports a usage, credit or spend limit, report that message instead of `RETRY:`, since a retry fails the same way. No-verdict transport failures are recorded and their reserved round refunded; never manually reset the review counter. Exit 5 / `TRANSPORT_UNHEALTHY` stops automatic retries until the backend is repaired.

The three **hard invariants** (never self-declare SHIP, never mix backends, never skip review silently) live with the shared anti-patterns in [workflow-common.md](workflow-common.md) §"Anti-patterns (all backends)".

Input

Arguments: $ARGUMENTS Format: `<spec-id> [--review=codex|copilot|cursor|claude|host|none]`

• Spec ID - Required, e.g. `fn-1` or `fn-22-53k`
• `--review` - Optional backend override

Workflow

Step 0: Parse Arguments

Parse $ARGUMENTS for:

• First positional arg matching `fn-*` → `SPEC_ID`
• `--review=<backend>` → backend override
• Remaining args → focus areas

Step 0.5: Resume terminal status persistence before dispatch

Run this checkpoint after parsing `SPEC_ID` and **before** loading or dispatching any backend. Run the same checkpoint again immediately after host records a verdict. It recovers a terminal status write that failed after the verdict round was durably consumed, without reserving or dispatching another review. Host terminal status has one owner, `review-rounds record --status-target completion` (with a journaled receipt, that status leg lands when the receipt publishes); this checkpoint only repairs a write that did not land. A stored `not_required` (work's 3g policy skip) is neither `ship` nor `unknown` here: the checkpoint has no terminal attempt to resume for it, and an explicit manual invocation may still run a real review and overwrite it with `ship`/`needs_work` — the upgrade direction is legal, while the skip's own write stays gated on `unknown`.

TERMINAL_REVIEW_JSON="$($FLOWCTL review-rounds resume-terminal "$SPEC_ID" --review-type completion --json)" || exit $?
TERMINAL_ACTION="$(printf '%s' "$TERMINAL_REVIEW_JSON" | jq -r '.action')"
TERMINAL_STATUS="$(printf '%s' "$TERMINAL_REVIEW_JSON" | jq -r '.status')"
TERMINAL_EXIT="$(printf '%s' "$TERMINAL_REVIEW_JSON" | jq -r '.exit')"
case "$TERMINAL_ACTION" in
  continue) ;;
  retry) echo "RETRY: no verdict (backend or transport failure)"; exit "$TERMINAL_EXIT" ;;
  ship) echo "VERDICT=SHIP"; exit "$TERMINAL_EXIT" ;;
  superseded) echo "COMPLETION_REVIEW_STATUS=$TERMINAL_STATUS"; exit "$TERMINAL_EXIT" ;;
  escalate)
    if [ "$TERMINAL_STATUS" = needs_human ]; then
      echo "ESCALATE: reviewer requested human review"
    else
      echo "ESCALATE: completion-review did not converge within the verdict-round cap"
    fi
    exit "$TERMINAL_EXIT" ;;
  *) echo "Unknown terminal review action: $TERMINAL_ACTION" >&2; exit 1 ;;
esac

An exi