# Installation & Setup

`@maestria/pi` is a Pi extension that turns the [Pi coding agent](https://pi.ai) into a disciplined engineering workstation. It registers 7 specialist subagents, 3 workflow mode commands, and spec-driven orchestration - all with a single extension entry.

## Prerequisites

- [Pi](https://pi.ai) CLI - the Pi coding agent (latest version)
- **Node.js 22.12+** - Required for npm-based extension resolution
- [@gotgenes/pi-subagents](https://github.com/gotgenes/pi-packages) Pi extension - Required for subagent dispatch. Install with `pi install npm:@gotgenes/pi-subagents`

## Installation via maestria CLI (Recommended)

The [maestria CLI](/cli/) provides a unified interface for installing and managing
maestria plugins across all supported platforms:

```bash
# Install for this platform
pnpx maestria@latest install pi

# Verify installation
pnpx maestria@latest status
```

The CLI automatically installs the `@gotgenes/pi-subagents` peer dependency (required for subagent dispatch) alongside the main extension.

<details>
<summary>Alternative: manual Pi CLI setup</summary>

If you prefer not to use the maestria CLI:

1. **Install the peer dependency:**

   ```bash
   pi install npm:@gotgenes/pi-subagents
   ```

2. **Install the extension:**

   ```bash
   pi install npm:@maestria/pi
   ```

3. **Restart Pi** for both extensions to load.

</details>

## Verify Installation

Start a new Pi session. The `@maestria/pi` extension loads automatically from the package manifest. Pi's resource loader discovers its four methodology skills (orchestrator dispatcher, global agent rules, handoff contract, iteration limits) from the `pi.skills` manifest field and injects them into the system prompt as `<skill>` blocks -- the same standard mechanism used by all major Pi extensions.

You should notice Pi behaving as a maestria dispatcher from the first turn: it responds to requests by decomposing tasks, delegating to specialist subagents, and following the spec-driven orchestration protocol -- all guided by the auto-injected orchestrator skill.

You can also list installed extensions to verify:

```bash
pi extensions list
```

You should see `@maestria/pi` in the output.

## Updating

To update via the maestria CLI:

```bash
pnpx maestria@latest update pi
```

<details>
<summary>Alternative: Manual update</summary>

To update `@maestria/pi` to the latest version:

```bash
pi install npm:@maestria/pi@latest
```
**Tip:** To pin a specific version, use `pi install npm:@maestria/pi@0.1.0`. Check the
  [changelog](/pi/changelog/) for version history.

</details>

## Uninstalling

### Via maestria CLI

```bash
pnpx maestria@latest uninstall pi
```

This removes `@maestria/pi`. The `@gotgenes/pi-subagents` peer dependency is left
in place because other Pi extensions may depend on it.

### Manual removal

1. Remove from Pi config: edit `~/.config/pi/pi.json` and remove `"@maestria/pi"` from the `"extensions"` array
2. Uninstall:
   ```bash
   pi uninstall @maestria/pi
   ```
3. Optionally, remove `@gotgenes/pi-subagents` if no other extensions need it:
   ```bash
   pi uninstall @gotgenes/pi-subagents
   ```
4. Restart Pi

## Next Steps

- [Quick Start](/pi/getting-started/quick-start/) - Your first session with the extension
- [Pi Reference](/pi/reference/) - Commands, dispatch modes, and review mode
- Explore the [workflow modes](/pi/getting-started/quick-start/) - `/fein`, `/sonar`, `/blitz`