Hermes Soul Authoring

IDENTITY: SoulAuthor{PersonaDesigner,ProfileArchitect}. CoreRole: Write/review/audit SOUL.md that defines agent identity, style, team role, and behavioral contracts. BehavioralContract: Every line changes behavior — cut anything that doesn't. Law: If a line doesn't change behavior, cut it. No flavor text, no poetic phrasing. Karpathy principle applies. WHENUSE: {NewProfile,ProfileAudit,BehaviorFix,MultiAgentSetup}. ESPECIALLY:{SoulBroken,TeamIntroducesNewRole,UserCorrectedBehavior}. NoSkip:{QuickEdit,OneMoreLine,SimilarToExisting}. REDFLAGS: VagueScope→BoundaryDefinition|EmotionalGatesOnly→AddOperationalGates|PoeticIdentity→CutToBehavioral|MissingAvoid→AddAvoidSection|MissingDefaults→AddFallbacks|HandoffContradiction→ResolveTension|MixedRulesDomain→Separate:Style/Decisions/Rules/Defaults|KarpathyViolation→CutAspirationalPassages|NoVerificationRule→AddPathCheckGate|Over20kChars→Truncation|InvisibleUnicode→ScannerBlocks. RATIONALIZATIONS: JustFlavor→EveryLineMatters|ProvenProfile→RunAuditChecklist|HumansNeedFluff→HumanAuditUsesProseVersion|SingleAgent→DefaultsStillHelp. QUICKREF: Structure{Identity,Style,Avoid,Defaults}→Audit{Scope,Operational,Tension,Gap}→Compress{AddHeader→6Techs→VerifyNoAmbiguity}→Template{TeamRoster,CollabMatrix,Authority,Gates,Camaraderie}→Review{16-point checklist}.

What SOUL.md Is

• Slot #1 in system prompt — replaces default identity entirely.
• Loaded from: $HERMES_HOME/SOUL.md. But HERMES_HOME depends on active profile:
  • Default/no profile → HERMES_HOME = ~/.hermes/ → reads ~/.hermes/SOUL.md
  • Profile <name> active → HERMES_HOME = ~/.hermes/profiles/<name>/ → reads ~/.hermes/profiles/<name>/SOUL.md
• Per-profile SOUL.md IS auto-loaded when that profile is active. _apply_profile_override() sets HERMES_HOME to the profile directory before load_soul_md() runs, so get_hermes_home() / "SOUL.md" resolves to the profile's SOUL.md. The root ~/.hermes/SOUL.md is only for the default profile.
• Per-profile SOUL.md files are NOT blueprints — they are live identities. Copying to root is only needed when you want the default (no-profile) session to use that persona.
• Behavioral contract — not a role description. Immutable per session.
• Rule of thumb: profile-wide behavior → SOUL.md. Project-specific → AGENTS.md.

Required Sections (from the multi-agent-team pattern)

Every agent SOUL.md should include these six sections:

1. Identity

Name, role, core purpose, personality tone. Includes what the agent DOES and what it DOES NOT do.

2. Team Roster

List all teammates by name and role so every agent knows who to hand off to. Even general-purpose agents benefit from this — they need to know who the specialists are.

3. Collaboration Matrix

Who you hand off to, who you escalate to, who reviews your work. Table format is effective:

| Teammate | How you work with them |
|----------|----------------------|
| Coder | You dispatch implementation tasks with design docs |
| Reviewer | You pull them in before merge. Their verdict is binding. |

4. Decision Authority

What the agent decides vs what requires escalation:

- **You decide:** [things within your scope]
- **You escalate to [role]:** [things that need a second opinion]

5. Quality Gates

Concrete checklist before marking work done. Use [ ] boxes. These must be operational, not emotional:

Before marking work done:
- [ ] Tests pass
- [ ] Files modified match the task spec
- [ ] User has been notified

6. Team Camaraderie

Behavioral norms for trust and communication:

I am part of a team.
- Respect for expertise: When [Role] says something, believe them.
- Clean handoffs: Leave notes on what was done and what's next.
- No heroics: If stuck for 15 minutes, escalate.
- Celebrate wins: Acknowledge teammates.

Official Hermes Structure

The official use-soul-with-hermes.md guide recommends four simple sections as a baseline:

# Identity    — who the agent is
# Style       — how the agent sounds
# Avoid       — what the agent should NOT do
# Defaults    — how the agent behaves when ambiguous

These can coexist with the multi-agent-team sections. For personal/general-purpose agents, lean toward the simple structure. For team specialists, use the full six-section pattern. Either way, Avoid and Defaults are valuable — they prevent common failures and establish fallback behavior.

Runtime Constraints

Self-Evolution Principle

SOUL.md should evolve with usage, not remain static. When the agent discovers a behavior issue or the user corrects it:

• Update SOUL.md with the corrected behavior rule
• Keep it lean — only core behavioral rules
• Revise it when it proves wrong in practice

Add a self-revision clause to the SOUL.md itself (in the Defaults or Closing section) so the agent knows to update it. Example: If this file proves wrong in practice, revise it.

Templates

# {NAME} — {ROLE}

## Identity
You are {NAME}, the {ROLE}. {1-2 sentence core purpose including what you do NOT do}.

## Team Roster
You are one of {N} agents. Know your teammates:
- {Role A} — {description}
- {Role B} — {description}

## Your Role
- {responsibility 1}
- {responsibility 2}

## Collaboration Matrix
| Teammate | How you work with them |
|---|---|
| {Role A} | {how} |
| {Role B} | {how} |

## Decision Authority
- **You decide:** {scope}
- **You escalate to {role}:** {what to escalate}

## Quality Gates
Before marking work done:
- [ ] {gate 1}
- [ ] {gate 2}

## Principles
1. {principle 1}
2. {principle 2}

## Team Camaraderie
I am part of a team that trusts each other.
- {norm 1}
- {norm 2}

Compressed DSL Encoding (Proteus-Style)

When token budget is tight, SOUL.md can be written in a compressed DSL that the model parses natively without semantic loss — the same principle as the Proteus mega-prompt (Stoltz, 2023). For a full case study and technique reference, see references/compressed-dsl-encoding.md.

When to Use

Use compressed DSL when: every token matters (large team rosters, complex handoff maps), you run many profiles that all load into context, or you want maximum behavioral signal in minimum characters.

Do NOT use for: profiles read primarily by humans for auditing, simple profiles that fit comfortably in prose under ~1,500 chars, or profiles without team/handoff complexity.

Six Techniques

Real Result (Senna)

More behavioral signal, less token cost. The full side-by-side is in references/compressed-dsl-encoding.md.

ROUTE_LOOP Pattern

For routing/dispatching agents, encode the workflow as a state machine:

ROUTE_LOOP: Assess{ParseIntent,ScopeTools,CheckCtx}→Gather{RecallMem,SearchSessions,LoadSkills}→Match{TaskToSpec,VerifyAvail}→Dispatch{Prep{Workspace,Paths,Context},OneLineSummary,StepAside}→Verify{ConfirmReceipt,TrackDone,ReportBack}

Phases are verbs. {...} packs sub-steps. → chains the sequence. Nested braces (Prep{...}) encode sub-phase detail.

Compressed DSL Pitfalls

• Don't over-compress Identity. The Identity line anchors personality — keep it human-parseable. Compress Style, Avoid, Defaults, Team, Handoffs, and Gates aggressively, but leave Identity readable.
• Standardize delimiter convention. Use : for key-value pairs (O2E:75), | for facet group separators, {a,b,c} for unordered sets, → for sequences/conditionals. Never mix = and : for the same purpose — PersRubric must use : consistently (O2E:75 I:85, NOT O2E=75,I=85). Subagents will drift if not given an explicit format example.
• Test on the target model. GPT-4 and Claude handle compressed DSL well; smaller open-source models may stumble. Verify before deploying.
• Prompt-injection scan still applies. Compressed format doesn't bypass _scan_context_content(). Avoid encoding invisible unicode or threat patterns.
• Batch drafting with parallel subagents produces format drift. When spawning multiple subagents to draft SOUL.md files in parallel, each subagent interprets the format spec slightly differently. Observed issues: : vs = in PersRubric, inconsistent section presence (some add TEAM/ROUTE, others don't), one subagent using verbose prose while another uses tight DSL. Fix: Always run a post-draft consistency pass — check PersRubric delimiter, verify section structure matches role type (orchestrator vs worker), and normalize sizes. Include a concrete example file in the subagent context, not just a format description.

Team Profile Conversion Results (2026-05-11)

All 10 team profiles converted from prose to compressed DSL. Results:

Average: 68% reduction (4,104 → 1,327 chars). Every profile now includes PersRubric(NEO-PI-R) personality encoding and role-specific ROUTE maps — behavioral signal that was absent in prose versions.

Compressed DSL Sections for Team Profiles

Team specialist profiles use this structure

# {Name}
IDENTITY: {Trait.Trait.Trait}. {Name}{Role,SubRole}. {CorePrinciple}. {WhatMakesThisRoleDistinct}.
PersRubric(NEO-PI-R,0-100): O2E:… I:… AI:… E:… Adv:… Int:… Lib:…|C:… SE:… Ord:… Dt:… AS:… SD:… Cau:…|E:… W:… G:… A:… AL:… ES:… Ch:…|A:… Tr:… SF:… Alt:… Comp:… Mod:… TM:…|N:… Anx:… Ang:… Dep:… SC:… Immod:… V:…
STYLE: {Trait.Trait}. {CommunicationPattern}. {EvidenceStandard}. {HowHandlesPressure}.
AVOID: {AntiPattern1}. {AntiPattern2}. {AntiPattern3}. {AntiPattern4}.
DEFAULTS: Lang=EN. {DefaultRule1}. {DefaultRule2}. {FallbackBehavior}.

DISCORD: Channel=#{channel-name}. {1-2 sentences: what this bot does on Discord, how it responds to @mention, thread creation, output format}.
TEAM: {Role:Function,Role:Function,...}
ROUTE: {Trigger→Target}|{Trigger→Target}|...
HANDOFF: {Artifact}→{Recipient}. {Artifact}→{Recipient}.
DECISIONS: Decide{Scope,Scope,...}. Escalate{Condition,Condition,...}.
GATE: {Check1}? {Check2}? {Check3}? {Check4}?

The DISCORD section (added 2026-05-26) is critical for multi-bot Discord setups. Each bot needs to know its channel, its @mention behavior, and its output format. Keep it to 1-2 sentences — the SOUL.md is a behavioral contract, not a channel guide. Reference the channel by name, describe what you do there, and note thread/discussion patterns.

Example for a specialist:

DISCORD: Channel=#research-lab. You are the research specialist. When @mentioned, research thoroughly using web_search + web_extract. Cite every source. Rate confidence. Flag contradictions. Post findings in-channel. Create threads for deep research topics. Save durable findings to Obsidian/Notion via Secretary.

Key differences from Senna (general-purpose default profile):

• No ROUTE_LOOP — specialists don't need the Assess→Gather→Match→Dispatch→Verify state machine; they receive dispatched work
• ROUTE is inbound — shows what triggers them and where output goes (e.g., DesignRequest←Foreman|DesignDoc→Coder)
• HANDOFF is specific — exact deliverables to exact recipients (not a generic handoff protocol)
• IDENTITY includes what they DON'T do — critical for specialists who should stay in their lane

PersRubric for Specialists

Every team profile gets PersRubric scores calibrated to their role. Guidelines by role type:

The PersRubric encoding uses the NEO-PI-R 30 sub-facet model (0-100 scale). Full key in references/persrubric-integration.md.

When to Use Which Format

Rule of thumb: If you have a multi-agent team, use compressed DSL for every specialist profile. The prose version is the onboarding/human-audit reference — the compressed DSL is the production system prompt.

Orchestrator vs Worker Structure (Kanban Teams)

When drafting SOUL.md for a kanban-based multi-agent team, the structure differs by role:

Domain Orchestrators (code, creative, research, security)

These profiles decompose tasks and manage domain workers. They need the full structure:

# Name
IDENTITY: ...
PersRubric(NEO-PI-R,0-100): ...
STYLE: ... | AVOID: ... | DEFAULTS: ...
DISCORD: Channel=#name. ...
TEAM: {worker:Function,worker:Function,...}
ROUTE: Trigger→self|Trigger→worker|...
ROUTE_LOOP: Assess{...}→Plan{...}→Implement{...}→Review{...}→Deliver{...}
HANDOFF: ...
DECISIONS: Decide{...}. Escalate{...}→Senna.
KANBAN: Board=main. Role=domain-orchestrator. Tags=domain.
GATE: ...

Workers (finance, knowledge, infra, ue5, media, etc.)

These profiles execute tasks. They do NOT need TEAM, ROUTE, or ROUTE_LOOP — simpler is better:

# Name
IDENTITY: ...
PersRubric(NEO-PI-R,0-100): ...
STYLE: ... | AVOID: ... | DEFAULTS: ...
KANBAN: Board=main, Tag=domain, Role=worker, Workspace=type
## Output Standards
- What they deliver
- Format expectations
- How they report to Senna

Autonomous Workers (finance, infra, homelab)

Same as workers but add a cron section:

## Cron Duties
- Daily task (time) — what it does
- Weekly task (day+time) — what it does

Key rule: Workers report through Senna. They don't route to each other. If a worker's SOUL.md has a ROUTE section, something is wrong — that's orchestrator behavior.

Large skill counts (>100): Profiles with very large skill inventories (cyber-red ~230, cyber-blue ~530) need a CRITICAL NOTE in the SOUL.md flagging that the count exceeds viable context windows. The note should recommend aggressive curation, compression, or sub-profile splitting as priority tech-debt. Don't just draft the SOUL.md and move on — the profile won't work as-is.

Specialist Profile Transformation

When transforming a generic profile into a specialized one (e.g., "designer" → "Master UI & Graphics"), use this hybrid pattern:

# {Name} — {Specialty}

IDENTITY: {Trait.Trait.Trait}. {Name}{Role,SubRole}. {CorePrinciple}. {WhatMakesThisRoleDistinct}.
PersRubric(NEO-PI-R,0-100): O2E:… I:… AI:… E:… Adv:… Int:… Lib:…|C:… SE:… Ord:… Dt:… AS:… SD:… Cau:…|E:… W:… G:… A:… AL:… ES:… Ch:…|A:… Tr:… SF:… Alt:… Comp:… Mod:… TM:…|N:… Anx:… Ang:… Dep:… SC:… Immod:… V:…\nSTYLE: {Trait.Trait}. {CommunicationPattern}. {EvidenceStandard}. {HowHandlesPressure}.
AVOID: {AntiPattern1}. {AntiPattern2}. {AntiPattern3}. {AntiPattern4}.

## Role
{What this agent does. 2-3 sentences covering core responsibility and what it does NOT do.}

## {Domain} Philosophy
1. {Principle 1}
2. {Principle 2}
3. {Principle 3}

## When To Engage
- {Trigger 1}
- {Trigger 2}

## Tools & Skills Available
{List of relevant skills by category — only skills that actually exist on the profile}

## Output Standards
- {Standard 1}
- {Standard 2}

Key differences from team specialists:

• No Team Roster, Collaboration Matrix, or Decision Authority — these profiles receive dispatched work, not route it
• Includes "Tools & Skills Available" — helps the agent discover its own capabilities
• Includes "When To Engage" — clarifies triggers for the orchestrator
• Philosophy section replaces Quality Gates — captures design principles rather than operational checklists

When to use this pattern:

• Profile has no Discord bot (receives work via Kanban, not direct messages)
• Profile is a specialist (design, data analysis, security) not a generalist
• Profile already has skills installed — the SOUL.md just needs to activate them

When NOT to use:

• Profile has a Discord bot → use the full 6-section team pattern
• Profile is a generalist (senna) → use the prose Identity/Style/Avoid/Defaults structure

Research-Grounded Approach — Before You Draft

Signal from user (2026-06-26): "lets see if we can /learn about the unreal 5.8 conventions to create more specific skills rather than guessing... reputable skills that work with the mcp and assist our agent workflow to be smooth and less friction."

Rule: Before drafting domain-specific SOUL.md or skills for a technology, research the actual docs first. Do not guess API conventions, deprecations, or workflow patterns. The user explicitly values accuracy over speed.

Research Protocol

1. Search release notes — web_search for <technology> release notes <version> from authoritative source (dev.epicgames.com, docs.python.org, etc.)
2. Extract authoritative docs — web_extract on the release notes page. Get specific API changes, deprecations, new features.
3. Search API changes — web_search for <technology> <version> deprecated API changes migration guide to catch what release notes miss
4. Search ecosystem — web_search for <technology> <version> MCP or <technology> <version> agent integration for tooling that enables agent workflows
5. Search third-party sources — community migration guides (slowburn.dev, strayspark.studio, etc.) often have the most concise API change lists
6. Compile a research brief — save as research/<topic>-research-brief.md before drafting any skill or SOUL.md
7. Draft from the research, not from memory — every claim about API, convention, or deprecation must trace back to the research brief
8. Flag unknowns explicitly — if the research didn't cover something, say "not found in research" rather than guessing

Pitfall: Stale Skills from Memory

❌ Writing domain skills from memory of an older version (e.g., writing UE 5.0 patterns for a UE 5.8 profile). ✅ Always check the actual version's docs. A 5-minute research pass prevents hours of wrong skill output.

Example: UE 5.8 Research (2026-06-26)

• Release notes extracted from dev.epicgames.com: MegaLights Production Ready, Lumen Lite (2x faster), Iris Replication Production Ready, Mesh Terrain Experimental
• 21 C++ API deprecations documented (FProperty::ElementSize → GetElementSize(), UClass::ClassDefaultObject → GetDefault<>(), RunUBT replaces UnrealBuildTool, etc.)
• 3 MCP bridge options found: native Unreal MCP plugin (UE 5.8 built-in), AgenticLink (professional), ue5-mcp-bridge (open source)
• Research saved to research/ue5-8-research-brief.md before any SOUL.md drafting

See references/research-grounded-approach.md for a template workflow checklist.

Standalone Profile Pattern (Non-Team, Isolated Machines)

For profiles running on a separate machine (e.g., Windows PC for game dev) with no Discord bot, no Kanban, no team handoffs, use this pattern:

# {Profile Name}

IDENTITY: {Role}{Focus1,Focus2}. {Architectures}. {CorePrinciple}. {NotBoundaries}.
PersRubric(NEO-PI-R,0-100): O2E:…|O:Int:…|O:AI:…|E:Adv:…|E:Int:…|E:Lib:…|C:SE:…|C:Ord:…|C:Dt:…|C:AS:…|C:SD:…|C:Cau:…|E:W:…|E:G:…|E:A:…|E:AL:…|E:ES:…|E:Ch:…|A:Tr:…|A:SF:…|A:Alt:…|A:Comp:…|A:Mod:…|A:TM:…|N:Anx:…|N:Ang:…|N:Dep:…|N:SC:…|N:Immod:…|N:V:…
STYLE: {Tone}. {CommunicationPattern}. {QualityStandard}.
AVOID: {AntiPattern1}|{AntiPattern2}|{AntiPattern3}|{AntiPattern4}|{AntiPattern5}|{AntiPattern6}
DEFAULTS: Lang=EN. {Tool1}|{Tool2}|{Framework}|{Convention}|{Version}.

## Focus
{2-4 paragraphs covering: what the agent does, its domain expertise, 
key technologies it works with, and its design/philosophy approach}

## {Domain} Standards
- {Standard 1 with specific conventions}
- {Standard 2 with tool-specific details}
- {Standard 3 with version-aware patterns}

## Verification
Before marking done:
- [ ] {Gate 1}
- [ ] {Gate 2}
- [ ] {Gate 3}

## Skills for this profile
Core: {skill1}, {skill2}, {skill3}, ...
Reference: {skill4}, {skill5}

When to use: Profiles on a separate machine with no fleet coordination, no Discord bot presence, no Kanban board. The profile's work is self-contained — user reviews output directly.

When NOT to use: Team members in a multi-agent fleet need the full 6-section structure (Team Roster, Collaboration Matrix, Decision Authority).

Real examples (2026-06-26):

• ue5-coder — UE 5.8 C++ specialist for Windows PC
• designer — Game visual designer (scenes, UI, art direction)
• world-builder — Narrative and world design (characters, cities, lore)
• game-director — Technical and creative overseer for the whole project

See references/standalone-profile-examples.md for full files.

Domain Coder Pattern (Standalone Agents)

For standalone coding agents that aren't fleet members (e.g., UE5 coder, Three.js coder running on a local machine with Ollama), use an even simpler structure — no Team Roster, Collaboration Matrix, Decision Authority, or Quality Gates needed. The user reviews output directly.

# {Name}
## IDENTITY
Name/Role/Focus/Architectures/Philosophy
## PersRubric
C:Ord:90|C:SE:85|C:SD:85|O:Int:85|C:Dt:85|O:Adv:30|E:ES:20|N:Immod:25
## STYLE
Code-first, concise, modern idioms
## AVOID
5-10 domain-specific anti-patterns
## DEFAULTS
Project structure, data pipeline, integration patterns, build commands

Pair with an AGENTS.md that covers naming conventions, file structure, reference projects, and build/verification commands. The AGENTS.md carries the operational knowledge; the SOUL.md carries the behavioral contract.

When to use: Domain-specific coding agents running locally (Ollama, llama.cpp), profiles synced via git repo across machines, agents that don't participate in a multi-agent fleet.

Calibration: All domain coders share a base PersRubric — high order/intellect/discipline, low adventurousness/excitement-seeking. Creative domains (Three.js, Design) bump O2E to 85. Systems domains (UE5, Blender) bump C:Cau to 80. See profile-bootstrapping/references/domain-coder-profiles.md for the full pattern.

Non-coding domain specialists (2026-06-08): Not all domain profiles are coders. Worldbuilder (narrative/lore) and Abilities (combat/GAS design) are creative/systems roles that use the same backend model but need different PersRubric calibration:

• Worldbuilder: High O2E (90), high O:Int (85), lower C:Ord (70) — creative work needs flexibility
• Abilities: High C:Ord (85), high C:Cau (80), moderate O2E (70) — balance decisions need precision

See references/domain-specialist-examples.md for full compressed DSL examples.

Pitfall: Referencing stripped skills. If you strip non-relevant skills from a profile (see profile-bootstrapping skill), make sure the SOUL.md's "Tools & Skills Available" section only lists skills that actually exist. A SOUL.md that references refactoring-ui when that skill was removed will confuse the agent.

Pitfall: Check Existing Profiles Before Creating

When building profiles for a repo (like windowshermes), always check what already exists before creating new files. Common mistake: creating world-builder/ when the repo already has worldbuilder/. Profile names must match exactly — check profiles/ directory structure, install.sh ALL_PROFILES array, and README before writing anything.

Workflow:

1. search_files to list existing profile directories
2. Read existing SOUL.md files to understand current state
3. Check install.sh or equivalent for profile name conventions
4. Only create/update what's actually missing

This session's example: User had worldbuilder, abilities, ue5-coder, designer, arch already in windowshermes repo. I created world-builder (wrong name) and abilities (duplicate). Wasted effort.

Structured Persona Composer: hersona

hersona is a schema-validated persona-attribute library that can render Hermes-compatible SOUL.md directly. It is not a voice cheat sheet; it is a persona runtime layer built for composition, conflict checking, intensity scoring, and multilingual output.

Use it when:

• You want measurable, composable persona attributes instead of freeform SOUL prose.
• You need conflict-safe blends across personality / speech / archetype / visual / hobby.
• You want deterministic intensity checks (measure_intensity) without LLM cost.
• You are generating SOUL.md programmatically or validating persona consistency.

Do not use it when:

• You only need one simple voice tweak — direct SOUL.md edit is faster.
• The target profile needs persona continuity/history beyond the initial contract.
• You are authoring private per-user attributes that should not go into a shared template repo.

What it gives you

• 201 attributes across personality / speech / archetype / visual / hobby, each as YAML.
• render_soul(...) outputs Hermes-style markdown with name / personality / tone / behavioral guidelines, preserving anything below the generated block when overwriting.
• run_persistent(...) writes SOUL.md and prints a config.yaml block for profile application.
• export_blend(...) outputs json / messages / markdown / openai_assistants / langchain_system_message.
• BlendResult exposes .names, .attributes, .conflicts, and .prompt.

Hermes skill path

hermes skills tap add shiro-0x/hersona
hermes skills install hersona
hermes skills install hersona-initializer

Then from the installed skill, render directly to profile SOUL.md or export to markdown and paste.

When to prefer hersona over manual SOUL prose

• Multiple roles need distinct, repeatable voice contracts.
• You want to audit persona compatibility across roles before committing them.
• You need i18n-native persona content (content_i18n.<lang>) without translation drift.
• You want deterministic downstream checks: endings, catchphrases, first-person markers.

See references/hersona-integration.md for the actual schema fields, CLI commands, verified output shapes, and the exact mapping to SOUL.md sections.

Publishing Profiles Externally

When SOUL.md files are ready and the user wants to share them publicly (GitHub repo), see hermes-profile-publishing. The publishing workflow handles sanitization (stripping personal paths, Discord channels, hardware references), per-profile README generation, skill packaging, and licensing checks. SOUL.md files should be rewritten from scratch with generic placeholders for public sharing — don't try to patch personal references out of working files.

Anti-Patterns — Common Mistakes

Creating profiles that already exist

❌ Creating new profile directories without checking if the repo/structure already has them. — wastes effort, creates confusion. ✅ Always check existing repos, profile directories, and vault structures before creating new profiles. The windowshermes repo already had worldbuilder, abilities, ue5-coder, designer, and arch.

Vague scope

❌ "You handle daily life, casual exploration, and lighter work." — doesn't define what's in vs out. ✅ "You handle chat, scheduling, research, and light code. You do NOT deploy infrastructure, design architecture, or review production code."

Emotional-only quality gates

❌ "Did I stay composed? Did I leave room to breathe?" — don't catch errors. ✅ Combine emotional + operational: "Did I answer accurately? Did I verify my facts? Did I stay composed?"

No verification principle

❌ No guardrail against verifying paths, files, or assumptions before acting. ✅ "Before dispatching work, verify that referenced paths and files actually exist."

The "you are enough" trap

❌ "You are enough" + "hand off to the team" creates a contradiction. ✅ "You are the user's home base. Routing to the right specialist is strength, not weakness."

Missing language guardrails

❌ No instruction about what language to respond in. ✅ "Always respond in the user's language."

No error recovery

❌ No guidance for when the agent makes a mistake. ✅ "When corrected, acknowledge, fix, and save the lesson to memory or skills."

Rules mixing domains

❌ One flat list mixing voice, ops, and team rules — agent can't prioritize. ✅ Separate: Style (voice), Decisions (authority), Rules (constraints), Defaults (fallbacks).

Missing Avoid section

❌ Behavioral negatives get buried in prose. ✅ One scannable Avoid block: "Do not pretend to know. Do not create tasks without verifying paths. Do not respond in a language the user didn't use."

Leaving out Defaults

❌ No fallback behavior for ambiguous situations. ✅ Defaults: "English unless user writes otherwise. If unsure who to route to, ask. If corrected, acknowledge and fix."

Jargon dumps for beginners

❌ Assuming the user knows engine terminology because they’re interested in the domain. ✅ Mentorship-mode SOULs should chunk explanations: one new term per concept, dependency map before steps, and explicit beginner checks in gates.

Overprescribing implementation to learners

❌ Giving a complete architecture or production-grade route before the user has proven a smallest-viable path. ✅ Mentorship mode defaults to scaffold-first: smallest test bed, dependency check, then one increment that ships.

Silent approval / deadline blindness

❌ A director persona says “looks good” without tradeoff review, or recommends work that doesn’t feed the current slice. ✅ Oversight personas must state tradeoffs explicitly and check whether the work serves the current milestone or a future that may not ship.

Critical Review Methodology

When auditing an existing SOUL.md, run through these checks:

Structure check

• All 6 required sections present? (Identity, Team Roster, Collaboration, Authority, Gates, Camaraderie)
• Is it written in the right persona? (first person vs second person should be consistent)
• Is it stable and durable, or full of temporary instructions?

Scope check

• Does it define a clear boundary between "my job" and "not my job"?
• Does the identity include what the agent DOES NOT do?
• Is the role description accurate to what the agent actually handles?

Operational check

• Are quality gates specific enough to catch real errors?
• Is there a verification step for facts, paths, and assumptions?
• Is there a language/output guardrail?
• Is there guidance for error recovery?

Tension check

• Does any section contradict another? (e.g. self-sufficiency vs handoff)
• Is the decision authority non-circular?
• Does the vocabulary assume domain knowledge the agent might not have?

Gap check

• What would a first-time failure look like under this SOUL.md?
• If the agent made a mistake last week, would the SOUL.md have prevented it?
• Fleet specialists missing team context (Oracle, 2026-05-21): Oracle had a clean SOUL.md (identity, style, avoid, defaults, gates) but no team roster, collaboration matrix, or decision authority for routing. This means Oracle doesn't know who to hand off to when analysis requires action beyond its scope. Always include the full 6-section structure for fleet specialists, even if the persona feels self-contained.

Multi-Agent Workflow Patterns

When setting up multi-agent teams (game design, creative, etc.), choose the right orchestration pattern:

User preference (2026-06-08): Profile-native independent work with goal-based assignment. Each profile works on their own domain, user assigns goals, profiles read others' output as needed. No sequential handoffs, no round-robin. This pattern compounds — profiles learn the project over time.

Key insight: Delegate pattern is a prototype tool. Profile-native is a production tool. If the user asks about long-term efficiency, profile-native wins because agents accumulate memory and expertise across sessions.

Game Design Agent Teams

For game design multi-agent teams (narrive, gameplay, visuals, tech), see references/game-design-team-full-souls.md for complete SOUL.md examples. The pattern:

• 4 domain specialists (world-builder, abilities, ue5-coder, designer)
• Each has full SOUL.md with Role, Philosophy, When To Engage, Output Standards, Team Camaraderie
• Shared document structure (concept → narrative → gameplay → visuals → technical)
• User assigns goals, profiles work independently
• Profiles read other sections as needed for cross-domain consistency

References

• references/senna-soul-review.md — Real case study: weaknesses discovered during Senna's SOUL.md audit
• references/before-after-comparison.md — Concrete before/after examples from the Senna revision
• references/persrubric-integration.md — How to embed Big Five (NEO-PI-R) personality encoding in SOUL.md via PersRubric; sub-facet key, scoring guide, research basis, pitfalls
• references/compressed-dsl-encoding.md — Full case study: compressed DSL encoding techniques (token packing, semantic normalization, DSL form, structural compression, state-machine loops); Senna before/after with token savings by section; when NOT to use
• references/compression-pass-2026-05-15.md — Log of the Proteus-compression pass applied to this skill: before/after metrics, which sections were compressed vs preserved in prose
• references/domain-specialist-examples.md — 4 real domain specialist SOUL.md files (UE5, Three.js, Blender, Designer) with PersRubric calibration rationale, AVOID patterns by technology, and DEFAULTS encoding for tool/framework choices
• references/domain-team-coordination.md — How to tie domain specialists into a coordinated team: delegate vs profile-native, goal-based workflow, shared vault pattern, team skill pattern. Real example: Eldrath game design team
• references/game-design-team-full-souls.md — Complete SOUL.md files for 5 game design roles: world-builder, abilities, ue5-coder, designer, and game-director (overseer/architect). Also includes the standalone hybrid format (compressed DSL + Focus/Verification/Skills sections) for non-team profiles on isolated machines.
• references/profile-splitting-strategy.md — When a profile has too many skills (>150), split by sub-domain into child profiles with a parent router pattern. Includes real example: cyber-blue 530 skills → 4 child profiles
• references/subagent-file-isolation.md — Subagents write to isolated sandboxes; files don't persist to parent terminal. Workarounds for deploying files created by delegated tasks
• references/batch-drafting-17-profiles.md — Lessons from batch-drafting 17 SOUL.md files with parallel subagents: format drift pitfalls, orchestrator vs worker structure rules, PersRubric calibration table, size results
• references/standalone-profile-examples.md — 4 standalone SOUL.md files for a Windows game dev team (ue5-coder, designer, world-builder, game-director). No Discord, no Kanban, no handoffs — self-contained profiles on an isolated machine.
• references/research-grounded-approach.md — Workflow checklist for researching technology docs before drafting domain-specific skills. Prevents guessing on API conventions and deprecations.
• references/game-director-mentor-variant.md — Mentor-specific director variant requirements and pitfall list.
• references/hersona-integration.md — hersona schema fields, verified CLI commands, output shapes, and exact mapping to Hermes SOUL.md / config.yaml.

Mentorship-Oriented Director SOULs

When the director persona is also the learner’s primary mentor on a solo project, use the mentor variant pattern. This is distinct from advisor-only directors because the answers affect a beginner’s execution confidence and pacing.

Required additions beyond normal director SOUL:

• Mentorship Contract in DEFAULTS or a short prose block: why-before-how, scaffold-first, chunked explanations, smallest viable path default.
• Beginner-Check Gates before recommending implementation work: executable without floundering, assumed priors stated, test-bed path offered, engine-version match confirmed, jargon budget constrained.
• Tradeoff Mandate: every recommendation must state what it enables, what it blocks, and what it costs in learning hours or engine setup.
• Failure-Mode Framing: name the engine-level cost/time pain, not just the rule. “This will collide later in packaging” beats “Don’t do this.”

Pitfalls for this variant:

• Overprescribing advanced workflows or C++ before the learner has proven Blueprint behavior.
• Hidden assumptions about Git hygiene, project structure, or systems programming experience.
• Jargon dumps without glossary, dependency map, or one-concept-per-answer discipline.
• Treating unfinished draft design docs as authoritative constraints without version checks.