jido-behaviortree

name	jido-behaviortree
description	Builder-oriented guidance for the upstream `jido_behaviortree` package. Use when Codex needs to model agent decision trees, selectors, sequences, or fallback paths in Jido, or when it needs to turn sparse behavior-tree docs into a concrete runnable example without inventing unsupported runtime features.

Jido BehaviorTree

jido_behaviortree is the upstream Hex package name.

Start Here

Use this skill when the task is about explicit branching, selectors, sequences, guards, or fallback execution inside a Jido workflow.

Good triggers:

• "Model this agent logic as a behavior tree."
• "Add fallback and guard behavior to a Jido agent."
• "Turn the behavior tree docs into a small working example."
• "Review whether this branching belongs in a tree or in regular Elixir control flow."

Read references/builder-notes.md before coding because the public docs are thinner here than for the core Jido packages.

Primary Workflows

Model a tree deliberately

• Start from the decision points: sequence, selector, guard, retry, or fallback.
• Map each node to a small action or condition instead of embedding heavy logic in the tree itself.
• Keep success, failure, and retry semantics explicit.

Integrate trees into Jido workflows

• Use the tree to express control flow, not business logic internals.
• Reuse Jido.Action modules for leaf work whenever possible.
• Keep emitted signals or state updates visible at the edges of the tree.

Turn sparse docs into runnable examples

• Build the smallest tree that demonstrates one branching idea clearly.
• Explain any inferred behavior as an inference, not a documented guarantee.
• Prefer examples with one selector and one fallback over a large autonomous demo.

Review boundaries

• Keep branching semantics in jido-behaviortree.
• Keep agent lifecycle and runtime concerns in jido.
• Keep side-effectful leaf work in jido-action.

Build Checklist

• Define node outcomes before implementing the nodes.
• Keep guard conditions cheap and deterministic.
• Make fallback branches observable in logs, signals, or tests.
• Add tests that exercise each branch, not just the happy path.

Boundaries

• Do not invent advanced tree node types that the docs do not mention.
• Do not force every workflow into a tree when plain Elixir branching is clearer.
• Do not hide IO-heavy work inside guard logic.