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, and shows the full draft before any file is written.

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 interview targetable afterward. Capture the material first, then sharpen; “interview me on this ticket” skips the step that makes the interview 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 is thin or one-sided, run /flow-next:interview afterwards to deepen it. Chart decision evidence (D-IDs, assets, supersession) is cited as briefing provenance - it does not become acceptance-criterion source tags. Capture (and interview) own trailing tags on criteria they newly write.

Source tags

Every R-ID carries a tag so reviewers can see where it came from:

[user]: verbatim user requirement
[paraphrase]: restated user requirement
[inferred]: agent filled the gap
[strategy:<track>]: derived from STRATEGY.md

The read-back surfaces the [inferred] count up front so the user can reject anything fabricated before it lands on disk.

Mandatory read-back

Capture never writes silently. The full draft is shown through the platform’s blocking question primitive. Only an explicit approve writes the spec file. Anything else aborts cleanly with no on-disk state.

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, the read-back includes a concrete proposal: per-spec titles, which requirements go to which spec, and the dependency edges between them. Answering split-as-proposed shows you every composed spec document, then one confirmation writes the whole linked set.

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 interview - 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 approve. 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 Pilot 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.

flowchart LR
  Chat["Conversation"] --> Extract["Extract user turns"]
  Extract --> Draft["Draft spec"]
  Draft --> Tag["Tag R-IDs by source"]
  Tag --> Read["Read-back to user"]
  Read -->|approve| Write[".flow/specs/<id>.md"]
  Read -->|edit / abort| Stop["No write"]

Flags

Flag	Use
`mode:autofix`	Scripted use; runs without questions and requires `--yes` to commit.
`--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...
Read-back (confirm before write): 9 sections - Goal, Boundaries, 5 acceptance criteria (R1-R5),
  2 Open Questions. Source tags: [stated] x7, [inferred] x2.
Created: .flow/specs/fn-7-rate-limit-alerts.md

The read-back is mandatory: you see exactly what was stated versus inferred before anything is written.

Dynamic usage

Recipes that compose with capture in the cookbook:

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

Next step

/flow-next:plan <spec-id>

Or, to deepen via structured Q&A first:

/flow-next:interview <spec-id> --scope=business