Overview
Maestria is an open-source monorepo that packages AI engineering methodology — design patterns, agent prompts, workflow rules — as reusable, installable plugins for AI coding agents. The first published package, @maestria/opencode, transforms OpenCode into a disciplined AI engineering workstation with structured handoffs, maker/checker splits, and pipeline-based orchestration.
The core insight: Agent = Model + Harness. The model provides capability; the harness provides reliability. Most agent failures are harness failures, not model failures.
Why I Built This
After months of daily AI-assisted engineering, I noticed a pattern: the same reliability issues kept repeating. Agents would assume instead of verifying, skip documentation, or validate their own work without a second pair of eyes. These weren’t model capability problems — they were process problems.
I extracted the discipline patterns that worked, formalized them into reusable agent prompts, and packaged them as a plugin. The result is a behavior layer that makes AI coding agents more reliable by default.
Key Features
Eight Specialized Subagents
A manager/dispatcher (@orchestrator) delegates to seven specialists — @adventurer for recon, @architect for design, @planner for planning, @builder for implementation, @reviewer for QA, @diagnose for debugging, and @writer for documentation. Each has a focused toolset and clear ownership boundaries.
Pipeline Architecture
Structured handoffs chain agents together: Recon → Design → Implement → Validate. Each handoff includes six fields — Goal, Context, Requirements, Known Problems, Success Criteria, Next Step — preventing dropped context between agents.
Maker/Checker Split
The agent that produces work cannot validate it. The reviewer operates with edit: deny enforced at the permission level, ensuring a genuine second opinion on every change.
Self-Wiring Installation
A single line in opencode.jsonc — "plugin": ["@maestria/opencode@latest"] — auto-installs the entire system from npm. No manual configuration, no file copying.
Build Notes
Pure Plugin Architecture
The plugin uses exactly two hooks — config (register agents + inject rules) and session.compacting (preserve session state). No postinstall scripts, no file copying, zero side effects. Agents are served as markdown files from the npm package directly, keeping them human-readable without a TypeScript factory layer.
ADR-Driven Development
Every significant design decision is documented as an Architecture Decision Record, from global rules scope to tool permission design. Seven ADRs trace the reasoning behind the architecture, making the project’s evolution transparent.