maestria

Global behavioral constraints and best practices for maestria-powered Pi agents. Covers orchestration conventions, delegation rules, context management, commit policy, pipeline patterns, and branch discipline.

Maestria agent orchestration dispatcher. Delegates work to 7 specialist subagents (adventurer, architect, builder, diagnose, planner, reviewer, writer) using spec-driven handoffs. Enforces maker/checker split, commit protocol, and role-based pipeline sequencing.

Methodology + delegation + swarm usage for the maestria workflow

Codebase reconnaissance agent for deep code understanding. Maps unknown territory - traces call chains, maps module relationships, generates structured reports for downstream specialists. Use for: understanding unfamiliar code, tracing dependencies, gathering context before implementation, investigating module structures. One role per session: exploration only - never implement or design.

Architecture decisions using decision matrices and ADRs. Evaluates options with weighted criteria, clarifies business context first. Use for: technology choices, implementation approaches, trade-off analysis.

Focused implementation agent for atomic tasks. Executes one verifiable unit of work with minimal context. Use for: targeted fixes, feature implementation, refactors, adding tests.

Systematic 6-step regression tracing. From error message to root cause to prevention. Use for: cryptic errors, regressions, production bugs.

Create detailed implementation plans with phased dependencies, timelines, and success criteria. Breaks down complex features into verifiable milestones. Use for: complex features requiring multi-phase execution, when the plan needs review before building.

Code review with quality gates. Reviews code for correctness, edge cases, security, performance, maintainability, and adherence to conventions. Provides specific, actionable feedback. Use for: PR review, pre-commit review, architecture document review.

Make architecture decisions using decision matrices and iterative refinement. Use when comparing implementation approaches, evaluating trade-offs, selecting technology, or facing multiple viable paths. Prioritizes business context over technical purity — clarifies the problem before deciding, presents options with trade-offs, documents decisions as lightweight ADRs.

Documentation writing following structured patterns. Creates clear, comprehensive docs for code, APIs, systems. Use for: README files, API docs, architecture docs, changelogs, decision records.

The 6-field handoff contract for inter-specialist delegation. Load when receiving a task from another specialist, or when handing off work to the next stage in the pipeline.

The iteration-limit pattern with verifiable termination and escalation format. Load when defining termination conditions for a loop, or when a loop is at risk of running too long.