docs / agents & orchestration

Agents & orchestration

One agent is the default. A fleet is something you ask for: a ledger of steps, disjoint file ownership, isolated worktrees, and a check before any patch lands.

Custom agents

A custom agent is a specialist you define once: its own system prompt, tool allowlist, permissions, MCP servers, skills and optional model. Select any number per session and the planner treats them as first-class workers.

wombat agent new math-research
wombat agent list
wombat run --agents math-research,design "research MCTS and design a deck"

Definitions live in ~/.wombat/agents/<name>.json (or markdown with flat frontmatter), or in .wombat/agents/ inside a project, where the project wins. They can also be declared inline under agents in config.json.

{
  "name": "math-research",
  "description": "Verifies mathematical claims and writes clear proofs",
  "prompt": "You are a rigorous mathematician. Justify each step and cite sources.",
  "provider": "",
  "model": "",
  "tools": ["read", "grep", "websearch", "webfetch"],
  "exclude_tools": [],
  "mcp_servers": [],
  "permissions": { "write": "deny" },
  "skills": ["careful-proofs"],
  "max_steps": 0,
  "readonly": true
}

field	meaning
`description`	When the planner and the picker should reach for this agent.
`prompt`, `prompt_file`	The agent's system prompt, inline or from a file.
`provider`, `model`	Run this agent on a different model than the lead.
`tools`	Allowlist of names, globs (`web*`), classes (`class:read`) or `mcp:<server>`. Empty means every worker-eligible tool.
`exclude_tools`	Remove tools that would otherwise be included.
`mcp_servers`	Restrict the agent to the named MCP servers.
`permissions`	`allow` or `deny` for bash, write, edit, network, dangerous, sensitive-read, outside, mcp and mcp:<server>. Custom agents never prompt, so `ask` is rejected.
`skills`	Skill names whose instructions are appended to the prompt.
`max_steps`	Per-run step budget; 0 uses the session default.
`readonly`	Blocks writes, edits and mutating commands.

In the TUI, /agents opens a multi-select picker with a Create a new agent… row. The builder has sections for the prompt, tools, MCP servers, permissions, skills and options, and writes the definition file for you. Space toggles an agent, a selects all or none, enter applies. Selections are saved on the session and come back with wombat resume. Chat mode forces every selected agent read-only, and max_parallel_agents (default 5) caps how many run at once.

The plan

The lead keeps a task ledger: goal, durable facts, and ordered steps with explicit dependencies. Each step names its kind (scout for read-only research, write for owned files), the files it may change, and optionally a custom agent.

update_plan     goal, facts, steps, checks
run_plan        execute the ledger as a dependency graph
run_plan        background=true returns immediately; cancel=true stops it
delegate        one worker, one self-contained brief
delegate_many   2-6 workers in one wave; id + depends_on build a DAG
delegate_write  writer with explicit file ownership
resume_worker   answer a worker that reported needs_input

Scheduling is continuous, not round-based. A slow step does not hold back an independent one, free slots start newly-ready work, long dependency chains are scheduled first, writers can review and merge while scouts are still running, and a timed-out or transient step is retried once. Canceled or interrupted steps stay pending, so a later run_plan resumes them instead of starting over.

Workers and worktrees

Workers are full-access by default: they read, write, edit, run commands, use the network, browse and search. Orchestration tools and question stay with the lead.

Writers declare the files they own. Writes outside that set are refused.
Work runs in a git worktree where possible; warm worktrees are reused between steps.
Changes are reviewed, checks run once, and the patch is three-way merged.
A worker that needs a decision returns needs_input; resume_worker continues the same session and worktree.
A dirty tracked tree blocks writers — commit or stash first.

wombat config set worker_full_access false   # read-only research workers
wombat config set max_parallel_scouts 5
wombat config set max_parallel_writers 2
wombat config set check_policy auto          # auto | worktree | merge | both
wombat config set review_policy always       # always | auto | never
wombat config set review_writers true

When not to use a fleet. One shell command, one file, or several agents reading the same source is slower with workers. Parallelism pays when the slices are genuinely independent: different files, different pages, different audits.

Skills

A skill is a markdown file of instructions that one or more agents load. Skills live in ~/.wombat/skills/<name>.md for the user and .wombat/skills/<name>.md for a project; the project copy wins on a name clash. They are attached per agent through the skills field, or with the Skills section of the agent builder.

mkdir -p .wombat/skills
$EDITOR .wombat/skills/careful-proofs.md

/skill                 # browser: list, inspect, expand
/skill list
/skill careful-proofs  # print the instructions in full

A skill only reaches the model when an agent that names it is running, so a library of skills costs nothing until it is used. Skills run with that agent's permissions; read one before you install it.

Skills vs MCP. A skill is instruction and taste. An MCP server is reach. Install skills to change how the agent decides; attach MCP servers to change what it can touch.

Modes

create mode (the default) can write and run. chat mode is read-only: writes and mutating commands are off for the lead and every selected agent. Switch with /mode or wombat config set mode chat; /modes lists what is available.