Specialist Reference
maestria defines 5 agents: one orchestrator and 4 domain specialists, each with a focused scope and a specific place in the pipeline. Native profiles and tool controls vary by host; role guidance alone is advisory. On Agent Plugins hosts the main session takes the orchestrator role through the global policy, so @maestria/agent-plugins ships the four specialists as profiles; OpenCode registers all 5. Direct-route turns execute on the host; platform invocation syntax lives in the plugin documentation.
Orchestration Model
Section titled “Orchestration Model”The orchestrator routes and manages: it decomposes complex tasks into atomic units, delegates each to a specialist, integrates the results, and verifies completion. It does not implement work it has delegated.
For multi-slice implementation, it plans reviewable PR boundaries early and commits coherent slices after validating them. Each PR receives its own review and evidence; the integrated outcome receives final verification. When the architect guides implementation, the orchestrator first presents a concise design brief so the user can understand the intended changes, sequence, and trade-offs. Tables or diagrams are used when they help explain the design.
Full orchestration groups the 4 specialists into three roles:
- Thinker - reconnaissance, design, planning, analysis
- Worker - implementation, documentation
- Verifier - validation, quality gates
The orchestrator routes dynamically; a pipeline that includes a verifier terminates when the verifier accepts the result.
See When to Use maestria for when orchestration is worth its coordination cost.
Three workflow modes control pipeline depth; activation and enforcement depend on the platform:
| Mode | Full Form | Pipeline | Use Case |
|---|---|---|---|
| fein | Full pipeline | Thinker → Worker → Verifier (adaptive sequencing) | Production-grade work, mandatory validation |
| sonar | Research only | Read-only @adventurer/@architect specialists - STOP before implementation |
Understanding before committing |
| blitz | Fast implementation | Direct execution when permitted; otherwise the permitted specialist, skipping optional recon/design but keeping required safeguards/review. | Quick fixes, known territory |
Where keyword detection is supported, mode keywords are recognized anywhere in a message and case-insensitively; matches inside code fences or inline code are ignored, and the most restrictive mode wins when several keywords appear (fein > sonar > blitz).
Specialist Reference
Section titled “Specialist Reference”| Specialist | Role | When to Use | Key Constraints |
|---|---|---|---|
| Orchestrator | Router and manager - decomposes complex tasks, delegates routed work, integrates results | Multi-step tasks, cross-specialist workflows, anything requiring structured coordination | Cannot implement delegated work; direct-route turns execute on the host. |
| Adventurer | Codebase reconnaissance and read-only diagnosis - maps unfamiliar code, traces dependencies, finds key files, and loads the diagnose skill to stop at a supported root cause | Unfamiliar code, tracing how something works, finding where logic lives, or a bug with an unknown cause | Read/search only - no editing |
| Architect | Architecture decisions and phased plans - trade-off analysis, decision records, and milestones with verification criteria | Technology or design choices, comparing implementation approaches, or complex features needing structured rollout | No state-mutating work; may research external sources; loads the plan skill for multi-phase work |
| Builder | Focused implementation and documentation - one atomic task per invocation, including bug fixes and structured prose | Bug fixes, features, tests, refactors after reconnaissance and design, plus READMEs, API docs, changelogs, and ADRs | Full edit access. One atomic task per invocation. Reports at signature level. Loads the diagnose skill when the cause is not established and docs-update for prose. |
| Reviewer | Code review - correctness, edge cases, security, performance, maintainability | Pre-merge review, security audit, post-implementation validation | Read-only - cannot edit; one general review plus only risk-matched lenses, with blind review, observation-first verification, and [fix]/[dismiss]/[escalate] triage |
Portable Utilities
Section titled “Portable Utilities”The consolidated Agent Plugins package exports two portable utilities, handoff for transferring task context and iteration-limits for bounding repair loops, alongside the bundled methodology skills. Each is generated from the matching section of the global rules, so it always states the same policy the full integrations carry. Full methodology uses host-specific native profiles, commands, and policy entry points. Portable utilities alone do not activate this roster or its modes.
Skills
Section titled “Skills”Bundled methodology skills
Section titled “Bundled methodology skills”The global rules name four maestria-specific skills, so every maestria package ships them: @maestria/agent-plugins (Claude Code, Codex, Cursor, Kimi Code, Devin, ZCode, OMP, Hermes), @maestria/opencode, and @maestria/pi. They update with the package; there is nothing extra to install or select.
- create-pull-request - Title, body, and visual-evidence conventions for a reviewable PR. Agents load it before drafting when the task owns an active PR, follow the project template while preserving the required information, and stop on explicit project opt-out.
- docs-update - Documentation and changeset procedure. Agents load it before finishing a change to behavior, interfaces, configuration, or user-facing workflows, and follow it to classify and update affected docs; ordinary docs work proceeds without it.
- diagnose - Systematic debugging that traces errors from symptom to root cause. Adventurer loads it for a read-only diagnosis and builder applies the fix, or builder loads it directly for a small local fix.
- plan - Phased planning with milestones and verification criteria. Architect loads it for multi-phase features, rollouts, and migrations.
For an agent maestria does not package, install them with skills.sh; this offers the plugin’s six skills, including handoff and iteration-limits:
npx skills add agustinusnathaniel/maestriaEarlier CLI versions installed these two skills separately for each agent. maestria update and maestria uninstall now remove the copies the CLI installed, and maestria doctor lists any that remain; copies you installed yourself are left alone.
Optional engineering skills
Section titled “Optional engineering skills”Agents load these when the assignment calls for them. Every one is optional: a missing skill never blocks the work, and the core directives still apply.
The architect loads architecture-decision-framework when a consequential trade-off benefits from a structured comparison. It lives in the separate agustinusnathaniel/skills repository with other general-purpose engineering skills. After installing a maestria platform, add that repository for your agents with skills.sh (drop -g to install into the current project instead):
npx skills add agustinusnathaniel/skills -gEach specialist also names community skills it loads on a matching trigger, such as agent-browser for UI verification or tdd for explicit test-driven work. The list lives in the Skills section of each specialist definition; install any of them from their own sources if you want that behavior.