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 plain-text numbered prompt reachable). On portable hosts without plain-text numbered prompt, fall back to a plain-text numbered prompt with a final Other - type your own answer option.

Preamble

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

FLOWCTL="${CODEX_HOME:-$HOME/.codex}/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.

There is no fixed prospect -> chart -> capture conveyor. Each hop re-evaluates the matrix.

Router staleness is a defect, not drift. This table is the router's inventory of what ships. Recommending a skill that no longer exists, or failing to know one that does, is a broken router - the recommendation looks confident and sends the user nowhere. Adding or removing a flow-next skill updates this table in the same change (agent_docs/adding-skills.md).

Prompt-first behavior

1. Infer starting state from $ARGUMENTS + conversation (and optional read-only probes).

2. If exactly one matrix row fits, emit one recommendation (natural-language prompt first). Ask the user via plain text. Render the options below as a numbered list 1. … N., followed by a final option N+1. Other — type your own answer. Print the question, then the numbered list, then stop and wait for the user's next message before continuing. Parse the reply as: a bare number 1–N+1 → that option; the literal text of an option label → that option; free text after Other → custom answer.

3. If two routes would materially change cost, consent, or discovery vs build path, ask at most one plain-text numbered prompt via bare plain-text numbered prompt (or the plain-text numbered fallback). Then recommend.

4. Never present chart as required onboarding, a pipeline stage, or the default after prospect.

5. Never mutate .flow/ or invoke write-capable flowctl subcommands.

When the situation reads as a concrete task, the pull is to just answer it - the fix is one edit away, the question has an obvious response. That pull is the tell that a route exists and you are about to skip naming it. Name the route instead; a guide that does the work has stopped being a router.

Recommendation shape (template)

Next: <natural-language prompt or slash command to run>

Route: <name>
Signal: <positive signal>
Skip/narrow: <explicit safe skip or narrow condition>
Skip kind: signal absent | despite unresolved risk
Why not the alternatives: <one line>

Examples of natural-language next prompts (not required flags):

• "Run prospect for DX improvements in the skills tree"
• "Chart this: multi-tenant billing with unknown pricing and migration risks"
• "Capture what we just agreed - intent and boundaries are clear"
• "Interview fn-12 on the open product judgment questions"
• "Plan the ready spec fn-12"
• "Just fix the typo in README and open a small review"

Forbidden

• Writing files under .flow/, creating charts/specs/tasks, or any flowctl mutation
• Using Write or Edit tools
• Presenting chart as mandatory or as a pilot/build-loop stage
• A fixed multi-stage conveyor that always chains prospect -> chart -> capture
• Asking more than one plain-text numbered prompt per invocation
• Leading with flag vocabulary when a natural-language next prompt exists
• Claiming that skipping a command also skips its evidence/consent/review contracts