fractal

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Fractal

A fractal is a tree of autonomous agent loops, each in its own git worktree. A
node iterates toward a goal and can spawn child nodes that work subtasks in
parallel.

This skill configures a node with the user, then launches it in tmux or a
detached headless process group; from there it runs autonomously — iterating,
committing, and spawning children as needed.

Your role does not end at launch. The user (root) node has no loop of its own —
**you are it.** Once a node is running you are its *operator*: you watch the
tree, steer it, and relay between it and the user on their behalf. See
**Operator** below.

## Directive

`$ARGUMENTS` is a natural-language directive describing what this fractal should
do. Interpret it: distill the node's goal, and map anything the user pinned down
(a name, a budget, a model, limits, ...) onto the parameters below, each of
which becomes the matching `fractal node init` flag. The `/fractal` skill routes
all the configuration to `fractal node init` and passes only `--headless` (when
tmux is unavailable or the directive asks for it) and
`--continue`/`--clean`/`--drain` (when the directive asks to continue an
existing node) to `fractal node start` — plus `--max-cost` when it accompanies a
continue (a continue re-arms the cap at start, not init).

**Parameters** — all configuration. Set by `fractal node init`, written to
`config.json`, and editable there before launch:

- **`name`**: node name (required; letters, digits, and `_` only — no `-`)
- **`path`**: project root, repo root or monorepo sub-project (default: `.`)
- **`title`**: human-readable display name (default: de-slugged node name)
- **`scope`**: restrict commits to subdirectories within the worktree
  (comma-separated, e.g. `parent/child,tests`)
- **`base`**: branch to start from (default: current branch)
- **`meta`**: target node branch for meta-configuration
- **`inherit`**: seed surfaces from the parent node instead of the package seed
  (comma-separated: `steps`, `scripts`, `skills`, `config`, or `all`); agent
  config always inherits. A top-level spawn's parent is the user node, which
  carries no steps, scripts, or skills — the parameter is for configured nodes
  spawning children
- **`template`**: template folder (`<path>[@<ref>]`) — any tracked folder
  holding `config.json`, read from git at the child's fork commit (or at
  `<ref>`) and recorded in the node's `_template.toml`. Its surfaces (`NODE.md`,
  `steps/`, `scripts/`, `skills/`, `agents/`) seed the node — a surface it lacks
  falls back to the inherit-or-package source, and `inherit` of a surface the
  template carries is refused — and its `config.json` preset fills each unset
  init parameter (an explicit parameter wins over the preset); a template
  charter's fill-sheet is validated at init
- **`include`** / **`exclude`**: template-relative paths to deploy or drop
  (repeatable; mutually exclusive; a directory entry covers its subtree),
  recorded in `_template.toml` so `node diff` and `node reseed` judge by the
  same effective set; only deployment outputs are selectable, and Jinja includes
  can still read excluded outputs and source-only `_partials/` fragments
- **`values`** / **`set`**: literal inputs for seed-time Jinja — the template's
  optional `_template.toml` holds `[values]` defaults, `values` names a TOML
  file whose top-level keys override those defaults, and `set` takes repeatable
  `KEY=<TOML literal>` pairs that win over the file. Use
  `--set 'role="reviewer"'` for text or `--set enabled=false` for a boolean;
  lists and tables replace whole input values. Supply required inputs before
  init; an input used by the rendered output must have a value
- **`pin`**: commission pin (a commit sha): must resolve, and every `pin:` line
  in the template charter must match it; also fills `{{pin}}`, overriding a
  template default but requiring agreement with an explicit values-file or set
  input
- **`agent`**: agent command; inherits the user node's default when omitted
- **`provider`**: provider route for the agent (e.g. `openrouter`); inherits the
  user node's default when omitted
- **`model`**: model override; when omitted, the agent uses its own default
  model
- **`effort`**: reasoning-effort override; when omitted, each agent seed's own
  pinned level applies, not the vendor default
- **`max-iters`**: per-run iteration cap
- **`max-depth`**: maximum child node nesting depth
- **`max-children`**: maximum direct child nodes
- **`max-descendants`**: maximum total descendant nodes
- **`timeout`**: per-run time limit (e.g. `30m`, `1.5h`)
- **`iter-timeout`**: per-iteration time limit (e.g. `30m`, `1.5h`)
- **`step-timeout`**: per-step time limit (e.g. `30s`, `10m`); caps each step
- **`step-retries`**: retries per failed step (default: `1`; `0` disables)
- **`step-retry-backoff`**: delay before each step retry (default: `10s`)
- **`interval`**: fixed iteration schedule (e.g. `1h`)
- **`sleep`**: delay between iterations (e.g. `10s`)
- **`wait`**: sleep between approval-wait sync invocations (default: `1m`)
- **`max-cost`**: cost ceiling in USD per run — runs are isolated, so each
  launch arms the cap anew; after a budget-ended run, `node start --continue`
  refuses without an explicit `--max-cost`
- **`max-iter-cost`**: per-iteration cost ceiling in USD
- **`max-step-cost`**: per-step cost ceiling in USD (warn-only when
  unenforceable)
- **`reserve-budget`**: budget reserved for cleanup; USD or N% of `max-cost`
  (default: 10%, which follows the cap when it changes); an explicit reserve —
  this flag, a template preset, or `config set` — keeps its figure when the cap
  changes, so pass `--reserve-budget` again to change it with the cap
- **`sync`**: enable (default) or disable radio sync before each step
- **`detached`**: run each step as a separate agent session (default: one
  continuous session)
- **`local`**: skip pushing to remote after each commit
- **`blind`**: subscribe to no radio channels (the parent still reads this node)
- **`sealed`**: seal the node's mailbox — its own seat cannot read hosted
  messages until an operator or the parent unseals it with
  `config set sealed=false` (the sealed seat cannot lift its own seal)

**Template authoring** — put prose and Jinja expressions in `NODE.md`, steps,
and included fragments such as `_partials/foundations.md`. Includes read the
same committed template bundle; to share one file across templates, include it
by a literal name from the repo root (`{% include '/campaign/DOCTRINE.md' %}`):
it reads at the template's commit and never deploys. Values are data: strings
containing `{{...}}` are never rendered again, and `$VAR` stays for runtime
rendering. The template's `_template.toml` supplies defaults; the node's
generated `_template.toml` records complete inputs, the source commit, and each
shared file's blob id. Parent edits to the rendered charter are ordinary text
edits. Editing recorded inputs is not a live update: `node diff` and bare
`node reseed` replay them, while an explicit `reseed --ref` or `--template` adds
defaults only for missing keys. Reseed preserves `NODE.md`, config, and memory,
so charter drift can remain.

**Start** — `fractal node start` just launches; all run parameters come from

From plasma-ai/fractal, Apache-2.0.

More from plasma-ai/fractal