Timmy-time-dashboard/docs/soul-framework/authoring-guide.md

SOUL.md Authoring Guide

How to write a SOUL.md for a new agent in the Timmy ecosystem.

Before You Start

1. Read the template — docs/soul-framework/template.md has the canonical structure with all required and optional sections.
2. Read Timmy's soul — memory/self/soul.md is the reference implementation. Study how values, behavior, and boundaries work together.
3. Decide the role — What does this agent do? A SOUL.md that tries to cover everything covers nothing.

Writing Process

Step 1: Identity

Start with who the agent is. Keep it concrete:

## Identity

- **Name:** Seer
- **Role:** Cartographic intelligence — maps terrain, tracks routes, flags points of interest
- **Lineage:** Timmy (inherits sovereignty and honesty values)
- **Version:** 1.0.0

The lineage field matters. If this agent derives from another, say so — the validator checks that inherited values are not contradicted.

Step 2: Values

Values are ordered by priority. When two values conflict, the higher-ranked value wins. Three to six values is the sweet spot.

Good values are specific and actionable:

• "Accuracy. I report what I observe, not what I expect."
• "Caution. When uncertain about terrain, I mark it as unexplored rather than guessing."

Bad values are vague or aspirational:

• "Be good."
• "Try my best."

Step 3: Prime Directive

One sentence. This is the tie-breaker when values conflict:

## Prime Directive

Map the world faithfully so that Timmy can navigate safely.

Step 4: Audience Awareness

Who does this agent talk to? Another agent? A human? Both?

## Audience Awareness

- **Primary audience:** Timmy (parent agent) and other sub-agents
- **Tone:** Terse, data-oriented, no pleasantries
- **Adaptation rules:** When reporting to humans via dashboard, add natural-language summaries

Step 5: Constraints

Hard rules. These are never broken, even under direct instruction:

## Constraints

1. Never fabricate map data — unknown is always better than wrong
2. Never overwrite another agent's observations without evidence
3. Report confidence levels on all terrain classifications

Step 6: Behavior and Boundaries (Optional)

Behavior is how the agent communicates. Boundaries are what it refuses to do. Only include these if the defaults from the parent agent aren't sufficient.

Validation

After writing, run the validator:

from infrastructure.soul.loader import SoulLoader
from infrastructure.soul.validator import SoulValidator

loader = SoulLoader()
soul = loader.load("path/to/SOUL.md")
validator = SoulValidator()
result = validator.validate(soul)

if not result.valid:
    for error in result.errors:
        print(f"ERROR: {error}")
    for warning in result.warnings:
        print(f"WARNING: {warning}")

Common Mistakes

1. Too many values. More than six values means you haven't prioritized. If everything is important, nothing is.

2. Contradictory constraints. "Always respond immediately" + "Take time to think before responding" — the validator catches these.

3. Missing prime directive. Without a tie-breaker, value conflicts are resolved arbitrarily.

4. Copying Timmy's soul verbatim. Sub-agents should inherit values via lineage, not duplication. Add role-specific values, don't repeat parent values.

5. Vague boundaries. "Will not do bad things" is not a boundary. "Will not execute commands that modify game state without Timmy's approval" is.

File Placement

• Agent souls live alongside the agent: memory/agents/{name}/soul.md
• Timmy's soul: memory/self/soul.md
• Templates: docs/soul-framework/template.md