Skip to main content
skill CX Codex

flow-next-capture — Claude Code skill: what it does, how to install

flow-next-capture synthesizes the active conversation context into a structured flow-next spec under .flow/specs/ using the bundled flowctl tool.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What flow-next-capture does

The skill inspects user turns in the active session, drafts a spec against the target template, and writes the output file into .flow/specs/<spec-id>.md. It tags generated text systematically: exact user quotes remain untouched, while any paraphrased or deduced elements receive [paraphrase] or [inferred] tags. Inventing unmentioned tech stacks is explicitly blocked.

The required flowctl CLI tool comes bundled inside the plugin repository rather than installed in the global PATH, meaning running which flowctl will fail as expected. Everything runs inline within the agent session so tool calls like AskUserQuestion remain functional without subprocess detachment.

Interactive runs prompt only on critical decisions, present a summary, and offer the file in your editor. For automated tasks, passing mode:autofix suppresses all user prompts and halts unless the --yes flag is explicitly present.

What it helps with

  • turn a messy discussion into a structured .flow/specs/ document
  • isolate agent inferences with source tags before saving
  • overwrite an existing spec cleanly via --rewrite <spec-id>
  • pass conversational context downstream into /flow-next:flow runs

Example prompts for the agent

  • /flow-next:capture
  • lock down what we discussed into a flow-next spec
  • convert conversation to spec --no-plan

How to install flow-next-capture

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

This installs the whole flow-next plugin with all its skills

2Skills CLI (Vercel)

npx skills add gmickel/flow-next --skill flow-next-capture -a claude-code

3Manually: put the files in place

~/.claude/skills/flow-next-capture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/flow-next-capture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about flow-next-capture

How to install flow-next-capture in Claude Code?

Register the catalog with /plugin marketplace add gmickel/flow-next and then install the plugin using /plugin install flow-next@flow-next.

What does flow-next-capture do?

It reads conversation turns, creates a spec at .flow/specs/<spec-id>.md via flowctl, and tags inferred points so no context gets lost between sessions.

Do I need to install flowctl globally beforehand?

No, flowctl is bundled within the plugin; testing for it with which flowctl will fail by design.

Source text

SKILL.md · MIT
---
name: flow-next-capture
description: Synthesize the current conversation context into a flow-next spec at `.flow/specs/<spec-id>.md` via `flowctl spec create --plan-file` — agent-native, source-tagged, with a saved-spec summary and editor follow-up. Triggers on /flow-next:capture, "capture spec", "lock down what we discussed", "make a spec from this conversation", "convert conversation to spec". Optional `mode:autofix` token runs without questions and requires `--yes` to write. Optional `--rewrite <spec-id>` overwrites an existing spec; `--from-compacted-ok` overrides the incomplete-evidence refusal after compaction; `--override-strategy` proceeds despite a contradiction with an active STRATEGY.md track (and prompts to record the override as a decision); `--no-plan` sets the spec-level `no_plan` field after the write (explicit opt-in on a user invocation, never inferred there); `from:flow` marks a run dispatched by `/flow-next:flow`, where capture applies the shared plan-versus-no-plan rule and sets the field itself when the rule resolves to direct; `from:goal` marks a `/flow-next:flow --goal` run, which writes without asking from a goal source or for a goal's child.
user-invocable: false
allowed-tools: AskUserQuestion, Read, Bash, Grep, Glob, Write, Edit, Task
---

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

A discussion (or a `/flow-next:prospect` survivor) often holds a complete spec that never gets written down, and the next session loses it. Capture is the synthesis step: the host agent extracts the user's turns, drafts a spec against the resolved template, **tags only what it paraphrased or inferred** (`[paraphrase]` / `[inferred]` / `[strategy:<track>]`; the user's verbatim words stay untagged), writes it through flowctl, prints a compact summary, and offers the saved file in the editor ([docs/read-back.md](../../docs/read-back.md)). The capture request authorizes the write; substantive choices still get short questions. No Python synthesizer, no model subprocess.

flowctl supplies thin plumbing (`spec create`, `spec set-plan`, `spec set-branch`, `memory search`) plus the `chart link-spec` callback after a chart-briefing capture. Capture never writes chart files or a chart's `ready` flag; chart never writes `.flow/specs`.

Clear ideas and finished chart briefings route here; capture never manufactures a chart for clear work. Unsure: `/flow-next:flow --explain`.

**Read [workflow.md](workflow.md) for the phases and [phases.md](phases.md) for the source tags.** Branch-specific machinery lives in `references/*.md`, loaded only when its gate fires.

Read [working-rules.md](../../references/working-rules.md) first unless you already have this run; it holds for every step of this skill.

## Preamble

**CRITICAL: flowctl is BUNDLED — NOT installed globally.** `which flowctl` will fail (expected).
workflow.md's Preamble defines `$FLOWCTL`; later blocks (there and in `phases.md`) use it.

**Inline skill (no `context: fork`)** — `AskUserQuestion` must stay reachable across phases; subagents cannot call blocking question tools.

## Mode Detection

Parse `$ARGUMENTS` for the literal tokens `mode:autofix`, `from:flow` and `from:goal` and the flags `--rewrite <spec-id>`, `--from-compacted-ok`, `--yes`, `--override-strategy`, `--no-plan`. Strip recognized tokens; the remainder is ignored (the conversation is the input), except under `from:goal`, where it names the goal or its source.

```bash
RAW_ARGS="$ARGUMENTS"
MODE="interactive"
REWRITE_TARGET=""
FROM_COMPACTED_OK=0
COMMIT_YES=0
OVERRIDE_STRATEGY=0

if [[ "$RAW_ARGS" == *"mode:autofix"* ]]; then
  MODE="autofix"
  RAW_ARGS="${RAW_ARGS//mode:autofix/}"
fi

if [[ "$RAW_ARGS" =~ --rewrite[[:space:]]+([^[:space:]]+) ]]; then
  REWRITE_TARGET="${BASH_REMATCH[1]}"
  RAW_ARGS="${RAW_ARGS//--rewrite ${REWRITE_TARGET}/}"
fi

if [[ "$RAW_ARGS" == *"--from-compacted-ok"* ]]; then
  FROM_COMPACTED_OK=1
  RAW_ARGS="${RAW_ARGS//--from-compacted-ok/}"
fi

# --yes (autofix write gate), --override-strategy, --no-plan, from:flow and
# from:goal authorize durable writes, so they are EXACT-token matches: lookalikes
# ("--yesterday", "--no-planning", "from:flowchart", "from:goals") stay in the remainder.
NO_PLAN_OPT=0
FROM_FLOW=0
FROM_GOAL=0
CLEANED_ARGS=""
for TOK in $RAW_ARGS; do
  if [ "$TOK" = "--yes" ]; then
    COMMIT_YES=1
  elif [ "$TOK" = "--override-strategy" ]; then
    OVERRIDE_STRATEGY=1
  elif [ "$TOK" = "--no-plan" ]; then
    NO_PLAN_OPT=1
  elif [ "$TOK" = "from:flow" ]; then
    FROM_FLOW=1
  elif [ "$TOK" = "from:goal" ]; then
    FROM_GOAL=1
  else
    CLEANED_ARGS="$CLEANED_ARGS $TOK"
  fi
done
RAW_ARGS="$CLEANED_ARGS"

# from:goal is an unattended write the --goal invocation already consented to.
if [ "$FROM_GOAL" = "1" ]; then
  MODE="autofix"
  COMMIT_YES=1
  echo "GATE ACTIVE — STOP. Read references/from-goal.md before continuing."
fi
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 | Asks on duplicates and must-ask cases; writes the spec, shows its summary, offers the editor; no generic write approval |
| **Autofix** (`mode:autofix`) | Batch or scripted invocation | No questions; every ask becomes exit 2; writes only with `--yes` |

When the sentinel prints, read [references/autofix-mode.md](references/autofix-mode.md) before Phase 0; it owns the per-phase autofix rules. Under `from:goal`, read [references/from-goal.md](references/from-goal.md) as well; it says where a goal run's source differs. On the interactive path, read nothing.

## Questions (interactive only)

Interactive capture follows the working rules' attended contract, plus:

- Use `AskUserQuestion` (load it with `ToolSearch` `select:AskUserQuestion` if needed); plain-text numbered options only when the tool is unreachable. Never skip a question silently.
- The body leads with the recommendation, a one-sentence reason, and a confidence tier (`[high]` / `[judgment-call]` / `[your-call]`; before asking, read [references/confidence-tiers.md](references/confidence-tiers.md)). Option labels stay neutral and state their consequence.
- Plain language: one sentence of stakes, everyday words, a short gloss for any needed term (`R-ID`, `[inferred]`).
- Never ask for facts the conversation already gave. Phase 3 asks only its must-ask cases; other `[inferred]` content surfaces in the summary instead.

## Forbidden behaviors

These protect spec trust:

- **Unstated technology.** "Needs persistence" is fine; "uses PostgreSQL" needs the user to have said it. Capture writes intent; plan writes implementation.
- **Unmarked invention.** An untagged line claims to be the user's words and must be findable in the evidence; every paraphrase or fill-in carries its tag, and `[inferred]` criteria surface in the summary for the user to keep, edit, or drop. Saving never upgrades a tag.
- **Process fences as spec content.** New-vs-rewrite decisions, ready-marking, "do not implement", and the duplicate-scan outcome are capture's lifecycle, never spec body or `## Boundaries` lines, and never evidence lines. Boundaries hold only product constraints a worker could get wrong.
- **Coordinates in the spec body.** State contracts (types, signatures, behaviors, invariants), not code snippets, file paths, or line numbers, unless the exact location is itself the decision. Paths belong in plan's task specs.
- **Silent overwrite.** Replacing a spec needs `--rewrite <spec-id>`; otherwise Phase 0's duplicate branch decides.
- **Acting without its own consent.** Never auto-split (the user picks), never mark ready or add glossary terms without their separate questions (autofix writes neither; seeding an empty glossary is `/flow-next:prime`'s job), never treat a saved spec as implementation consent, and never admit a draft/stale briefing silently or treat a forced draft chart briefing as final (the override names the D-IDs and reads back the risk).
- **Committing.** Capture never stages or commits; the user owns when `.flow/` changes land.
- **`context: fork`.** Blocking questions must stay reachable.

## Workflow

Execute [workflow.md](workflow.md) in order:

The spec at `.flow/specs/<spec-id>.md` is the deliverable. Autofix without `--yes` prints the draft summary and exits 0 with no spec allocated.

© Gordon Mickel · MIT · gmickel/flow-next

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set70

The whole set →
flow-next-plan-review The flow-next-plan-review skill routes Flow specs and plans to a selected reviewer, then handles fixes and a follow-up review. Use it to check a Flow document before moving ahead. CX Codex +1 ★ 730repo stars flow-next-impl-review Runs John Carmack-style implementation review via a chosen backend — claude, codex, copilot, cursor or a human. Invoked with /flow-next:impl-review. CX Codex +1 ★ 730repo stars flow-next-work flow-next-work executes Flow-Next specs and tasks step by step: manages Git branches, tracks task states in .flow/ via flowctl, runs tests, and creates clean commits. CX Codex +1 ★ 730repo stars flow-next-spec-completion-review flow-next-spec-completion-review is a skill that checks whether a spec's tasks together meet its requirements. Run it before marking work on the spec complete. CX Codex +1 ★ 730repo stars flow-next-prime flow-next-prime assesses whether a codebase is ready for agents and production, checks that commands run, then leads with a verdict and ranked next steps. CX Codex +1 ★ 730repo stars repo-scout repo-scout scans a repository for existing patterns, conventions and related code before an agent starts implementing a requested change. CX Codex ★ 730repo stars flow-next-features flow-next-features is a Claude Code skill that creates or updates a user-facing feature map in .flow/features/. QA and drive can reuse its notes on how users reach each feature. CX Codex +1 ★ 730repo stars flow-next-sync flow-next-sync runs plan-sync by hand to bring downstream task specs back in line once the code has moved ahead, touching tasks still in todo or blocked. CX Codex +1 ★ 730repo stars

Project sponsors

Companies that keep this analytics open