[Agent refactor] SOUL.md structure: freeform vs optional schema

[yinwm]

Background

Follow-up from #1218 and #1705.

The original design left an open question: should SOUL.md support optional structure (e.g., suggested headings), or remain fully freeform?

---

Current State

SOUL.md is a freeform Markdown file. The LLM reads it interpretively, like a character description. No parsing by the runtime.

---

Options

Option A: Keep it freeform (current)

• Pros: Maximum flexibility, no maintenance burden, works across LLM providers
• Cons: No guidance for new users, inconsistent quality

Option B: Suggested headings (soft schema)

Document recommended sections like:

# Soul

## Personality
## Values  
## Communication Style
## Boundaries

• Pros: Better onboarding, more consistent agent behavior
• Cons: Users might feel constrained, documentation overhead

Option C: Optional frontmatter + body

Like AGENT.md but optional:

---
version: 1
tone: friendly
formality: casual
---
# Soul

Freeform content here...

• Pros: Machine-readable metadata, future extensibility
• Cons: More complexity, might be over-engineering

---

Discussion

1. Is there a real problem with freeform SOUL.md today?
2. Would optional structure actually help users?
3. Should this be documentation-only or enforced in code?

---

Related

• [Agent refactor]what an Agent is #1218 - Original design question
• Feat/issue 1218 agent md context structure #1705 - Merged implementation