Workflow Patterns

Use this page to choose a starting point for a task. Specialist Reference has role details, Pipeline & Roles the execution model, and When to use maestria the cost and risk trade-off.

Match the Task to a Route

Task	Start with	Continue with
Familiar, atomic change	Direct execution	Review only if the risk warrants it
Unfamiliar codebase or dependency path	adventurer	Implement directly or hand the map to builder
Architecture or technology choice	architect	Record the decision, then implement
Multi-step feature or migration	planner	builder for each atomic milestone, then reviewer
Bug with an unclear cause	diagnose	Implement the confirmed fix, then review
Documentation or release notes	writer	Review the rendered or published result
Pre-merge validation	reviewer	Fix findings, then rerun the relevant checks
Complex or high-risk change	Full pipeline	Stop when the verifier accepts the result

Add a stage only when it supplies missing information, reduces a material risk, or creates a useful independent check.

Keep Handoffs Small

Give the next specialist enough to act without copying the whole conversation:

Outcome: what the recipient must produce
Context and constraints: relevant files, decisions, and limits
Acceptance/evidence: how to tell the result is complete
Next step: who consumes the result

Prefer links to existing artifacts, omit empty fields, and keep the brief proportional to the task. For example:

Adventurer: Map the authentication entry points and session writes in src/auth/; return file paths, call paths, and the smallest relevant risks. Do not edit. Architect receives the map.

Builder: Implement the accepted session-refresh design as one atomic change; run the focused tests and report changed files, evidence, and unresolved assumptions. Reviewer receives the result.

Common Sequences

Understand, then implement - adventurer -> direct implementation or builder -> reviewer when needed. Stop reconnaissance once the entry points, dependencies, and constraints are known.
Decide, then implement - architect -> builder -> reviewer. Use planner instead when delivery needs ordered milestones, verification criteria, or rollback points.
Diagnose, then fix - diagnose -> builder or direct implementation -> reviewer. Hand over the confirmed cause, affected paths, smallest safe fix, and prevention evidence.
Research only - adventurer -> architect or planner -> stop. sonar packages this boundary where the platform supports it; a research result states what was learned, what remains uncertain, and what would justify implementation.

Match review depth to risk

Use one independent reviewer for ordinary pre-merge validation, adding a security, architecture, performance, or UX lens only when the requirements or diff expose that risk. The maker must not review the same artifact; Pipeline & Roles covers repair-loop limits.

Project-Specific Workflows

Projects may add two root-only files, loaded in order: .maestria/workflow.md for project context, required reading, and quality gates, then .maestria/rules.md for local non-negotiable constraints. Each file carries a subordinate-guidance header: it may replace configurable workflows but never waives safety, authorization, or host permissions. Runtime safeguards, selected-route protections, review independence, bounded retries, and commit authorization still take precedence.

Keep these files short: reusable methodology belongs in the canonical maestria directives, project decisions in ADRs, and one-off task details in the handoff.

How engines load them

Engine	Project root	Freshness
OpenCode	SDK project worktree, then instance worktree, then session directory	Read fresh on every model call; edits need no restart
Pi / OMP	Session working directory, each turn	Read fresh on every agent turn, composed with the mode prompt

Compaction and carry-over preserve them: OpenCode keeps active project constraints in the compaction summary while content re-injects on every call; Pi and OMP recompose sections each turn and persist the mode across turns in the same process.

Absent versus unusable

Missing or empty files are skipped silently. A present-but-unusable file (a directory, a non-file, a symlink escaping the project root, or an unreadable file) fails loud with a diagnostic that names only the relative path, never absolute paths or file contents. OpenCode propagates it as a failed model call; Pi and OMP surface it via notification plus a STOP banner. Do not execute the request until the files are fixed.