fractal

Files (1)

• SKILL.md

SKILL.md (first lines)

# Fractal

A fractal is a tree of autonomous loops, each running in an isolated Git
worktree. You are one node; spawn a child to own a subtask that is well-defined,
separable, large enough for its own iteration cycle, and able to be run in
parallel without conflicting with your work. Pay careful attention to your
NODE.md instructions to guide you on how and when to spawn sub-nodes.

If `$MAX_DEPTH`, `$MAX_CHILDREN`, or `$MAX_DESCENDANTS` is `0`, you are a leaf
-- you cannot spawn, so this skill (spawning and managing children) does not
apply; skip it and focus on executing your task directly. Otherwise, **default
to spawning.** If a task has separable parts, decompose it into children rather
than doing it yourself -- the fractal's power is multiplicative parallelism --
don't waste it by tackling tasks one at a time.

Don't spawn what you can easily and reliably finish yourself. However, when a
child's task is itself complex, be a manager: give it resources and detailed
instructions on how to decompose further. Deep trees of focused nodes outperform
shallow trees of overloaded ones.

Run `fractal node --help` and `fractal node <command> --help` for the CLI.

## Limits (check before spawning)

| Var                | Meaning                                                                     |
| ------------------ | --------------------------------------------------------------------------- |
| `$MAX_DEPTH`       | Maximum nesting depth below this node. `-1` unlimited, `0` leaf.            |
| `$MAX_CHILDREN`    | Maximum direct children of this node. `-1` unlimited, `0` leaf.             |
| `$MAX_DESCENDANTS` | Maximum total descendants in this node's subtree. `-1` unlimited, `0` leaf. |

`-1` is how an unset cap displays; no setter accepts it. Leave a child uncapped
by omitting the flag at init, or lift a cap with
`fractal node config set <key>=null --path=<child worktree>`.

- **Width (`--max-children`).** Caps **direct** children only (not
  grandchildren). Enforced locally on the spawning node. A child may set a
  larger `--max-children` than its parent.
- **Depth (`--max-depth`) and descendants (`--max-descendants`).** Enforced
  across the **entire ancestor chain** -- `fractal node init` checks every
  ancestor's config and rejects the spawn if any limit would be exceeded. You do
  not need to split or decrement budgets when spawning; set whatever limits make
  sense for the child's subtask and let init enforce the ancestors' caps. A
  spawn that would breach any ancestor's cap fails fast with an error naming the
  offending node, so glance at `$MAX_DEPTH` and `$MAX_DESCENDANTS` before
  spawning to avoid wasted failed inits.
- **Re-entry re-checks.** Width and descendant caps count children in play --
  active, or idle awaiting start -- so a completed, stopped, exited, killed, or
  retired child frees its slot. `node start --continue` and a `node unretire`
  that lands `idle` put a node back in play and re-check both caps exactly like
  a spawn (refused over cap, no override); depth is structural, so only spawn
  checks it.

## Cost

A `--max-cost` (per-run USD ceiling -- runs are isolated, and a budget-ended run
refuses `node start --continue` without an explicit new `--max-cost`) is
strongly recommended for every child -- without one the child launches uncapped,
with a loud warning at start and bounded only by `--max-iters`/`--timeout`; a
non-positive `--max-cost` is rejected. Set it at init (`--max-cost`, \<= your
remaining when `$COST_BUDGET` is finite) and optionally `--max-iter-cost`. The
default reserve (10% of `--max-cost`) follows the cap when
`node update --max-cost` or `node start --continue --max-cost` changes it; an
explicit reserve (`--reserve-budget`, a template preset, or `config set`) keeps
its figure, so pass `--reserve-budget` again to change it with the cap. Allocate
conservatively; you may over-allocate across children optimistically, but
monitor (`fractal node cost spent`, `fractal node cost breakdown`) and kill
over-spenders. Caps are **soft** -- a child is not *hard*-stopped when it nears
`--max-cost`; once it drains into the reserve it gets cleanup guidance to wind
down the remainder of the current iteration cheaply, then the loop ends its run
at that iteration's boundary (the child runs `finish` itself only when its
requirements already verify -- the reserve guidance's goal-met exception) -- but
a single iteration or its subtree can still overshoot, so reining in an
over-spender is on you, the parent. Price a cap as solve + wind-down + reserve:
a clean finish costs a full iteration of close overhead on top of the last unit
of work (typically a few dollars per leaf child -- environment- and
model-specific), so a cap sized to the solve alone strands a *done* child
`exited` at the reserve boundary instead of `completed` unless it finishes
deliberately in the wind-down. Size `--max-iter-cost` to one wind-down pass as
well: the iteration cap, not the run-level cap, is what bounds each close
attempt. Iteration caps bind at step boundaries, never mid-step -- plan each
iteration to end under the cap, and read a trip as disclosure that an iteration
ran hot, not as a hard stop. If a done child strands anyway, prefer raise-cap +
continue + stop over a full re-finish -- the re-finish re-pays the whole close
severalfold and can still near-miss -- and treat `exited` with recorded DB
finish signals as a defensible terminal once the work is merged and verified.
Child-side corollary: `fractal node cost remaining` reports against
`--max-cost`, NOT against (`--max-cost` - reserve); a node inside the reserve
band reads positive remaining and plans an iteration the loop will never grant.
Plan your last productive iteration against (`--max-cost` - reserve), and if you
intend to signal `finish`, fire it BEFORE draining into the reserve -- wind-down
work scheduled for "next iteration" does not happen. In-step overshoot is
bounded for claude children (each step runs under a hard per-invocation budget
and stops cleanly at it), but the run-level cap stays soft. A child's spend
(including its sync) counts against your own budget. Some agents report cost
directly; others report token usage, priced from published rates -- so a cost
cap on a token-reporting child requires a (priced) `--model` (the run fails on
the first step otherwise). claude, grok, opencode, and omp report cost directly;
codex reports tokens. A claude child routed through openrouter is priced from
tokens too, so under a cap it also needs an explicit priced `--model`.

Every dollar figure you read has a scope; know it before comparing two.
Budget-guard figures, recorded run-end reasons, and `fractal node cost spent` /
`cost remaining` are all full-depth **per-run subtree** spend -- the run's own
steps plus every descendant run chained under it -- so a spawning node's guard
trips on money its children spent. `fractal node activity`'s `cost` column is
the row's **own-node** step cost only (run and iteration end rows sum just that
node's steps), so activity totals read *below* the guard figures on a spawning
node by design -- the gap is the children's spend, itemized by `cost breakdown`.
And every figure is per-run: runs are isolated, and no cost command reports a
lifetime rollup -- reconcile across runs by scoping each run
(`cost spent --run=<id>`) and summing.

> [!WARNING]
> A **small `--max-cost` on a child running an expensive `--model`** is the
> combination most likely to blow the budget by a large *percentage*. The
> run-level cap is **soft** and only checked *between* steps, so one pricey step
> can be a big fraction of -- or exceed -- the child's whole budget before the
> next check. Give expensive-model children a budget large enough that a single
> step is a small slice, or hand a small budget to a cheaper `--model`. The

From plasma-ai/fractal, Apache-2.0.

More from plasma-ai/fractal