# Pi Reference

## Spec-Driven Delegation

The orchestrator gives each specialist a **spec** - a structured handoff containing six 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            |
| **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 `maestria_subagent` call 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.

## Commands

| Command              | Description                                                                   |
| -------------------- | ----------------------------------------------------------------------------- |
| `/orchestrate`       | Start a full pipeline by delegating to the orchestrator with a goal           |
| `/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                          |

## Subagent Dispatch

Specialists are dispatched via `maestria_subagent`. The tool supports three dispatch modes:

### Single Mode

Dispatch one task to one specialist. The orchestrator waits for completion before proceeding.

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

### Parallel Mode

Dispatch multiple specialists concurrently. Useful for independent research or parallel implementation.

```json
{
  "mode": "parallel",
  "tasks": [
    { "agent": "adventurer", "task": "Find all API route definitions" },
    { "agent": "architect", "task": "Evaluate database migration options" }
  ]
}
```

### Chain Mode

Dispatch specialists sequentially, piping each result to the next. Use `{previous}` to reference the prior step's output.

```json
{
  "mode": "chain",
  "tasks": [
    { "agent": "adventurer", "task": "Find the current login implementation" },
    { "agent": "builder", "task": "Refactor login using findings from: {previous}" }
  ]
}
```

Maximum parallel tasks: 8.

## Review Mode

The `/review` command switches Pi 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.** The default 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 six 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.

## Specialist Agent Registration

The 7 specialist agents (adventurer, architect, builder, diagnose, planner, reviewer, writer) are registered with pi-subagents via the **file-based agent type system** -- the standard mechanism used by all pi-subagents extensions.

### How it works

1. **Sync pipeline** generates `agents/*.md` files from canonical maestria directives with pi-subagents 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 `~/.pi/agent/agents/` -- pi-subagents' designated agent discovery directory
3. **Subagent dispatch** (`maestria_subagent` tool) calls `registry.reload()` which discovers the files and registers each as an agent type
4. **`service.spawn("adventurer", task)`** looks up the registered type, merges the role-specific prompt on top of the inherited parent context via `prompt_mode: append`, and spawns the subagent with correct tools and instructions

### Agent file format

Each specialist agent file uses pi-subagents' standard YAML frontmatter format:

```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 `~/.pi/agent/agents/`, respecting any user-customized agents with the same name. To reset to maestria defaults, remove the files from `~/.pi/agent/agents/` and restart Pi.

## See Also

- [Specialist Reference](/core/agents/)
- [Pipeline & Roles](/core/pipeline/)
- [Workflow Patterns](/core/workflow-patterns/)
- [Installation & Setup](/pi/getting-started/installation/)