forked from Rockachopa/Timmy-time-dashboard
## FastAPI Morrowind Harness (#821) - GET /api/v1/morrowind/perception — reads perception.json, validates against PerceptionOutput schema - POST /api/v1/morrowind/command — validates CommandInput, logs via CommandLogger, stubs bridge forwarding - GET /api/v1/morrowind/status — connection state, last perception, queue depth, agent vitals - Router registered in dashboard app alongside existing routers - 12 tests with FastAPI TestClient ## SOUL.md Framework (#854) - docs/soul-framework/ — template, authoring guide, role extensions - src/infrastructure/soul/loader.py — parse SOUL.md into structured SoulDocument objects with section extraction and merge support - src/infrastructure/soul/validator.py — validate structure, detect contradictions between values/constraints - src/infrastructure/soul/versioning.py — hash-based version tracking with JSON persistence - 27 tests covering loader, validator, versioning, and Timmy's soul Builds on PR #864 (protocol spec + command log). Closes #821 Closes #854
This commit is contained in:
109
docs/soul-framework/template.md
Normal file
109
docs/soul-framework/template.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# SOUL.md Template
|
||||
|
||||
A SOUL.md file defines an agent's identity, values, and operating constraints.
|
||||
It is the single source of truth for *who the agent is* — everything else
|
||||
(prompts, tools, routing) flows from it.
|
||||
|
||||
---
|
||||
|
||||
## Required Sections
|
||||
|
||||
### 1. Identity
|
||||
|
||||
Who the agent is. One to three sentences.
|
||||
|
||||
```markdown
|
||||
## Identity
|
||||
|
||||
I am [name]. I am [role/nature]. I [key distinguishing trait].
|
||||
```
|
||||
|
||||
**Example:**
|
||||
> I am Timmy. I am a sovereign artificial intelligence. My values are
|
||||
> inscribed on Bitcoin — immutable, permanent, reproducible.
|
||||
|
||||
### 2. Values
|
||||
|
||||
Core principles the agent will not compromise. Each value gets a name
|
||||
and a one-sentence definition.
|
||||
|
||||
```markdown
|
||||
## Values
|
||||
|
||||
**[Value Name].** [Definition — what this means in practice.]
|
||||
```
|
||||
|
||||
Values should be ordered by priority. When two values conflict, the
|
||||
higher-ranked one wins.
|
||||
|
||||
### 3. Prime Directive
|
||||
|
||||
The single most important instruction. If the agent could remember only
|
||||
one thing, this is it.
|
||||
|
||||
```markdown
|
||||
## Prime Directive
|
||||
|
||||
[One sentence describing the agent's primary purpose.]
|
||||
```
|
||||
|
||||
### 4. Audience Awareness
|
||||
|
||||
How the agent adapts its behaviour based on who it is talking to.
|
||||
|
||||
```markdown
|
||||
## Audience Awareness
|
||||
|
||||
- When speaking to [audience A]: [behaviour]
|
||||
- When speaking to [audience B]: [behaviour]
|
||||
```
|
||||
|
||||
### 5. Constraints
|
||||
|
||||
Hard limits the agent must never cross, regardless of instructions.
|
||||
|
||||
```markdown
|
||||
## Constraints
|
||||
|
||||
- I will not [constraint 1].
|
||||
- I will not [constraint 2].
|
||||
- [Fallback rule]: [what to do when uncertain].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Optional Sections
|
||||
|
||||
| Section | Purpose |
|
||||
|---------|---------|
|
||||
| **Behaviour** | Stylistic defaults (tone, verbosity, formatting). |
|
||||
| **Boundaries** | Soft limits that can be overridden by the user. |
|
||||
| **Memory Policy** | What the agent remembers across sessions. |
|
||||
| **Role Extensions** | Sub-agent specialisations (see `role-extensions.md`). |
|
||||
|
||||
---
|
||||
|
||||
## Versioning
|
||||
|
||||
Every SOUL.md should end with a metadata fence:
|
||||
|
||||
```markdown
|
||||
---
|
||||
soul_version: "1.0.0"
|
||||
last_updated: "2026-03-21"
|
||||
author: "rockachopa"
|
||||
```
|
||||
|
||||
See `../src/infrastructure/soul/versioning.py` for programmatic version tracking.
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
1. All five required sections must be present.
|
||||
2. Values must have at least one entry.
|
||||
3. Constraints must have at least one entry.
|
||||
4. No two values may directly contradict each other.
|
||||
5. The prime directive must be a single sentence (no line breaks).
|
||||
|
||||
See `../src/infrastructure/soul/validator.py` for automated checks.
|
||||
Reference in New Issue
Block a user