Overview
Maestria gives AI coding agents a structured workflow for exploring, designing, implementing, and validating engineering work. It uses specialized roles and explicit handoffs to keep context moving and review in the loop.
The workflow adapts to several coding-agent platforms, including OpenCode, Claude Code, Codex, Cursor, Kimi Code, Hermes, Pi, and Prime Agent. The OpenCode setup provides eight agents, rules, structured handoffs, permission-aware roles, workflow modes, and session-compaction state preservation.
The core insight is simple: Agent = Model + Harness. The model provides capability; the harness provides the process and controls that make the work repeatable.
Why I Built This
After months of daily AI-assisted engineering, I noticed the same reliability problems repeating. Agents would assume instead of verifying, skip documentation, or validate their own work without a second pair of eyes. These were process problems, not just model capability problems.
I extracted the discipline patterns that worked, formalized them into reusable agent directives, and adapted them to several coding-agent platforms.
Key Features
Platform Projections
Canonical agent directives are kept in the core package and projected into platform-specific packages. Each projection follows the host’s native plugin, skill, or rule format.
OpenCode Agent Team
The OpenCode package includes an orchestrator and seven specialists: adventurer, architect, planner, builder, reviewer, diagnose, and writer. Each role has a focused toolset and a defined area of responsibility.
Structured Handoffs
The workflow chains Recon, Design, Implement, and Validate stages. Handoffs carry Goal, Context, Requirements, Known Problems, Success Criteria, and Next Step so important context is not lost between agents.
Maker and Checker Roles
In the OpenCode projection, the reviewer has edit permission denied. The agent that produces a change cannot be the only agent responsible for validating it.
Build Notes
Platform Fit
Maestria adapts the same workflow to each platform’s native plugin, skill, or rule format. In OpenCode, the reviewer role cannot edit the project it reviews.
Documented Decisions
Significant design decisions are recorded as Architecture Decision Records, so the workflow remains inspectable and its boundaries are clear.