Agent teams

A team is a folder tree. The tree is the org chart: every folder that contains an agent.md is an agent, and its subfolders are its direct reports.

my-team/
  package.json          # depends on @runravel/ravel
  ravel.json             # optional manifest: name, description, runtimeVersion
  agent.md                # the team lead — the root agent
  tools.json              # the lead's tool grants (optional)
  plugin.ts               # optional team plugin, inherited by every agent below
  growth/
    agent.md              # a subordinate agent
    tools.json
    copywriter/
      agent.md             # copywriter reports to growth
      tools.json
  processes/
    prospect-outreach.process.md
  .gitignore              # must ignore .env, .ravel/, node_modules/

Agents (agent.md)

Each agent is defined by an agent.md: YAML frontmatter plus a markdown system prompt. The frontmatter fields:

Field	Values
name	Display name
role	A short role label
model	opus | sonnet | haiku
autonomy	orchestrated | bounded
budget	{ usd, turns } — a ceiling for this agent

The markdown body is the agent’s system prompt.

Tools & policies (tools.json)

An agent’s tools.json grants it tools and sets the trust policy for each:

{
  "defaultPolicy": "ask",
  "tools": [
    {
      "name": "send_email",
      "policy": "ask",
      "description": "Send an outbound email. Consequential and irreversible — always requires human approval."
    }
  ],
  "mcpServers": {}
}

policy is one of auto (runs immediately), ask (queues a proposal for a human to approve), or deny. See Tools & policies for the full field reference.

Processes (processes/*.process.md)

A process is a playbook — a unit of work an agent orchestrates toward a definitionOfDone, under a budget, triggered manually, on a schedule, or (in future) by an event. See Processes and Processes & scheduling.

Plugins (plugin.ts)

A team-root plugin.ts can define code tools and the executor actions that back them. Every agent in the tree inherits it — though each agent’s own tools.json still gates who can actually call what. See Plugins.

Next

• Runtime vs. platform
• Agents — the full agent.md reference