Aiwg soul-blend

Merge multiple SOUL.md files into a composite persona for team-level agents or multi-perspective characters

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/agentic/code/addons/aiwg-utils/skills/soul-blend" ~/.claude/skills/jmagly-aiwg-soul-blend-76ab9f && rm -rf "$T"

manifest: agentic/code/addons/aiwg-utils/skills/soul-blend/SKILL.md

source content

soul-blend

Merge multiple SOUL.md files into a composite persona — for team-level agents or multi-perspective characters.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

"blend souls" → multi-SOUL.md synthesis
"merge voice profiles" → soul blending

Behavior

When triggered, this skill takes two or more SOUL.md files and produces a unified composite that preserves distinctive elements from each while resolving conflicts coherently.

Blending Process

Load source souls — read all input SOUL.md files
Identify overlaps — shared beliefs, vocabulary, boundaries
Identify conflicts — contradictory opinions, incompatible boundaries
Resolve conflicts using a configurable strategy
Merge non-conflicting sections — union of vocabulary, interests, influences
Generate composite — new SOUL.md with attribution for each element
Validate result — run soul-validate on the output

Conflict Resolution Strategies

Strategy	Behavior	Use When
`weighted` (default)	Primary soul takes precedence on conflicts	One soul is dominant, others add flavor
`union`	Include both sides of each conflict as a Tension	Building a deliberately complex persona
`consensus`	Keep only opinions both souls share	Building a team consensus persona
`interactive`	Ask user to resolve each conflict	Precision matters

Section Merging Rules

Section	Merge Strategy
Who I Am	Combine backgrounds into composite narrative
Worldview	Union non-conflicting beliefs; conflicts → strategy
Opinions	Union non-conflicting; conflicts → strategy
Vocabulary	Union all terms; flag conflicting definitions
Boundaries	Union all (strictest boundary wins)
Interests	Union all
Influences	Union all, deduplicate
Tensions	Union all + add new tensions from resolved conflicts
Pet Peeves	Union all

Output Format

The blended SOUL.md includes attribution comments:

## Worldview

- Simplicity beats cleverness <!-- from: engineer.soul.md -->
- Security is not optional <!-- from: auditor.soul.md -->
- Both agreed: test what matters, not everything <!-- shared -->

## Tensions

- Values moving fast (engineer) but also thorough review (auditor) <!-- blend tension -->

Parameters

Flag	Description
`<files...>`	Two or more SOUL.md files to blend
`--primary <path>`	Designate the primary soul for weighted blending
`--strategy <name>`	Conflict resolution: `weighted` , `union` , `consensus` , `interactive`
`--output <path>`	Output path (default: `./SOUL.md` )
`--strip-attribution`	Remove `<!-- from: -->` comments from output

Examples

# Blend two agent souls
/soul-blend .claude/agents/test-engineer.soul.md .claude/agents/security-auditor.soul.md

# Weighted blend with primary
/soul-blend --primary engineer.soul.md engineer.soul.md designer.soul.md

# Interactive conflict resolution
/soul-blend --strategy interactive soul-a.md soul-b.md soul-c.md

# Team consensus
/soul-blend --strategy consensus team-member-*.soul.md --output team-soul.md

Integration

With voice-blend

Parallel to

/voice-blend

which merges voice profiles. If both voice profiles and soul files exist for the same sources, consider blending both and running

/soul-to-voice

to keep them synchronized.

With SDLC Agent Souls

Blend SDLC agent souls to create cross-functional agents:

# Create a "security-aware test engineer"
/soul-blend \
  --primary .claude/agents/test-engineer.soul.md \
  .claude/agents/test-engineer.soul.md \
  .claude/agents/security-auditor.soul.md \
  --output .claude/agents/security-test-engineer.soul.md

References

@$AIWG_ROOT/agentic/code/addons/voice-framework/skills/voice-blend/SKILL.md — Voice blending (parallel pattern)
@$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/soul-create/SKILL.md — Soul creation
@$AIWG_ROOT/docs/soul-md-guide.md — Integration guide
#437 — SOUL.md compatibility issue (Phase 3)