flow-next-strategy

/flow-next:strategy — repo-root STRATEGY.md anchor

flow-next-strategy produces and maintains STRATEGY.md — a short, durable anchor at the repo root (peer of README.md / GLOSSARY.md) that captures what the product is, who it serves, how it succeeds, and where the team is investing. Downstream skills (/flow-next:prospect, /flow-next:plan, /flow-next:interview, /flow-next:capture, /flow-next:sync) read it as grounding when sections_filled >= 1.

The document is short and structured on purpose. Good answers to a handful of sharp questions produce a better strategy than any amount of prose. This skill asks those questions, pushes back on weak answers, and writes the doc.

Note: The current year is 2026. Use this when dating the strategy document.

Preamble

flowctl is bundled — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks use $FLOWCTL:

FLOWCTL="$HOME/.codex/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Interaction Method

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.

Default to plain-text numbered prompt. Never silently skip the question.

Ask one question at a time. Free-form responses for the substantive sections (Target problem / Our approach / Who it's for / Key metrics / Tracks). Single-select with lead-with-recommendation only for routing decisions (which section to revisit, include this optional section, foreign-file resolution).

Focus Hint

<focus_hint> #$ARGUMENTS </focus_hint>

Interpret any argument as an optional focus: a section name to revisit (metrics, approach, tracks, problem, persona, milestones, not-working-on) or a scope hint. With no argument, proceed open-ended and let the file state decide the path.

Core Principles

1. Anchor, not plan. Strategy is what the product is and why. Features belong in /flow-next:prospect; tasks belong in specs and /flow-next:plan. Do not let either creep into the doc.
2. Rigor in the questions, not the headings. The section headers are plain English. The interview questions enforce strategy discipline (references/interview.md).
3. Short is a feature. The template is constrained. Adding sections costs more than it looks like. Push back on expansion.
4. Durable across runs. This skill is rerunnable. On a second run it updates in place, preserves what is working, and only challenges sections that look stale or weak.
5. Survives .flow/ wipe. STRATEGY.md lives at repo root, never under .flow/. The project's strategy belongs to the project, not flow-next (R18 invariant from the 0.39.0 glossary epic).

Pre-check: local setup version

Same pattern as /flow-next:plan and /flow-next:audit — non-blocking notice when .flow/meta.json setup_version lags the plugin version:

if [[ -f .flow/meta.json ]]; then
 SETUP_VER=$(jq -r '.setup_version // empty' .flow/meta.json 2>/dev/null)
 PLUGIN_JSON="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$HOME/.codex}}/.codex-plugin/plugin.json"
 PLUGIN_VER=$(jq -r '.version' "$PLUGIN_JSON" 2>/dev/null || echo "unknown")
 if [[ -n "$SETUP_VER" && "$PLUGIN_VER" != "unknown" && "$SETUP_VER" != "$PLUGIN_VER" ]]; then
 echo "Plugin updated to v${PLUGIN_VER}. Run /flow-next:setup to refresh local scripts (current: v${SETUP_VER})." >&2
 fi
fi

Execution Flow

Phase 0: Route by file state

0.1 — Ralph block (R17)

/flow-next:strategy is exploratory and human-in-the-loop. Autonomous loops have no business deciding repo strategy. Hard-error with exit 2 when running under Ralph.

if [[ -n "${REVIEW_RECEIPT_PATH:-}" || "${FLOW_RALPH:-}" == "1" ]]; then
 echo "[STRATEGY: user-triggered only — Ralph cannot run /flow-next:strategy]" >&2
 exit 2
fi

No env-var opt-in. Ralph never decides direction.

0.2 — Read file state

STATUS_JSON=$("$FLOWCTL" strategy status --json)
EXISTS=$(printf '%s' "$STATUS_JSON" | jq -r '.exists')
HUSK=$(printf '%s' "$STATUS_JSON" | jq -r '.husk')
SECTIONS_FILLED=$(printf '%s' "$STATUS_JSON" | jq -r '.sections_filled')
GENERATOR_MATCH=$(printf '%s' "$STATUS_JSON" | jq -r '.generator_match')
FILE_PATH=$(printf '%s' "$STATUS_JSON" | jq -r '.file_path // empty')

JSON fields (frozen by Task 1):

• exists (bool) — file present
• husk (bool) — exists: true AND sections_filled == 0
• sections_filled (int) — populated required-section count (0-5)
• total_sections (int) — always 5 (the 5 required)
• last_updated (str|null) — ISO date from frontmatter
• file_path (str|null) — absolute path of resolved STRATEGY.md
• generator (str|null) — frontmatter generator value
• generator_match (bool) — generator == "flow-next-strategy"

0.3 — Subdirectory walk-up surfacing (R16)

If file_path is set and differs from ${PWD}/STRATEGY.md, surface one line in chat before any question fires:

Using repo-root STRATEGY.md at <file_path>.

This is the only line printed before routing — keep the noise floor low.

0.4 — Foreign-file resolution (R15)

If exists: true AND generator_match: false, do not write. Fire plain-text numbered prompt:

• body: "Found a STRATEGY.md at <file_path> not generated by flow-next-strategy (generator: <generator or "missing">). Recommended: keep — do not overwrite a hand-written or external-tool strategy doc. Confidence: [your-call] — your project, your call."
• options:
• keep → exit 0 with one-line stdout: Keeping existing STRATEGY.md unchanged.
• migrate → exit 0 with stderr: Multi-format migration deferred to v2. Either delete or rename the file, then re-run /flow-next:strategy to bootstrap from scratch.
• rewrite → second confirmation plain-text numbered prompt:
• body: "Confirm destructive overwrite? The existing file at <file_path> will be replaced. Recommended: cancel. Confidence: [your-call]."
• options: confirm-overwrite → proceed to Phase 1 first-run interview; cancel → exit 0.

Single-select plain-text numbered prompt, lead-with-recommendation, neutral option labels.

0.5 — Routing

After Ralph block, walk-up surfacing, and foreign-file resolution:

| State | Route | |-------|-------| | exists: false | Phase 1 (first-run interview) | | exists: true AND husk: true AND generator_match: true | Phase 1 (first-run; husk was probably an aborted run) | | exists: true AND husk: false AND generator_match: true | Phase 2 (section-revisit update) |

Announce path in one line: Strategy doc not found — let's write it. or Found existing strategy — let's review and update.

Phase 1: First-run interview

1.1 — Load interview rules (non-optional)

Read `references/interview.md`.

This load is non-optional. The pushback rules, anti-pattern examples, and quality bar for each section live there. Improvising from memory produces a passive transcription instead of a strategy doc.

1.2 — Run the interview in section order

For each of the 5 required sections (in order: Target problem → Our approach → Who it's for → Key metrics → Tracks), follow the per-section rule in references/interview.md:

• Ask the opening question verbatim from the references file.
• Evaluate the answer against the strong-answer signature.
• If the answer falls into a named anti-pattern, push back with the sharper follow-up — quoting the user's words back at them, NOT paraphrasing. Anti-pattern label names (vanity, fluff, feature-list, etc.) are internal-only — never appear in question bodies.
• 2 rounds maximum. After round 2, captu