# 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.

```json
{
  "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.

```text
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):

```yaml
---
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](/core/agents/)
- [Pipeline & Roles](/core/pipeline/)
- [Workflow Patterns](/core/workflow-patterns/)
- [Installation & Setup](/pi-omp/getting-started/installation/)