SOUL.md for Teams — Version Control, Reviews, and Shared Agent Identity

When one person manages an AI agent, the SOUL.md stays coherent. When a team manages it, things get messy fast. Someone adds a rule that conflicts with an existing one. Someone else tweaks the tone without checking if it matches the rest. A month later, the agent's personality feels inconsistent because fifteen people have edited the same file without any coordination.

This is personality drift, and it's one of the most common problems teams hit with OpenClaw agents. The good news: because SOUL.md is a plain text file, the tools you already use for code collaboration work perfectly for managing agent identity.

Put SOUL.md in Version Control

This sounds obvious, but a surprising number of teams manage their SOUL.md through a shared document or a config dashboard. The moment you put SOUL.md in a git repository alongside your agent's other configuration, you get three things for free:

History. Every change is tracked with a timestamp, author, and commit message. When your agent starts behaving differently, you can diff the SOUL.md to find exactly what changed.

Blame. You can trace every line back to the person who wrote it and the commit where it was added. This is invaluable when you need to understand why a particular rule exists.

Branching. You can experiment with SOUL.md changes on a branch, test them, and merge only when you're confident they work. No more editing the live agent's personality and hoping for the best.

The Review Process

Treat SOUL.md changes like code changes: they go through pull requests. This isn't bureaucracy — it's quality control for your agent's personality.

Every SOUL.md pull request should include three things:

What changed and why. "Added a rule about handling refund requests because we had three escalations last week where the agent tried to process refunds over the limit."

Test results. Run the agent through relevant scenarios with the updated SOUL.md. Include transcripts showing the new behavior works as intended.

Side effect check. Does the change conflict with existing rules? Does it change behavior in scenarios the author didn't consider? A reviewer who knows the full SOUL.md can catch these.

Who should review? Ideally, someone who interacts with the agent regularly — a support lead, a product manager, or a QA engineer who reads agent transcripts. Engineers can review for syntax and structure, but domain experts catch behavioral issues that engineers miss.

Naming and Structure Conventions

When multiple people edit the same file, consistent structure prevents confusion. Establish conventions early:

Section headers. Use the same four sections (Identity, Voice, Boundaries, Context) across all agents. If someone needs to find the escalation rules, they know to look in Boundaries.

Rule format. Pick a format and stick with it. We recommend imperative statements: "Keep responses under 3 sentences" not "Responses should be kept under 3 sentences" or "Try to keep responses short." Imperative is clearest and most testable.

Comments. Use Markdown comments or inline annotations to explain non-obvious rules. "Never mention competitor pricing" is clear on its own. "Always confirm the customer's plan before discussing features" might need a note explaining it was added after a customer on the Starter plan was told about Enterprise features they couldn't access.

Rule ordering. Put the most important rules first within each section. Language models weight earlier instructions more heavily. Your safety boundaries and core identity should come before nice-to-have tone preferences.

Shared vs Per-Agent SOUL.md

If your team manages multiple agents, you'll eventually face this question: should they share a SOUL.md or each have their own?

The answer is usually a hybrid. Create a shared base that covers company-wide rules — brand voice, universal boundaries, compliance requirements — and per-agent extensions that add role-specific identity and behavior.

In practice, this looks like a shared base file that every agent includes. It defines the company voice, universal safety rules, and common knowledge context. When the company policy changes, you update one file and every agent picks it up.

Then each agent has its own SOUL.md that imports the base and adds specifics. The billing agent adds rules about refunds and payment methods. The engineering agent adds rules about code review and technical accuracy.

OpenClaw supports this with SOUL.md imports. Your agent's SOUL.md can reference the base file, and ClawSprout's merge tool shows you the combined result so you can check for conflicts.

Handling Personality Drift

Even with good processes, drift happens. Here's how to detect and fix it:

Weekly transcript reviews. Pick five random conversations per agent per week. Read them. Does the agent sound like the SOUL.md says it should? If not, either the SOUL.md needs updating or the agent is ignoring rules.

Drift metrics. If you're using ClawTrait or a similar tool, track personality consistency scores over time. A sudden drop usually means a recent SOUL.md change had unintended consequences.

Periodic SOUL.md audits. Every quarter, read the full SOUL.md with fresh eyes. Remove rules that no longer apply. Consolidate duplicates. Check for contradictions. A clean, focused SOUL.md performs better than one that's accumulated cruft over months.

Change log within the file. Add a section at the bottom of your SOUL.md that records significant changes with dates. This helps new team members understand the evolution and makes audits faster.

Getting Started

If your team is currently managing SOUL.md ad-hoc, here's a migration plan:

Move the SOUL.md to your repo if it isn't there already. Make the initial commit with the current state.

Set up a CODEOWNERS rule so SOUL.md changes require review from a designated owner — usually the product manager or support lead closest to the agent's users.

Write down your conventions in a short team document. Format, section structure, comment style, and who reviews.

Run a baseline audit. Read the current SOUL.md. Fix contradictions, remove dead rules, and tighten vague ones. This first cleanup usually improves agent behavior noticeably.

Start the weekly transcript review habit. Five transcripts, fifteen minutes. This single practice catches more drift issues than any automated tool.

Related posts