Flow Next Features

/flow-next:features - compounding user-POV drive knowledge

A committed directory (.flow/features/, beside .flow/memory/) records, from the user's point of view, what each user-facing feature is, how a user reaches it, how an agent drives it, and which traps waste a verification run. QA and drive stop re-deriving navigation; work can reuse it to verify what it built.

Split that keeps existing contracts intact: map = how a user gets there (compounds). Spec = what to prove this time. Live drive = proof.

Read seed.md for seed-mode phases. Feature file shape: references/feature-entry-contract.md. Doctor + proof: references/doctor-and-proof.md. Maintain (when MODE=maintain) executes maintain.md.

There is no flowctl features subcommand. The skill validates the four-H2 shape itself. The only flowctl calls are memory list for the feature-map-drift tag handoff and memory add (overlap-judged fold) for bug filing on the maintain path.

Preamble

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

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"

Inline skill (no context: fork) - AskUserQuestion must stay reachable for the few facts seed cannot observe. Subagents cannot call blocking question tools (Claude Code issues #12890, #34592). On portable hosts without AskUserQuestion, fall back to a plain-text numbered prompt with a final Other - type your own answer option. (sync-codex.sh rewrites AskUserQuestion to a plain-text numbered prompt in the Codex mirror.) For read-only scouts use Task with subagent_type: Explore (or the host's generic read-only dispatch with Edit/Write disallowed when Explore is unavailable).

Autonomy refusal

/flow-next:features is user-invoked (or a host loop the human started). Pilot, land, Ralph, and every other autonomous driver must not dispatch it. Scan the autonomy-marker namespace, never a fixed two-var list. Any hit refuses with the typed one-line report and stops.

REFUSE=0
# Namespace scan over autonomy marker families. Never a fixed two-var list.
# Families: FLOW_RALPH*, REVIEW_RECEIPT_PATH, any FLOW_*AUTONOM* name,
# plus the mode:autonomous argument token.
if env | grep -E '^(FLOW_RALPH|REVIEW_RECEIPT_PATH)' >/dev/null 2>&1; then
  REFUSE=1
fi
if env | grep -E '^FLOW_[^=]*AUTONOM' >/dev/null 2>&1; then
  REFUSE=1
fi
case " ${ARGUMENTS:-} " in
  *" mode:autonomous "*) REFUSE=1 ;;
esac
if [ "$REFUSE" = "1" ]; then
  echo 'FEATURES_VERDICT=REFUSED features=0 reason="autonomy marker present; /flow-next:features is user-invoked only"'
  exit 2
fi

Mode Detection

State-resolved, cwd-relative to the repo root (.flow/features/ under the current working directory). No .flow/features/ directory, or explicit init intent (--init, init, mode:seed, --seed in $ARGUMENTS), routes to seed. A present map with no init intent routes to maintain. Consumers elsewhere gate on directory existence only: no config key, no registration.

MODE="maintain"
if [ ! -d ".flow/features" ]; then
  MODE="seed"
fi
RAW_ARGS="${ARGUMENTS:-}"
for ARG in $RAW_ARGS; do
  case "$ARG" in
    --init|init|mode:seed|--seed) MODE="seed" ;;
  esac
done
printf 'MODE=%s\n' "$MODE"

Interaction Principles

• Interview the repo, not the user. Surface, run command, drive mechanism, observable evidence, isolation: read them from the checkout. Ask only what cannot be observed.
• Ask one question at a time via AskUserQuestion (call ToolSearch with select:AskUserQuestion first if its schema is not loaded). Fall back to numbered options in plain text only if the tool is unreachable or errors. Never silently skip the question.
• Prefer multiple choice when natural options exist. Lead with the recommended option and a one-sentence rationale.
• Do not ask before evidence is gathered. Observation first, questions second.
• Multi-surface repos (web + CLI) seed per-surface feature groups under one index. Enumeration is observation: each feature file carries **Surface:**; consumers select by surface + sub-feature IDs.

Forbidden

• Dispatch by an autonomous driver. Pilot, land, Ralph, or any autonomy-marker hit: refuse. Cadence belongs to the human or their host loop.
• Editing product code in maintain. Maintain's edit scope is .flow/features/ plus harness scripts the map owns. Product bugs are reported and kept out of the PR.
• Merging. Never gh pr merge, never /flow-next:land. A changed maintain PR stays open for the human or land.
• Driving an instance this run did not start. Doctor names the owner. An orphaned port from a crashed prior run ends BLOCKED; reclaim is left to the human. Never kill by process name - kill what this run started.
• Setting context: fork - blocking-question tools must stay reachable.
• Duplicating the drive-skill ladder. Live driving consumes flow-next-drive by pointer. A copy of CDP / agent-browser / Computer-Use actuation detail in this skill has broken this.
• Writing an undriven feature file. Nothing enters the map that was not driven once.
• Treating the map as the intent source. Specs and acceptance criteria stay the contract of what to prove. The map is how-to-drive only.

Workflow

1. Run the autonomy-refusal fence. On refuse, the FEATURES_VERDICT=REFUSED line is the last line of the run.
2. Run the mode-detection fence. Honor MODE.
3. seed - execute seed.md in order.
4. maintain - execute maintain.md in order.

Terminal line

Every run ends with exactly one terminal line, the last line of the response, with nothing after it:

FEATURES_VERDICT=<SEEDED|CLEAN|CHANGED|BLOCKED|REFUSED> features=<n> reason="<one line>"

Use features=0 when nothing landed. reason is one line, quoted.