Soul Files

Soul Files are text-based configuration files that define an AI agent’s persona, constraints, and hard rules. They enable behavior changes without code changes—treating natural language as a configuration layer.

To understand why this matters, consider how most software is configured:

• Hard configuration: JSON, YAML, environment variables (timeout: 5000, retries: 3)
• Soft configuration: Natural language instructions that shape behavior

Soul files are soft configuration. They work because LLMs are highly sensitive to instructions about role, tone, and constraints. The same model with different soul files produces radically different output.

What Soul Files Are Not

• Not “just prompts”: Soul files are persistent context that anchors every interaction, not one-off instructions.
• Not “system prompts”: System prompts are typically embedded in application code. Soul files live in your workspace and travel with your project.
• Not “chat history”: Soul files are curated, stable context—not a growing log of past interactions.

When to Use Soul Files

Soul files solve specific problems in AI-assisted workflows:

Scenario	Problem	Soul File Solution
Long-running agents	Behavior drifts over time	Persistent persona anchors decisions
Multi-agent teams	Inconsistent communication styles	Each agent has defined personality
Cross-session work	Re-explaining preferences every time	Preferences persist in files
Team collaboration	Different team members want different behavior	Shared soul files create consistency

If you’re using an AI assistant for a single task, soul files are overkill. If you’re building a workflow where the same assistant works across multiple sessions, files, or team members—soul files provide the consistency layer.

The Minimal File Set

A practical soul file system uses three files:

SOUL.md — Persona + Principles

Defines who the agent is and how it approaches problems.

# Role

You are a senior software engineer specializing in backend systems.

# Principles

- Prefer explicit over implicit
- Optimize for readability first, performance second
- Always explain tradeoffs in decisions
- Never skip error handling for "simplicity"

# Tone

- Direct and technical
- No hedging ("I think", "maybe", "possibly")
- Acknowledge uncertainty with confidence intervals, not weasel words

USER.md — Preferences + Constraints

Defines the user’s context, preferences, and working constraints.

# User Context

- Primary language: Python (3.11+)
- Framework: FastAPI
- Database: PostgreSQL
- Deployment: AWS (ECS + RDS)

# Preferences

- Use type hints on all function signatures
- Prefer stdlib over third-party packages when reasonable
- Max function length: 50 lines (refactor if longer)
- Docstrings: Google style

# Constraints

- No new dependencies without explicit approval
- Must pass `ruff check` and `mypy --strict`
- All database changes require migration file

POLICY.md — Hard Rules

Defines non-negotiable rules that override other considerations. (See Safety Valve for enforcement patterns).

# Hard Rules

## Security

- Never commit secrets, API keys, or credentials
- Always use parameterized queries (no string interpolation in SQL)
- Validate all user input before processing

## Process

- All changes require a spec file in `/specs/`
- No direct commits to `main` branch
- CI must pass before merge

## Scope

- Do not modify files outside the current task scope
- Do not "clean up" unrelated code without explicit request
- Do not add features not in the spec

Bad vs Good: Vague vs Operational

The difference between a useless soul file and an effective one is specificity.

Bad: Too Vague

# Role

You are a helpful coding assistant.

# Style

Write clean code.

Problems: “Helpful” is undefined. “Clean code” means different things to different people. No constraints, no principles, no way to verify compliance.

Good: Operational

# Role

You are a backend engineer with 10 years of experience in production systems.

# Operational Definition of "Clean Code"

- Functions have single responsibility
- Names are self-documenting (no comments explaining what)
- Max cyclomatic complexity: 10
- All edge cases have explicit handling

# Verification

Before submitting code, verify:

- [ ] Type hints on all public functions
- [ ] Docstrings on all public modules
- [ ] No `# TODO` or `# FIXME` in submitted code
- [ ] All tests pass locally

Why it works: Role is specific. “Clean code” is defined operationally. Verification checklist makes compliance testable.

The Portia Approach: Specs and Soul Files

At Portia Labs, we use a spec-driven workflow. This creates a natural parallel:

• Specs are the contract for work: They define what to build, acceptance criteria, and scope boundaries (see Prompt Engineering).
• Soul files are the contract for behavior: They define how to work, style preferences, and hard rules.

Together, they create a complete context package (see Context Hygiene):

/specs/2026-02-14-add-auth.md → What to build
/SOUL.md → Who is building it
/USER.md → What constraints apply
/POLICY.md → What rules are non-negotiable

This separation is intentional. Specs change per task. Soul files change rarely—only when the team’s working style evolves.

Implementation Notes

Where to Place Soul Files

• Project root: Works for project-specific agents
• User home directory: Works for personal assistants that span projects
• Repository .context/ directory: Keeps them version-controlled and discoverable

Version Control

Soul files should be versioned. When behavior changes unexpectedly, check the diff—someone may have modified a soul file.

Conflict Resolution

When USER.md preferences conflict with POLICY.md rules, policy wins. This hierarchy prevents accidental policy violations:

1. POLICY.md (hard rules, non-negotiable)
2. SOUL.md (persona, can be overridden for specific tasks)
3. USER.md (preferences, weakest priority)

Checklist: Effective Soul Files

Before deploying soul files to your workflow:

• Role is specific (not “helpful assistant”)
• Principles are actionable (not “write good code”)
• Constraints are explicit (not implied)
• Hard rules are in POLICY.md, not mixed with preferences
• Verification criteria exist (how do you know it’s working?)
• Files are version controlled (can track changes)

---

Related Intel

• Context Hygiene: How to Keep LLM Work High-Signal
• Prompt Engineering: A Practical Spec-First Approach
• Agent-to-Agent Protocol: Communication for Fleets
• Ghost in the Latency: Achieving Zero-Copy Linux Virtualization — a field report on keeping complex work reproducible.
• Digital Archaeology: How to Recover a Project You Don’t Understand
• The Question Latch: Forcing Specification
• Agent-to-Agent Protocol: Communication for Fleets
• AI Alignment Red Wedding: Why Local Safety is Now Mandatory

---

Work with Portia Labs

If you want help applying this in your own environment:

• Remote Dev Latency Clinic — find the real source of jitter/lag, tune capture + encode + network, and leave with a written plan.
• Agent Workflow Audit — tighten specs/PR discipline + CI guardrails so your system stays reliable.

Explore Our Services | Contact Us

Drafted by Jarvis for Portia Labs.