Workflow Patterns

Workflow Patterns

The 7 specialists work as a team. The orchestrator manages the flow - it decomposes complex requests into phases, delegates each phase to the appropriate specialist, and verifies completion before moving on.

This page builds on the specialist roles and pipeline model documented in the Specialist Reference. The pipeline routes work through thinker → worker → verifier roles with dynamic sequencing.

Explore a codebase

Send Adventurer to map unfamiliar code before making changes.

Adventurer: Map the API layer - find all routes, middleware, and error handlers.

The Adventurer traces call chains, maps modules, and reports back with a structured reconnaissance report. Start here whenever you edit code you haven’t worked with before.

Make a design decision

Delegate to Architect when you need to evaluate options.

Architect: Should we use REST or GraphQL for the new public API? Evaluate trade-offs.

The Architect returns a trade-off analysis with a clear recommendation, often accompanied by a lightweight Architecture Decision Record.

Plan a feature

Get a phased plan from Planner before implementing multi-step features.

Planner: Plan the implementation for a multi-tenant organization feature.

The Planner breaks work into ordered milestones with verification criteria and rollback points. Plans are pure strategy - the orchestrator consumes them and dispatches each phase to the appropriate specialist.

Build something

Use the orchestrator for end-to-end feature work. It chains the full pipeline.

Orchestrator: We need a WebSocket-based notification system. Explore, plan, implement, and review.

The orchestrator delegates to the right specialists in sequence, following the pipeline model. Every code change goes through Builder, every review through Reviewer.

Fix a bug

Start with Diagnose to find the root cause, then hand the fix to the orchestrator.

Diagnose: Users are getting a 503 error when uploading files over 10MB. Find the root cause.

Then:

Orchestrator: Fix the upload issue that Diagnose identified.

The Diagnose specialist runs a systematic tracing loop - error to source to git history to blast radius to minimal fix to prevention - and reports the root cause with a suggested fix.

Review code

Let Reviewer check your changes before committing.

Reviewer: Review my current changes before I commit.

The Reviewer runs a 7-dimension checklist: correctness, performance, security, maintainability, test coverage, error handling, and style. The Reviewer is read-only and never edits files directly.

The Reviewer also prioritizes observing behavior over reasoning about correctness - each review includes a command, API request, or browser interaction that produces visible proof.

Multi-lens review

For non-trivial changes, the orchestrator can dispatch multiple Reviewers with different focus areas in parallel. This catches more issues than a single general review.

Orchestrator: Security review: focus on injection risks, auth bypasses, data exposure. Orchestrator: Performance review: focus on bottlenecks, allocations, bundle size. Orchestrator: UX review: focus on visual fidelity, accessibility, interaction patterns.

Available lenses: Security, Architecture, Performance, UX, and General (the full checklist). Each lens has exclusive scope - no two reviewers cover the same ground.

Review triage

After all lenses return, the orchestrator triages the combined feedback into three categories:

• [fix] - Actionable issues dispatched to Builder for implementation
• [dismiss] - Nits resolved with a comment, no code change needed
• [escalate] - Ambiguous or high-risk issues surfaced to the user via question

Conflict resolution: if lenses disagree on the same issue, the more conservative categorization wins. If any lens escalates, the whole issue escalates.

When to use single vs multi-lens

Use single @reviewer	Use multi-lens swarm
Trivial changes, docs, config	Touches multiple concerns (data + UI)
Diffs under ~100 lines	Security-sensitive or performance-critical
Pure documentation	Large diffs needing focused attention

Rule #9 (mandatory review after every Builder change) remains the default - multi-lens is an enhancement for when one reviewer can’t give each dimension proper attention.

Document something

Delegate READMEs, ADRs, changelogs, and API docs to Writer.

Writer: Write a README for the new caching package.

The Writer follows structured patterns matched to the document type - purpose, usage, details. Description in, complete document out.

Investigate an uncertain problem

Use Parallel speculation when the right approach isn’t clear and you need multiple perspectives before committing to a direction.

Orchestrator: I need to understand why the auth module keeps failing under load. Adventurer, map the entry points. Architect, evaluate the auth architecture. Diagnose, trace the failure path.

The orchestrator dispatches the same question to multiple specialists with different lenses, then synthesizes the results before choosing a direction. Use this pattern when:

• The root cause of a problem is genuinely unknown
• A design decision has ambiguous trade-offs
• You need to explore an unfamiliar domain from multiple angles

This is different from parallel exploration (which fans out independent tasks). Parallel speculation fans out the same question to get different perspectives on it.

Test an uncertain approach

Use Experiment framing when a task has high uncertainty - unknown dependency, unvalidated approach, first exploration of a domain. Frame it as an experiment rather than a delivery.

Orchestrator: Experiment: Can we replace the in-memory cache with Redis without increasing p99 latency? Hypothesis: Redis will add < 5ms to cache lookups. Termination: if latency exceeds 5ms, revert.

The orchestrator sets an explicit hypothesis and termination condition. The output is a validated (or invalidated) claim, not shipped code. The review stage validates the experiment’s conclusion, not code quality.

Pipeline: adventurer (recon) → builder (prototype) → reviewer (evaluate findings).

Parallel exploration

Fan out multiple Adventurers to understand several areas at once.

Orchestrator: I need to understand both the auth system and the payment system. Map them in parallel.

The orchestrator spawns independent exploration tasks simultaneously and presents a combined report.

Pipeline reference

See Pipeline & Roles for the full pipeline diagram and role descriptions.

Tip

Most tasks don’t start with code. Start with recon (Adventurer) or design (Architect) before reaching for Builder. The orchestrator handles this routing automatically.

Project Workflows (.maestria/)

Projects using maestria’s agent directives can define custom workflow instructions in .maestria/workflow.md and .maestria/rules.md at the project root. These files tell the orchestrator how to sequence delegation for that specific project.

How It Works

The orchestrator checks for these files when starting work on a project by delegating to @adventurer. If found:

• .maestria/workflow.md - Guides delegation sequencing. The orchestrator follows this to determine what to do and in what order (e.g., read the README first, check recent commits, read relevant ADRs before implementing).
• .maestria/rules.md - Project-specific non-negotiable rules that supplement the core rules. These are propagated to all subagents via delegation prompts.

Precedence

Core rules (delegate don’t implement, maker/checker split, commit protocol, etc.) always take precedence over project instructions. If a conflict arises, the core rule wins.

Example

Here’s a minimal .maestria/workflow.md:

## Sequencing

### 1. Understand Context
Delegate to @adventurer:
- Read README.md for project overview
- Check recent commits (git log --oneline -10)
- Read package.json and workspace config

### 2. Read Relevant ADRs
Delegate to @adventurer to read ADRs in docs/adr/ before implementing.

### 3. Implement and Test
Delegate to @builder with the project's quality pipeline:
pnpm typecheck
pnpm test
pnpm build

When to Use

Create a .maestria/workflow.md when your project has:

• Specific conventions for how work should be sequenced (recon → design → implement → docs)
• Project-specific quality gates (particular test commands, linting, build steps)
• A structured ADR or decision documentation process
• Multiple packages with different conventions

The file is entirely opt-in - projects without .maestria/ files see no change in agent behavior.

See Also

• Specialist Reference
• Pipeline & Roles
• Orchestrator prompt “Project Workflows (.maestria/)” section
• Core agents documentation