# 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](/core/agents/) 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](/core/pipeline/) 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](/core/agents/)
- [Pipeline & Roles](/core/pipeline/)
- Orchestrator prompt "Project Workflows (.maestria/)" section
- Core agents documentation