flow-next-opencode-interview

# 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: ```bash 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: ```bash 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 ```bash 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>` 2. **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>` 3. **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 4. **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. ```bash $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:** ```bash $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`. ```bash $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:** ```bash $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 ```bash # 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