pi-config/extensions/pi-crew/docs/resource-formats.md

pi-crew Resource Formats

Agent files

Location:

agents/{name}.md                                # builtin (in this package)
~/.pi/agent/agents/{name}.md                    # user-global
.crew/agents/{name}.md                          # project (new layout)
.pi/teams/agents/{name}.md                      # project (legacy layout when .pi/ exists)

Format:

---
name: executor
description: Implement planned code changes
model: claude-sonnet-4-5
fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
thinking: high
tools: read, grep, find, ls, bash, edit, write
extensions: /path/to/extension.ts
skills: safe-bash
systemPromptMode: replace
inheritProjectContext: true
inheritSkills: false
triggers: auth, tests
useWhen: multi-file implementation with tests
avoidWhen: one-line typo
cost: cheap
category: implementation
---

System prompt body.

Optional routing metadata fields:

Field	Meaning
triggers	Comma-separated terms that should route work to this agent/team
useWhen	Comma-separated natural-language use cases
avoidWhen	Comma-separated cases where the agent/team should not be used
cost	free, cheap, or expensive hint for autonomous routing
category	Free-form grouping such as frontend, security, docs

Team files

Location:

teams/{name}.team.md                            # builtin (in this package)
~/.pi/agent/teams/{name}.team.md                # user-global (shared with pi-mono)
.crew/teams/{name}.team.md                      # project (new layout)
.pi/teams/teams/{name}.team.md                  # project (legacy layout when .pi/ exists)

Format:

---
name: implementation
description: Full implementation team
defaultWorkflow: implementation
workspaceMode: single
maxConcurrency: 3
triggers: implementation, refactor
useWhen: multi-file implementation
cost: cheap
category: implementation
---

- explorer: agent=explorer map the codebase
- planner: agent=planner create plan
- executor: agent=executor implement
- verifier: agent=verifier verify

Role line:

- {role-name}: agent={agent-name} [model={provider/model}] [skills={a,b}|false] [maxConcurrency={n}] optional description

Workflow files

Location:

workflows/{name}.workflow.md                    # builtin (in this package)
~/.pi/agent/workflows/{name}.workflow.md        # user-global
.crew/workflows/{name}.workflow.md              # project (new layout)
.pi/teams/workflows/{name}.workflow.md          # project (legacy layout when .pi/ exists)

Format:

---
name: default
description: Explore, plan, execute, verify
---

## explore
role: explorer

Explore for: {goal}

## plan
role: planner
dependsOn: explore
output: plan.md

Create a plan for: {goal}

Step fields:

Field	Meaning
role	Team role to run
dependsOn	Comma-separated step IDs
parallelGroup	Optional grouping metadata
output	Output file name or false
reads	Comma-separated read files or false
model	Step model override
skills	Comma-separated skills or false
progress	true/false
worktree	true/false metadata
verify	true/false verification marker

Each step starts with ## step-id followed by recognized step metadata such as role: before the blank line. Level-2 headings inside task bodies are preserved unless they look like a step section with recognized metadata; use ### or lower for maximum compatibility.