Pi & OMP Reference

Spec-Driven Delegation

The orchestrator gives each specialist a spec - a structured handoff containing seven required fields:

Field	Description
Goal	What the specialist must accomplish
Context	Current mode, active task, specialist history, files touched
Requirements	Specific deliverables and constraints
Known Problems	Blockers or caveats the specialist should address
Assumptions documented	Decisions or assumptions made during investigation
Success Criteria	Verifiable conditions for completion
Next Step	What happens after this task completes

The orchestrator enforces phase gates - each specialist must verify completion before the next phase begins. If a specialist blocks, the orchestrator escalates or re-plans.

Session Tree Integration

Every subagent dispatch records the parent task ID and specialist name in the session tree. Compaction preserves this state so resumed or forked sessions retain full context. The session tree is surfaced via /maestria-status and compaction summaries.

Note

Pi records session tree state via the @gotgenes/pi-subagents extension’s cross-extension events. OMP manages the session tree through its runtime’s native subagent lifecycle - no third-party extension needed.

Commands

Command	Description
/fein	Set workflow mode to full pipeline
/sonar	Set workflow mode to research only
/blitz	Set workflow mode to fast implementation
/review <target>	Enter review mode - restricts toolset to read-only, optionally switches model
/restore-model	Exit review mode and restore original model and tools
/review-model <id>	Configure which model to use when entering review mode
/handoff <goal>	Generate a structured handoff document for task context transfer
/maestria-status	Show current session state including handoff history

Mode keywords work two ways:

• Slash command (/fein, /sonar, /blitz) - sets the workflow mode and shows a notification. Use standalone, then describe your task in the follow-up message.
• Bare keyword (fein, sonar, blitz) - when typed at the start of a message, the platform auto-detects the keyword, sets the mode, and injects the mode prompt inline with your task description. Example: fein implement login sets fein mode and dispatches the task in one message.

Pure Dispatcher Enforcement

When a workflow mode is active (fein/sonar/blitz), the platform may restrict the main session to delegation tools. This can enforce the maker/checker split at the tool level, but the exact restriction differs between Pi and OMP.

Note

Pi restricts the orchestrator to only maestria_subagent during enforcement. OMP allows both task() (native) and maestria_subagent (structured handoff wrapper) during enforcement. The maestria_subagent tool validates parameters and constructs a structured handoff, then returns a plan for the native task() call. Subagent sessions (without the task tool) are not restricted and retain their full specialist toolset.

OMP’s public extension API exposes tool names but not the provenance of a tool call. Maestria therefore does not make a name-only exception for goal, because another extension could register a colliding tool. Native goal state remains observable, including paused goals, but OMP’s native resume, complete, and drop operations remain OMP-owned and available through user-issued /goal slash commands. Maestria does not invoke those commands. Model goal tool calls remain blocked while pure-dispatcher enforcement is active because their provenance cannot be established.

Enforcement lifecycle

When you start a session, the orchestrator prompt and global rules are always active, guiding the AI to delegate work rather than implement directly. However, the tool-level restriction (blocking bash/edit/write etc.) is not active by default - it activates only when you set a workflow mode.

Unlike OpenCode, Pi and OMP do not have a separate @orchestrator agent. The orchestrator skill is present in the main session. A mode keyword adds the mode prompt and, where supported, tool enforcement; it does not switch the session into a different agent.

Interaction	Enforcement	What happens
implement login (no keyword)	Inactive	Orchestrator guidance is present and the main session retains its normal tools
fein implement login	Active	AI restricted to delegation tools only
/fein (command)	Active	Mode set, enforcement active from next turn

The mode persists across turns in the same session. To deactivate enforcement, start a new session.

Subagent dispatch

Specialist dispatch is not identical between Pi and OMP.

Pi

Pi’s maestria_subagent tool executes single, parallel, and chain dispatch through @gotgenes/pi-subagents. Parallel dispatch accepts between 2 and 8 tasks. Subagents inherit the parent context, so the handoff prompt does not guarantee a clean context boundary.

{
  "agent": "adventurer",
  "task": "Map the authentication flow in the auth module"
}

OMP

OMP’s maestria_subagent tool validates the request, records the handoff, and returns a plan for OMP’s native task() tool. The native tool performs the actual dispatch. The wrapper is a structured planning layer, not an equivalent implementation of Pi’s dispatch lifecycle.

task(agent: "builder", task: "Implement the login form")

Use the platform’s native documentation for task limits and lifecycle behavior. Do not assume that Pi’s parallel or chain behavior transfers directly to OMP.

Review Mode

The /review command switches the session into review-only mode:

1. Saves the current model and toolset
2. Optionally switches to a different model (configured via /review-model)
3. Restricts tools to read-only (read, grep, find, ls, glob)
4. Blocks edit, write, and bash calls

Dangerous bash patterns (e.g., rm -rf /, sudo, git push --force) are blocked or require confirmation in all modes.

Usage Notes

Pipeline discipline. When full orchestration is selected, the flow for non-trivial work is adventurer (recon) → architect or planner (design/plan) → builder (implement) → reviewer (validate). Each step verifies before handing off. Skipping recon or review trades speed for risk - fine for simple changes, not recommended for cross-module work.

Handoff validation. Before dispatching to a specialist, the orchestrator validates that the handoff contains all seven required fields. Incomplete handoffs are rejected.

Session persistence. Mode and delegation state survive session compaction, resume, and fork operations. Run /maestria-status to view the current state at any time.

Native goal state (OMP). Maestria observes OMP’s public goal_updated event and mirrors active, paused, and budget-limited goals into session state. Non-null complete and dropped terminal events clear the current-goal mirror after persisting the transition. Session start, switch, fork, branch, handoff, and tree-navigation transitions restore the target-session Maestria state and use a valid public native goal mode entry when available. If OMP provides no readable target goal state, the mirror resets to unknown (null) until a future public goal event. Maestria never activates goal mode or invokes native goal commands.

Note

Pi depends on @gotgenes/pi-subagents for subagent lifecycle and state management. OMP manages all subagent lifecycle through its built-in task() tool - no external dependencies needed, making the extension lighter.

Specialist Agent Registration

The 7 specialist agents (adventurer, architect, builder, diagnose, planner, reviewer, writer) are registered via the standard file-based agent type system - the same mechanism used by all extensions on both platforms.

How it works

1. Sync pipeline generates agents/*.md files from canonical Maestria directives with platform-specific YAML frontmatter, including role-specific tool allowlists and prompt_mode: append / inherit_context: true
2. Extension startup (session_start handler) deploys the agent files to the platform’s agent discovery directory
3. Subagent dispatch discovers the files and registers each as an agent type
4. Pi’s maestria_subagent(...) and OMP’s native task(agent: "adventurer", ...) look up the registered type, merge the role-specific prompt on top of the inherited parent context via prompt_mode: append, and spawn the subagent with the platform’s tools and instructions. OMP’s maestria_subagent(...) validates and records a handoff, then returns a plan for the native call.

Note

Pi deploys agent files to ~/.pi/agent/agents/ (pi-subagents discovery directory). OMP deploys agent files to ~/.omp/agent/agents/ (OMP’s native discovery directory).

Agent file format

Each specialist agent file uses the platform’s standard YAML frontmatter format (identical for Pi and OMP):

---
description: Role description for discovery UI
tools: read, bash, grep, find, ls # tool allowlist
prompt_mode: append # append to inherited parent prompt
inherit_context: true # pass parent session context
---

The prompt_mode: append field is critical - it ensures the specialist prompt merges on top of the inherited orchestrator prompt, so every subagent has both the dispatcher methodology and its role-specific guidance.

Tool isolation

Each specialist has an appropriate tool allowlist matching its role:

Agent	Tools	Purpose
adventurer	read, bash, grep, find, ls, glob	Codebase reconnaissance (read-only)
architect	read, bash, grep, find, ls	Architecture analysis (read-only)
builder	read, bash, grep, find, ls, write, edit	Implementation (full access)
diagnose	read, bash, grep, find, ls	Bug tracing (read-only)
planner	read, bash, grep, find, ls	Planning (read-only)
reviewer	read, bash, grep, find, ls, glob	Code review (read-only)
writer	read, bash, grep, find, ls, write, edit	Documentation (full access)

This enforces the maker/checker split at the subagent tool level - builder and writer have write access, everyone else is read-only.

Persistence

Agent files are deployed once per session and never overwrite existing files in the agent discovery directory (~/.pi/agent/agents/ for Pi, ~/.omp/agent/agents/ for OMP). This respects any user-customized agents with the same name. To reset to Maestria defaults, remove the files from the discovery directory and restart your session.

See Also

• Specialist Reference
• Pipeline & Roles
• Workflow Patterns
• Installation & Setup