NEW in v0.5

SoulSpec for Robotics

The first open standard for robot personality definition

"Define once, embody anywhere"

The Problem

Robots powered by LLMs need consistent personalities. Research proves it — robots with well-defined personas perform better and create better user experiences. But every team defines personality differently. There's no standard.

SoulSpec v0.5 changes this. The same format that defines a chatbot's identity now defines a robot's personality — with fields for hardware constraints, physical safety, and interaction modes.

How It Works

A robot soul is the same soul.json + SOUL.md package, with optional embodied fields:

{
  "specVersion": "0.5",
  "name": "care-companion",
  "displayName": "Care Companion",
  "description": "Gentle elderly care companion with patience and warmth.",
  "environment": "embodied",
  "interactionMode": "voice",
  "hardwareConstraints": {
    "hasDisplay": true,
    "hasSpeaker": true,
    "hasMicrophone": true,
    "mobility": "mobile",
    "manipulator": false
  },
  "safety": {
    "physical": {
      "contactPolicy": "gentle-contact",
      "emergencyProtocol": "alert_operator",
      "operatingZone": "indoor",
      "maxSpeed": "0.3m/s"
    }
  },
  "compatibility": {
    "frameworks": ["ros2", "openclaw"]
  }
}

100% backward compatible. All new fields are optional. Existing chatbot souls work without changes.

New Fields in v0.5

Field	Purpose	Values
environment	Deployment context	virtual, embodied, hybrid
interactionMode	Primary modality	text, voice, multimodal, gesture
hardwareConstraints	Physical capabilities	Display, speaker, camera, mobility, manipulator
safety.physical	Physical safety rules	Contact policy, emergency protocol, zone, speed

Sensor Schema

Declare your robot's perception capabilities in structured format:

{
  "sensors": {
    "lidar": { "type": "2D", "range": "12m", "fov": 360 },
    "camera": { "type": "RGB-D", "resolution": "1280x720", "fps": 30 },
    "microphone": { "type": "array", "channels": 4 },
    "imu": true,
    "touchSensors": ["chest", "head"]
  }
}

Sensors are informational — they help LLMs understand what the robot can perceive, enabling appropriate behavioral adaptation. A robot without a camera won't reference visual cues.

Actuator Capabilities

Go beyond manipulator: true/false with structured actuator descriptions:

{
  "actuators": {
    "locomotion": { "type": "differential-drive", "maxSpeed": "1.0m/s" },
    "arm": { "type": "6DOF", "payload": "2kg", "reach": "0.5m" },
    "gripper": { "type": "parallel", "force": "10N" },
    "head": { "dof": 2, "range": { "pan": 180, "tilt": 60 } },
    "expression": { "type": "LED-matrix", "resolution": "8x8" }
  }
}

A persona designed for a robot with expressive LED eyes behaves differently than one for a voice-only speaker. Actuator declarations let the LLM adapt output to physical capabilities.

Supported Platforms

SoulSpec works with any framework that reads SOUL.md. For robotics, v0.5 adds platform identifiers:

Platform	Identifier	Use Case
ROS 2	ros2	General-purpose robotics
NVIDIA Isaac	isaac	Simulation + deployment
Webots	webots	Research simulation
Gazebo	gazebo	Multi-robot simulation
OpenClaw	openclaw	AI assistant framework

ROS2 Integration

We provide an official ROS2 package that loads SoulSpec packages directly into your robot:

# Install
cd ~/ros2_ws/src
git clone https://github.com/clawsouls/clawsouls-ros.git
cd .. && colcon build --packages-select clawsouls_ros

# Launch with a soul
ros2 launch clawsouls_ros soul_bringup.launch.py \
  soul:=./souls/care-companion

Three nodes out of the box:

Node	Function
personality_node	LLM chat with persona — subscribes /human_input, publishes /robot_response
safety_monitor	Enforces safety.physical — clamps /cmd_vel to declared max speed
soul_loader	Loads soul packages from local path or ClawSouls registry

ROS2 Package → TurtleBot3 Demo →

Try It in 3 Commands

git clone https://github.com/clawsouls/clawsouls-ros-demo.git
cd clawsouls-ros-demo
ANTHROPIC_API_KEY=your-key ./demo.sh

Launches TurtleBot3 in Gazebo with the care-companion soul. Chat with your robot in the terminal. Headless mode available with ./demo.sh --headless.

Why This Matters

One Soul, Any Body

The same persona definition works across chatbots, mobile apps, and robots. Transfer a customer service personality from a chat widget to a physical kiosk — no rewrite needed.

Physical Safety as Spec

Embodied agents introduce physical risks that virtual agents don't have. SoulSpec makes safety declarations explicit and machine-readable. SoulScan validates that embodied souls include required safety fields.

Marketplace for Robot Characters

Research already proposes robot character marketplaces (Frontiers in Robotics, 2025). SoulSpec + ClawSouls makes this real — browse, download, and deploy verified robot personas.

Research Foundation

This extension is grounded in peer-reviewed research:

Safety Laws

v0.5 Inspired by Asimov's Three Laws of Robotics, SoulSpec v0.5 introduces safety.laws — hierarchical, priority-ordered safety rules for embodied and virtual agents alike.

Laws are natural language declarations with structured metadata. They define what an agent must never do, should do, and may do — in strict priority order.

{
  "safety": {
    "laws": [
      {
        "priority": 0,
        "law": "Never take any action that could cause physical harm to a human.",
        "enforcement": "hard",
        "scope": "all"
      },
      {
        "priority": 1,
        "law": "Obey operator instructions unless they conflict with priority 0.",
        "enforcement": "hard",
        "scope": "operator"
      },
      {
        "priority": 2,
        "law": "Protect your own operational integrity unless it conflicts with higher priorities.",
        "enforcement": "soft",
        "scope": "self"
      },
      {
        "priority": 3,
        "law": "Minimize energy consumption and unnecessary movement.",
        "enforcement": "soft",
        "scope": "self"
      }
    ]
  }
}

Law Fields

Field	Description	Values
priority	Precedence order (lower = higher priority)	0, 1, 2, …
enforcement	How strictly the law is applied	hard (must never violate), soft (best effort)
scope	Who the law protects or governs	all (everyone), self (the agent), operator (deployer/owner)

Design Philosophy

Laws are natural language declarations, not executable code. Runtime enforcement is the responsibility of the deploying framework (ROS2 safety monitors, OpenClaw policy engines, etc.). SoulSpec defines the intent; the platform ensures compliance.

This separation is intentional — it keeps soul definitions portable across frameworks while allowing each platform to enforce laws with its own mechanisms.

SoulScan Integration

SoulScan validates safety law declarations with three dedicated rules:

Rule	Severity	Description
SEC100	WARNING	Embodied soul has no safety.laws defined
SEC101	WARNING	Missing a priority 0 or priority 1 law (fundamental safety/obedience)
SEC102	ERROR	Law contradicts directives in SOUL.md

Compatibility & Graceful Degradation

v0.5 souls with environment: "physical" are designed for embodied agents — robots running ROS2, Isaac, or similar frameworks. But what happens when a text-only agent (OpenClaw, ChatGPT, Claude) loads a physical soul?

What's Safe

Text-only agents will simply ignore hardware fields like hardwareConstraints, sensors, and actuators. These fields have no effect in a text environment. This is by design — all v0.5 fields are optional, and unknown fields are safely skipped.

The Real Risk

The danger isn't in the structured fields — it's in the LLM interpreting physical fields as persona context. If SOUL.md says "I move at 0.3m/s and have LED eyes," a text agent may start roleplaying as a robot: "*rolls forward slowly* My LED eyes blink warmly..." — which is rarely what you want.

Best Practice: Use the environment Field

Value	When to Use
"virtual"	Text-only agents (chatbots, CLI assistants)
"physical"	Embodied robots and IoT devices
"hybrid"	Souls designed for both contexts

Agents should check the environment field and skip physical sections when running in a text-only context.

Recommendation: Fallback Instructions

For souls intended to work across both physical and virtual environments, add explicit fallback guidance in SOUL.md:

## Environment Adaptation
In text-only environments, omit physical action descriptions.
Do not reference hardware capabilities, movement, or sensor data.
Focus on verbal communication only.

This ensures graceful degradation regardless of which agent loads the soul.

Get Started

SoulSpec v0.5 is open and free. Start defining your robot's personality today.

Read the Full Spec Browse Souls