docs: OpenCode → OpenAI Agents SDK + LiteLLM + Burr migration plan

[pofallon]

Summary

• Rewrites docs/BURR.md from the original "is Burr a reasonable xoscar replacement?" research note into a full plan for migrating the LLM substrate from OpenCode HTTP runtime to OpenAI Agents SDK + LiteLLM + Burr, in three phases. Original Burr-specific research is preserved in dedicated sections.
• Adds docs/migration-phase-0-spike.md — a concrete spike with a ~300 LOC standalone script outline, five named validations, and a decision-gate matrix tying outcomes to migration verdicts. Phase 0 is the gate for Phase 1.

What the plan proposes

A staged, layer-by-layer swap (not role-by-role) of the LLM substrate:

Phase 0  Spike (1–2 days)        End-to-end validation on one bead; go/no-go
Phase 1  Replace OpenCode (3–4w) ~2400 LOC of runtime/opencode/ deleted; landmines 1–4 die
Phase 2  Replace xoscar (2–3w)   Burr Applications drive workflows
Phase 3  Cleanup (1 week)        Drop opencode binary dep + xoscar dep

Each phase has a documented back-out path. Phase 1 is the biggest win and is independent of Phase 2 — if Burr disappoints, Phase 1's wins stand.

Why this stack

• LiteLLM (in-process library) — first-class github_copilot/* provider via OAuth device flow → Copilot Pro subscription path survives the migration.
• OpenAI Agents SDK — first-party LiteLLM bridge (vs PydanticAI's community shim), first-class output_type=PydanticModel, as_tool() for Maverick's Task subagent pattern.
• Burr — clean workflow state-machine ergonomics without xoscar's ceremony. Already analyzed as a fit in the prior research.
• Maverick Squadron + Agent classes (merged in refactor: extract Agent + Squadron from OpenCodeAgentMixin (plan steps 1–3.7) #94) — survive unchanged at the seam between Burr and the SDK.

Full alternatives table including PydanticAI, smolagents, vendor Agent SDKs, LangChain/LangGraph, Instructor + custom loop, and others is in BURR.md.

What's NOT in this PR

This PR is documentation only. No code changes, no spike script implementation. Phase 0 is the next step and is scoped at 1–2 days; expect a follow-up PR with scripts/spike-openai-agents-sdk-litellm.py and the report once executed.

Test plan

• BURR.md renders correctly in GitHub markdown.
• migration-phase-0-spike.md renders correctly in GitHub markdown.
• Cross-references between the two docs resolve.
• Reviewer can read both docs end-to-end and answer: (a) what's the target architecture? (b) what's the migration order? (c) what does Phase 0 prove and what does each failure mode mean?

Related

• Closes nothing directly.
• Sets up future work to close Detect silent upstream-retry storms in OpenCode (Landmine #4) #95 (silent retry storm landmine) by deleting the OpenCode runtime in Phase 3.
• Builds on the Squadron + Agent extraction merged in refactor: extract Agent + Squadron from OpenCodeAgentMixin (plan steps 1–3.7) #94.

🤖 Generated with Claude Code