opencode-implement

opencode-implement

Plan a coding task with Claude, get user approval on the plan, then hand the plan file to OpenCode to execute. Claude verifies the result against the plan when OpenCode returns.

This skill is for plan-first workflows. If the user wants direct delegation without a planning phase, use opencode-delegate instead.

When to use this skill

• The user asks to "plan and implement", "plan then delegate", "design first", "think through the approach".
• The task is non-trivial (multi-file, ambiguous scope, architectural decisions).
• Getting the design right matters as much as getting it done.
• When in doubt between this and opencode-delegate, prefer this one — planning is cheap, bad implementation without planning is expensive.

When NOT to use this skill

• The user explicitly wants direct delegation ("just run this", "skip planning", "delegate directly") → use opencode-delegate.
• Trivial fixes, single-line changes, obvious one-file edits → just let Claude do it.
• Pure conversation, explanation, or debugging with no code writing → neither skill applies.
• When opencode isn't installed — stop and direct the user to install, don't silently fall back.

---

Interaction rules (load-bearing)

Follow these strictly — the skill's UX depends on them.

Use AskUserQuestion for every decision point. Do not compress multiple decisions into a single prose message with numbered questions.

Decision points that must use AskUserQuestion, each as its own call:

1. Plan approval (Phase 3) — "Looks good", "Needs changes", "Cancel".
2. Model selection (Phase 4a) — authed models as options plus "Other".
3. Permission selection (Phase 4b) — "Read-only", "Implement", "Implement, no shell".

Ask them in sequence. Use the answer to one before asking the next. Do not batch.

If you find yourself writing "Before I delegate, a few confirmations:" followed by a numbered list — stop. That's the failure mode. Back up and use AskUserQuestion for the next single decision.

---

Preflight — required, not optional

Run these two bash commands before anything else, every delegation:

opencode --version
opencode auth list

This is mandatory. The output of opencode auth list is what drives model selection — without it, you don't know which models the user is authed for, and any model list you present from memory is wrong.

See references/preflight.md for full details and references/model-selection.md for how to build the actual model list from the auth output.

Failure modes to avoid:

• Hardcoded marketing list: "GPT-5 (Recommended) / GLM-5.1 / Claude Sonnet" — that's training-data marketing, not the user's actual options.
• Editorial commentary in options: "opencode/big-pickle — Largest available", "opencode/gpt-5-nano — may struggle", "opencode/minimax-m2.5-free — Free-tier alternative". Each option must be just the literal provider/model string, no description, no recommendation, no speculation about behavior.
• Truncated lists from a stale cache: if opencode models returns only a handful when more should be available, run opencode models --refresh and retry. If still short, try OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true opencode models.
• Querying a single provider: never use opencode models <provider>. Use opencode models with no argument. Some providers expose models under multiple provider IDs (e.g., opencode and opencode-go are separate, but a single subscription can give access to both), so querying just one ID hides models the user actually has.
• Showing models from non-authed providers: if the user only authed opencode, don't pad the list with anthropic/... or openai/... options they can't use.

If you catch yourself doing any of these, stop and re-read references/model-selection.md.

---

The five phases

Phase 1: Explore

Read the repo to ground the plan in reality:

• Find the files the task will touch (Grep, Glob, Read).
• Identify existing patterns to mirror.
• Check the test setup.
• Note cross-cutting concerns (types, config, public APIs).

Keep exploration focused. Don't read the whole repo — target what the task needs. If the task is ambiguous (unclear scope, missing context), ask the user one or two clarifying questions now. Clarifying before planning is much cheaper than replanning after a bad delegation.

Don't write code yet. The goal is understanding.

Phase 2: Write the plan

Write a plan to .claude/plans/<slug>.md, where <slug> is a short kebab-case name for the task. Create .claude/plans/ if it doesn't exist.

There is no fixed template. Use your judgment about what structure serves the specific task. Good plans usually cover: the goal, files that will change, the approach in enough detail to execute, what tests to add, what stays stable (constraints), and any notes about project conventions the implementer needs to know.

What makes a plan useful for delegation:

• Concrete file paths, not "the HTTP module" — opencode runs in the working directory and needs paths.
• Approach is executable — specific enough that a capable model following it would produce the right code.
• Constraints are explicit — anything you don't say, opencode may change. If the public API must stay stable, write it down.
• Scope is bounded — the plan should have a clear end state. Open-ended plans produce sprawling implementations.

Err on the side of slightly over-specifying for delegation. If the plan is vague, opencode will make design choices you didn't intend.

Phase 3: Get approval

Show the plan to the user. Then call AskUserQuestion with just this single question and three options:

• "Looks good, delegate to opencode"
• "Needs changes"
• "Cancel"

This question stands alone. Do not bundle it with model selection, permission selection, or any other question. The plan approval is a binary gate — user says yes or no to the plan, and only after yes do you move on to model/permission questions in Phase 4.

If changes are requested, edit the plan file in place, show the updated version, then ask approval again. Always write changes into the file so what opencode eventually sees is canonical. Don't keep modifications in chat memory.

Don't proceed on ambiguous affirmation like "sure" or "ok" — if the user didn't click an option, restate what you're about to do and ask once more via AskUserQuestion.

Phase 4: Delegate

Now — and only now, after the plan has been approved in Phase 3 — ask about model and permissions. These are two separate AskUserQuestion calls in sequence:

Step 4a: Ask for model. See references/model-selection.md — but only after running opencode models (no provider argument) via bash_tool. The model list MUST come from that bash output, not from memory. Single AskUserQuestion call. Wait for the answer.

Step 4b: Ask for permissions. See references/permissions.md for the three presets. Single AskUserQuestion call. Wait for the answer.

Step 4c: Run opencode. Construct and run the command per references/argument-order.md.

Do not combine 4a and 4b into one message.

Prompt pattern for the opencode invocation:

Implement the plan in the attached plan file exactly as written. Do not redesign.
If you hit an ambiguity, follow the closest existing pattern in the repo.
Run tests and confirm everything in the plan's definition-of-done section.
Report what you did and any deviations from the plan.

The framing matters. Without "exactly as written" and "do not redesign", models — especially capable ones like GLM-5.1 or GPT-5 — will quietly "improve" the plan based on their own judgment. Tell them not to.

Attach the plan file with -f. Optionally attach the current state of files the plan modifies, so opencode sees their exact contents rather than relying on its own disk read.

For running the command (timeouts, handling mid-run exits), see references/running.md.

Phase 5: Verify

When opencode returns successfully (not mid-run — see references/running.md for that case), verify the work against the plan. Don't just relay opencode's summary.

1. Check the diff against the plan. Did opencode touch files the plan said to touch? Miss anything? Touch anything extra?
2. Walk the definition-of-done. For each verifiable item, check it yourself — run tests, run the type-checker, read the code. Don't trust the model's "tests pass" claim.
3. Check constraints. Grep for the specific things the constraints said to preserve.
4. Read any deviation report opencode produced. Surface each deviation to the user.

Report back concisely:

• Plan adherence: ✓ or deviations with specifics
• Definition-of-done: which items genuinely verify
• Tests: pass / fail / not run (include failure output if relevant)
• Session ID (for resume)
• Recommended next step: accept, resume with fix-up, or revert

---

Troubleshooting

See references/troubleshooting.md for common errors and fixes.

---

Reference files

• references/preflight.md — opencode version + auth check.
• references/model-selection.md — building the model list from authed providers.
• references/permissions.md — the three permission presets.
• references/argument-order.md — the File not found trap and how to avoid it.
• references/running.md — timeouts, mid-run exits, session continuation.
• references/troubleshooting.md — common errors and fixes.
• references/cli-flags.md — full opencode run flag reference.