Skip to content

Prospect

/flow-next:prospect surfaces candidate ideas before there is a spec to capture.

Each candidate is scored against the repo’s actual state: recent files, open specs, .flow/memory/ entries, CHANGELOG.md, and STRATEGY.md. Nothing is invented from generic advice.

When you have a focus area but no specific idea yet.

  • “What should we do about authentication this quarter?”
  • “Ideate inside src/billing/.”
  • “Three improvements to onboarding.”

Prospect is plural and upstream of selection. After you pick a candidate: use optional /flow-next:chart only if that candidate remains oversized and unclear; otherwise promote it and hand it to /flow-next:flow, which picks the next stage, or go to /flow-next:capture when you already know the shape and want to write the spec yourself. Flow splits a spec into tasks only when you ask for a plan. Unsure? Ask /flow-next:flow --explain.

Pass nothing for open-ended ideation, or one hint to scope the search. Prospect reads the whole hint as one kind:

KindRecognised whenExample
PathIt contains /, has no spaces, and resolves inside the repo/flow-next:prospect src/billing
VolumeIt is top N, N ideas or raise the bar/flow-next:prospect top 5
ConceptAnything else, including a constraint/flow-next:prospect authentication, /flow-next:prospect "no new dependencies"

Without a volume hint, prospect generates 15 to 25 candidates and keeps 5 to 8 survivors. top N generates enough candidates for at least N to survive the critique, N ideas generates at least N, and raise the bar generates 25 to 30 and rejects more of them. A path that does not exist on disk stops for a question: continue open-ended, enter another hint, or abort.

Prospect needs a person at the terminal. Under mode:autonomous, FLOW_AUTONOMOUS=1 or AUTONOMOUS=1 it exits with status 2 before it reads the repo, because deciding what a repo tackles next is your call.

Survivor candidates become specs via flowctl:

Terminal window
flowctl prospect promote <n>

Promoted specs land in .flow/specs/, and promote prints Next: /flow-next:flow <spec-id> so the router picks the next stage; it sends the spec to refine only when a named product or authority decision is open. Each survivor in the prospect artifact carries the same pointer: **Next step:** promote, then /flow-next:flow <spec-id>.

flowchart LR
  Focus["Focus hint"] --> Ground["Ground in repo state"]
  Ground --> Rank["Rank candidates"]
  Rank --> Review["User reviews list"]
  Review -->|promote| Spec[".flow/specs/<id>.md"]
  Review -->|archive| Drop["Discard"]

Ideas live under .flow/prospects/ until promoted or archived. Default retention is 30 days; older candidates are pruned so the directory stays small enough to scan.

/flow-next:prospect src/billing
Grounding: 14 recent files, 2 open specs, 5 memory entries, CHANGELOG, STRATEGY.md
1. Idempotent retry for webhook ingestion (grounded: bug/integration memory entry + TODO at src/billing/webhooks.ts:112)
2. Invoice-line rounding audit (grounded: CHANGELOG regression note, 2.3.1)
3. Usage-metering backfill job (grounded: STRATEGY.md metering track, no spec covers it)
... 3 more survivors in .flow/prospects/billing-2026-11-15.md
Next step: promote, then /flow-next:flow <spec-id>

Every candidate cites its grounding in the repo’s actual state - nothing arrives from generic best-practice lists.

Recipes that compose with prospect in the cookbook:

  • Prompt into a stage - constraints in the prompt (“quick wins only”) reshape the candidate list.
  • One-shot chains - “prospect billing, then plan the top candidate” runs the promotion in the same message.
Terminal window
flowctl prospect promote <n>
/flow-next:flow <spec-id> # the router picks the next stage
# if the selected candidate is still too unclear:
/flow-next:chart "the selected candidate - settle the unknowns before capture"
# if intent is already stateable:
/flow-next:capture