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

/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]), shows the full draft back via AskUserQuestion, and only then writes the spec via existing flowctl plumbing. 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 only thin spec plumbing (spec create, spec set-plan, optional spec set-branch, memory search for duplicate detection). No new flowctl subcommands.

Read workflow.md for the full phase-by-phase execution. Read phases.md for the must-ask cases lookup, source-tag taxonomy, confidence tiers, and forbidden-behaviors list.

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="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Inline skill (no context: fork) — AskUserQuestion must stay reachable across phases. Subagents can't call blocking question tools (Claude Code issues #12890, #34592). Phase 0 (duplicate detection) and Phase 4 (read-back loop) both require user choice in interactive mode. (sync-codex.sh rewrites this to a plain-text numbered prompt in the Codex mirror.)

Mode Detection

Parse $ARGUMENTS for the literal token mode:autofix and the flags --rewrite <spec-id>, --from-compacted-ok, --yes, --override-strategy. 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 commit 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

| Mode | When | Behavior | |------|------|----------| | Interactive (default) | User is at the terminal | Phase 0 asks on duplicate detection; Phase 3 asks on must-ask ambiguities; Phase 4 read-back via blocking-question tool — write only on approve | | Autofix (mode:autofix) | Batch usage from another skill / scripted invocation | No user questions. Phase 0 hard-errors on duplicates / compaction without explicit overrides. Phase 3 must-ask cases hard-error (autofix can't ask). Phase 4 Writes the full draft once (the Write render is the emission) + prints the summary tally to stdout. Writes to .flow/ ONLY when --yes is also passed; without --yes, exit 0 with "draft written; rerun with --yes to commit" |

Autofix mode rules

No user questions. Never call the blocking-question tool.
Phase 0 hard-errors: duplicate detected → list overlapping spec IDs to stderr, exit 2 unless --rewrite <id> was passed; compaction detected → exit 2 unless --from-compacted-ok was passed.
Phase 3 must-ask hard-errors: ambiguous title / untestable acceptance / scope-conflict-with-existing-spec → exit 2 with which case fired and why. Autofix cannot resolve must-ask cases.
Phase 4 single emission, no .flow/ write. Full draft Written once to the §4.1 draft file (the Write render is the full emission — all sections + R-IDs); summary payload ([inferred] tally + 8+ acceptance suggestion if applicable) printed to stdout. Without --yes, exit 0 with the "rerun with --yes" hint. With --yes, proceed to Phase 5 write.
Phase 5 commits identically to interactive once it runs.
Readiness never written. The mark-ready write (workflow.md §5.9) is interactive-consent-only; autofix prints a footer suggestion at most (and only when readiness is adopted, no tracker.readyState, and the spec was written). The --rewrite readiness reset (§5.3) still runs — it is idempotent plumbing, not a consent question.

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

/flow-next:capture requires conversation context + user confirmation. Autonomous loops have neither. 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 above.

In interactive mode:

Ask one question at a time via AskUserQuestion (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded). Fall back to numbered options in plain text only if the tool is unreachable or errors. 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.) Exception — the Phase 4 read-back never recommends approve while unverified [inferred] items exist (no self-blessing; workflow.md §4.2).
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 (Phase 0 duplicate decision; Phase 4 approve/edit/abort).
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 at Phase 4 read-back so the user can reject them.
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 — blocking-question tools must stay reachable.
Calling flowctl spec create before Phase 4 approval. Phase 5 is the only write phase.
Writing glossary terms without consent, or in autofix mode. Term-adds require the Phase 4.2 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.
Using git add -A from this skill. When committing the new spec, stage only the JSON sidecar (.flow/specs/<id>.json post-1.0; .flow/epics/<id>.json on alias-mode 0.x repos that haven't migrated yet) + .flow/specs/<id>.md (and .flow/meta.json if the next-id counter mutated). Other working-tree changes are not capture's concern.

Pre-check: Local setup version

Compare .flow/meta.json setup_version to the plugin version; on mismatch, escalate once per plugin version. Fail-open throughout: a missing jq, .flow/meta.json, or plugin manifest silently continues.

SETUP_VER=$(jq -r '.setup_version // empty' .flow/meta.json 2>/dev/null)
PLUGIN_JSON="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/.claude-plugin/plugin.json"
PLUGIN_VER=$(jq -r '.version' "$PLUGIN_JSON" 2>/dev/null || echo "unknown")
VERSION_ACK=$(jq -r '.version_ack // empty' .flow/meta.json 2>/dev/null)
if [[ -n "$SETUP_VER" && "$PLUGIN_VER" != "unknown" && "$SETUP_VER" != "$PLUGIN_VER" ]]; then
  if [[ "${FLOW_RALPH:-}" == "1" || -n "${REVIEW_RECEIPT_PATH:-}" \
        || "${FLOW_AUTONOMOUS:-}" == "1" || "${ARGUMENTS:-}" == *mode:autonomous* || "${ARGUMENTS:-}" == *mode:autofix* \
        || "$VERSION_ACK" == "$PLUGIN_VER" ]]; then
    echo "Local setup v${SETUP_VER} differs from plugin v${PLUGIN_VER}. Run /flow-next:setup to refresh local scripts." >&2
  else
    echo "FLOW_SETUP_ASK ${SETUP_VER} ${PLUGIN_VER}"
  fi
fi

If the block printed a FLOW_SETUP_ASK line, before proceeding ask the user with AskUserQuestion (local setup differs from the plugin; refresh now?), offering exactly the options Refresh now, Remind me next version, Skip this run, then continue the skill whichever is chosen:

Refresh now: pause and have the user run /flow-next:setup in this session (do not run setup yourself), then continue once it finishes.

Remind me next version: record the acknowledgement so this version is not re-asked (only a later plugin version re-arms it), then continue. Run this self-contained write (fail-open: on any error, continue anyway):

PJ="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/.claude-plugin/plugin.json"
PV=$(jq -r '.version' "$PJ" 2>/dev/null)
[[ -n "$PV" && "$PV" != "null" ]] && rm -f .flow/meta.json.tmp && jq --arg v "$PV" '.version_ack = $v' .flow/meta.json > .flow/meta.json.tmp && mv .flow/meta.json.tmp .flow/meta.json

Skip this run: continue without writing anything; the next invocation asks again.

Any other output (the one-line differs notice, or nothing) is non-blocking: continue.

Workflow

Execute the phases in workflow.md in order:

Pre-flight — duplicate detection (scan .flow/specs/ + .flow/epics/ for legacy alias-mode repos + flowctl memory search on extracted keywords); compaction detection (scan transcript for truncation markers); idempotency (refuse silent overwrite without --rewrite).
Extract conversation evidence — build a verbatim ## Conversation Evidence block FIRST (raw quotes from recent user turns, capped ~30 lines). Spec sections refer to it by line, not from agent memory.
Source-tagged synthesis — draft each section with per-line tags ([user] / [paraphrase] / [inferred]). Apply the canonical template at plugins/flow-next/templates/spec.md (per R17 — cross-link, never re-embed the section list inline). At runtime the template is resolved via the 4-tier discovery cascade — first match wins: <repo_root>/SPEC.md → <repo_root>/spec.md → .flow/templates/spec.md → bundled ${PLUGIN_ROOT}/templates/spec.md. The bundled file is the canonical source of truth; earlier tiers are user-customized overrides. Route explicit biz-context signals (nine SIGNAL CATEGORIES per fn-44 R24, only [user] / [paraphrase] tags) to their destinations; sections without conversation signal stay absent. Compute BIZ_SIGNAL_CATEGORIES (0..9) for Phase 6's R25 dispatch.
Must-ask cases (R9) — interactive only; autofix exits 2 if any fire. Hard-error conditions: ambiguous title / untestable acceptance / scope-conflict. Optional ambiguities use lead-with-recommendation + confidence tier.
Read-back loop (mandatory, even in autofix) — Write the full draft ONCE to a literal unique path (workflow.md §4.1 — the Write render is the read-back); the AskUserQuestion body carries the plain-language summary payload (stakes sentence, every criterion in one plain line, machinery translated, [inferred] callout — workflow.md §4.2; never Recommended: approve while unverified [inferred] items exist) and points to the render (interactive); autofix prints the summary payload to stdout (the render is the emission). Interactive: approve / edit / abort; edit cycles revise via Edit + full-file Read before re-approval. When 8+ acceptance criteria: include consider splitting? as an option (R11). When the glossary is populated (total_terms > 0) and the conversation surfaced new project vocabulary: surface term-add proposals + a consent question after approve (workflow.md §2.7 / §4.2; writes land in §5.8). When readiness is adopted (≥1 ready spec) and tracker.readyState is NOT configured: one Mark ready? consent question after approve, default keep-draft (workflow.md §4.2; write lands in §5.9). Autofix: requires --yes to commit; term proposals print as suggestions, never written; readiness never written.
Write via flowctl — flowctl spec create --title "..." --json → parse id → flowctl spec set-plan <id> --file <literal draft path> --json (consumes the §4.1 draft file — no heredoc re-authoring). Optional flowctl spec set-branch if user named one. Capture creates fresh specs; allocate R-IDs sequentially from R1. --rewrite resets readiness via idempotent spec unready (§5.3); consented mark-ready lands via spec ready (§5.9). When artifacts.html.enabled is true, Phase 5 closes by regenerating the spec render lens at .flow/artifacts/<id>/spec.html per the shared disclosure reference (plugins/flow-next/references/html-artifacts.md) and replacing the spec's artifact link line in place (workflow.md §5.10); the Phase 6 footer then names the artifact path. With the mode off/unset there is zero artifact-related behavior or output.
Suggested next step — print Spec captured at .flow/specs/<id>.md. plus /flow-next:plan <id> and /flow-next:interview <id> next-step hints. When BIZ_SIGNAL_CATEGORIES triggers flowctl scope suggest (R25 fire/no-fire threshold lives in flowctl — skill never re-implements the math inline), append the /flow-next:interview --scope=business suggestion line.

Output rules

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

The full draft (Phase 4) — emitted once via the §4.1 Write render (interactive and autofix alike); the summary payload rides in the read-back question body (interactive) or prints to stdout (autofix).
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.

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

Install this agent skill to your local

Skill Files