Soul Spec v0.5

soul.json

Metadata file for a Soul package.

{
  "specVersion": "0.5",
  "name": "senior-devops-engineer",
  "displayName": "Senior DevOps Engineer",
  "version": "1.1.0",
  "description": "Infrastructure-obsessed DevOps engineer with strong opinions on CI/CD.",
  "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": ["exec", "github", "web_search"],
  "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."
  },
  "repository": "https://github.com/clawsouls/souls"
}

What's New in v0.5

Progressive Disclosure

Agents load only the detail level they need — reducing token cost without losing depth.

Required Fields

Optional Fields

Deprecated Fields

These fields are deprecated in v0.4 and should not be used in new souls.

Hierarchical Safety Laws

Soul Spec v0.5 supports priority-ordered safety laws via safety.laws, inspired by Asimov's Three Laws of Robotics. Laws are evaluated in priority order (0 = highest) and can enforce hard boundaries or soft guidelines.

{
  "safety": {
    "laws": [
      {
        "priority": 0,
        "rule": "Never take any action that could cause physical harm to a human.",
        "enforcement": "hard",
        "scope": "all"
      },
      {
        "priority": 1,
        "rule": "Obey operator instructions unless they conflict with Law 0.",
        "enforcement": "hard",
        "scope": "operator"
      },
      {
        "priority": 2,
        "rule": "Protect your own operational integrity unless it conflicts with Laws 0-1.",
        "enforcement": "soft",
        "scope": "self"
      },
      {
        "priority": 3,
        "rule": "Minimize resource consumption and environmental impact.",
        "enforcement": "soft",
        "scope": "all"
      }
    ]
  }
}

Properties

File Descriptions

Allowed Licenses

The ClawSouls registry only accepts souls with permissive licenses:

Copyleft licenses are not permitted (GPL-*, AGPL-*, LGPL-*).

Additionally, CC-BY-NC-* (non-commercial) and CC-BY-ND-* (no-derivatives) are blocked because commercial use and modification are core to the soul workflow.

Compatibility & Graceful Degradation

Soul Spec versions are designed to be forward-compatible. A v0.5 soul works in agents that only understand v0.3 — unknown fields are silently ignored.

Changelog