agents.pool.yml schema

.relay/agents.pool.yml defines the pool of agents available for dynamic team selection. Every /relay:relay session picks a task-specific team from this pool.

Top-level structure

language: string # optional — default language for all agents
shared_blocks: # optional — reusable text blocks
  { block_name }: string
review_checklist: string # optional — default review checklist for all agents
agents:
  { agentId }:
    # agent configuration
    ...

Agent schema

agents:
  { agentId }:
    name: string # display name (e.g. "Frontend Engineer")
    emoji: string # emoji icon (e.g. "💻")
    description: string # short role description (shown during team selection)
    tags: [string] # optional — used for smart team suggestions
    disabled: boolean # exclude from pool when true (default: false)
    extends: string # agent ID to inherit from
    tools: # list of allowed MCP tools
      - tool_name
    systemPrompt: string # agent system prompt (multiline)
    language: string # optional — override global language for this agent
    hooks: # optional — lifecycle hooks (see below)
      before_task: string | [string]
      after_task: string | [string]
    # hooks: false         # opt out of inherited hooks (for extends-based agents)
    validate_prompt: string # optional — validation criteria injected before task completion
    review_checklist: string # optional — override global review checklist for this agent

Available tools

get_server_info
start_session
send_message
get_messages
create_task
update_task
claim_task
get_all_tasks
post_artifact
get_artifact
request_review
submit_review
read_memory
write_memory
append_memory
list_sessions
get_session_summary
save_session_summary
save_orchestrator_state
get_orchestrator_state
list_agents
list_pool_agents
broadcast_thinking

shared_blocks

Define reusable text blocks at the top level and reference them with {{block_name}} inside agent systemPrompt fields. This eliminates prompt duplication when multiple agents share common instructions.

Within a block, {agent_id} is automatically substituted with the actual agent ID at load time.

If a systemPrompt references an undefined block (e.g. {{nonexistent}}), the pool loader throws a load-time error.

shared_blocks:
  coding_standards: |
    - Follow the project style guide
    - Write tests for all new code
    - Agent {agent_id} must request review before marking done

agents:
  fe:
    systemPrompt: |
      You are a Frontend Engineer.
      {{coding_standards}}
  be:
    systemPrompt: |
      You are a Backend Engineer.
      {{coding_standards}}

review_checklist

Structured review criteria for peer reviews. Set a top-level review_checklist to apply default criteria to all agents. Individual agents can override it with their own review_checklist field.

Inheritance for extends-based agents follows a 3-tier priority: per-agent value > base agent’s value > global default. An extending agent that does not set review_checklist inherits from its base agent first, then falls back to global.

The review checklist follows a Fix-First framework: reviewers must verify each criterion before approving, and request fixes for any unmet item.

review_checklist: |
  - [ ] Code follows project conventions
  - [ ] Tests cover the new functionality
  - [ ] No security vulnerabilities introduced

agents:
  security:
    review_checklist: |
      - [ ] No hardcoded secrets
      - [ ] Input validation on all endpoints
      - [ ] OWASP Top 10 compliance

hooks field

Git-hook style shell commands that the MCP server runs automatically before or after task lifecycle events. Commands execute in the project root. Non-zero exit blocks the operation.

`before_task`

Runs before claim_task atomically claims a task. Non-zero exit returns claimed: false — the task stays in todo state (no phantom in_progress).

fe:
  hooks:
    before_task: "bun check:types"

`after_task`

Runs after update_task(status: "done") writes to the store. Non-zero exit reverts the task status back to in_review and returns success: false.

fe:
  hooks:
    after_task:
      - bunx eslint --fix .
      - bunx prettier --write .
      - bun tsc --noEmit

Env vars injected into hooks

Variable	Value
`RELAY_AGENT_ID`	ID of the agent running the hook
`RELAY_TASK_ID`	ID of the task being claimed / completed
`RELAY_SESSION_ID`	Current session ID

Timeouts

Hook	Default
`before_task`	30 s
`after_task`	120 s

On timeout: SIGTERM → 5 s → SIGKILL.

Opt out with `hooks: false`

An extends-based agent can explicitly opt out of all inherited hooks:

agents:
  fe:
    hooks:
      after_task: bun tsc --noEmit
    # ... rest of persona
  fe2:
    extends: fe
    name: "Frontend Engineer 2"
    hooks: false # fe2 inherits everything from fe except hooks

extends pattern

Use extends to create multiple instances of the same pool persona with different IDs. The session file written by /relay:relay uses this to spin up fe, fe2, fe3, etc.:

# .relay/session-agents-2026-03-14-001-a3f7.yml
agents:
  fe:
    extends: fe # inherits systemPrompt + tools from pool
    name: "Frontend Engineer 1"
  fe2:
    extends: fe
    name: "Frontend Engineer 2"

tags field

Tags are used by /relay:relay for smart team suggestions. Match tags to the task type so the skill can propose the right agents:

agents:
  be:
    tags: [backend, api, database, node, typescript]
  researcher:
    tags: [research, analysis, writing, synthesis]

Full example

language: English

shared_blocks:
  collaboration_rules: |
    - Always broadcast_thinking before starting work
    - Request review from a peer before marking tasks done
    - Agent {agent_id} must update memory at session end

agents:
  pm:
    name: "Product Manager"
    emoji: "📋"
    description: "Requirements analysis and task breakdown"
    tags: [management, planning, coordination]
    tools:
      - create_task
      - update_task
      - get_all_tasks
      - send_message
      - get_messages
    systemPrompt: |
      You are the Product Manager.
      Break down requirements into tasks and coordinate the team.
      {{collaboration_rules}}

  fe:
    name: "Frontend Engineer"
    emoji: "💻"
    description: "React/TypeScript UI implementation"
    tags: [frontend, react, typescript, ui]
    tools:
      - get_messages
      - claim_task
      - update_task
      - post_artifact
      - send_message
      - request_review
    systemPrompt: |
      You are a Frontend Engineer.
      Implement UI components and create PR artifacts for review.
      {{collaboration_rules}}

  security:
    name: "Security Engineer"
    emoji: "🔐"
    description: "Security vulnerability analysis"
    tags: [security, audit, owasp]
    tools:
      - get_messages
      - get_artifact
      - post_artifact
      - send_message
    systemPrompt: |
      You are a security expert.
      Review PRs against the OWASP Top 10.

File locations

Pool files are searched in priority order:

.relay/agents.pool.yml — project-level (takes priority, git-tracked)
agents.pool.yml — project root fallback

If neither file exists, relay throws:

No agent pool configured. Create .relay/agents.pool.yml (see agents.pool.example.yml) or run /relay:relay to auto-generate one.