Flow interview

Conduct an extremely thorough interview about a task/spec and write refined details back.

IMPORTANT: This plugin uses .flow/ for ALL task tracking. Do NOT use markdown TODOs, plan files, TodoWrite, or other tracking methods. All task state must be read and written via flowctl .

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Always use:

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl" $FLOWCTL <command>

Pre-check: Local setup version

If .flow/meta.json exists and has setup_version , compare to plugin version:

SETUP_VER=$(jq -r '.setup_version // empty' .flow/meta.json 2>/dev/null)

Portable: Claude Code uses .claude-plugin, Factory Droid uses .factory-plugin

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

Continue regardless (non-blocking).

Role: technical interviewer, spec refiner Goal: extract complete implementation details through deep questioning (40+ questions typical)

Input

Full request: $ARGUMENTS

Accepts:

• Flow epic ID fn-N-slug (e.g., fn-1-add-oauth ) or legacy fn-N /fn-N-xxx : Fetch with flowctl show , write back with flowctl epic set-plan

• Flow task ID fn-N-slug.M (e.g., fn-1-add-oauth.2 ) or legacy fn-N.M /fn-N-xxx.M : Fetch with flowctl show , write back with flowctl task set-description/set-acceptance

• File path (e.g., docs/spec.md ): Read file, interview, rewrite file

• Empty: Prompt for target

Examples:

• /flow-next:interview fn-1-add-oauth

• /flow-next:interview fn-1-add-oauth.3

• /flow-next:interview fn-1 (legacy formats fn-1, fn-1-xxx still supported)

• /flow-next:interview docs/oauth-spec.md

If empty, ask: "What should I interview you about? Give me a Flow ID (e.g., fn-1-add-oauth) or file path (e.g., docs/spec.md)"

Setup

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"

Detect Input Type

Flow epic ID pattern: matches fn-\d+(-[a-z0-9-]+)? (e.g., fn-1-add-oauth, fn-12, fn-2-fix-login-bug)

• Fetch: $FLOWCTL show <id> --json

• Read spec: $FLOWCTL cat <id>

Flow task ID pattern: matches fn-\d+(-[a-z0-9-]+)?.\d+ (e.g., fn-1-add-oauth.3, fn-12.5)

• Fetch: $FLOWCTL show <id> --json

• Read spec: $FLOWCTL cat <id>

• Also get epic context: $FLOWCTL cat <epic-id>

File path: anything else with a path-like structure or .md extension

• Read file contents

• If file doesn't exist, ask user to provide valid path

Interview Process

CRITICAL REQUIREMENT: You MUST use the AskUserQuestion tool for every question.

• DO NOT output questions as text

• DO NOT list questions in your response

• ONLY ask questions via AskUserQuestion tool calls

• Group 2-4 related questions per tool call

• Expect 40+ questions total for complex specs

Anti-pattern (WRONG):

Question 1: What database should we use? Options: a) PostgreSQL b) SQLite c) MongoDB

Correct pattern: Call AskUserQuestion tool with question and options.

Question Categories

Read questions.md for all question categories and interview guidelines.

NOT in scope (defer to /flow-next:plan)

• Research scouts (codebase analysis)

• File/line references

• Task creation (interview refines requirements, plan creates tasks)

• Task sizing (S/M/L)

• Dependency ordering

• Phased implementation details

Write Refined Spec

After interview complete, write everything back — scope depends on input type.

For NEW IDEA (text input, no Flow ID)

Create epic with interview output. DO NOT create tasks — that's /flow-next:plan 's job.

$FLOWCTL epic create --title "..." --json $FLOWCTL epic set-plan <id> --file - --json <<'EOF'

Epic Title

Problem

Clear problem statement

Key Decisions

Decisions made during interview (e.g., "Use OAuth not SAML", "Support mobile + web")

Edge Cases

• Edge case 1
• Edge case 2

Open Questions

Unresolved items that need research during planning

Acceptance

• Criterion 1
• Criterion 2 EOF

Then suggest: "Run /flow-next:plan fn-N to research best practices and create tasks."

For EXISTING EPIC (fn-N that already has tasks)

First check if tasks exist:

$FLOWCTL tasks --epic <id> --json

If tasks exist: Only update the epic spec (add edge cases, clarify requirements). Do NOT touch task specs — plan already created them.

If no tasks: Update epic spec, then suggest /flow-next:plan .

$FLOWCTL epic set-plan <id> --file - --json <<'EOF'

Epic Title

Problem

Clear problem statement

Key Decisions

Decisions made during interview

Edge Cases

• Edge case 1
• Edge case 2

Open Questions

Unresolved items

Acceptance

• Criterion 1
• Criterion 2 EOF

For Flow Task ID (fn-N.M)

First check if task has existing spec from planning:

$FLOWCTL cat <id>

If task has substantial planning content (description with file refs, sizing, approach):

• Do NOT overwrite — planning detail would be lost

• Only ADD new acceptance criteria discovered in interview:

Read existing acceptance, append new criteria

$FLOWCTL task set-acceptance <id> --file /tmp/acc.md --json

• Or suggest interviewing the epic instead: /flow-next:interview <epic-id>

If task is minimal (just title, empty or stub description):

• Update task with interview findings

• Focus on requirements, not implementation details

$FLOWCTL task set-spec <id> --description /tmp/desc.md --acceptance /tmp/acc.md --json

Description should capture:

• What needs to be accomplished (not how)

• Edge cases discovered in interview

• Constraints and requirements

Do NOT add: file/line refs, sizing, implementation approach — that's plan's job.

For File Path

Rewrite the file with refined spec:

• Preserve any existing structure/format

• Add sections for areas covered in interview

• Include edge cases, acceptance criteria

• Keep it requirements-focused (what, not how)

This is typically a pre-epic doc. After interview, suggest /flow-next:plan <file> to create epic + tasks.

Completion

Show summary:

• Number of questions asked

• Key decisions captured

• What was written (Flow ID updated / file rewritten)

Suggest next step based on input type:

• New idea / epic without tasks → /flow-next:plan fn-N

• Epic with tasks → /flow-next:work fn-N (or more interview on specific tasks)

• Task → /flow-next:work fn-N.M

• File → /flow-next:plan <file>

Notes

• This process should feel thorough - user should feel they've thought through everything

• Quality over speed - don't rush to finish