Role author path

Define and customize agent roles

Roles package a reusable agent policy: model, thinking level, tools, skills, extensions, prompt instructions, and context-file scope. Use a role file for stable defaults, then use per-call AgentOptions to override model, thinking, capabilities, and context files.

Overview

A workflow agent selects a role by name. The role body always comes from the named file. Per-call AgentOptions override the role-file defaults.

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

const fastReview = await agent("Review this change", {
  role: "reviewer",
  model: "cheap-model",
  contextFiles: ["cwd"],
  tools: ["!*", "read", "grep"]
});

Per-call model, thinking, tools, skills, extensions, and contextFiles override role-file defaults. Built-in subagent tools discover these same role files and apply the same validation to standalone agent runs.

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. The bundled starter roles follow that rule; see Bundled starter for aliases, reviewLoop, and how to disable the factory.

---
description: Reviews code for correctness
model: anthropic/claude-fable-5:high
tools: ["!*", read, grep]
skills: ["!*", "review-*"]
extensions: ["!**/unsafe.mjs"]
---
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, resource selectors, 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`.
`tools`, `skills`, `extensions`	Ordered Minimatch selectors. Positive patterns enable discovered candidates, `!pattern` disables them, later layers override earlier layers, and `!*` clears the current selection before narrower additions.
`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.

Relative extension selectors in role frontmatter resolve from the role file's directory; call-level selectors resolve from the agent launch cwd. See the settings reference for ~, file://, glob, and canonicalization rules.

Customize calls

role is a name string. Per-call model, tools, skills, extensions, and contextFiles override the role file. Concrete models are provider/model:thinking. overrideSystemPrompt stays on the role file.

await agent("Inspect the API", {
  role: "reviewer",
  contextFiles: ["cwd"],
  model: "cheap-model:low",
  tools: ["!*", "read", "grep"]
});

Use tools: ["*"] to re-enable all tools after a role restriction.

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]
skills: ["!*", "review-*"]
extensions: ["!*", "**/review-tools/**"]
tools: ["!*", read]
---

Selectors affect only agents using the role and compose after global and trusted-project selectors. Use piewf doctor --role <name> to inspect selector sources and effective skills, extensions, and tools without contacting a provider.

Inspect a role

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

The role inspection is read-only. The positional form piewf doctor reviewer is equivalent to --role reviewer. Both resolve the active role and report its effective resources and prepared prompt. The optional probe prompt is useful when prompt hooks depend on the agent request. Add --json to emit the structured report for machine consumers; either role form includes roleTarget and includes roleInspection when inspection succeeds.

Role discovery is fail-closed: invalid frontmatter or the rejected legacy selector in any packaged or global role file, or in any trusted-project role file, blocks the complete role set. See the doctor reference for diagnostics and exit behavior. At runtime, a missing named role fails with UNKNOWN_AGENT_TYPE and Unknown agent role: <name>.

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

< Back to documentation home