Pi Reference
This page describes the @maestria/pi runtime extension. The Oh My Pi integration uses the shared portable package and has different activation and lifecycle behavior; see maestria for OMP.
Workflow Modes
Section titled “Workflow Modes”| Command | Behavior |
|---|---|
/fein |
Full pipeline with reconnaissance, design, implementation, and review |
/sonar |
Research-only route that stops before implementation |
/blitz |
Fast path that skips optional reconnaissance and design while preserving required safeguards |
A mode keyword anywhere in a message, outside code, sets the mode and applies it to that message; when several appear, the most restrictive wins (fein > sonar > blitz). A slash command sets the mode without a task. Either way the mode stays active for the session until another mode is set or you run /mode-clear.
Specialist Dispatch
Section titled “Specialist Dispatch”The extension registers four specialist agents: adventurer, architect, builder, and reviewer. Its maestria_subagent tool dispatches one specialist, up to eight in parallel, or a chain, through @gotgenes/pi-subagents; without that extension, dispatch reports that it is unavailable. Adventurer handles read-only diagnosis with the diagnose skill, except that on Pi a diagnosis that must reproduce a failure goes through builder, since adventurer has no shell tool. Architect handles phased plans with the plan skill, and builder handles implementation and documentation.
{ "agent": "adventurer", "task": "Map the authentication flow in the auth module"}The subagents inherit parent context. Treat handoff prompts as guidance and include the goal, constraints, acceptance evidence, and next step needed by each child.
Session State
Section titled “Session State”The extension records subagent runs and handoff history in the session. /maestria-status shows the active mode and handoff history. State handling across compaction and resumed sessions follows Pi’s host lifecycle.
Review Mode
Section titled “Review Mode”/review <target> enters the extension’s review-only path. /review-model <id> selects a review model, and /restore-model returns to the previous model and tools. Review-mode tool availability is an extension behavior; do not use a reviewer persona as a substitute for checking the active tools.
Project Instructions
Section titled “Project Instructions”The extension checks .maestria/workflow.md and then .maestria/rules.md from the session working directory. Missing or empty files are skipped. A present but unusable file triggers a notification and a STOP banner in the system prompt that tells the agent not to execute the request until the file is fixed. See Workflow Patterns for precedence and carry-over.