# Getting started

[Documentation index](README.md)

This page covers the shortest supported path from prerequisites to a completed
managed-worker assignment.

## 1. Check requirements

You need:

- Herdr `>=0.8.0`;
- Pi `>=0.84.2 <0.85.0` (the version range tested for this release);
- Herdr Pi integration version `2` or newer;
- Node `>=22.19.0`.

Install or refresh the Herdr Pi integration:

```sh
herdr integration install pi
herdr integration status
```

Install the package from npm:

```sh
pi install npm:pi-herd
```

Pi reads the package manifest and loads the extension plus the optional
`subagents` skill.

## 2. Start the supervisor inside Herdr

The root Pi session must run inside Herdr. A supervisor started outside Herdr
cannot safely manage Herdr workers.

The extension distinguishes three environments:

- a root supervisor running inside Herdr;
- a valid managed worker;
- an unmanaged or invalid environment.

Only the first two receive their appropriate managed-worker behavior.

## 3. Inspect the roster

The first safe operation is:

```json
{ "action": "list" }
```

The result contains:

- `agent_definitions`: definitions available to the current controller;
- `workers`: exact managed workers visible to that controller.

A root can see the complete effective roster. A managed parent sees only its
allowed direct-child definitions.

The default bundled roster is:

- `implementer`
- `researcher`
- `reviewer`
- `scout`
- `worker`

See [Agent definitions](guides/agent-definitions.md) for role selection.

## 4. Assign a fresh worker

```json
{
  "action": "assign",
  "agent": "implementer",
  "task": "Implement the approved change"
}
```

A fresh assignment creates a managed worker, starts a Pi session, durably
submits one task, and returns immediately after acceptance.

Do not poll for completion. Continue only with useful work that does not depend
on this worker, or end the turn. Completion is delivered back to the owning Pi
session.

## 5. Use the result

A completion includes the worker result and may include a private `resultPath`.

For dependent work, prefer passing that path:

```json
{
  "action": "assign",
  "agent": "reviewer",
  "task": "Review the implementation result and relevant source.",
  "files": ["/exact/result/path"]
}
```

`files` supplies evidence; strict UTF-8 text is embedded at submission time and
other files remain canonical local references (not copied or snapshotted).
Canonical duplicate
paths are included once.

See [Handoffs and files](guides/handoffs.md).

## 6. Reuse a worker when appropriate

Create a reusable worker:

```json
{
  "action": "assign",
  "agent": "worker",
  "task": "Perform phase one",
  "reusable": true
}
```

After completion and result delivery, `list` reports it as `ready`.

Then reuse the exact label:

```json
{
  "action": "assign",
  "label": "worker",
  "task": "Perform phase two"
}
```

A live worker's reusable policy cannot be changed by a later assignment.

## 7. Handle a worker question

A managed worker may call `ask_owner` when it cannot continue correctly without
an owner decision. The worker becomes `blocked`.

Answer with the exact listed label:

```json
{
  "action": "reply",
  "label": "worker",
  "message": "Use option B."
}
```

The same assignment and Pi session resume.

See [`ask_owner` API](reference/ask-owner.md).

## Next steps

- Understand [worker identity](concepts/workers.md).
- Learn [worker lifecycle](concepts/lifecycle.md).
- Configure [agent definitions](guides/agent-definitions.md).
- Customize bundled roles with [global overrides](guides/customizing-agents.md).
- Use the exact [`subagent` API](reference/subagent.md).