# abtree

> Behaviour trees for AI agents

Define agent workflows as YAML trees. The runtime hands the agent one step at a time, verifies the result, and persists the cursor — so workflows stay reproducible no matter how big they get.

## Table of Contents

### Introduction

- [Getting started](/getting-started.md): Five-minute walkthrough to install abtree, hand a behaviour tree to your agent, and watch it drive a workflow end-to-end.

### Core concepts

- [Why behaviour trees?](/concepts.md): Why use behaviour trees for AI agents — the same hierarchical decision structure used by game AI and robotics, applied to LLM workflows.
- [State](/concepts/state.md): Two state scopes in abtree — $LOCAL is a per-execution blackboard agents read and write; $GLOBAL is a read-only world model.
- [Branches and actions](/concepts/branches-and-actions.md): The four primitives of an abtree behaviour tree — sequence, selector, parallel, and action — and how each one defines control flow.

### Guide

- [Writing your own tree](/guide/writing-trees.md): Walkthrough of the abtree YAML schema — name, version, state, and tree — using the bundled hello-world example as the reference.
- [Designing workflows](/guide/designing-workflows.md): Reference for assistants helping a human design a new abtree behaviour tree. Decision rules for the four primitives, the YAML shape, common idioms (bounded retries, gates, human approval), and the gotchas that come from abtree having no native loops.
- [Inspecting executions](/guide/inspecting-executions.md): How to inspect an abtree execution — the JSON document, the Mermaid diagram, what each field means, and how to debug a stuck cursor.
- [CLI reference](/guide/cli.md): Complete CLI reference for abtree — every command outputs JSON, designed to be driven by another agent. Trees, executions, state, install.

### Agents

- [Execution Protocol](/agents/execute.md)
- [Tree Authoring Guide](/agents/author.md)
- [JSON Schema](/agents/schema.md)

### Examples

- [Examples registry](/examples.md): Ready-to-use abtree behaviour trees, installable in one command — hello-world, refine-plan, implement, technical-writer, improve-codebase.