Specialist Reference
maestria defines 8 agents: one orchestrator and 7 domain specialists, each with a focused scope, clear permissions, and a specific place in the pipeline. 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 an architect or planner 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 7 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/@planner 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 - maps unfamiliar code, traces dependencies, finds key files | Unfamiliar code, tracing how something works, finding where logic lives | Read/search only - no editing |
| Architect | Architecture decisions - trade-off analysis and decision records | Technology or design choices, comparing implementation approaches | No state-mutating work; may research external sources |
| Builder | Focused implementation - one atomic task per invocation | Bug fixes, features, tests, refactors after reconnaissance and design | Full edit access. One atomic task per invocation. Reports at signature level. |
| Diagnose | Systematic debugging - traces errors from symptom to root cause | Bugs, regressions, crashes, mysterious errors, failing tests | Edit access only for confirmed fixes |
| Planner | Implementation plans - phased milestones with verification criteria | Complex features needing structured rollout, migration plans, multi-phase work | Plan-only output; investigates with read-only tools |
| 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 |
| Writer | Documentation - structured patterns for READMEs, API docs, changelogs, ADRs | READMEs, API docs, changelogs, architecture decisions | Documentation scope; not a code-editing role |
Methodology Skills
Section titled “Methodology Skills”Standalone skills the CLI installs and agents load when the assignment calls for them. A missing skill never blocks the work; follow the core directive instead.
- create-pull-request - Title, body, and visual-evidence conventions for a reviewable PR. 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 update procedure. Load it when docs work applies and follow it; ordinary docs work proceeds without it.
- spec-contract - Optional contract header shape for persistent intent across steps. Load it only when cross-step intent refs would reduce risk; absence is normal, and reviewers apply its drift and acceptance-coverage rules only when a header or owning spec is linked.