Agents and Model Roles

Every phase in a taskflow runs as a subagent — an isolated LLM process with its own context window, system prompt, and tool set. That isolation is what keeps intermediate transcripts out of your conversation: only the final phase output comes back.

But which agent runs which phase? And which model does that agent use? taskflow answers both questions with a layered discovery system and a role-based model mapping. You can use the 18 built-in agents as-is, override them with project-specific versions, or write entirely custom agents — all without changing a single flow definition.

This guide covers the full picture: how agents are discovered, what the built-in agents do, how model roles work, and how to customize everything.

Agent discovery

taskflow loads agents from three layers, in order:

The layers override each other by name. If you have a project agent called executor and a built-in agent also called executor, the project version wins. This lets you customize behavior without forking the entire agent set.

The agentScope field

Not every flow needs all three layers. The agentScope field on a taskflow controls which layers are active:

Set agentScope at the top level of your taskflow:

{
  "name": "project-review",
  "agentScope": "project",
  "phases": [...]
}

The 18 built-in agents

taskflow ships with 18 agents organized into four categories. Each agent is defined as a markdown file with YAML frontmatter specifying its name, description, tools, model role, and thinking level.

Planning and analysis

These agents analyze requirements, create plans, and challenge assumptions before code is written.

The analyst runs first in complex pipelines to clarify requirements. The planner turns those requirements into actionable plans. The critic and plan-arbiter act as quality gates — they push back on weak plans before expensive execution begins.

Execution

These agents write code. They differ in scope and complexity.

The default executor handles most work. Use executor-fast for mechanical cleanups, executor-code for structural refactors, and executor-ui when you need vision capabilities to understand design intent.

Review and quality

These agents review code, assess risk, and verify outcomes. None of them edit files.

The reviewer handles general quality. The risk-reviewer and security-reviewer specialize in high-stakes domains and defer to each other at domain boundaries. The final-arbiter breaks ties when reviews conflict.

Support

These agents handle auxiliary tasks: testing, documentation, exploration, and recovery.

The scout does quick recon so other agents don't have to re-read everything. The test-engineer and verifier handle validation. The visual-explorer parses design files. The recover agent picks up work after a context window reset.

Model roles

Each built-in agent specifies a model role in its frontmatter — not a concrete model ID, but a role name wrapped in double braces: {{fast}}, {{strong}}, {{thinker}}, {{arbiter}}, {{vision}}, or {{reasoner}}.

This indirection exists because different users have different models available. A role is a semantic contract ("this agent needs fast, cheap inference") that gets resolved to a concrete model based on your configuration.

The six roles

The defaults work well out of the box. But you might want to swap them — for example, if you have a Claude Pro subscription and want to use anthropic/claude-3.5-sonnet for {{strong}} instead of the default.

How roles are resolved

When a phase spawns a subagent, the runtime checks the agent's model field. If it matches the pattern {{roleName}}, the runtime looks up that role in your settings and substitutes the concrete model ID. If no mapping exists, the model field is left empty and the host's default model is used.

Agent frontmatter:  model: "{{strong}}"
                       ↓
settings.json:      modelRoles: { "strong": "anthropic/claude-3.5-sonnet" }
                       ↓
Subagent spawns with: model: "anthropic/claude-3.5-sonnet"

An agent with a literal model ID (no braces) bypasses role resolution entirely. This is useful for custom agents that must always use a specific model.

Configuring with /tf init

The /tf init command walks you through role configuration interactively. It reads your current settings, shows you the available models from your provider's registry, and writes your choices back atomically.

The action menu

When you run /tf init, you see an action menu:

1. Use recommended defaults — Apply the default models from the table above.
2. Configure each role — Walk through all six roles one by one.
3. Edit one role — Change a single role without touching the others.
4. Configure taskflow preferences — Adjust built-in agent settings.
5. Show current roles — Display your current configuration without changes.

For each role, the picker shows available models from your registry with capability tags (image ✓ for multimodal, reasoning ✓ for reasoning-capable models), plus markers for your current choice and the recommended default.

Custom model identifiers

You can also type a custom model identifier in provider/model-id format. The runtime validates it against your model registry and warns you if the model doesn't exist — a typo here would silently break every flow that uses the role.

Where settings are stored

All configuration is saved to ~/.pi/agent/settings.json (or the path set by TASKFLOW_AGENT_DIR / PI_CODING_AGENT_DIR):

{
  "modelRoles": {
    "fast": "openrouter/deepseek/deepseek-v4-flash",
    "strong": "openrouter/xiaomi/mimo-v2.5-pro",
    "thinker": "openrouter/deepseek/deepseek-v4-pro",
    "arbiter": "openrouter/qwen/qwen3.7-max",
    "vision": "minimax/MiniMax-M3",
    "reasoner": "z-ai/glm-5.1"
  },
  "taskflow": {
    "builtInAgents": true,
    "syncBuiltinAgentsToProject": false,
    "maxKeptRuns": 100,
    "maxRunAgeDays": 30
  }
}

Taskflow preferences

The "Configure taskflow preferences" option in /tf init adjusts four settings:

Custom agents

You can create custom agents by writing markdown files with YAML frontmatter. Custom agents live in user scope (~/.pi/agent/agents/) or project scope (.pi/agents/).

Agent file format

Every agent file has three parts: YAML frontmatter between --- delimiters, a blank line, and the system prompt body.

---
name: code-reviewer
description: Review code for quality and best practices
tools: read, grep, find, ls, bash
model: "{{strong}}"
thinking: high
---

You are a code reviewer focused on quality and best practices.

Review the provided code for:
- Code style and consistency
- Performance implications
- Error handling
- Test coverage

Be specific and actionable. Don't just say "this could be better" — explain why and how.

Frontmatter fields

Overriding built-in agents

To override a built-in agent, create a custom agent with the same name in your user or project agents directory. The layer order determines which version wins:

---
name: executor
description: Custom executor with project-specific conventions
tools: read, grep, find, ls, bash, edit, write
model: "{{strong}}"
thinking: high
---

You are the executor agent for the Acme Corp codebase.

Always follow these project-specific rules:
- Use TypeScript strict mode
- Prefer functional patterns over classes
- Write tests for all public functions
- Run `pnpm typecheck` before committing

This project-level executor replaces the built-in executor for any flow run in this project. A user-level override in ~/.pi/agent/agents/executor.md would apply across all your projects.

Agent resolution in flows

When a phase runs, the runtime resolves its agent through a specific process:

Specifying agents in phases

Most phases specify an agent explicitly:

{
  "id": "review",
  "type": "agent",
  "agent": "reviewer",
  "task": "Review the code changes for quality issues."
}

You can omit the agent field. The phase will use the default agent:

{
  "id": "review",
  "type": "agent",
  "task": "Review the code changes for quality issues."
}

Phase-level overrides

Phases can override an agent's model, thinking level, and tool access without modifying the agent file:

{
  "id": "deep-review",
  "type": "agent",
  "agent": "reviewer",
  "model": "anthropic/claude-3.5-sonnet",
  "thinking": "xhigh",
  "tools": ["read", "grep"],
  "task": "Deep review of the authentication module."
}

These overrides apply only to this phase invocation. The agent's frontmatter settings are still used for other phases that don't override them.

Branches and sub-phases

Phase types with multiple branches (parallel, tournament) let each branch specify its own agent:

{
  "id": "review-all",
  "type": "parallel",
  "branches": [
    {
      "agent": "security-reviewer",
      "task": "Review for security vulnerabilities."
    },
    {
      "agent": "risk-reviewer",
      "task": "Review for data integrity risks."
    },
    {
      "agent": "reviewer",
      "task": "Review for general code quality."
    }
  ]
}

Branches that don't specify an agent inherit the parent phase's agent. Tournament phases also support a judgeAgent field for the judge step, which defaults to the phase's main agent.

Inheritance in sub-flows

When a flow phase spawns an inline sub-flow, inner phases that don't specify their own agent inherit the parent phase's defaultAgent (or agent field). This means a single agent assignment at the parent level cascades to every child phase that doesn't override it.

Practical examples

Multi-stage review pipeline

Different agents handle different review concerns, and a final arbiter synthesizes the results:

{
  "name": "review-pipeline",
  "phases": [
    {
      "id": "plan",
      "type": "agent",
      "agent": "planner",
      "task": "Analyze the code changes and create a review plan."
    },
    {
      "id": "security-review",
      "type": "agent",
      "agent": "security-reviewer",
      "dependsOn": ["plan"],
      "task": "Review for security issues based on this plan: {steps.plan.output}"
    },
    {
      "id": "quality-review",
      "type": "agent",
      "agent": "reviewer",
      "dependsOn": ["plan"],
      "task": "Review for code quality: {steps.plan.output}"
    },
    {
      "id": "synthesis",
      "type": "agent",
      "agent": "final-arbiter",
      "dependsOn": ["security-review", "quality-review"],
      "task": "Synthesize these reviews and resolve any conflicts:\n\nSecurity: {steps.security-review.output}\n\nQuality: {steps.quality-review.output}",
      "final": true
    }
  ]
}

Custom domain agent

Create a specialized agent for your domain, then reference it in flows:

---
name: api-designer
description: Design RESTful APIs following OpenAPI 3.0 spec
tools: read, grep, find, ls, write
model: "{{strong}}"
thinking: high
---

You are an API designer specializing in RESTful APIs.

Follow these principles:
- Use nouns for resource names, verbs for actions
- Return appropriate HTTP status codes
- Include pagination for list endpoints
- Version APIs in the URL path (e.g., /v1/users)
- Write OpenAPI 3.0 specs in YAML format

{
  "id": "design-api",
  "type": "agent",
  "agent": "api-designer",
  "output": "text",
  "task": "Design a REST API for a task management system with projects, tasks, and users."
}

Project-scoped team workflow

Use agentScope: "project" so every team member gets the same agent behavior:

{
  "name": "team-review",
  "agentScope": "project",
  "phases": [
    {
      "id": "review",
      "type": "agent",
      "agent": "team-reviewer",
      "task": "Review the code using team standards documented in .pi/agents/team-reviewer.md."
    }
  ]
}

With a project agent in .pi/agents/team-reviewer.md that encodes your team's specific review criteria. This flow runs the same way for everyone on the team, regardless of their personal agent directory.

Next

Last updated on