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:

ROOT="$(git rev-parse --show-toplevel)"
OPENCODE_DIR="$ROOT/.opencode"
FLOWCTL="$OPENCODE_DIR/bin/flowctl"
$FLOWCTL <command>

Pre-check: Local setup version

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

SETUP_VER=$(jq -r '.setup_version // empty' .flow/meta.json 2>/dev/null)
OPENCODE_VER=$(cat "$OPENCODE_DIR/version" 2>/dev/null || echo "unknown")
if [[ -n "$SETUP_VER" && "$OPENCODE_VER" != "unknown" && "$SETUP_VER" != "$OPENCODE_VER" ]]; then
  echo "Flow-Next updated to v${OPENCODE_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: Fetch with flowctl show, write back with flowctl epic set-plan
• Flow task ID fn-N.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
• /flow-next:interview fn-1.3
• /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) or file path (e.g., docs/spec.md)"

Setup

ROOT="$(git rev-parse --show-toplevel)"
OPENCODE_DIR="$ROOT/.opencode"
FLOWCTL="$OPENCODE_DIR/bin/flowctl"

Detect Input Type

1. Flow epic ID pattern: matches fn-\d+ (e.g., fn-1, fn-12)

- Fetch: $FLOWCTL show <id> --json - Read spec: $FLOWCTL cat <id>

1. Flow task ID pattern: matches fn-\d+\.\d+ (e.g., fn-1.3, fn-12.5)

- Fetch: $FLOWCTL show <id> --json - Read spec: $FLOWCTL cat <id> - Also get epic context: $FLOWCTL cat <epic-id>

1. 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

1. New idea text: everything else

- Create a new epic stub and refine requirements - Do NOT create tasks (that's /flow-next:plan)

Interview Process

Ask questions in plain text (no question tool). Group 5-8 questions per message. Expect 40+ total for complex specs. Wait for answers before continuing.

Rules:

• Keep questions short and concrete
• Offer 2-4 options when helpful
• Include “Not sure” when ambiguous
• Number questions for easy replies

Example:

1) Primary user goal?
2) Platforms: web, iOS, Android, desktop?
3) Auth required? (yes/no/unknown)
4) Performance targets? (p95 ms)
5) Edge cases you already know?

Question Categories

Read [questions.md](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 Flow Epic ID

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

First check if task has existing spec from planning:

$FLOWCTL cat <id>

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

• Do NOT overwrite — planning detail would be lost
• Only add new acceptance criteria discovered in interview:

``bash $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

# Preferred: combined set-spec (2 writes instead of 4)
$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: /flow-next:plan or /flow-next:work

Notes

• This process should feel thorough - user should feel they've thought through everything
• Quality over speed - don't rush to finish