pi-roles

Unified composable roles and dynamic skill scoping for Pi coding agent and subagents.

The Problem

1. Context Bloat: Loading 40+ skills into Pi injects thousands of tokens of XML descriptions into the system prompt on every turn. This wastes budget and degrades instruction following.
2. Harness Schizophrenia: Subagents get isolated roles and skill scoping, but the interactive main agent is stuck as an unspecialized generalist carrying every skill at once.
3. Monolithic Prompts: Teams write giant 600-line system prompts that try to do everything, instead of composing small, focused capabilities.

The Solution

Define once. Run as the main agent, or dispatch as a subagent.

                 ~/.pi/agent/agents/<name>.md
                             │
            ┌────────────────┴────────────────┐
            ▼                                 ▼
   Main Agent (/role)                Subagent (subagent tool)
   Embody the role interactively      Dispatch to run in background
   Scoped skills & system prompt      Isolated child session

Features

• Composition over Inheritance: Roles can compose other roles via roles: [role-a, role-b]. Skills, tools, and instructions are recursively resolved and deduplicated.
• Dynamic Skill Scoping: When a role is active, only its declared skills appear in <available_skills>. Shrinks prompt overhead by up to 80%.
• On-Demand Skill Loading: Model can call load_skill to pull in an unlisted skill temporarily when an unexpected subtask arises.
• Startup Ergonomics:
  • CLI flag: pi --role architect
  • Project default: "defaultRole": "architect" in .pi/settings.json
  • Interactive TUI: type /role to open a keyboard-navigable role selector
• Full Subagent Compatibility: Standard Agent Markdown format compatible with pi-subagents.

Role Definition Format

Save roles to ~/.pi/agent/agents/<name>.md (global) or .pi/agents/<name>.md (project):

---
name: tech-lead
description: Fullstack technical lead orchestrating architecture and code review
roles:
  - architect
  - code-reviewer
  - feishu-ops
skills:
  - git-worktree
tools: [read, bash, edit, write]
---

You are the technical lead.
Ensure architectural boundaries are respected and changes are verified with runtime evidence.

Composed Roles Resolution

When tech-lead activates:

1. It resolves architect, code-reviewer, and feishu-ops recursively.
2. Skills are merged: [architect, search-space-analysis, unslop, deslop, lark-doc, lark-task, lark-base, git-worktree].
3. Circular dependencies are caught and reported as errors.
4. Instructions are layered with structured XML wrappers.

Commands & Tools

• /role: Opens the interactive role selector in terminal.
• /role <name>: Switches directly to a named role.
• /role off: Disables role scoping, returning to default generalist mode.
• switch_role({ role }): Tool allowing the agent to switch its own active role.
• load_skill({ skill }): Tool allowing the agent to dynamically load an extra skill.
• list_roles({}): Tool to list all discovered roles and composition trees.

Builtin vs Custom Roles

pi-roles is a clean, dependency-free capability engine. It does not force-feed hardcoded agents into your environment. Users define their own roles in ~/.pi/agent/agents/<name>.md (global) or .pi/agents/<name>.md (project-local).

Example definitions are provided under examples/agents/:

• architect.md: Systems architect focused on domain modeling, module boundaries, and types.
• code-reviewer.md: Strict code review specialist for maintainability, simplicity, and evidence.
• feishu-ops.md: Lark/Feishu docs, bitable, and task workflows.
• researcher.md: Deep web and paper research with primary source verification.
• tech-lead.md: Composite role combining architect, code-reviewer, and feishu-ops.
• generalist.md: Clean mode with 0 skills overhead.
• all.md: Wildcard mode with skills: ["*"].

Development & Test

npm test

Runs tests using native Node.js:

• Frontmatter parser tests
• Recursive role composition & deduplication tests
• Circular dependency cycle detection tests
• Prompt options & dynamic skill scoping tests