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.

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

Parallel Mode

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

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

{
  "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:

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 (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

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
Extension startup (session_start handler) deploys the agent files to ~/.pi/agent/agents/ – pi-subagents’ designated agent discovery directory
Subagent dispatch (maestria_subagent tool) calls registry.reload() which discovers the files and registers each as an agent type
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:

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