Skip to content

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.

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. Under flow --auto --from-issue it is invoked with from:issue, and the issue is its only source (Capture from a tracker issue). 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.

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.

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.

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.

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.

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"]

Name the issue and the spec links to it. With the tracker bridge active, a capture that names an existing issue (“capture a spec for WOR-17”) links the new spec to that issue in every id mode. Under tracker.specIds=tracker the spec is keyed by the issue (wor-17-...). In the default flow-id mode the spec keeps its fn-N id and, since 9.11.0, records the issue as its tracker link, so the capture push updates that issue instead of creating a second one. When the issue cannot be read, or another spec already links it, capture saves the spec unlinked, names the reason (and the spec that holds the link, when that is the reason), and skips the tracker push: Tracker sync: skipped (named issue not linked: <reason>). It never takes a link away from another spec.

Under a parent. Name a parent for the work while capturing, for example “capture this under PROJ-12” or “as sub-issues of ENG-40”, and every spec this capture writes records it, each child of a split included unless you say otherwise. Capture records the parent only while the tracker bridge is active; with the bridge off it records nothing and says so in one line. The issue each spec gets is created under that parent on Jira Cloud, Linear and GitLab (an epic). The parent is never treated as the spec’s own issue: capture does not read it, link to it or seed the spec from it. On GitHub and Jira Data Center / Server the create refuses a parent, and capture reports that as its Tracker sync: outcome rather than creating the issue without it (Parent issue at creation).

From an issue start. flow --auto --from-issue invokes capture with from:issue. The issue stands in for the conversation: its body and comments are the only source, and after an earlier question the body and the comments since that question. Goal & Context opens with the issue’s own text quoted verbatim, so the design review that follows compares the spec with the issue itself. Every acceptance criterion is the issue’s words or a [paraphrase] of them. A criterion that would have to be [inferred] becomes a question for the issue instead, and capture writes nothing. Capture also refuses a duplicate open spec, and it never splits an issue into several specs. The spec’s Boundaries carry the line “Every task gets implementation review; the risk rule does not skip it.”, so every worker and later run that reads the spec reviews each task. Under from:issue capture never marks the spec ready and never commits; the run does both.

When flow starts from a Jira Product Discovery idea, capture treats the idea as source material and never links a spec to it as the spec’s own issue. Capture runs as usual, with its split proposal, your choice and its cycle check. Each spec’s Goal & Context quotes the part of the idea it serves and gives the idea’s key and URL, and its Decision Context names the sibling specs and the idea, with the parent issue’s key and URL added once flow settles the parent. Capture saves the specs locally with flow ids. Its push, its later sync check and any retry push all wait until flow has created their issues under the idea’s parent, so nothing reaches the tracker before the specs exist and no issue is created without its parent. See Idea intake.

FlagUse
mode:autofixScripted use; runs without questions, and every question it would have asked becomes exit 2. Without --yes it prints the draft summary and exits 0 with no spec written.
--yesThe write consent for mode:autofix.
--rewrite <spec-id>Re-synthesize over an existing spec instead of refusing.
--from-compacted-okOverride the compaction-detection refusal for compressed transcripts.
--override-strategyProceed when the draft contradicts an active STRATEGY.md track; prompts to log a decision-record entry.
--no-planAfter the spec is written, set its no_plan field so work builds it as one unit with no task breakdown. Capture sets the field only on this flag; it never infers it on a run you invoke.
from:flowSent by /flow-next:flow. Capture applies flow’s plan-or-no-plan rule and sets no_plan itself when the rule resolves to building directly.
from:issueSent by an issue start. Writes one linked no-plan spec from the tracker issue without asking.
from:goalSent by /flow-next:flow --goal. Writes without asking: the goal spec from the source named after the token (a path, a URL, a tracker issue or pasted text), or, when an open goal spec id follows, one child spec for the gap the goal run stated. A goal with no checkable criterion, or a child that would cross a goal Boundary, reopen a settled decision or duplicate an open spec, exits 2 with the reason.

The flags and tokens match exact words only, so --yesterday or from:flowchart in your text is not read as one.

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.

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.

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> - a plan or task breakdown was asked for. Direct execution is the default for a ready spec. Plan is chosen only when you ask for a plan or a task breakdown, in your request or in the spec. Size, risk, file count, several repositories, separate owners and delivery over several PRs all stay on the direct route. 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.

Terminal window
/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):

Terminal window
/flow-next:refine <spec-id>