opencode-interviewer

Spec-driven development workflow for OpenCode that runs as an interview.

The goal is to take a vague idea ("we should refactor X" / "add Y" / "improve Z") and turn it into a builder-ready spec + implementation plan with milestones.

This repo provides:

• A primary interview agent (tab-cyclable) that leads the interview and writes a spec to plans/.
• A recon-code subagent that does read-only codebase reconnaissance.
• A research-external subagent that does read-only external research (Context7 + web + GitHub).

Workflow

1. Switch to the interview agent (Tab until you see it).
2. Describe your idea at a high level.
3. The interview agent will:
   • Run code reconnaissance early (via recon-code).
   • Build a mind map of relevant branches (API, data, infra, UI, etc.).
   • Ask structured questions using OpenCode's AskUserQuestion UI.
   • Dispatch additional recon/research sub-tasks when needed.
   • Continue questioning until you say "finalize spec".
4. Say: finalize spec
5. The agent writes a Markdown spec to plans/YYYY-MM-DD--<slug>.md including:
   • Detailed spec
   • Implementation plan
   • Milestones (M1/M2/M3)

Tip: after finalizing, you can hand the spec directly to Build mode (same session) or use the /build-from-spec command.

Model Selection (and why)

These are the models configured in the agent frontmatter.

• interview: openai/gpt-5.3-codex

  • Strong synthesis, architecture guidance, and tool orchestration.
  • Good at leading an interview and producing a coherent spec.

• recon-code: google/antigravity-gemini-3-flash

  • Fast and cost-effective for scanning a repo (glob/grep/read).
  • Produces a concise Context Map + relevant file anchors.

• research-external: google/antigravity-gemini-3-pro

  • Better at synthesizing documentation and external constraints.
  • Used only when external APIs/libraries/standards are relevant.

If your environment does not have access to these providers/models, edit the model: fields in the agent files.

Install

You can install this workflow per-project (recommended) or globally.

Option A: Per-project (recommended)

Copy these directories into your target repo:

• .opencode/agents/
• .opencode/commands/

OpenCode auto-discovers .opencode/agents/*.md and will make interview available as a primary agent.

Option B: Global install

Copy the agent files into:

• ~/.config/opencode/agents/

Copy the command files into:

• ~/.config/opencode/commands/

Then restart OpenCode.

External Research Setup (Context7)

research-external can use Context7 when you configure the Context7 MCP server.

Example config (do not commit secrets):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

Command: build-from-spec

This repo includes a convenience command:

• /build-from-spec plans/2026-02-05--my-spec.md

It runs the Build agent on the spec file so you can implement milestone-by-milestone.

Repo Contents

• .opencode/agents/interview.md
• .opencode/agents/recon-code.md
• .opencode/agents/research-external.md
• .opencode/commands/build-from-spec.md

License

MIT