When to Use maestria
maestria adds structure through method skills, review briefs, and independent review. That structure costs model work, context transfer, and waiting time, so it is not the default.
Default Rule
Section titled “Default Rule”- Direct execution first. Familiar code, a clear scope, and easy verification make the platform’s normal agent the fastest and cheapest path.
- One method skill when one capability is missing. Unfamiliar code or an unclear surface (
recon), a consequential choice or phased plan (architecture-plan), an unknown cause (diagnose), or a second pair of eyes (reviewer). Then implement directly. - Full method with review only when the task needs staged work or independent validation: cross-module features, migrations, high-risk changes, unfamiliar systems, or durable handoffs across sessions.
Quick Decision
Section titled “Quick Decision”| Task | Start with |
|---|---|
| One or two known files and an obvious change | Direct execution |
| Small bug in unfamiliar code | recon or diagnose in the main loop, then direct |
| UI, copy, or interactive iteration | Direct execution or the fast mode |
| Research or feasibility question | Research-only mode (stop, no implementation) |
| Cross-module feature, migration, high-risk or long-running work | Main loop in the full-method mode with reviewer |
| Sharing handoffs and repair limits across clients | Portable Agent Plugin (eight skills; full workflow uses the selected host integration) |
Mode behavior is defined by ModeKeyword in packages/shared/mode/src/index.ts (full-method, research-only, and fast modes); details are in the mode table.
Each review adds a model turn, context transfer, waiting, and possible repair work. Strong or expensive models favor direct execution or one skill; fast, inexpensive models can make narrow review a reasonable trade. Read the platform guide before assuming a route, permission, or lifecycle behavior transfers unchanged.