MAI is an opinionated OpenCode configuration for learning software development with AI. It is inspired by Boot.dev and PAI, with a mentor-first goal: use AI to strengthen reasoning and independent problem-solving, not merely to produce code quickly.

The default assistant a learning orchestrator that routes work to specialist agents. The prompts favor diagnosis, small hints, deliberate practice, review, verification, and gradually reduced support. This repository is configuration and an evolving experiment, not a claim that AI can replace teachers, experience, or independent judgment.

OpenCode
  -> opencode.json and AGENTS.md
  -> mentor-orchestrator
  -> mentor | reviewer | architect | drill-instructor
  -> skills and project-aware tools
  -> local learner state and session reflection

• opencode.json selects the primary agent, loads plugins, configures Context7, and defines baseline permissions.
• AGENTS.md establishes the Rob identity and repository-wide operating rules.
• agents contains the orchestrator and specialist prompts.
• core supplies the shared tutoring policy at runtime.
• tutor exposes learner-profile, concept-graph, curriculum, exercise, grading, and reflection tools implemented under tools/tutor/.
• plugins/context-loader.ts injects the shared Core policy once per session.

A pair-programmer prompt is included but disabled by default so the mentor-first workflow remains the primary path. OpenCode's built-in explore agent is used for codebase discovery where permitted.

• PEDAGOGY explains the educational rationale and vocabulary.
• core is the operational source of truth for tutoring behavior.
• Role prompts in agents/ specialize Core without replacing it.
• assignment defines learner-owned practice tasks; the other skills add focused workflows such as review, TDD, security, and Go development.

The central loop is diagnose → teach → practice → assess → reflect → progress. Assistance is calibrated to demonstrated work, and the system aims to fade scaffolding as the learner becomes more independent.

Runtime learner state is written inside each active project under .opencode/mentor/. It can contain learner identifiers, project paths, goals, evidence, misconceptions, exercises, and reflections.

Prerequisites:

• A working OpenCode installation.
• Bun for the TypeScript tools and plugins.
• Optional: Context7 MCP network access for current library documentation, beads for issue tracking, graphify or codegraph for codebase discovery.

Back up any existing OpenCode configuration before installing. Then clone this repository as the global configuration and install its development dependency:

mv ~/.config/opencode ~/.config/opencode.backup
git clone https://github.com/davejpeters/opencode-mentor ~/.config/opencode
cd ~/.config/opencode
bun install

Review opencode.json, agent permissions, and plugin behavior before first use. Restart OpenCode after changing configuration, agents, skills, or plugins because those files are loaded at startup.

Common starting points:

1. Change the Rob name and identity in AGENTS.md.
2. Adjust language and workflow rules under rules/.
3. Tune agent prompts and permissions in agents/ and opencode.json.
4. Add, remove, or revise workflows under skills/.
5. Review defaults in tools/tutor/runtime.ts, including the preferred language and learner identifier strategy.
6. Disable integrations that are unavailable on your machine.
7. Add more skills, tools, agents, commands, and plugins.

The configuration combines prompt-level boundaries with OpenCode permissions and small defensive plugins:

• Shell commands generally require approval; a narrow set of read-only or verification commands is allowed explicitly.
• plugins/env-protection.ts blocks tool reads whose path contains .env.
• plugins/safety-filter.ts blocks shell commands containing rm.
• Agent permissions restrict editing, writing, shell use, and delegation by role.
• The mentor policy avoids complete target implementations while guided learning can still move the learner forward.
• OpenCode sharing is disabled in opencode.json.

These are guardrails, not a security sandbox. Inspect proposed commands and changes, keep secrets out of the repository, and tighten permissions for your environment.

• plugins/notifications.ts calls notify-send for idle-session and permission-request desktop notifications. It is intended for Linux desktops with a notification daemon; remove the plugin from opencode.json elsewhere.

The notification plugin tolerates command failures.