AGENTS.md

Type: Agent operating manual (workspace configuration file)

Definition

AGENTS.md is the operating manual that defines how the agent behaves as an orchestrator — its routing rules, named agent configurations, quality gates, and escalation protocol. It's read at every session start alongside SOUL.md and MEMORY.md, making it the definitive source of truth for how work gets routed and validated. Unlike openclaw.json (which controls runtime behavior and requires a Gateway restart), AGENTS.md is hot-reloaded at each session start with no restart needed.

How It Works

AGENTS.md defines several key sections. First, router role — the agent's job is to route, not execute. It receives tasks, determines which lead handles them, spawns sub-agents, validates output, and escalates failures. Second, named agent configurations — each lead (research-lead, project-lead, test-lead) has a name, domain, triggers, capabilities, and output directory. Third, routing rules — which agent type handles which task type. Fourth, quality gate criteria — explicit checks before any task is marked complete. Fifth, RALPH escalation protocol — the rules for when and how to escalate failures.

The file is written once as part of initial workspace setup and updated when the operating model changes. It drives behavior without being stored in conversation history — the agent reads it fresh at each session start, so updates take effect immediately.

A minimal quality gate before marking any task complete checks: output file exists, file is non-empty, content addresses the original request. More thorough gates might include linting, testing, or review pass requirements depending on the task type.

AGENTS.md is complemented by SOUL.md (identity) and MEMORY.md (cross-session facts). Together, SOUL + AGENTS + MEMORY form the core agent configuration layer that determines how OpenClaw behaves.

Key Properties

  • Hot-reload at session start — changes take effect immediately; no Gateway restart needed
  • Five key sections — router role, named agents, routing rules, quality gates, RALPH protocol
  • Source of routing truth — which task goes to which agent is defined here
  • Quality gate definition — explicit criteria for marking tasks complete
  • Workspace file — lives alongside SOUL.md, MEMORY.md, USER.md in the workspace root
  • Drives behavior without history — read fresh each session, not stored in conversation context
  • kelly-router — the Router reads AGENTS.md to understand its role and routing rules
  • quality-gates — quality gate criteria are defined in AGENTS.md
  • ralph-protocol — RALPH escalation protocol is defined in AGENTS.md
  • workspace-boot — AGENTS.md is one of five canonical workspace files read at session start

Source Chapters