Pi & OMP Reference

Contract-Driven Delegation

Historically called Spec-Driven Delegation. The model is now contract-driven delegation: compact handoffs, spec-aware but format-agnostic, with persistent intent refs via the spec-contract skill only when they reduce risk.

The orchestrator gives each specialist a compact, material handoff: outcome, relevant context and constraints, acceptance or expected evidence, material assumptions or known problems, and the next step or blocker. There is no fixed field count; the orchestrator validates handoffs before dispatch and rejects incomplete ones.

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

Pipeline discipline. For non-trivial work, the flow is adventurer (recon) → architect or planner (design/plan) → builder (implement) → reviewer (validate); each step verifies before handoff. Skipping recon or review trades speed for risk.

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. /maestria-status and compaction summaries surface the tree, and mode and delegation state also survive compaction, resume, and fork.

Pi records session tree state via the @gotgenes/pi-subagents extension’s cross-extension events.

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 block mutation tools in the main session. This enforces the maker/checker split at the tool level. The behavior differs between Pi and OMP:

Pi blocks edit, write, patch, and mutating bash calls while the subagent delegation tool is available. Read-only tools and read-only bash commands keep working.
OMP blocks the same mutations while the native task() tool is available, and leaves maestria_subagent (the structured handoff wrapper) callable.

The maestria_subagent tool validates parameters, builds a structured handoff, and returns a plan for the native task() call. Subagent sessions (without the task tool) keep their full specialist toolset.

Enforcement lifecycle

The orchestrator prompt and global rules are always active. The tool-level restriction (blocking bash mutations, edit, and write) is not active by default; it activates only when you set a mode.

Unlike OpenCode, Pi and OMP have no separate @orchestrator agent: the orchestrator skill lives in the main session, and a mode keyword adds the mode prompt and, where supported, tool enforcement without switching agents.

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	Mutation tools blocked; read-only tools remain
`/fein` (command)	Active	Mode set, enforcement active from next turn

The mode persists across turns in the same process. Use /mode-clear to return to neutral routing without restarting.

OMP goal state

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 the transition is persisted. Session start, switch, fork, branch, handoff, and tree-navigation transitions restore the target-session state using a valid public native goal mode entry when available; without readable target goal state, the mirror resets to unknown (null) until the next public goal event.

OMP’s public extension API exposes tool names but not call provenance, so maestria makes no name-only exception for goal: another extension could register a colliding tool. Native goal state remains observable, including paused goals, but resume, complete, and drop remain OMP-owned and available through user-issued /goal commands, which maestria never invokes. Model goal calls stay blocked during enforcement because their provenance cannot be established.

Subagent dispatch

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 handoffs do not guarantee a clean context boundary.

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

OMP’s maestria_subagent tool validates the request, records the handoff, and returns a plan for OMP’s native task() tool, which performs the dispatch. The wrapper is a planning layer, not a copy 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. Pi’s parallel or chain behavior does not transfer directly to OMP.

Review Mode

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

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

Dangerous bash patterns (for example rm -rf /, dd if=, mkfs, the fork bomb :(){ :|:& };:, curl | bash, crontab -r) are blocked or require confirmation in all modes.

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

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
Extension startup (session_start handler) deploys the agent files to the platform’s agent discovery directory
Subagent dispatch discovers the files and registers each as an agent type
Pi’s maestria_subagent(...) and OMP’s native task(agent: "adventurer", ...) look up the registered type, merge the role prompt over the inherited parent context, and spawn the subagent with the platform’s tools and instructions.

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 merges the specialist prompt on top of the inherited orchestrator prompt, so every subagent has both the dispatcher methodology and its role-specific guidance.

Tool isolation

Tool allowlists by role:

Agent	Tools	Purpose
adventurer	read, grep, find, ls, glob	Codebase reconnaissance; no write/edit tools
architect	read, bash, grep, find, ls	Architecture analysis; Bash is available for evidence gathering
builder	read, bash, grep, find, ls, write, edit	Implementation (full access)
diagnose	read, bash, grep, find, ls	Bug tracing; Bash is available for evidence gathering
planner	read, grep, find, ls	Planning; no write/edit tools
reviewer	read, grep, find, ls, glob	Code review; no write/edit tools
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, while the other roles have no write/edit tools. Architect and diagnose retain Bash for evidence gathering, so their role boundaries are not a universal no-execution sandbox.

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), so user-customized agents with the same name stay put. To reset to maestria defaults, remove the files from the discovery directory and restart your session.

Project Loading

.maestria/workflow.md then .maestria/rules.md load from the session working directory, read fresh on every agent turn and composed with the mode prompt. Missing or empty files are skipped; a present-but-unusable file surfaces via notification plus a STOP banner instead of executing the request. See Workflow Patterns for order, precedence, and carry-over.