[Agent refactor] AGENT.md frontmatter extension: soul link, memory, on_handoff

[yinwm]

Background

Follow-up from #1218 and #1705.

The structured AGENT.md format was merged in #1705, but some frontmatter fields from the original design are not yet implemented.

---

Missing Fields

1. soul field (explicit link)

The original design proposed a soul field to create an explicit, traceable link between AGENT.md and SOUL.md:

---
name: pico
soul: ./SOUL.md  # or a path like ../shared/souls/default.md
---

Current behavior: Hardcoded to read SOUL.md from the same directory.

Proposed behavior:

• If soul is specified, load from that path
• If not specified, fallback to ./SOUL.md (backward compatible)
• Enables multiple agents to share a single soul file

---

2. memory field

Configuration for agent memory behavior. Questions to discuss:

• What memory-related settings should be configurable?
• Max memory size? Retention policy? Compression strategy?
• Or is this better handled elsewhere?

---

3. on_handoff field

Behavior when this agent is invoked/handed off to from another agent. Questions:

• What should happen when a parent agent spawns this agent?
• Should there be a standard handshake protocol?
• What context should be passed?

---

Discussion Points

1. Priority: Which of these fields are most needed right now?
2. Scope: Should these be in AGENT.md frontmatter or in a separate config file?
3. Compatibility: How do we ensure changes don't break existing workspaces?

---

Related

• [Agent refactor]what an Agent is #1218 - Original agent definition design
• Feat/issue 1218 agent md context structure #1705 - Structured AGENT.md implementation (merged)
• [Agent refactor] Context management: boundaries, compression, and token budgeting #1439 - Context management (related to memory)