01
Pipeline composition
Route work through focused stages so no single context does everything.
Maestria
OPEN-SOURCE AGENT METHODOLOGY
Make every step intentional.
A portable harness for AI coding agents. Route complex work through specialists, structured handoffs, and independent review.
npx maestria install opencodenpm · pnpm · yarn · bun · deno
- any runtime works
Harness transcript example
npx maestria install opencode
@maestria/opencode installed - 8 agents wired
maestria status
opencodeconnectedclaude-codeconnected
kimi-codeavailablecursoravailable
# one task through the harness - thinker, worker, verifier
thinkeradventurerrecon report
thinkerarchitectdecision record
plannerphased plan
workerbuilderimplementation + tests
verifierreviewerverdict: approved
01 / THE METHOD
Structure beats improvisation.
02
Maker/checker split
The builder produces; the reviewer sees it fresh.
03
Platform independence
The methodology stays consistent while each platform uses its native primitives.
02 / SPECIALISTS
One dispatcher, seven specialists.
Orchestrator
Routes tasks to specialists, manages commit protocol
The dispatcher routes every task to the right specialist, enforces the maker/checker split, and manages the commit protocol. It never implements.
- Scope
- Dispatch only - never implements
- Artifact
- Route assignments, commit protocol
- Constraint
- Maker/checker split enforced
Adventurer
Codebase reconnaissance, deep code understanding
Maps unknown territory so downstream specialists can work with full context. Explores code paths, traces dependencies, and produces structured reconnaissance reports.
- Scope
- Unfamiliar code territory
- Artifact
- Reconnaissance report
- Constraint
- Read-only - no edits
Architect
Architecture decisions, trade-off analysis, ADRs
Makes architecture decisions systematically. Clarifies the problem, presents options with trade-offs, and documents decisions as Architecture Decision Records.
- Scope
- Approach selection, trade-offs
- Artifact
- Decision record (ADR)
- Constraint
- Decisions documented, not coded
Builder
Focused implementation, single-task execution
Handles exactly one atomic task per invocation. Reads context, edits minimally, verifies with tests, and reports what changed and why.
- Scope
- One atomic task
- Artifact
- Implementation + tests
- Constraint
- Never reviews its own work
Diagnose
Systematic bug tracing, root cause analysis
Traces bugs systematically from error to source, source to git history, and history to blast radius. Finds root cause and all similar problems in the codebase.
- Scope
- Regressions, incidents
- Artifact
- Root cause analysis
- Constraint
- Root cause before fix
Planner
Implementation plans with phased milestones
Creates implementation plans with goals, phased milestones, atomic tasks, verification criteria, and rollback points for complex features.
- Scope
- Complex, multi-step features
- Artifact
- Phased implementation plan
- Constraint
- Plan first, build later
Reviewer
Code review with quality gates
Runs one general review for quality, correctness, security, and maintainability, adding specialist lenses only for matching security, performance, architecture, or UX risk. Preserves blind review, lens exclusivity, observation over reasoning, and [fix]/[dismiss]/[escalate] triage. Enforces the maker/checker split.
- Scope
- Pre-merge quality gates
- Artifact
- Review verdict
- Constraint
- Sees work fresh - independent
Writer
Documentation following structured patterns
Writes documentation following structured patterns. Covers purpose, usage, and details with progressive disclosure and plain language.
- Scope
- Documentation and prose
- Artifact
- Structured docs
- Constraint
- Follows the source of truth
03 / ADAPTERS
One methodology, built on native primitives.
@maestria/opencode8 specialized agents with global rules injected into every session.@maestria/claude-codeNamespaced agents, skills, and workflow commands for Claude Code.@maestria/codexSpecialist and workflow skills for Codex CLI.@maestria/kimi-code8 specialized skills with swarm-aware orchestration and no build step.@maestria/cursorSpecialist agents, orchestrator skill, and workflow commands for Cursor IDE and CLI.@maestria/pi & @maestria/omp7 specialist subagents with spec-driven orchestration for Pi and Oh My Pi.@maestria/hermesMethodology layer for Hermes Agent: specialists, pipeline, and mode system.@maestria/prime-agentSkills-first Maestria for Prime Agent: specialists, orchestrator, and workflow modes.Shared ecosystemOptional companion tooling: CodeGraph indexing and RTK.
8PIPELINE AGENTS
3THINKER / WORKER / VERIFIER
9PLATFORM ADAPTERS
0VENDOR LOCK-IN
04 / FIND YOUR WAY
Start with the docs.
Core
How It WorksThe dispatcher, seven specialists, and the staged pipeline.Pipeline & RolesThinker, worker, and verifier roles, plus the maker/checker split.Specialist ReferenceAll eight agents: scope, artifact, and constraint for each.When to UseDecide between direct execution, a specialist, or the full pipeline.