Role author path

Define and customize agent roles

Roles package a reusable agent policy: model, thinking level, tools, prompt instructions, context-file scope, and resource exclusions. Use a role file for the stable defaults, then use a role object when one call needs a deliberate exception.

Overview

A workflow agent can use a role name or a role object. A string applies the role file unchanged. An object must contain name and can override role frontmatter for that call. The role name and role body always come from the named file.

const plan = await agent("Plan the implementation", {
  role: "planner"
});

const fastReview = await agent("Review this change", {
  role: { name: "reviewer", model: "cheap-model", tools: [] }
});

Top-level model, thinking, and tools cannot be combined with either role form. Put per-call changes inside the role object.

Role files

Global roles live under <agentDir>/pi-extensible-workflows/roles/<name>.md, normally ~/.pi/agent/pi-extensible-workflows/roles/<name>.md. Set PI_CODING_AGENT_DIR to change the agent directory.

Trusted project roles live under <cwd>/.pi/pi-extensible-workflows/roles/<name>.md. A trusted extension can provide packaged defaults with roleDirectories, using an absolute path or a file: URL. Global and trusted project roles override extension roles with the same name; duplicate names across extension directories are rejected.

---
description: Reviews code for correctness
model: anthropic/claude-fable-5
thinking: high
tools: [read, grep]
---
Focus on correctness and regressions.

The body is prompt guidance. It is appended to the native Pi system prompt unless overrideSystemPrompt: true is set. Role files are trusted configuration and can affect model, tools, resources, and the system prompt.

Frontmatter fields

Field	Purpose
`description`	Role description shown in role discovery and Pi guidance.
`model`	Configured alias or concrete `provider/model[:thinking]`.
`thinking`	Default thinking level for the role.
`tools`	Allow-list of Pi tools available to the role.
`overrideSystemPrompt`	When true, use the role body instead of appending it to the native system prompt.
`contextFiles`	Choose which Pi context-file scopes reach the role: `global`, `cwd`, and `project`.
`disabledAgentResources`	Role-specific `skills` and `extensions` exclusions.

Customize calls

Role-object keys use three-way merge semantics:

Omit a key to inherit the role-file value.
Use null to unset an inherited value.
Use an explicit value to replace it, including [] and false.

await agent("Inspect the API", {
  role: {
    name: "reviewer",
    model: "cheap-model",
    thinking: null,
    tools: []
  }
});

Per-call overrides can set model, thinking, tools, description, overrideSystemPrompt, contextFiles, and disabledAgentResources. They never change the role name or body. Other agent options such as label, outputSchema, retries, timeoutMs, and withWorktree remain top-level call options.

Context and resources

contextFiles controls Pi context discovery for that role. global selects the Pi agent-directory file, cwd selects the exact working-directory file, and project selects discovered project and ancestor files excluding those two. Omit the field for normal discovery or use [] to load none. Scopes can be combined.

---
contextFiles: [global, project]
disabledAgentResources:
  skills: [interactive-skill]
---

Resource exclusions affect only agents using the role. They merge with global and trusted-project policy. Use piewf doctor --role <name> to inspect the effective model, tools, skills, extensions, exclusions, setup hooks, and prepared system prompt without contacting a provider.

Inspect a role

npx piewf doctor --role reviewer
npx piewf doctor --role reviewer --prompt "Review the current change"

The role inspection is read-only. It resolves the active role and reports its effective resources and prepared prompt. The optional probe prompt is useful when prompt hooks depend on the agent request.

See workflow tool usage, settings for model aliases and global exclusions, and extension resources for packaged role directories.

< Back to documentation home