RFC: Soul Spec v0.6 — SOUL.md as the only required file + custom extras

[TomLeeLive]

Summary

Soul Spec v0.6 proposes a significant shift: SOUL.md is the only required file. Everything else becomes optional.

We're opening this discussion to gather community feedback before finalizing the spec.

Key Changes in v0.6

1. Minimal Soul — Just SOUL.md

Currently (v0.5), a valid Soul Pack requires soul.json + SOUL.md at minimum. In v0.6:

• SOUL.md is the only required file
• soul.json can be auto-generated by platforms (parsed from SOUL.md's title, first paragraph, keywords)
• Lower barrier to entry: drop a single markdown file and you have a persona

2. File Tier System

Tier	Files	Required?
Tier 1 (Core)	soul.json, SOUL.md	soul.json can be auto-generated
Tier 2 (Standard)	IDENTITY.md, AGENTS.md, STYLE.md, HEARTBEAT.md, README.md	Optional
Tier 3 (Extensions)	RULES.md, TOOLS.md, USER.md, SYNC.md, custom .md/.yaml/.json	Optional

3. Custom Files (Extras)

Creators can include any .md, .yaml, or .json file in their Soul Pack. Examples:

• TOOLS.md — tool boundaries and permissions
• USER.md — user calibration profiles
• RULES.md — behavioral rules and constraints
• exports/CLAUDE.md — platform-specific exports
• Custom workflow definitions, skill files, etc.

4. Shell Scripts (Conditional)

.sh files are allowed only if they pass SoulScan static analysis:

• Scanned for: rm -rf, sudo, curl|bash, eval, env variable leaks
• Flagged with "Contains executable scripts" badge on platform
• Download warning dialog + ToS disclaimer
• Separate Script Safety sub-grade

5. Size Limits

• Individual extra file: 100KB
• Total extras: 1MB

Questions for the Community

1. Minimal Soul: Is SOUL.md-only the right minimum? Or should soul.json remain required?
2. Tier placement: Should RULES.md be Tier 2 (standard) instead of Tier 3 (extension)?
3. Shell scripts: Should .sh files be allowed at all, even with static analysis? Or should we keep it to .md/.yaml/.json only?
4. Size limits: Are 100KB per file / 1MB total reasonable for extras?
5. Auto-generated soul.json: What fields should platforms extract from SOUL.md? Current proposal: name, description, tags, category, specVersion, author.
6. Custom file conventions: Should we recommend naming conventions for common use cases (e.g., TOOLS.md for tool boundaries)?

Context

• Soul Spec v0.5 (current)
• Soul Spec Documentation

What's Next

We plan to finalize v0.6 based on community feedback and internal testing. If you're building with Soul Spec or have opinions on AI agent persona standards, we'd love to hear from you.

[iamevandrake]

I agree with your direction.
At Soulcraft Agency, we're helping companies with their soul.md files:

1. I'd say soul.md-only is the minimum, and soul.json is not required.
2. I like rules.md as a tier 3.
3. I'd keep it to .md/ .yaml/ .json only. Else, I would imagine you start creating more security vulnerabilities.
4. I'm noticing that the Claude 4.5 Soul file is ~684K. I'd make it 1MB.
5. Core character traits could be helpful.
6. Yes, recommendations would be good.

[TomLeeLive]

Thanks for the thoughtful feedback, Evan! Really appreciate you taking the time.

Great points across the board:

1. SOUL.md-only minimum — agreed, this is the direction we're going. soul.json will be auto-generated by platforms.
2. RULES.md Tier 3 — noted. We'll keep it there and promote if adoption grows.
3. .sh exclusion — makes sense. We are considering this. but we have SoulScan for scanning static file.
4. Size limit → 1MB per file — great call. 684KB for a Claude 4.5 soul is a real data point. We'll bump the per-file limit to 1MB (total extras stays at 5MB).
5. Core character traits — interesting idea. Could be a standard section in SOUL.md or a field in auto-generated soul.json.
6. Naming conventions — we'll document recommended names (RULES.md, TOOLS.md, USER.md, etc.) in the spec.

Curious — have you tried the ClawSouls CLI (npx clawsouls) or SoulScan for validating soul files? Would love to hear how it fits into your workflow at Soulcraft.

Thanks again for being an early contributor to the spec!