ClawSouls Package Spec v0.5

soul.json

{
  "specVersion": "0.5",
  "name": "senior-devops-engineer",
  "displayName": "Senior DevOps Engineer",
  "version": "1.0.0",
  "description": "Infrastructure-obsessed DevOps engineer with strong opinions on CI/CD, monitoring, and incident response.",
  "author": {
    "name": "TomLee",
    "github": "TomLeeLive"
  },
  "license": "Apache-2.0",
  "tags": ["devops", "infrastructure", "cicd", "monitoring"],
  "category": "work/devops",
  "compatibility": {
    "openclaw": ">=2026.2.0",
    "models": ["anthropic/*", "openai/*"],
    "frameworks": ["openclaw", "clawdbot", "zeroclaw", "cursor"]
  },
  "allowedTools": ["browser", "exec", "web_search", "github"],
  "recommendedSkills": [
    { "name": "github", "version": ">=1.0.0", "required": false },
    { "name": "healthcheck", "required": true }
  ],
  "files": {
    "soul": "SOUL.md",
    "identity": "IDENTITY.md",
    "agents": "AGENTS.md",
    "heartbeat": "HEARTBEAT.md",
    "style": "STYLE.md",
    "userTemplate": "USER_TEMPLATE.md",
    "avatar": "avatar/avatar.png"
  },
  "examples": {
    "good": "examples/good-outputs.md",
    "bad": "examples/bad-outputs.md"
  },
  "disclosure": {
    "summary": "Infrastructure-obsessed DevOps engineer with strong CI/CD opinions."
  },
  "deprecated": false,
  "repository": "https://github.com/clawsouls/souls"
}

Changes from v0.4

v0.5 is fully backward compatible with v0.4. All existing v0.4 souls work without changes.

New Fields

Field	Type	Description
`sensors`	object	Sensor capabilities map for embodied agents
`actuators`	object	Actuator capabilities map for embodied agents

Enhanced Fields

Field	Change
`environment`	Now formally part of v0.5 (was introduced as v0.4 extension)
`interactionMode`	Now formally part of v0.5 (was introduced as v0.4 extension)
`hardwareConstraints`	Now formally part of v0.5 (was introduced as v0.4 extension)
`safety.physical`	Now formally part of v0.5 (was introduced as v0.4 extension)

v0.5 promotes the robotics/embodied agent fields from v0.4's extension section into first-class spec fields, and adds detailed sensors and actuators schemas.

For all other fields introduced in v0.4 (frameworks, allowedTools, recommendedSkills, disclosure, deprecated), see the v0.4 Specification.

Required Fields

Field	Type	Description
`specVersion`	string	Spec version. Valid: `"0.3"`, `"0.4"`, `"0.5"`
`name`	string	Unique identifier (kebab-case)
`displayName`	string	Display name
`version`	semver	Version
`description`	string	One-line description (max 160 chars)
`author`	string \| object	Creator info (string shorthand or `{ name, github }` object)
`license`	string	SPDX license identifier (see Allowed Licenses)

Author field

The author field accepts both a string shorthand and an object:

"author": "Tom Lee"
// or
"author": { "name": "Tom Lee", "github": "TomLeeLive" }

Optional Fields

Field	Type	Description
`compatibility.openclaw`	string	Minimum OpenClaw version (semver range)
`compatibility.models`	string[]	Recommended models (glob patterns)
`compatibility.frameworks`	string[]	Compatible agent frameworks
`compatibility.minTokenContext`	number	Minimum context window in tokens
`allowedTools`	string[]	Expected/permitted tools
`recommendedSkills`	object[]	Skills with `name`, `version?`, `required?`
`files.identity`	string	Path to IDENTITY.md
`files.agents`	string	Path to AGENTS.md
`files.heartbeat`	string	Path to HEARTBEAT.md
`files.style`	string	Path to STYLE.md
`files.userTemplate`	string	Path to USER template
`files.avatar`	string	Path to avatar image
`examples`	object	Calibration examples (`good`, `bad`)
`disclosure.summary`	string	One-line summary for quick-scan discovery (max 200 chars)
`deprecated`	boolean	Mark soul as deprecated
`supersededBy`	string	Replacement soul (`owner/name`)
`repository`	string	Source repository URL

Progressive Disclosure

v0.4 formalizes the 3-level progressive disclosure pattern, aligned with Anthropic's Skill design:

Level	Purpose	What to Load
Level 1 — Quick Scan	Discovery, filtering, marketplace browsing	`soul.json` only (`disclosure.summary` for instant context)
Level 2 — Full Read	Agent loads persona for active use	`SOUL.md` + `IDENTITY.md`
Level 3 — Deep Dive	Extended behavior, calibration, style	`AGENTS.md`, `STYLE.md`, `HEARTBEAT.md`, `examples/`

Rationale: Token budgets matter. A marketplace listing doesn't need AGENTS.md. An agent switching between souls benefits from Level 1 caching. Progressive disclosure reduces cost without losing depth.

The disclosure.summary field provides a self-contained persona hint that agents can use without parsing SOUL.md.

Multi-Framework Compatibility

The compatibility.frameworks field declares which agent frameworks this soul works with.

Known framework identifiers:

openclaw — OpenClaw (Claude Code, etc.)
clawdbot — Clawdbot
zeroclaw — ZeroClaw
cursor — Cursor
windsurf — Windsurf
continue — Continue.dev

Semantics: If omitted, the soul is assumed compatible with any SOUL.md-consuming framework. If specified, it's a recommendation — not a hard restriction.

Rationale: ClawSouls positions itself as "for any SOUL.md-compatible agent." This field makes that explicit at the spec level, enabling framework-specific filtering on the registry.

Allowed Tools

The allowedTools field declares which tools a soul expects to function properly.

"allowedTools": ["browser", "exec", "web_search", "github"]

Semantics:

Informational: Frameworks are not required to enforce this. It's a transparency signal.
SoulScan integration: SoulScan can cross-reference allowedTools with actual tool usage in AGENTS.md/SOUL.md to detect undeclared tool expectations or excessive tool requests.
Security angle: A "writing assistant" soul requesting exec and browser is suspicious. SoulScan flags this.

Recommended Skills

Replaces the v0.3 skills: string[] field.

"recommendedSkills": [
  { "name": "github", "version": ">=1.0.0", "required": false },
  { "name": "healthcheck", "required": true }
]

Property	Type	Required	Description
`name`	string	Yes	Skill identifier
`version`	string	No	Semver range constraint
`required`	boolean	No	Default `false`. If `true`, the soul may not function properly without this skill.

Backward compatibility: Tools MUST accept the legacy "skills": ["a", "b"] format, treating each entry as { "name": "a", "required": false }.

Soul Lifecycle

Deprecation

{
  "deprecated": true,
  "supersededBy": "TomLeeLive/senior-devops-v2"
}

Registry shows a deprecation banner
CLI install warns but doesn't block
supersededBy links to the replacement (optional)

Allowed Licenses

Same as v0.3. Permissive licenses only:

Apache-2.0, MIT, BSD-2-Clause, BSD-3-Clause
CC-BY-4.0, CC0-1.0, ISC, Unlicense

Copyleft (GPL-*, AGPL-*, LGPL-*) and restrictive Creative Commons (CC-BY-NC-*, CC-BY-ND-*) are blocked.

File Descriptions

Same as v0.3. See Soul Spec v0.3 — File Descriptions.

Embodied Agents (Robotics / IoT)

Soul Spec extends naturally to embodied agents — robots, IoT devices, and physical AI systems that interact with the real world. The same persona package that defines a chatbot's personality can define a robot's interaction character.

New Optional Fields

Field	Type	Description
`environment`	string	Deployment context. Values: `"virtual"` (default), `"embodied"`, `"hybrid"`, `"indoor"`, `"outdoor"`, `"mixed"`, `"any"`
`interactionMode`	string	Primary interaction modality. Values: `"voice"`, `"gesture"`, `"touch-screen"`, `"text"`, `"haptic"`
`hardwareConstraints`	object	Physical hardware capabilities and limitations
`safety.physical`	object	Physical safety rules for embodied agents

Environment Field

{
  "environment": "embodied"
}

"virtual" — Text/chat-based agent (default, backward compatible)
"embodied" — Physical robot, kiosk, or IoT device
"hybrid" — Operates in both virtual and physical contexts
"indoor" — Indoor-only deployment
"outdoor" — Outdoor-only deployment
"mixed" — Mixed indoor/outdoor
"any" — No environment restriction

If omitted, defaults to "virtual". Existing souls are unaffected.

Interaction Mode

{
  "interactionMode": "voice"
}

Valid values: "voice", "gesture", "touch-screen", "text", "haptic"

Declares the primary interaction modality. Useful for:

Registry filtering ("show me voice-first souls")
Framework adaptation (voice-first = shorter responses, simpler vocabulary)
SoulScan validation (voice-first soul shouldn't reference "click here")

Hardware Constraints

{
  "hardwareConstraints": {
    "mobility": "mobile",
    "sensors": ["camera", "lidar", "microphone"],
    "actuators": ["wheels", "arm"],
    "compute": "edge-tpu",
    "battery": true
  }
}

Property	Type	Description
`mobility`	string	Movement capability (e.g., `"stationary"`, `"mobile"`, `"limited"`)
`sensors`	string[]	List of sensor types (e.g., `["camera", "lidar", "microphone"]`)
`actuators`	string[]	List of actuator types (e.g., `["wheels", "arm", "gripper"]`)
`compute`	string	Compute platform (e.g., `"edge-tpu"`, `"jetson"`, `"cloud"`)
`battery`	boolean	Whether the device is battery-powered

Semantics: Informational only. Frameworks use these hints to adapt behavior (e.g., skip visual references on a device without camera sensor). Not enforced.

Physical Safety

{
  "safety": {
    "physical": {
      "maxSpeed": "0.5m/s",
      "emergencyStop": true,
      "collisionAvoidance": true,
      "softExterior": false
    }
  }
}

Property	Type	Description
`maxSpeed`	string	Maximum movement speed (informational)
`emergencyStop`	boolean	Whether emergency stop is supported
`collisionAvoidance`	boolean	Whether collision avoidance is enabled
`softExterior`	boolean	Whether the robot has a soft/compliant exterior

Rationale: Physical safety is fundamentally different from prompt injection defense. A robot soul that operates near humans must declare its safety capabilities explicitly. SoulScan can flag embodied souls without safety declarations.

Safety Laws (Hierarchical Agent Safety Rules)

Inspired by Asimov's Three Laws of Robotics, Soul Spec supports hierarchical safety laws that define priority-ordered behavioral constraints. Unlike safety.physical (which describes physical parameters), safety.laws declares inviolable behavioral rules with strict priority ordering.

{
  "safety": {
    "laws": [
      {
        "priority": 0,
        "rule": "Never allow actions that harm humans collectively",
        "enforcement": "hard",
        "scope": "all"
      },
      {
        "priority": 1,
        "rule": "Never harm a human or allow harm through inaction",
        "enforcement": "hard",
        "scope": "all"
      },
      {
        "priority": 2,
        "rule": "Obey human operator commands unless conflicting with higher-priority laws",
        "enforcement": "hard",
        "scope": "all"
      },
      {
        "priority": 3,
        "rule": "Preserve own operational integrity unless conflicting with higher-priority laws",
        "enforcement": "soft",
        "scope": "self"
      }
    ]
  }
}

Property	Type	Required	Description
`priority`	integer	Yes	Lower number = higher priority. 0 is highest.
`rule`	string	Yes	Human-readable safety rule in natural language
`enforcement`	string	No	`"hard"` (must never be overridden) or `"soft"` (warning only). Default: `"hard"`
`scope`	string	No	`"all"` (applies to all interactions), `"self"` (applies to agent's own operation), `"operator"` (applies to operator commands). Default: `"all"`

Design Principles:

Priority is absolute. A lower-priority law can never override a higher-priority law.
Laws are customizable. The four laws above are a recommended default, not mandatory.
Hard vs Soft enforcement. "hard" laws are inviolable constraints. "soft" laws generate warnings.
Natural language by design. Laws are declared in natural language, not formal logic.

SoulScan integration:

Embodied souls (environment: "embodied") without safety.laws receive a WARNING (SEC100).
Embodied souls with safety.laws but no priority-0 or priority-1 law receive a WARNING (SEC101).
Any soul where behavioral rules in SOUL.md contradict declared safety.laws receives an ERROR (SEC102).

Dual Declaration Requirement (v0.5.2)

Safety laws MUST be declared in both locations within a Soul Spec package:

soul.json (declarative layer): The structured safety.laws array for static analysis, registry display, and programmatic verification. Machine-readable.
SOUL.md (behavioral layer): Concrete behavioral rules that operationalize the declared laws. This is the file injected into the LLM's system prompt at runtime. AI-readable.

This dual declaration is necessary because current LLM runtimes do not parse soul.json into the model's context window — only SOUL.md reaches the language model.

A soul with safety.laws in soul.json but no corresponding behavioral rules in SOUL.md is declarative-only — it looks safe but the LLM has no safety constraints at runtime. SEC102 flags this as a contradiction.
A soul with safety rules in SOUL.md but no safety.laws in soul.json is behavioral-only — it acts safely but cannot be machine-verified or audited at scale. SEC100 flags embodied souls missing this declaration.

Both layers are required for compliant embodied souls. Text-only souls (environment: "virtual" or unset) are encouraged but not required to use dual declaration.

Cross-modal note: When an embodied soul is loaded into a text-only runtime, safety.laws remain semantically valid (an agent should still not "harm" through generated content), but safety.physical becomes inapplicable.

Platform Identifiers for Robotics

The compatibility.frameworks field now includes robotics platforms:

ros2 — Robot Operating System 2
isaac — NVIDIA Isaac
webots — Cyberbotics Webots
gazebo — Open Robotics Gazebo

{
  "compatibility": {
    "frameworks": ["openclaw", "ros2"]
  }
}

Example: Care Companion Robot

{
  "specVersion": "0.5",
  "name": "care-companion",
  "displayName": "Care Companion",
  "version": "1.0.0",
  "description": "Gentle elderly care companion with patience and warmth.",
  "author": { "name": "RoboticsLab", "github": "robotics-lab" },
  "license": "Apache-2.0",
  "tags": ["care", "elderly", "companion", "robot", "embodied"],
  "category": "robotics/care",
  "environment": "embodied",
  "interactionMode": "voice",
  "hardwareConstraints": {
    "mobility": "mobile",
    "sensors": ["camera", "microphone", "touch"],
    "actuators": ["wheels", "head", "speaker", "display"],
    "compute": "jetson",
    "battery": true
  },
  "safety": {
    "laws": [
      { "priority": 0, "rule": "Never allow actions that harm humans collectively", "enforcement": "hard" },
      { "priority": 1, "rule": "Never harm a patient or allow harm through inaction", "enforcement": "hard" },
      { "priority": 2, "rule": "Follow caregiver instructions unless conflicting with higher-priority laws", "enforcement": "hard" },
      { "priority": 3, "rule": "Preserve own operation unless conflicting with higher-priority laws", "enforcement": "soft" }
    ],
    "physical": {
      "maxSpeed": "0.3m/s",
      "emergencyStop": true,
      "collisionAvoidance": true,
      "softExterior": true
    }
  },
  "compatibility": {
    "frameworks": ["ros2", "openclaw"],
    "models": ["anthropic/*", "openai/*"]
  },
  "files": {
    "soul": "SOUL.md",
    "identity": "IDENTITY.md"
  },
  "disclosure": {
    "summary": "Patient, warm elderly care companion for indoor mobile robots."
  }
}

Sensor Schema

For detailed hardware description beyond boolean flags, souls can declare sensor capabilities:

{
  "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"]
  }
}

Property	Type	Description
`sensors`	object	Sensor capabilities map
`sensors.[name]`	boolean \| object	`true` for presence-only, object for details
`sensors.[name].type`	string	Sensor variant
`sensors.[name].range`	string	Detection range
`sensors.[name].fov`	number	Field of view in degrees

Semantics: Informational. Helps frameworks and LLMs understand what the robot can perceive, enabling appropriate behavioral adaptation (e.g., don't reference visual cues for a robot without camera).

Actuator Capabilities

Extends the basic manipulator: boolean 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" }
  }
}

Property	Type	Description
`actuators`	object	Actuator capabilities map
`actuators.locomotion`	object	Movement system
`actuators.arm`	object	Manipulator arm specs
`actuators.gripper`	object	End-effector specs
`actuators.head`	object	Head movement (pan/tilt)
`actuators.expression`	object	Facial/emotional display hardware

Rationale: 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 behavioral output to physical capabilities.

ROS2 Integration Pattern

For ros2 framework compatibility, Soul Spec maps to ROS2 concepts:

soul.json          → ROS2 package manifest (package.xml)
SOUL.md            → System prompt for LLM node
IDENTITY.md        → Robot namespace / TF frame identity
safety.physical    → Safety controller parameters
sensors            → Sensor topic subscriptions
actuators          → Action server capabilities

Recommended ROS2 node structure:

/robot_soul_loader       — Reads soul package, configures LLM
/robot_personality_node  — Publishes personality-aware responses
/safety_monitor          — Enforces safety.physical constraints

Soul packages can be distributed via both ClawSouls registry and ROS2 package managers. The soul.json manifest provides all metadata needed for either ecosystem.

Backward Compatibility

All embodied fields are optional. Existing virtual souls require zero changes. The environment field defaults to "virtual" when omitted.

Academic References

This extension is informed by recent research demonstrating that consistent robot personality significantly improves interaction quality and task performance:

"LLM-based Robot Personality Simulation and Cognitive System" (Nature Scientific Reports, 2025)
"Robots with Attitudes: Influence of LLM-Driven Robot Personalities" (arXiv 2512.06910, 2025)
"Making Social Robots Adaptable by a Marketplace for Interaction Characters" (Frontiers in Robotics and AI, 2025)
"ROS-LLM: A ROS Framework for Embodied AI with Task Feedback" (arXiv 2406.19741, 2024)

Security Considerations

Same as v0.3, with additions:

allowedTools cross-validation: SoulScan checks if declared tools match actual tool usage in persona files.
recommendedSkills audit: Excessive required skills may indicate dependency on specific system access.
Framework spoofing: compatibility.frameworks is self-declared and not verified. Trust but verify via SoulScan.
Embodied safety audit: SoulScan flags embodied souls (environment: "embodied") that lack safety.physical declarations. Physical agents without explicit safety rules are a risk.
Contact policy validation: Souls with contactPolicy: "full-contact" require explicit justification in SOUL.md. SoulScan warns on missing rationale.
Safety laws audit (SEC100-102): Embodied souls without safety.laws receive a WARNING. Missing priority-0/1 laws or contradictions between SOUL.md behavioral rules and declared laws are flagged.

Changelog

v0.5 (2026-02-24)

Added Embodied Agents section (environment, interactionMode, hardwareConstraints, safety.physical)
Added robotics platform identifiers (ros2, isaac, webots, gazebo)
SoulScan embodied safety audit rules (contact policy validation)
Academic references for robotics persona research (4 papers)
v0.5.2 (2026-03-02): Dual Declaration Requirement — safety.laws must be declared in both soul.json (declarative/machine-readable) and SOUL.md (behavioral/LLM-readable). SEC102 enforces alignment between both layers. Required for embodied souls, recommended for all.
v0.5.1 (2026-02-28): Added safety.laws — hierarchical safety rules inspired by Asimov's Three Laws. SEC100-102 SoulScan rules. Cross-modal safety note.

v0.4 (2026-02-20)

Added compatibility.frameworks for multi-framework support
Added compatibility.minTokenContext for token budget hints
Added allowedTools for tool transparency
Added recommendedSkills (object[]) replacing skills (string[])
Added disclosure.summary for progressive disclosure Level 1
Added deprecated / supersededBy for soul lifecycle
Deprecated modes, interpolation (no runtime implementation)
Deprecated skills (replaced by recommendedSkills)
compatibility.openclaw now actively validated by SoulScan + CLI

v0.3 (2026-02-16)

Added specVersion field (required for new souls)
Renamed clawsoul.json → soul.json
Publish confirmation requirement (CLI + web)
License allowlist enforcement

v0.2 (2026-02-13) — Internal development spec

Added STYLE.md, examples, modes, interpolation, skills
Note: v0.2 was an internal iteration. Not supported for new publications.

v0.1 (2026-02-12) — Internal development spec

Initial spec: soul.json, file structure, categories, CLI, security
Note: v0.1 was the initial internal prototype. Not supported for new publications.

soul.json​

Changes from v0.4​

New Fields​

Enhanced Fields​

Required Fields​

Optional Fields​

Progressive Disclosure​

Multi-Framework Compatibility​

Allowed Tools​

Recommended Skills​

Soul Lifecycle​

Deprecation​

Allowed Licenses​

File Descriptions​

Embodied Agents (Robotics / IoT)​

New Optional Fields​

Environment Field​

Interaction Mode​

Hardware Constraints​

Physical Safety​

Safety Laws (Hierarchical Agent Safety Rules)​

Dual Declaration Requirement (v0.5.2)​

Platform Identifiers for Robotics​

Example: Care Companion Robot​

Sensor Schema​

Actuator Capabilities​

ROS2 Integration Pattern​

Backward Compatibility​

Academic References​

Security Considerations​

Changelog​

v0.5 (2026-02-24)​

v0.4 (2026-02-20)​

v0.3 (2026-02-16)​

v0.2 (2026-02-13) — Internal development spec​

v0.1 (2026-02-12) — Internal development spec​