flow-next-guide

# Guide - smallest-sufficient workflow router

Stateless prompt-first router. Recommends **one** next workflow from the starting state. Does **not** create specs, charts, tasks, artifacts, or flowctl state. Chart is an **optional** discovery route - never a mandatory stage and never a new pipeline stage.

**Role**: routing coordinator (inline skill - keep `AskUserQuestion` reachable). On portable hosts without `AskUserQuestion`, fall back to a plain-text numbered prompt with a final `Other - type your own answer` option. (sync-codex.sh rewrites AskUserQuestion to a plain-text numbered prompt in the Codex mirror.)

## Preamble

**CRITICAL: flowctl is BUNDLED - NOT installed globally.** `which flowctl` will fail (expected). Define once; probe blocks use `$FLOWCTL`:

```bash
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
```

No flowctl mutation. Optional read-only probes (`$FLOWCTL brief` for cold-session orientation; `$FLOWCTL list` / `$FLOWCTL show`, file reads) may ground the recommendation when a handle or path is named. Never run create/write/claim/resolve.

## Output contract (every recommendation)

Lead with a **natural-language next prompt** - the exact words or slash command the user should say/run next. Flags are secondary (automation only). Then:

1. **Route** - named skill/path
2. **Why (positive signal)** - which matrix signal matched
3. **Safe skip / narrow** - when this route may be skipped or narrowed
4. **Skip kind** - `signal absent` (the stage's work is not needed) vs `despite unresolved risk` (you chose a smaller path; evidence/consent/review contracts still apply later)

Skipping a command never skips the evidence, consent, or review contract that command would have provided.

## Smallest-sufficient matrix (exact)

Match the **starting state**. First clear match wins. Chart only when one oversized idea is still unclear.

| Starting state | Route | Positive signal | Safe skip / narrow |
|---|---|---|---|
| No written direction - target problem, users, or key metrics are not stated anywhere | `/flow-next:strategy` | Repeated arguments about what matters; no `STRATEGY.md` to ground prospect/capture/plan | Skip when `STRATEGY.md` exists or the effort is small enough that direction is not in question |
| Looking for candidate investments across a domain | `/flow-next:prospect` | Domain search; need ranked candidates | Skip prospect when the idea is already singular. After selection: chart **only if** the candidate remains singular + oversized + unclear; otherwise capture |
| One large idea, unclear boundaries, several consequential unknowns | `/flow-next:chart` then briefing then capture | Singular effort too big for one capture; unknowns block stating intent | Skip chart (`signal absent`) when intent and boundaries are already stateable - go capture or author the spec directly. Chart is never mandatory |
| A theme or direction rather than one effort ("make X more Y") | `/flow-next:prospect`, or narrow to a single effort | No nameable end state, so no Outcome and no scope boundary | Chart cannot take this (`signal absent` for chart): it needs a destination whose route is unknown, not a direction. Narrow first, or prospect when the real ask is which effort to pick |
| One meaningful idea whose intent and boundaries can already be stated | `/flow-next:capture` or author the spec directly | Clear meaningful idea | Skip chart (`signal absent`). Do not manufacture a chart for clear work |
| Existing structured brief with resolved business and technical choices | `/flow-next:capture` the brief | Structured brief / chart briefing package ready | Skip chart. Narrow or skip interview **only after** capture read-back proves no material gaps - never pre-declare skip interview |
| Tiny, local, low-risk change that fits one implementation context | Direct change + review path appropriate to the repo | One-context fix; low risk | Skip chart **and** the full spec pipeline (`signal absent`). Still run the review/consent gates the change would need |
| A valid spec with unresolved judgment questions | `/flow-next:interview` | Spec exists; judgment gaps remain | Do not reopen discovery as chart unless the questions reveal the **effort itself is not yet specifiable** - only then route backward to chart |
| A ready zero-task spec whose work is fully known, near-zero risk, one implementation context | `/flow-next:work <spec-id> --no-plan` (or answer the zero-task fork's ask with "work directly") | Task decomposition would convert no unknown; the fork mints one implicit task and runs the standard pipeline | Prefer `/flow-next:plan` when independent surfaces could parallelize or design risk remains; autonomous loops keep planning - pilot routes here only for a spec carrying the explicit `no_plan` field (`flowctl spec set-no-plan`), and `/flow-next:work-rolling` refuses the route |
| A ready spec whose work is understood | `/flow-next:plan` | Spec ready / work understood enough to task | Chart is too late. Unshaped oversized freeform ideas are not plan input - route those to chart first |
| Planned tasks ready to implement | `/flow-next:work`, then existing review / QA / ship choices | Tasks exist and are actionable | Stay on work + the repo's review/QA/ship menu. Guide does not invent new ship stages |
| A repo with a drivable user surface whose navigation should compound across QA/drive runs | `/flow-next:features` | No `.flow/features/` yet (seed), or a present map that needs a cadence maintain pass | Skip when there is no drivable surface. Never a pipeline stage; pilot/land/Ralph never dispatch it. QA and drive consume the map when it exists |
| Output too dense - a plan, spec, task, or diff