flow-next-capture

# /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](../../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](workflow.md) for the full phase-by-phase execution. Read [phases.md](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`: ```bash 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 across phases. Subagents can't call blocking question tools (Claude Code issues #12890, #34592). Duplicate detection, material ambiguities, split selection, and the editor follow-up still need 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 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`). ```bash 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 ``` | Mode | When | Behavior | |------|------|----------| | **Interactive** (default) | User is at the terminal | Phase 0 asks on duplicate detection; Phase 3 asks on must-ask ambiguities; After substantive choices are resolved, write the spec, show its summary, and offer the editor; no generic write approval | | **Autofix** (`mode:autofix`) | Batch usage from another skill / scripted invocation | No user questions; every "ask" branch becomes exit 2; Phase 4 Writes the draft once and requires `--yes` to reach the `.flow/` write | When the sentinel above prints, read [references/autofix-mode.md](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. ```bash 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 **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](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`** — blocking-question tools 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](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`](../../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` → parse `id` → `spec set-plan <id> --file <literal draft path>` (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.