Menu
REQUIRED before writing or editing any Escapement statechart/agent — covers the minimal skeleton, which example to clone, and traps the engine won't warn you about. Load it when building or editing an escapement agent/chart.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Build terminal UIs with OpenTUI. Covers the core API, native audio, keymaps, React and Solid bindings, components, layout, keyboard input, plugins, and testing.
Launch and observe Escapement's interactive TUI (the live streaming-token panel + inspector). Three modes — headless (tmux text capture, cross-platform, default for driving/verifying), shot (pixel-accurate PNG rendered OFFSCREEN with no window, via cage), and headful (PNG in a visible window). For a screenshot prefer `shot`; only use headful when the user wants to watch it live on their desktop. Use when asked to run, drive, or screenshot the TUI (e.g. `bb haiku '…'`, `bb -m escapement.cli run …`), or to confirm a UI change renders.
| name | writing-escapement-statecharts |
| description | REQUIRED before writing or editing any Escapement statechart/agent — covers the minimal skeleton, which example to clone, and traps the engine won't warn you about. Load it when building or editing an escapement agent/chart. |
Sources: Guide.adoc (Idioms/gotchas, params-fn), CLAUDE.md, the examples/ charts.
Clone the closest example, don't write from scratch. The src/escapement/examples/ charts are the canonical patterns — copy the nearest and adapt:
| Want to… | Clone |
|---|---|
| minimal single LLM turn → tool → done | hello.cljc |
| give the model real tools (fs/shell) | scan.cljc |
| loop the model until a condition (retry/iterate) | iterate.cljc |
| ask the human a question mid-run | ask.cljc / steer_midturn.cljc |
| multi-turn live conversation + a worker region | supervisor.cljc |
| fan out N concurrent subagents and join | parallel_demo.cljc / n_subagents_demo.clj |
| grade outputs with a verdict schema | scan.cljc (:verdict-schema) |
Minimal shape (from hello.cljc) — note the wrapped final, the h/llm-conversation block, and the namespaced event:
(chart/statechart {:initial :run}
(state {:id :run :initial :greeting}
(state {:id :greeting}
(h/llm-conversation
{:id "hello" :system system-prompt :real-tools []
:allowed-events [{:event :hello/done :data-schema [:map [:greeting :string]]}]
:message "Say hello."})
(transition {:event :hello/done :target :finished}
(script {:expr (fn [_env data]
[(ops/assign :greeting (get-in data [:_event :data :greeting]))])})))
(final {:id :finished}))) ; top-level final would empty the config — wrap it
Then read the traps below — the engine won't warn you about any of them. They are the actual reason this skill exists.
Traps the engine won't warn about:
:count/done, :count/tick, :iterate/retry). SCXML descriptors are prefix-matched, so a bare :done also matches synthesized :done.state.X/:done.invoke.Y from finalising compound/parallel states (and bare :error* matches the error.* family) → in a parallel chart the join re-fires your transition → eventless re-entry loop ("Eventless transition loop exceeded 1000 iterations"), pegs CPU. A namespaced kw has no dot in its first token so it can never collide — and you keep the natural name (:count/done is fine; bare :done is the hazard). Every chart under src/escapement/examples/ follows this. Leave framework events bare: :llm.idle, :llm.user-message, error.*, done.state.*, done.invoke.*. Canonical write-up: examples/fired.clj; full rationale: Guide.adoc "Event naming".:foo-bar → event__foo_bar; :my.ns/foo-bar → event__my_ns_foo_bar; non-alphanum → _.submit_verdict is reserved when using :verdict-schema — don't collide via :allowed-events/:real-tools.:type :internal to preserve it across transitions (scan.clj :found-bug, iterate.clj loop).h/tell-llm only works inside the bound state; outside it's silently dropped.tell-llm broadcasts to all live :llm-conversations; use h/tell-other-llm with :target <invokeid> to target one (kw/string invokeids normalize).:on-end-turn-event defaults to :llm.idle, payload {:text :from}, fires once per logical turn (both :end_turn and batched-terminator :tool_use shapes).--resume restarts any live LLM turn from empty history, so side-effecting tools (:fs/edit, :shell/run) are not at-most-once across resume — track durability in the data model (iterate.clj bumps :iterations). BUT: (a) delayed/timer events (send-after) now SURVIVE resume — they're persisted with the checkpoint and rehydrated, so a poller's pending tick re-fires and the loop stays alive (no need to re-arm on-entry); one whose delivery-time passed while down fires immediately. (b) The runner emits a chart-observable :escapement/resumed event on resume — add a transition on it to idempotently self-heal (rebuild a service registry, re-acquire a resource); a chart that ignores it drains it as a no-op (there is NO blanket on-entry replay). See examples/heartbeat.cljc for the canonical kill/resume loop.final empties the configuration — always wrap in a compound parent.:_event: (get-in data [:_event :data ...]) inside script :expr.:chart-tools palette is snapshotted at conversation start — late-registered service-region tools won't be callable in that conversation. Region-tools are NOT auto-discovered: you MUST declare :chart-tools [{:owner <registering-state-id>}] or the model never sees them.:type :internal. A transition whose source is a parallel region's root state and whose target is that region's <final> is, as an external transition, given the whole parallel as its SCXML domain (LCCA of root + its final child). Its exit set then spans every sibling region, so remove-conflicting-transitions drops it and the region never finalises → the join never completes. :type :internal keeps the domain in-region. (A transition sourced on a deeper substate is fine — its domain is the region.)send-after for safety timers, not a raw (send {:delay …}). A raw delayed send is NOT cancelled when the chart finishes early, so the runner idles for the full delay waiting on the orphaned timer after the chart already reached its final. (send-after {:id … :event … :delay …}) (from com.fulcrologic.statecharts.convenience) pairs an on-entry send with an on-exit cancel. Also: a region-root :safety/stop transition has the same external-domain trap as above — terminate via a top-level :safety/stop -> :finished instead, and handle :error.llm.max-turns at top level so a chatty model that burns :max-turns ends promptly.multiplex, not hand-rolled regions (com.fulcrologic.statecharts.invocation.multiplex + …multiplex-options :as mo). Keys: mo/child-type ::sc/chart, mo/count (fn [_ data] …), mo/child-params (fn [_ data idx] {:src <registry-id> :params {…}}). Patterns: n_subagents_demo.clj (deterministic), haiku_tournament_dynamic.clj (LLM, nested phases).^{:multi-session? true} — the runner reads it to drain child + aggregator queues. Without it the run wedges: children's done.invoke.* never reach the parent. (CLI threads it into runner/run!.)sp/register-statechart!) under the id mo/child-params resolves via :src.(mux/reply env :ev/foo {:idx (:idx data) …}); accumulate parent-side by :idx (a map/vector, NOT a counter) under a :type :internal transition. mo/from carries {:idx …}; this is unrelated to the LLM invokeid.final via an eventless (transition {:target :done}) after on-entry — that emits the natural done.invoke.<child-sid> the aggregator counts. Parent transitions on :done.invoke.<multiplex-id> when all finish.params-fn:max-tokens is ignored — output cap comes from the model catalog (models-api.json limit.output). Remove it.:resilience {:overrun {…}} (escapement.llm). OFF by default. On :max_tokens truncation it reruns the SAME turn with identical context up to :max-retries. :on-exhausted :truncate (accept, default) | :fail (:status :overrun envelope). :max-output-tokens is the trip-wire (+ fallback cap for catalog-unknown/local models). A deterministic model re-truncates forever — set :temperature-bump (attempt N adds N×bump, clamped :temperature-max 1.0) so output can vary and terminate. Example: haiku_tournament_dynamic.clj.:resilience {:latency {:first-token-ms N :fallback [...]}} (escapement.llm). OFF by default. Caps TIME-TO-FIRST-TOKEN only (not total generation): a backend that emits no first token within N ms is abandoned and the turn fails over to the next candidate / the inline :fallback chain (a vector of {:provider :model} targets, honored only when :first-token-ms set, ignored under :pinned). The slow model is NOT marked :down (slowness is transient, stays in rotation); each breach emits a :llm/latency-switch transcript event. With nowhere left to switch the turn rides out the slow model.:model or :models disables auto-fallback. Use :needs to filter without disabling the preference-ordered list.:auto-cache? true, 5-min ephemeral on system + tail of tools). Anthropic ignores cache_control below 1024 tokens (2048 Haiku).:temperature with :thinking — temperature is ignored.statecharts.simple/simple-async, statecharts.testing/testing-async, statecharts.invocation.statechart, any *_async*/core_async_event_loop, statecharts.integration.fulcro*.escapement.engine.env (env) and escapement.engine.testing (harness).escapement.test-support ts/queue/ts/pop-first!. SCI lacks LinkedBlockingDeque/ConcurrentLinkedDeque; LinkedBlockingQueue + TimeUnit are available.Worker threads (llm-conv-...) and transcript writer are daemons — they don't block bb exit. Drive graceful shutdown from the chart.