orkid: Skill for Claude Code

Orkid HFSM (Hierarchical Finite State Machine) Reference

When answering questions about state machines in orkid, consult these files.

Key Files

Component	Location
FSM Header	ork.core/inc/ork/util/fsm.h
FSM Implementation	ork.core/src/util/fsm.cpp
Python Bindings	ork.core/pyext/pyext_fsm.cpp
Tests	ork.core/pyext/tests/test_fsm.py
Complex Test	ork.core/pyext/tests/test_fsm2.py
Visualization Test	ork.core/pyext/tests/fsmviz_test.py

Architecture Overview

Two-Part Design

• FsmData — shared, immutable state machine definition (states + transitions)
• FsmInstance — per-entity runtime (current state, event queue, variables)
• One FsmData can be shared by many FsmInstances

State Classes

• State — base class with virtual onEnter/onExit/onUpdate
• LambdaState — concrete state with configurable lambda callbacks (primary Python type)

Hierarchical Support

States have optional _parent pointer forming a tree. Transitions between siblings only exit/enter the leaf states — common ancestors stay active.

Example: transition A1 → A2 (siblings under A):

• Exits: A1 only
• Enters: A2 only
• A stays active (no callbacks)

Key Classes

// Shared definition
struct FsmData {
  template<typename T> shared_ptr<T> newState(state_ptr_t parent, string name);
  void addTransition(state_ptr_t from, string event, state_ptr_t to);
  void addTransition(state_ptr_t from, string event, PredicatedTransition pt);
  state_ptr_t findState(string name);
  string generateDot(DotConfig config);
};

// Per-entity runtime
struct FsmInstance {
  static fsminstance_ptr_t create(fsmdata_ptr_t data);
  static void update(fsminstance_ptr_t inst);
  void sendEvent(string event);
  void changeState(state_ptr_t target);
  void setInitialState(state_ptr_t state);
  state_ptr_t currentState();
  varmap_ptr_t vars();  // Per-instance variables
};

// Multi-instance coordination
struct FsmGroup {
  fsminstance_ptr_t createInstance(fsmdata_ptr_t data);
  void broadcastEvent(string event);
  bool allInState(string state_name);
  void waitForAllInState(string state_name);
};

// Guard condition
struct PredicatedTransition {
  predicate_callback_t _predicate;  // bool(fsminstance_ptr_t)
  state_ptr_t _destination;
};