Case study · Evolving configuration

Opencode Mentor

A mentor-first OpenCode configuration that makes explanation, practice, and independent reasoning part of the development workflow.

My role
Workflow and system design
Focus
AI-assisted developer learning
Built with
OpenCode · Agent workflows · Prompt design
Illustrated mentoring exchange.
The problem
An assistant can complete a task while leaving its user no better equipped to solve the next one.
The approach
Make mentoring, review, architecture, and practice distinct responsibilities in the workflow.
Current outcome
A configurable mentor system with specialist roles, learning tools, and an explicit support ladder.

System at a glance

How the pieces fit.

  1. Developer request
  2. Mentor orchestrator
  3. Specialist role
  4. Practice and reflection

An orchestrator chooses the teaching mode, then tools and reflection support continuity between interactions.

The problem#

Most coding assistants optimize for producing code quickly. That can be useful, but it creates a tension for someone who is still developing programming judgment: the task can be finished before the learner has understood the problem.

Opencode Mentor explores a different goal. I want an assistant that helps me explain a boundary, recognize a tradeoff, debug an assumption, and gradually need less help. The configuration calls that approach MAI — Mentor AI Infrastructure.

Architecture and approach#

The system gives the assistant several distinct teaching responsibilities instead of one broad instruction to be helpful.

  • The orchestrator classifies the request and chooses the appropriate mode of support.
  • The mentor explains concepts and provides calibrated hints.
  • The reviewer evaluates an attempt without automatically rewriting it.
  • The architect discusses system shape, boundaries, and tradeoffs.
  • The drill instructor provides focused practice and feedback.

Skills supply targeted context, while learning tools support profiles, exercises, grading, and reflections. The intention is to carry a compact understanding of the learner forward rather than make every interaction start from zero.

Decisions that mattered#

Define the boundary before choosing the tools#

The most important design choice is behavioral: the assistant should not take the keyboard whenever guidance would let the learner proceed. Explanations, hints, and critique are first-class outputs, not delays before the real work.

That boundary also needs an exception. If the learner understands the approach but is blocked by unfamiliar syntax or an API, a small, concrete example can unblock them without taking over the surrounding problem.

Separate teaching modes#

Reviewing an implementation is a different task from explaining a new concept. Repetition is different again. Distinct roles make those expectations easier to express and inspect.

The tradeoff is coordination. More roles mean more names, permissions, and routing rules that can drift apart. The configuration needs consistency checks just as an application needs clear interfaces.

Keep useful memory bounded#

Remembering everything is not the same as remembering what matters. A compact summary of the current goal, recent blockers, and observed progress is more useful for the next interaction than replaying a long conversation history.

Learner state should also follow evidence. A successful exercise, a repeated misconception, or an explicit preference is a stronger basis for an update than an assistant’s impression of confidence.

Make implementation restraint part of the workflow#

The configuration has to operate in a development environment, where reading files, running checks, and making changes are normal activities. That makes restraint a workflow concern: tools should support understanding and verification rather than quietly bypass the opportunity to learn.

What the work demonstrates#

The result is a mentor-first configuration with explicit roles, a support ladder, and tools for continuity. It demonstrates an approach to designing AI workflows around a human outcome instead of treating generation speed as the only measure of success.

This is still an evolving experiment. The useful question for the next stage is whether each interaction leaves the developer better able to reason independently, and what evidence would make that progress visible.

Current state and next steps#

The existing write-up documents the configuration and its rough edges. Further work includes making role boundaries consistent, improving preference-aware routing, and giving exercises a clearer lifecycle from assignment through feedback and retry.

The long-term direction is simple: use AI to develop stronger programmers, not just larger codebases.

Engineering notes

Read the longer story.