# abtree

> <s>Hoping.</s> <span class="accent">Behaving.</span>

## Table of Contents

### Introduction

- [Motivation](/motivation.md): What abtree replaces (monolithic skill files), what it is not (an orchestration framework), and why it positions itself against a single, well-defined problem.
- [Get 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. Names the four primitives so the rest of the documentation can lean on them.
- [How it works](/concepts/how-it-works.md): A live walkthrough of an abtree execution — the YAML tree on one side, the CLI exchange on the other, and the cursor moving between them one step at a time.
- [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 the tree observes.
- [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

- [Use a tree](/guide/using-trees.md): Install a published abtree workflow and drive it with your agent of choice. Covers prerequisites, per-repo vs global install, the skill prompt, and how to run the workflow once installed.
- [Writing trees](/guide/writing-trees.md): Build the bundled hello-world tree from scratch — folder layout, file structure, state, primitives, retries. End-to-end tutorial that points at the reference for field-by-field detail.
- [Fragments](/guide/fragments.md): Split a large tree across files using JSON-Schema-style $ref. abtree resolves fragments at execution-creation time, so the runtime sees one fully-merged snapshot.
- [Design a new tree](/guide/design-process.md): A ten-step process for designing a new abtree behaviour tree. Start from the success state, work down to the root sequence, then validate that the tree loads.
- [Idioms](/guide/idioms.md): Reusable shapes for abtree behaviour trees — bounded retries, gates, parallel fan-out, fragments, globals as retrieval directives. Reach for these during design.
- [Delegating to subagents](/guide/delegating-to-subagents.md): Run a stretch of the tree in a spawned subagent, with the parent waiting on a verified exit token. Use delegate(...) in the DSL — it desugars to standard nodes; the runtime stays unchanged.
- [Driving abtree over MCP](/guide/mcp.md): Run abtree as an STDIO Model Context Protocol server so an agent can drive an execution through typed tool calls instead of spawning the CLI per step. Same surface, structured I/O, ~9× faster wall-clock in the bundled bench.
- [Anti-patterns](/guide/anti-patterns.md): Shapes that look like idioms but fail in practice — unbounded retries, native loops, pure-instruct actions, unordered parallels, and misuse of `submit running`. Recognise each so the runtime catches the bug at design time.
- [Test a tree](/guide/testing.md): Testing in abtree is itself a tree — the agent walks the tree-under-test in pretend mode, using fixtures in place of real side effects, then asserts the final state and the path it walked.
- [Programmatic test harness](/guide/test-harness.md): Drive an abtree execution deterministically from TypeScript with @abtree/testing — a when().respond() DSL that mirrors the abtree CLI surface. Both CLI and MCP transports built in; same scenario script runs against either.
- [Inspect an execution](/guide/inspecting-executions.md): Decode an abtree execution — the JSON document, the SVG diagram, every field, and how to debug a stuck cursor.
- [Publish a tree](/guide/publishing-a-tree.md): How to publish an abtree behaviour-tree package and list it on the registry. Package layout, npm publish workflow, and the pull request that adds your entry to the catalogue.
- [CLI reference](/guide/cli.md): Complete CLI reference for abtree — every command, every flag, every response shape, exit codes, and environment variables. JSON-shaped responses for agents to consume directly.

### Agents

- [Execution protocol](/agents/execute.md): Contract for an agent driving an abtree execution — the request/response loop, the four response shapes, and the strict read-from-store rule that keeps the gate uncorrupted.
- [Authoring trees](/agents/author.md): Reference for an agent (or human) authoring an abtree tree. Covers the full field reference — file shape, step kinds, retries, $ref fragments — plus a worked example and validation tooling.
- [JSON Schema](/agents/schema.md): Where the abtree tree-file JSON Schema lives, how to wire it into your editor for inline validation, and how the schema is regenerated and verified in CI.

### Discover trees

- [Discover trees](/registry.md): Searchable catalogue of abtree behaviour-tree packages. Each card links to a source repository you can install via npm, pnpm, or bun.
- [@abtree/hello-world](/trees/hello-world.md): Greet a user based on time of day. A small example tree that demonstrates the sequence, selector, and action primitives.
- [@abtree/implement](/trees/implement.md): Implement an approved plan with complexity-gated architectural review, following the clean-code rules in `clean-code.md`.
- [@abtree/improve-codebase](/trees/improve-codebase.md): Continuous code-improvement cycle. Scores quality metrics in parallel, hardens findings via a senior-principal critique, triages with a human gate, then iterates through each refactor with bounded retries until the queue is drained.
- [@abtree/improve-tree](/trees/improve-tree.md): Score the effectiveness of a tree using evidence from one of its sessions, find improvements in parallel, draft a plan in `plans/`, then commit and push.
- [@abtree/refine-plan](/trees/refine-plan.md): Refine a change request into an approved plan: analyse intent, draft to a per-execution draft file, critique it in place, promote to `plans/`, then take it through codeowner approval (either in-session or via an assigned MR).
- [@abtree/srp-refactor](/trees/srp-refactor.md): Score a codebase for Single Responsibility violations, pause for the human to pick one to tackle, refactor it in a bounded loop (re-scoring after every pass), run a multi-agent code review, and finish with a before-vs-after change report.
- [@abtree/technical-writer](/trees/technical-writer.md): Take a documentation goal, ground it in the repo's styleguide, find or build a home in the docs tree, write to it, and gate-check structure / flow / atomicity. Up to three write/review passes before surfacing failure to the human.
- [@abtree/test-tree](/trees/test-tree.md): Run a BDD test spec against a target tree. Compares the run's final $LOCAL against the spec's `then` assertions and writes a markdown report next to the spec.

### Blog

- [Blog](/blogs.md): Field notes on behaviour trees, agent design, and the shape of prompts that hold up under load.
- [The midnight greeting](/blogs/the-midnight-greeting.md): Same task, two methods. The skill answered in one turn and got it wrong. The tree answered one step at a time — slower, more expensive — and got it right.