Capture

/flow-next:capture turns a recent design conversation into a durable spec without losing the source of each requirement.

The host agent extracts user turns, drafts a structured spec at .flow/specs/<spec-id>.md, tags every acceptance criterion with its origin, saves the spec, and offers to open the saved file in your editor.

When to use it

Capture is the pipeline’s intake valve: it doesn’t want a requirements document, it wants whatever carries the intent. All of these are first-class inputs - pipe one in and say “capture the initial spec”:

• an idea you just talked through with the agent
• a briefing packet from a kickoff
• an already-well-described ticket
• research the agent just ran (“research competitor pricing, then capture a spec for a tiered pricing page”)
• a prototype (“capture a spec from this prototype - ignore the code quality, I want the intent and the requirements it demonstrates”)
• a chart briefing package

Capture is upstream of /flow-next:plan and /flow-next:work. What it hands downstream is more than a document. The spec-count proposal settles “one spec or several?” at intake, and the source tags mark exactly which lines are the agent’s guesses - which is what makes refine targetable afterward. Capture the material first, then sharpen; “refine this ticket” skips the step that makes the question pass precise.

Use it when:

• The conversation already contains the requirement, or a chart briefing is ready.
• Intent and boundaries are stateable (if they are not, chart first - do not force capture).
• You want the spec to credit user statements vs. agent inferences.
• A teammate will pick up the work and never saw the chat.

If the conversation left a product or authority decision open that would change what gets built, run /flow-next:refine afterwards to settle it. Under /flow-next:flow, capture is invoked with the token from:flow; the flow page describes what changes on that path. Chart decision evidence (D-IDs, assets, supersession) is cited as briefing provenance - it does not become acceptance-criterion source tags. Capture (and refine) own trailing tags on criteria they newly write.

Source tags

Capture tags only what it authored, so reviewers can see where each line came from. Your own words stay untagged:

• untagged: your verbatim requirement (trimmed is fine, reworded is not)
• [paraphrase]: your requirement restated in spec language
• [inferred]: agent filled the gap
• [strategy:<track>]: derived from STRATEGY.md

The summary surfaces the [inferred] count so you can inspect assumptions in the saved spec; your words count under [user] in its tally. Capture asks only on duplicates and its must-ask cases (an ambiguous title, an untestable criterion, a scope conflict); other inferred content surfaces in the summary instead of as a question.

The evidence block

An untagged criterion is a claim that you said it, so capture collects your verbatim turns first and checks every untagged line against them before it saves. A close rewording is tagged [paraphrase]. An option you picked from one of capture’s questions counts as your input, recorded as the option label exactly as shown.

With the bundled scaffold those quotes are also written into the spec as a ## Conversation Evidence section, so a reviewer can look up the quote behind a tag. No tool reads that section. If your team finds it is 15 to 20 lines nobody acts on, leave it out of your SPEC.md. The check still runs during capture, and the quotes stay out of the committed file.

Review the saved spec

Asking for capture authorizes saving the spec. Capture writes the file, reports its title, criteria and source tally, and offers open in editor or continue. Edits target that saved file; after an editor round, capture re-reads it, validates the result, and reports the changes. The full spec prints on request.

Substantive questions still happen before a decision is recorded. Saving a spec does not mark it ready, authorize implementation, or grant merge permission. Refine and plan retain their own approval contracts; scripted mode:autofix still requires --yes.

Spec-count proposal (epic-shaped inputs)

Since 3.16.2, capturing an epic, briefing package, or large feature answers the question “is this one spec or several?” for you. At 8+ counted requirements - business and technical only; standing criteria and process items like “tests must be green” never count - or when the requirements clearly serve more than one independently shippable outcome, capture presents a concrete proposal: per-spec titles, which requirements go to which spec, and the dependency edges between them. Choosing split-as-proposed authorizes saving the proposed linked set, followed by the editor offer.

This dissolves the perennial “how big should a spec be?” debate at intake: capture the entire epic, let the proposal scope it into specs whose dependencies are already sorted, then improve each spec where it’s soft - steering prose or a targeted refine - instead of hand-carving one oversized document. The judgment is independence, not size - a large-but-cohesive spec is recommended to stay one spec, and small captures see nothing new. Nothing splits without your say-so; autonomous runs record the proposal inside the spec’s Decision Context instead of acting on it.

Mark-ready offer

When tracker.readyState is not configured, a new capture in a repo that has adopted readiness (≥1 spec already ready) gets one optional consent question after saving. A rewrite gets that question only when the target itself was ready before rewriting - an unrelated ready spec no longer interrupts a draft rewrite. The question explains that mark-ready makes the spec eligible for flow --auto or another autonomous driver; default is keep-draft.

Tracker-connected repos set readiness on the board instead, because the next sync would overwrite a local toggle. --rewrite still resets a previously-ready target to draft before optionally restoring it with explicit consent, and announces the reset only when the flag actually changed. Autofix never writes readiness.

The --no-plan opt-in is the sibling flag for the no-plan route. Pass /flow-next:capture … --no-plan (exact token) and, after the spec write, capture sets the spec-level no_plan field so flow --auto and work take the direct route once the spec is ready. User-invoked capture treats it as explicit consent only - it never sets the field from the conversation or the draft, in interactive and autofix mode alike - and it is flow-local (the tracker-authoritative carve-out above applies to readiness, not to no_plan). Under /flow-next:flow (the from:flow token) capture applies the plan-versus-no-plan rule itself, sets no_plan when the rule resolves to direct, and writes no placeholder requirement-coverage table on that route; capture saves the spec before offering the editor. A request to capture only still stops before implementation. A fresh capture has no tasks yet, so the set always lands; only a --rewrite of an already-planned spec gets the one-line refusal notice.

flowchart LR
  Chat["Conversation"] --> Extract["Extract user turns"]
  Extract --> Draft["Draft spec"]
  Draft --> Tag["Tag what capture authored"]
  Tag --> Write["Save spec"]
  Write --> Review["Open in editor or continue"]
  Review --> Check["Re-read and validate edits"]

Invocation

Flag	Use
mode:autofix	Scripted use; runs without questions and requires --yes to write.
--rewrite <spec-id>	Re-synthesize over an existing spec instead of refusing.
--from-compacted-ok	Override the compaction-detection refusal for compressed transcripts.
--override-strategy	Proceed when the draft contradicts an active STRATEGY.md track; prompts to log a decision-record entry.

Worked example

After a long design conversation has settled the approach:

/flow-next:capture

Synthesizing spec from this conversation...
Saved: .flow/specs/fn-7-rate-limit-alerts.md
Title: Rate-limit alerts   Criteria: 5 (R1-R5)   Source tags: [user] x7, [inferred] x2
Recommended next: /flow-next:work fn-7 --no-plan - ready cohesive spec; no positive plan signal
open in editor / continue (or type a change)

The summary is mandatory. It shows what was stated versus inferred in the saved spec, and the full spec is one request away.

Tips

• Capture while the conversation is still rich. Historical compaction is only a warning when the relevant feature evidence remains fully visible; Capture stops when requirements needed for this spec are missing, truncated, summary-only, or depend on unavailable results.
• The [inferred] tags in the summary are where to look hardest; a wrong inference caught here costs seconds, caught at review it costs a cycle.
• Use --rewrite <spec-id> when the conversation continued past an earlier capture - it overwrites deliberately instead of forking a second spec.

Dynamic usage

Recipes that compose with capture in the cookbook:

• One-shot chains - “capture this, then build it” is a supported single message.
• Team patterns - capture + Spec-as-PR turns a design discussion into a reviewable artifact the same day.

Next step

The closer prints the plan-versus-no-plan rule’s result for the captured spec: Recommended next: /flow-next:work <spec-id> --no-plan - ready cohesive spec; no positive plan signal, or /flow-next:plan <spec-id> - <which signal>. Direct execution is the default for a ready spec. Plan is chosen only on a positive signal: you asked for a plan, separate human owners will implement, or delivery is staged across several PRs. Risk, size, and file count never trigger plan on their own. Design risk routes to plan-review, which reviews a spec with zero tasks; unresolved product or authority choices route to refine, and the closer recommends it only when it can name the open decision: Recommended next: /flow-next:refine <spec-id> - <the named open decision>. Inferred criteria alone are not a reason to refine, and neither are technical detail, performance, or edge cases that implementation, review, and QA will surface (when to refine). The recommendation never grants readiness or no-plan consent by itself.

/flow-next:work <spec-id> --no-plan

Or, when a named decision is still open (or to read the docs of a library the repo does not already use with --scope=research):

/flow-next:refine <spec-id>