/flow-next:capture — agent-native conversation → spec

A free-form discussion (or a /flow-next:prospect survivor) frequently produces enough material for a complete spec, but stops short of the formal flowctl spec create + spec set-plan heredoc documented in CLAUDE.md. Without an explicit synthesis step, that context decays — the next session loses the conversation, the spec never lands, and the user re-explains the same idea to /flow-next:plan.

This skill IS the synthesis. The host agent (Claude Code / Codex / Droid) extracts the recent user turns, drafts a CLAUDE.md-shaped spec with per-line source tags ([user] / [paraphrase] / [inferred] / [strategy:<track>]), writes the spec through existing flowctl plumbing, prints a compact summary, and offers to open it in the editor (capture's saved-spec review in docs/read-back.md). The capture request authorizes the write; there is no approve-and-write checkpoint. Substantive choices still use short questions. There is no Python synthesizer, no codex / copilot subprocess, no fast-model classifier. The host agent is already an LLM and does the work directly.

flowctl provides thin spec plumbing (spec create, spec set-plan, optional spec set-branch, memory search for duplicate detection) plus the chart handoff callback (chart link-spec) after a successful chart-briefing capture. Capture never writes chart files and never mutates a chart's ready flag; chart never writes .flow/specs.

Routing boundary (route matrix)

Clear meaningful ideas and finished chart briefings route here - to capture (or direct spec authoring). Capture does not manufacture a chart for clear work. When intent and boundaries are already stateable, skip chart (signal absent). After a structured brief lands, narrow or skip interview only once the source-grounded synthesis proves no material gaps - never pre-skip interview on hope. Unsure: /flow-next:flow --explain.

Read workflow.md for the full phase-by-phase execution. Read phases.md for the source-tag taxonomy and confidence tiers. Path-specific machinery lives in references/*.md, loaded only when the gate at its branch point fires — a run that never takes a branch never pays for it.

Preamble

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks (here and in workflow.md / phases.md) 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"

Inline skill (no context: fork) — plain-text numbered prompt must stay reachable across phases. Subagents can't call plain-text numbered prompts (Claude Code issues #12890, #34592). Duplicate detection, material ambiguities, split selection, and the editor follow-up still need user choice in interactive mode.

Mode Detection

Parse $ARGUMENTS for the literal tokens mode:autofix and from:flow and the flags --rewrite <spec-id>, --from-compacted-ok, --yes, --override-strategy, --no-plan. Strip recognized tokens; whatever remains is treated as freeform context (ignored - the conversation is the input, not $ARGUMENTS).

RAW_ARGS="$ARGUMENTS"
MODE="interactive"
REWRITE_TARGET=""
FROM_COMPACTED_OK=0
COMMIT_YES=0
OVERRIDE_STRATEGY=0

# Mode token
if [[ "$RAW_ARGS" == *"mode:autofix"* ]]; then
  MODE="autofix"
  RAW_ARGS="${RAW_ARGS//mode:autofix/}"
fi

# --rewrite <id>
if [[ "$RAW_ARGS" =~ --rewrite[[:space:]]+([^[:space:]]+) ]]; then
  REWRITE_TARGET="${BASH_REMATCH[1]}"
  RAW_ARGS="${RAW_ARGS//--rewrite ${REWRITE_TARGET}/}"
fi

# --from-compacted-ok
if [[ "$RAW_ARGS" == *"--from-compacted-ok"* ]]; then
  FROM_COMPACTED_OK=1
  RAW_ARGS="${RAW_ARGS//--from-compacted-ok/}"
fi

# --yes (autofix write gate)
if [[ "$RAW_ARGS" == *"--yes"* ]]; then
  COMMIT_YES=1
  RAW_ARGS="${RAW_ARGS//--yes/}"
fi

# --override-strategy (Phase 5.0 strategy-contradiction override)
if [[ "$RAW_ARGS" == *"--override-strategy"* ]]; then
  OVERRIDE_STRATEGY=1
  RAW_ARGS="${RAW_ARGS//--override-strategy/}"
fi

# --no-plan (explicit opt-in to set the spec-level no_plan field
# in §5.9b after the spec write; on a user invocation the field is never set
# without it) and from:flow (the run was dispatched by
# /flow-next:flow, so §5.9b sets the field when the plan-versus-no-plan rule
# resolves to direct). Both are EXACT-token matches, not substring tests:
# durable state must not be set by lookalikes ("--no-planning",
# "--no-plan=false", "from:flowchart") - those stay in the freeform remainder.
NO_PLAN_OPT=0
FROM_FLOW=0
CLEANED_ARGS=""
for TOK in $RAW_ARGS; do
  if [ "$TOK" = "--no-plan" ]; then
    NO_PLAN_OPT=1
  elif [ "$TOK" = "from:flow" ]; then
    FROM_FLOW=1
  else
    CLEANED_ARGS="$CLEANED_ARGS $TOK"
  fi
done
RAW_ARGS="$CLEANED_ARGS"

if [ "$MODE" = "autofix" ]; then
  echo "GATE ACTIVE — STOP. Read references/autofix-mode.md before continuing."
fi   # default branch: bare no-op — NO link, NO read path

When the sentinel above prints, read references/autofix-mode.md before Phase 0 — it owns the per-phase autofix rules (Phase 0 hard-errors, Phase 3 exits, §4.4 write gate, split / glossary / readiness behavior). On the default interactive path, read nothing.

Ralph-block (R13) — runs first, before everything else

/flow-next:capture requires conversation context and a user to resolve material questions. Ralph cannot provide that interaction. Hard-error with exit 2 when running under Ralph.

if [[ -n "${REVIEW_RECEIPT_PATH:-}" || "${FLOW_RALPH:-}" == "1" ]]; then
  echo "Error: /flow-next:capture requires conversation context + a user at the terminal; not compatible with Ralph mode (REVIEW_RECEIPT_PATH or FLOW_RALPH detected)." >&2
  exit 2
fi

No env-var opt-in. Ralph never decides direction.

Interaction Principles (interactive mode only)

In autofix mode, skip user questions entirely and apply the rules in the autofix reference.

In interactive mode:

Ask the user via plain text. Render the options below as a numbered list 1. … N., followed by a final option N+1. Other — type your own answer. Print the question, then the numbered list, then stop and wait for the user's next message before continuing. Parse the reply as: a bare number 1–N+1 → that option; the literal text of an option label → that option; free text after Other → custom answer.

• Ask one question at a time via plain-text numbered prompt. Never silently skip the question.
• Lead with the recommended option and a one-sentence rationale, followed by a confidence marker — [high] / [judgment-call] / [your-call]. The body carries the recommendation; option labels stay neutral so the user isn't anchored on the option text itself. (See phases.md §Confidence tiers.) Inferred content stays labeled in the saved spec and summary; saving never makes it user-approved.
• Plain language, explained answers (same contract as the interview skill, eval-validated): open with one sentence of stakes; everyday words; a needed term of art gets a ≤1-clause plain gloss at first use; no unexplained acronyms or tool shorthand (R-ID, [inferred] get translated when user-facing); option descriptions state their consequence ("Choose this if…"). Priorities, not length caps — trim repetition and background, never required content.
• Prefer multiple choice when natural options exist (duplicate decisions, split selection, and the open in editor / continue follow-up).
• Do not ask the user for facts they already gave you in conversation — Phase 1 extracts evidence first; Phase 3 asks only on the three hard-error must-ask cases plus genuinely missing context that can't be inferred.

The goal is automated synthesis with human oversight on judgment calls — not a question for every section.

Forbidden behaviors (R10)

• Tech-stack mentions the user did not state. "Needs persistence" is fine; "uses PostgreSQL" needs the user to have said PostgreSQL. Defer technology choices to /flow-next:plan (spec-kit convention — capture writes intent, plan writes implementation).
• Inventing acceptance criteria not in conversation. Every acceptance criterion must be source-tagged; pure [inferred] criteria must surface in the saved-spec summary so the user can edit or reject them.
• Process fences are never spec content. New-vs-rewrite decisions, ready-marking, "do not implement" instructions, and the Phase 0 duplicate-scan outcome are capture's own lifecycle rules; writing them into the spec body or ## Boundaries (under any tag), or stamping them [user], has broken this. Boundaries carry only product constraints a worker on this spec could get wrong.
• Code snippets or specific file paths in the spec body. Those belong in /flow-next:plan task specs after research lands. Capture's output is a high-level spec, not an implementation guide.
• Silent overwrite of an existing spec. Idempotency requires --rewrite <spec-id> (R8). Without it, Phase 0 conflict-detection branches into extend / supersede / proceed-anyway.
• Auto-splitting a spec that has 8+ acceptance criteria. Phase 4 surfaces the option to split; the user decides. Never auto-action a split.
• Setting context: fork — plain-text numbered prompt must stay reachable.
• Treating capture as readiness or execution consent. Phase 5 writes after pre-flight and substantive choices; marking ready, implementation, and external operations retain their own authority.
• Writing glossary terms without consent, or in autofix mode. Term-adds require the separate Glossary? approval; autofix prints suggestions only (--yes consents to the spec write, not to vocabulary changes). The gate is husk-aware (glossary list --json total_terms > 0) — seeding an empty glossary is /flow-next:prime's job, never capture's.
• Marking a spec ready without consent, in autofix, or outside the target-aware readiness predicate. Readiness is the human's gate — capture never infers it.
• Treating a forced draft chart briefing as final, or admitting a draft/stale briefing silently. Fail closed; the override requires named D-IDs + a risk read-back.
• Using git add -A from this skill. When committing the new spec, stage only the JSON sidecar (.flow/specs/<id>.json) + .flow/specs/<id>.md (and .flow/meta.json if the next-id counter mutated). Other working-tree changes are not capture's concern.

Workflow

Execute the phases in workflow.md in order. Each phase's detail — including which branch gate loads which reference — lives there; this index is navigation only:

0. Pre-flight — duplicate detection (spec-title overlap + flowctl memory search), compaction relevance check, idempotency (never a silent overwrite), plus the strategy / duplicate-branch / chart-briefing / rewrite gates.
1. Extract conversation evidence — a verbatim ## Conversation Evidence block FIRST (~30 lines of raw user quotes); spec sections refer to evidence by line, not from agent memory.
2. Source-tagged synthesis — draft each section against the canonical template at plugins/flow-next/templates/spec.md (per R17 — cross-link, never re-embed the section list inline) — the resolved template decides which sections are written, capture adds none it leaves out — tagging only acceptance criteria and prose capture newly authors; route explicit biz-context signals (nine R24 categories) and compute BIZ_SIGNAL_CATEGORIES for Phase 6.
3. Must-ask cases (R9) — ambiguous title / untestable acceptance / scope-conflict; interactive asks one at a time, autofix exits 2.
4. Prepare the write - Materialize the body once, verify source tags, resolve any split choice, and snapshot readiness before rewriting. Autofix retains its --yes write gate.
5. Write via flowctl, then review - spec create --plan-file <literal draft path> → parse id (no heredoc re-authoring), then summary and editor offer. Separate glossary/readiness consents remain. R-IDs allocate from R1; §5.9b sets no_plan on --no-plan, or under from:flow when the route resolves to direct.
6. Suggested next step - Spec captured at .flow/specs/<id>.md. plus the mandatory Tracker sync: slot and the Recommended next: line judged from the shared routing reference; the R25 business-pass suggestion fires at 1 <= BIZ_SIGNAL_CATEGORIES < 3.

Output rules

The new spec is the deliverable — it lives in .flow/specs/<spec-id>.md after Phase 5. Standard output also receives:

• Interactive: the saved-spec summary and editor offer (§5.6a); the full body prints only on request and edit cycles show the diff. Autofix: the draft summary before its existing --yes gate.
• The created spec id + spec path (Phase 5).
• The next-step footer (Phase 6).

Autofix mode without --yes produces a draft + the "rerun with --yes" hint and exits 0 — no write happens, no spec is allocated.