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	architect (plan skill)	builder for each atomic milestone, then reviewer
Bug with an unclear cause	adventurer (diagnose skill)	builder implements the confirmed fix, then review
Documentation or release notes	builder	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. Architect loads the plan skill when delivery needs ordered milestones, verification criteria, or rollback points.
Diagnose, then fix - adventurer (diagnose skill) -> builder or direct implementation -> reviewer. Hand over the confirmed cause, affected paths, smallest safe fix, and prevention evidence. For a small local fix, builder loads the diagnose skill directly.
Research only - adventurer -> architect -> 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	Project directory, or the session directory when OpenCode reports no project	Read fresh for every agent-loop and compaction request; edits need no restart
Pi	Session working directory, each turn	Read fresh on every agent turn, composed with the mode prompt

Compaction and carry-over preserve them: OpenCode sends the current project constraints and rules with every agent-loop and compaction request; Pi recomposes sections each turn and persists the mode across turns in the same process.

The declarative Agent Plugins integrations provide instructions to read project guidance; they do not install this runtime loader or its freshness and compaction guarantees. OMP owns native rule discovery, and Hermes requires optional manual host context configuration.

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 fails the request while assembling its context; Pi surfaces it via notification plus a STOP banner. Do not execute the request until the files are fixed.