Skip to content

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.

  1. Direct execution first. Familiar code, a clear scope, and easy verification make the platform’s normal agent the fastest and cheapest path.
  2. 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.
  3. 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.
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.