# Agent definitions

[Documentation index](../README.md)

Agent definitions describe an agent's capabilities, not a required
workflow. They are Markdown files containing strict frontmatter plus an optional
prompt body.

This guide covers normal creation and selection. For the complete field contract,
see the [agent-definition schema](../reference/agent-definition-schema.md).

## Sources

Bundled definitions live in:

```text
dist/agents/
```

Global definitions live by default in:

```text
~/.pi/agent/agents/
```

Project definitions are optional and live in the current project:

```text
<cwd>/.pi/agents/
```

Pi Herdsman discovers project definitions when Pi considers the project
trusted. Precedence is:

```text
bundled < global < trusted project < private repository
```

For trusted Git worktrees, the optional private layer is stored under the Git
common directory shared by linked worktrees. Find it by running
`git rev-parse --path-format=absolute --git-common-dir` from the worktree, then
put Agent files in its `pi-herdsman/agents/` directory and Coordinator profiles
in `pi-herdsman/coordinators/`. Do not assume `<worktree>/.git` is a directory; linked
worktrees use a `.git` file. Private definitions belong to one clone and do
not reach independent clones. Referenced skills or scripts need accessible
paths of their own and are not synchronized by this feature.

Global definitions are reusable defaults, not immutable policy: a trusted
project can override `enabled`, `tools`, `agents`, and opaque `permission`
values. Herdsman-owned authority and required coordination tools remain
protected by runtime policy. For example:

```text
.pi/
└── agents/
    └── reviewer.md
```

Project definitions apply only to their project cwd; private definitions apply
to trusted worktrees in their local Git clone. The Definitions UI defaults to
the most specific existing editable source (private repository, project, then
global). When multiple sources exist, choose another existing scope with `Edit
scope`. Bundled-only definitions create global overrides; missing project and
private files are not created. Project edits may appear in Git changes.

When Pi uses a custom agent directory, the global definitions live under that
agent directory's `agents/` subdirectory.

Coordinator profiles use sibling directories: `dist/coordinators/` for bundled
profiles, `<cwd>/.pi/coordinators/` for trusted project overlays,
`<agentDir>/coordinators/` for global overlays, and
`<git-common-dir>/pi-herdsman/coordinators/` for private repository overlays.
`<agentDir>` is Pi's agent directory (normally `~/.pi/agent`). The same
precedence applies. Reserved Coordinator names are invalid in Agent directories,
and ordinary Agent names are invalid in Coordinator directories. Chief is
global-only; project and private repository Chief profiles are errors.

Coordinator discovery rejects active Markdown profiles left at the former
locations; it does not load them as fallback. Move customized profiles and
their relative prompt assets, preserving both file contents and the assets'
relative paths, as follows:

```text
<agentDir>/pi-herdsman/roles/
    -> <agentDir>/coordinators/

<project>/.pi/pi-herdsman/roles/
    -> <project>/.pi/coordinators/

<git-common-dir>/pi-herdsman/roles/
    -> <git-common-dir>/pi-herdsman/coordinators/
```

Update symlinks that manage these definitions so they point to the canonical
directories. Files left under an applicable legacy `roles/` path cause an
actionable Coordinator-discovery error; Agent discovery is independent. No
configuration files are automatically copied, moved, or deleted.

Recognizable definitions placed in the opposite namespace are excluded from
discovery with a warning that identifies the source and intended destination.
Other valid definitions in that category continue loading; the misplaced file
is not automatically loaded from its intended category. Malformed definitions
and the existing legacy-path errors remain strict and still fail discovery.

A project or global definition whose `name` matches a lower-precedence
definition overlays it. An unmatched definition is standalone.

Definition configuration and runtime Agent discovery are separate views. The
Definitions UI and Markdown files expose editable configuration and source
layers. The session-start `agent_definitions` capability summary and
`list_agents` result expose only definitions currently available to that
controller, not source paths or complete frontmatter. They support runtime
selection and validation, not configuration management. Identify definitions
by frontmatter `name`, inspect contributing files, and resolve effective
overlays when changing them; never infer identity from filenames.
`list_agents` validates Agent discovery, not the complete Coordinator
configuration.

`flexible-lead`, `orchestrator-lead`, `managed-lead`, `manager`, and `chief`
are reserved Coordinator definitions. They use the layered definition engine but are
not Agents available through discovery or delegation. The first two configure
ordinary Lead runtime instructions and ordinary tools; `managed-lead` configures
launch policy for Manager-assigned project Leads; `manager` and `chief`
customize supervisory role instructions and ordinary tools. They appear under
`Coordinators` in canonical order; ordinary definitions appear under `Agents`.
Runtime profiles offer Details only;
`managed-lead` offers Model, Thinking, and Details. See
[customizing Coordinator profiles](customizing-agents.md#manager-and-chief-profiles).

### Permission-aware extensions

Agent definitions may include a `permission:` mapping for compatible
permission-aware Pi extensions.

[`pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system)
can consume the same global or trusted project-local agent definition as Pi
Herdsman:

```yaml
---
name: reviewer
tools: ["read", "ls", "find", "grep"]
permission:
  "*": deny
  read: allow
  ls: allow
  find: allow
  grep: allow
---
```

Pi Herdsman accepts and preserves `permission:` but does not evaluate its
contents or make authorization decisions from it. Managed agents publish the
conventional `<active_agent name="<definition>"/>` identity signal and
subagent lineage metadata used by compatible extensions. Herdsman separately
projects current semantic identity and direct-owner context in its
`pi_herdsman_agent` prompt section; this is not an authorization signal.
Permission policy is effective only when the
compatible permission extension is loaded in that Pi session. The permission
extension is optional; Pi Herdsman does not install or depend on it.

## Enable or disable a definition

Definitions are enabled by default. Set `enabled: false` in a matching project
or global overlay to make a definition unavailable without copying the bundled
definition:

```markdown
---
name: reviewer
enabled: false
---
```

The `/agents definitions` UI keeps disabled rows and shows their disabled
status so the source can be re-enabled. Disabled definitions are omitted from
the runtime `agent_definitions` capability summary for Leads and delegating
agents. A definition that requires a disabled or otherwise unavailable child
is also omitted from that summary; a delegating agent referencing such a child
is rejected during assignment or fresh agent startup with an explicit reason
rather than silently dropping the reference.

`delegate` and `continue` reject disabled definitions with an
actionable error. An already active agent may finish and remains controllable
according to its current available actions; disabling a definition does not
mutate that assignment.

## Bundled roster

### `implementer`

Focused source-edit agent for an explicitly approved implementation.

### `researcher`

Focused current/external research agent. Read-only local policy. Its tool
allowlist includes `web_enable` and the default web tools exposed by
`pi-web-access`: `web_search`, `fetch_content`, `get_search_content`, and
`source_check`. The `web_enable` loader is necessary when the extension uses
dynamic tool activation; Pi and the extension determine when the other tools
become available.

Web access is optional. The Docker distribution includes it for fresh Pi
environments; native installation offers it as an explicit optional choice.
You can also install it through Pi:

```sh
pi install npm:pi-web-access
```

Without the extension, the researcher retains local inspection capabilities
and reports unavailable external evidence. Normal Pi extension discovery is
intentionally enabled for this role so an installed compatible extension can
provide the tools. If `pi-web-access` is configured with different public tool
names, replace the researcher's `tools` array through a matching project or
global overlay. Search providers may receive external requests, and extension
code runs in the Pi process with that process's permissions; the callable-tool
allowlist is not an operating-system sandbox.

### `reviewer`

Independent read-only internal team reviewer. Findings inform the delegator's
decisions, not user or supervisor approval.

### `validator`

Verification-only execution of focused tests, checks, and isolated smoke
scenarios for existing changes. It reports observed results without authoring
fixes or reviewing design. Like `implementer` and `generalist`, it offers both
Pi's `bash` and Windows-only `powershell` tools; shell execution is not a
read-only sandbox.

### `scout`

Fast read-only codebase reconnaissance.

### `generalist`

General-purpose scoped execution agent.

The bundled definitions are portable defaults, not required workflow stages.
Project definitions are for repository-specific policy; global definitions are
for user-specific final policy.

### Write useful descriptions

Write `description` for the delegator: state what the Agent can do, when to use
it, and a meaningful boundary where another capability fits better. Prefer
concrete tasks over generic role labels. Descriptions guide selection; they do
not grant tools or dictate workflows. Keep them accurate when overrides change
capabilities, and qualify optional integrations.

## Create a standalone definition

Create a Markdown file in the global agents directory:

```markdown
---
name: docs-reviewer
description: Read-only documentation reviewer for correctness, navigation, and examples; use to verify documentation changes before publication
model: openai-codex/gpt-5.6-luna
thinking: medium
systemPromptMode: replace
noSkills: true
noExtensions: true
tools: ["read", "ls", "find", "grep"]
---

Review documentation for correctness, navigation, duplication, and broken
examples. Do not edit files.
```

Read-only behavior must be enforced by the effective tool policy, not only by
prompt text. For normal filesystem inspection, explicitly allow `read`, `ls`,
`find`, and `grep`, and omit mutation-capable tools such as `bash`,
`powershell`, `edit`, and `write`. Disable extension discovery when the role
does not need extension-provided capabilities.

The `name` is authoritative; the filename itself is not the public definition
name.

## Compose specialist Agents

Different Agents can share procedures while retaining distinct responsibilities,
model choices, tools, and Pi extension behavior. When the same instructions are
always needed, preload them through body `@file` references instead of making
the Agent discover and read a skill. For example, assume the shared file
`.pi/skills/release-conventions/SKILL.md` exists in the project.

`.pi/agents/release-drafter.md`:

```markdown
---
name: release-drafter
description: Draft release notes from supplied change evidence; do not publish
tools: [read, ls, find, grep, write]
noSkills: true
noExtensions: true
---

Use these shared release conventions:

@../skills/release-conventions/SKILL.md

Write a draft from the supplied evidence. Flag unsupported claims.
```

`.pi/agents/release-auditor.md`:

```markdown
---
name: release-auditor
description: Check release notes against supplied inline evidence; do not edit
tools: []
noSkills: true
noExtensions: true
extensions: ["/absolute/path/to/release-audit.ts"]
---

Use these shared release conventions:

@../skills/release-conventions/SKILL.md

Check the notes against evidence provided in the assignment text.
Report unsupported claims and omissions without editing files.
```

Herdsman expands each whole-line `@file` reference into the Agent's system
prompt at launch. This reuses the file's text, not Pi's native skill-discovery
mechanism; `noSkills: true` disables automatic discovery. The content is
included up front, including any skill frontmatter, and nested file references
or scripts are not loaded automatically. For larger or optional procedures,
use native `skills` instead to permit on-demand loading.

The auditor has no ordinary callable tools, so its evidence must be available
in the assignment text. Its optional `release-audit.ts` path illustrates a
user-provided Pi extension that can specialize supported session hooks or
model behavior; omit it if unneeded, or replace it with an existing accessible
extension. `noExtensions: true` disables ordinary discovery, not explicitly
listed `extensions`. Loading extension code is independent of model-callable
`tools`; an empty tool allowlist is not an extension or process sandbox.
See the [agent-definition schema](../reference/agent-definition-schema.md) and
[Handoffs and files](handoffs.md) for the exact contracts.

## Allow direct agents

```markdown
---
name: coordinator
tools: ["read", "bash"]
agents: ["scout", "researcher"]
---

Coordinate the assigned analysis and integrate direct agent results.
```

The effective roster is validated atomically. Every `agents` name must exist.
Bundled role descriptions communicate each role's purpose and selection boundary;
the active controller contract remains authoritative for delegation behavior.

A non-empty `agents` list is required but does not alone enable delegation;
the effective tool policy also governs eligibility. Every managed agent retains
mandatory `await_owner` and `notify_owner`, and an Agent at the configured maximum nesting depth
is a leaf. See
[Delegation](../concepts/delegation.md) for the ownership model and the
[agent-definition schema](../reference/agent-definition-schema.md#managed-agent-coordination-tools)
for the exact tool-policy rules.

## Add body files

A body line that consists only of one supported reference includes that file:

```markdown
---
name: docs-reviewer
---

Use the following additional policy.

@./prompts/docs-policy.md
```

Supported forms:

```text
@./relative.md
@../relative.md
@/absolute/path.md
@~/home-relative.md
```

On Windows, the native backslash forms are also supported, including
`@.\relative.md`, `@..\relative.md`, `@~\home-relative.md`, rooted paths,
drive-rooted paths, and UNC paths. References use the host platform's native
path resolution rules.

References are resolved from the Markdown file that declares them.

Startup discovery and `list_agents` provide runtime Agent capabilities, not a
complete configuration view. For their exact contract, see the
[`list_agents` reference](../reference/agent.md#list_agents); use the workflow
below to inspect and manage definition configuration.

For configuration management, inspect bundled, trusted project, and global
Markdown layers in precedence order (`bundled < global < trusted project`), identify
the target by frontmatter `name`, resolve overlays, and edit the smallest
correct project or global file. Never edit bundled definitions. Use
`list_agents` after an edit when available to invoke normal discovery and
validation, but do not treat its reduced summary as the full effective
configuration or claim runtime validation when the tool is unavailable.

For exact expansion, deduplication, and caller-file precedence, see
[Handoffs and files](handoffs.md).

## Inspect effective definitions

A lead Pi session can use:

```text
/agents definitions
```

or the model can use:

```json
{}
```

Both use effective definition discovery, but the Definitions UI exposes
configuration (including disabled definitions and reserved Coordinator profiles where
applicable), while `list_agents` returns only currently available capabilities
within the caller's scope.

For model-assisted definition management, ask Pi directly or explicitly invoke
`/skill:agent-definitions`. The bundled skill uses the same
project/global Markdown definitions and existing Herdsman validation rather than
a separate configuration interface.

The human `Agents & Coordinators` menu separates ordinary definitions under
`Agents` from reserved profiles under `Coordinators` (in canonical order).
Runtime profiles provide Details only. Each row identifies its contributing
sources as `bundled`, `global`, `project`, and/or `private repo`. Model,
thinking, and enabled settings default to the most specific existing editable
source; `Edit scope` selects another existing source. `Remove local override`
removes only that source's field. Unset model and
thinking fields inherit the spawning controller for fresh delegation, while
continuation restores the saved session's settings. Contextual help updates for
the selected row.

For continuation, an omitted model uses the saved Pi session's selection, not
the current caller's model. The resumed Agent verifies that Pi restored the
saved model before it accepts work; ambiguous history, an unavailable model,
or a mismatch stops startup. Extension discovery stays enabled when the
selected model's provider is identified as extension-registered, whether
configured, inherited, or restored, even if the definition sets
`noExtensions: true`. An explicit definition model overrides saved history; Pi
resolves the unchanged selector. Enabling discovery may load other configured
extensions too. Restarted Manager-assigned managed Leads apply
the same check before inbox activation; a model explicitly set by the effective
`managed-lead` definition overrides the saved selection. See the
[execution-settings contract](../reference/agent-definition-schema.md#execution-settings)
for the exact behavior.

## Override an existing bundled role

Do not copy the complete bundled file just to change one property. Create a
matching partial global definition instead.

See [Customizing bundled agents](customizing-agents.md).

## See also

- [Agent-definition schema](../reference/agent-definition-schema.md)
- [`/agents` commands](../reference/commands.md)
- [Configuration](../reference/configuration.md)