Pipeline & Roles

For complex work that uses the pipeline, Maestria separates three roles: Thinker, Worker, and Verifier. Each role is staffed by one or more specialists with focused expertise. An orchestrator (manager) sequences the selected roles adaptively, decomposing high-level goals into atomic tasks and routing each to the right specialist.

Overview

The pipeline separates three fundamentally different cognitive modes:

• Thinker - analyzes, designs, and plans when the selected route needs that work. Asks “what should we do and why?” before implementation when the task is unfamiliar or design-uncertain.
• Worker - executes, produces artifacts. Carries out the plan, one atomic task at a time.
• Verifier - validates output against quality criteria. Catches what the worker missed.

This separation prevents a single agent from grading its own homework. By enforcing distinct roles with different permissions and incentives, the pipeline produces higher-quality output with fewer hidden defects.

The Three Roles

Thinker

Thinkers gather information, evaluate options, and produce designs or plans. They are read-heavy, write-light - they consume context, produce analysis, and shape direction, but rarely modify production artifacts directly.

Specialist	Function	Scope
Adventurer	Reconnaissance	Maps unfamiliar code, traces dependencies, gathers context before implementation
Architect	Design & decisions	Evaluates trade-offs, selects approaches, documents architecture decisions
Planner	Phased plans	Breaks complex features into sequenced milestones with verification criteria
Diagnose	Root cause analysis	Traces bugs from symptom to cause, determines the correct fix

Worker

Workers execute. They take a clear specification (from a Thinker) and produce the corresponding artifact. Workers are write-heavy - they edit files, run commands, and ship changes.

Specialist	Function	Scope
Builder	Implementation	One atomic task per invocation - bug fix, feature slice, test, refactor
Writer	Documentation	Structured docs - READMEs, API docs, changelogs, architecture decisions

Verifier

Verifiers validate. They inspect artifacts produced by Workers against quality criteria - correctness, edge cases, security, performance, and maintainability. Verifiers are read-only: they can flag issues but cannot edit.

Specialist	Function	Scope
Reviewer	Review / QA	Pre-merge validation, security audit, post-implementation review

For a full review, the orchestrator dispatches one independent general Reviewer. It adds specialist lenses only when the requirements or diff show matching security, performance, architecture, or UX risk. Reviews remain blind and lenses remain exclusive. Results are triaged into [fix]/[dismiss]/[escalate] categories with conservative conflict resolution.

Pipeline Flow Diagram

Orchestrator (manager)
  ├─ Thinker (analysis/design/planning)
  │   ├─ Adventurer    → Reconnaissance
  │   ├─ Architect     → Design & decisions
  │   ├─ Planner       → Phased plans
  │   └─ Diagnose      → Root cause analysis
  ├─ Worker (implementation/documentation)
  │   ├─ Builder       → Implementation
  │   └─ Writer        → Documentation
  └─ Verifier (validation)
      └─ Reviewer      → Quality gates

Dynamic Sequencing

The default pipeline order is thinker → worker → verifier. A Thinker produces a plan or specification, a Worker executes it, and a Verifier confirms the result is correct.

However, the order is not fixed. The orchestrator adapts it to the task:

• High-risk changes - consider think → verify → work. Validate the design before investing in implementation. If the design is flawed, the Worker never builds the wrong thing.
• Rejected output - if the Verifier rejects a Worker’s output, the orchestrator routes back:
  • Back to Worker - the issue is an implementation defect; the Worker fixes and resubmits.
  • Back to Thinker - the issue is a design flaw; the scope or approach needs rethinking.
• Accepted output - the pipeline terminates. The artifact is ready for integration.

Caution

The orchestrator must define a verifiable termination condition before starting any delegated loop. Without one, the pipeline can cycle indefinitely between Worker and Verifier.

Maker/Checker Split

The specialist that wrote the code must not be the same specialist that reviews it. This is non-negotiable.

Caution

Maker/Checker Split - The agent that produced an artifact must not validate it. A model grading its own work is too lenient. Always use a different specialist for review. If the reviewer is blocked on context they lack, the Thinker (e.g. Adventurer or Architect) provides that context

• but the reviewer remains independent from the implementer.

The maker/checker split is why the pipeline defines separate specialists for Workers and Verifiers. A Builder never reviews their own output. A Reviewer is an independent specialist with different instructions, incentives, and permissions.

Iteration Limits

Delegated repair loops should converge within a practical normal bound of about three rounds. Extend the loop only when the latest attempt shows observable progress toward a verifiable termination condition. If the same cause recurs or no new evidence appears, change strategy or escalate with what was tried, what failed, and what is needed to proceed.

Implementation turns end at a delivered state - reviewed changes on a pushed branch with an open PR - and cancelled delegations are retried once rather than treated as stop signals.

Note

Repeated retries without progress consume context without improving the result. Use evidence of progress to justify another round; otherwise change strategy or escalate.

Workflow modes

The pipeline supports three modes that control its depth. Each mode is suited to a different class of work.

Mode	Pipeline	Use Case
Full pipeline	Thinker → Worker → Verifier (adaptive sequencing)	Explicitly chosen for high-risk or multi-phase work where the extra stages earn their cost.
Research	Thinker only - STOP after analysis/design	Understanding before committing. Reconnaissance, architecture evaluation, planning without execution.
Fast implementation	Direct execution when the host permits it; otherwise the permitted specialist - skip optional recon/design ceremony and keep required safeguards/review	Quick fixes in known territory where the design is obvious and risk is low.

The available mode names and activation rules depend on the platform. A task can also escalate from one mode to another - if a fast implementation hits unexpected complexity, the agent can fall back to the full pipeline. Strong or expensive models often work better with direct execution or a single specialist; see When to use Maestria.

See Also

• Specialist Reference
• Workflow Patterns