flow-next-flow

/flow-next:flow - the conductor

Flow chooses the next step so the user does not have to. It reads what it was given, routes from the shared routing reference, runs the routed stage skill, and continues until the next decision that belongs to a human. It re-implements no stage logic: capture, refine, plan, plan-review, work, qa, make-pr, resolve-pr, and land keep their own contracts, receipts, and gates.

Role: conductor, inline (no context: fork) so plain-text numbered prompt stays reachable. On hosts without it, fall back to a plain-text numbered prompt with a final Other - type your own answer option.

The hop loop is Steps 1 to 5 below. Read a reference only at the step that names it.

Preamble

CRITICAL: flowctl is BUNDLED - NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks (here and in the steps below) use $FLOWCTL:

FLOWCTL="${CODEX_HOME:-$HOME/.codex}/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"

Mode detection

Parse $ARGUMENTS as exact tokens (never substrings), before any read or write: --auto sets AUTO=1, and so does --goal, because goal mode is unattended; --tick sets AUTO_TICK=1 (one hop, then stop; meaningful only with --auto or --goal); --explain sets EXPLAIN=1; --review=<backend> sets REVIEW_OVERRIDE and is passed through unchanged to every stage it dispatches. The destination parse is shared by both modes:

FLOW_UNTIL=""
FLOW_DESTINATION_ERROR=0
LAND_AUTHORIZED=0
LAND_SCOPE_SPEC=""
LAND_SCOPE_PR=""
AUTO=0
for ARG in $ARGUMENTS; do
  case "$ARG" in
    --auto|--goal) AUTO=1 ;;
    --until=merge) FLOW_UNTIL=merge ;;
    --until|--until=*) FLOW_DESTINATION_ERROR=1 ;;
  esac
done
if [ "$FLOW_DESTINATION_ERROR" = 1 ]; then
  if [ "$AUTO" = 1 ]; then
    echo 'PILOT_VERDICT=NEEDS_HUMAN spec=- stage=- reason="invalid destination; use --until=merge"'
  else
    echo 'NEEDS_HUMAN: invalid destination; use --until=merge'
  fi
  exit 1
fi
export FLOW_UNTIL