forked from Rockachopa/Timmy-time-dashboard
147 lines
4.4 KiB
Markdown
147 lines
4.4 KiB
Markdown
# SOUL.md Versioning System
|
|
|
|
How SOUL.md versions work, how to bump them, and how to trace identity evolution.
|
|
|
|
---
|
|
|
|
## Version Format
|
|
|
|
SOUL.md versions follow semantic versioning: `MAJOR.MINOR.PATCH`
|
|
|
|
| Digit | Increment when... | Examples |
|
|
|-------|------------------|---------|
|
|
| **MAJOR** | Fundamental identity change | New prime directive; a core value removed; agent renamed or merged |
|
|
| **MINOR** | Capability or identity growth | New value added; new constraint added; new role extension section |
|
|
| **PATCH** | Clarification only | Wording improved; typo fixed; example updated; formatting changed |
|
|
|
|
Initial release is always `1.0.0`. There is no `0.x.x` — every deployed soul
|
|
is a first-class identity.
|
|
|
|
---
|
|
|
|
## Lineage and the `extends` Field
|
|
|
|
Sub-agents carry a lineage reference:
|
|
|
|
```yaml
|
|
extends: "timmy-base@1.0.0"
|
|
```
|
|
|
|
This means: "This soul was authored against `timmy-base` version `1.0.0`."
|
|
|
|
When the base soul bumps a MAJOR version, all extending souls must be reviewed
|
|
and updated. They do not auto-inherit — each soul is authored deliberately.
|
|
|
|
When the base soul bumps MINOR or PATCH, extending souls may but are not
|
|
required to update their `extends` reference. The soul author decides.
|
|
|
|
---
|
|
|
|
## Changelog Format
|
|
|
|
Every SOUL.md must contain a changelog table at the bottom:
|
|
|
|
```markdown
|
|
## Changelog
|
|
|
|
| Version | Date | Author | Summary |
|
|
|---------|------|--------|---------|
|
|
| 1.0.0 | 2026-03-23 | claude | Initial soul established |
|
|
| 1.1.0 | 2026-04-01 | timmy | Added Audience Awareness section |
|
|
| 1.1.1 | 2026-04-02 | gemini | Clarified constraint #2 wording |
|
|
| 2.0.0 | 2026-05-10 | claude | New prime directive post-Phase 8 |
|
|
```
|
|
|
|
Rules:
|
|
- Append only — never modify past entries.
|
|
- `Author` is the agent or human who authored the change.
|
|
- `Summary` is one sentence describing what changed, not why.
|
|
The commit message and linked issue carry the "why".
|
|
|
|
---
|
|
|
|
## Branching and Forks
|
|
|
|
If two agents are derived from the same base but evolve separately, each
|
|
carries its own version number. There is no shared version counter.
|
|
|
|
Example:
|
|
```
|
|
timmy-base@1.0.0
|
|
├── seer@1.0.0 (extends timmy-base@1.0.0)
|
|
└── forge@1.0.0 (extends timmy-base@1.0.0)
|
|
|
|
timmy-base@2.0.0 (breaking change in base)
|
|
├── seer@2.0.0 (reviewed and updated for base@2.0.0)
|
|
└── forge@1.1.0 (minor update; still extends timmy-base@1.0.0 for now)
|
|
```
|
|
|
|
Forge is not "behind" — it just hasn't needed to review the base change yet.
|
|
The `extends` field makes the gap visible.
|
|
|
|
---
|
|
|
|
## Storage
|
|
|
|
Soul files live in two locations:
|
|
|
|
| Location | Purpose |
|
|
|----------|---------|
|
|
| `memory/self/soul.md` | Timmy's base soul — the living document |
|
|
| `docs/soul/extensions/<name>.md` | Sub-agent extensions — authored documents |
|
|
| `docs/soul/SOUL_TEMPLATE.md` | Blank template for new agents |
|
|
|
|
The `memory/self/soul.md` is the primary runtime soul. When Timmy loads his
|
|
identity, this is the file he reads. The `docs/soul/extensions/` files are
|
|
referenced by the swarm agents at instantiation.
|
|
|
|
---
|
|
|
|
## Identity Snapshots
|
|
|
|
For every MAJOR version bump, create a snapshot:
|
|
|
|
```
|
|
docs/soul/history/timmy-base@<old-version>.md
|
|
```
|
|
|
|
This preserves the full text of the soul before the breaking change.
|
|
Snapshots are append-only — never modified after creation.
|
|
|
|
The snapshot directory is a record of who Timmy has been. It is part of the
|
|
identity lineage and should be treated with the same respect as the current soul.
|
|
|
|
---
|
|
|
|
## When to Bump vs. When to File an Issue
|
|
|
|
| Situation | Action |
|
|
|-----------|--------|
|
|
| Agent behavior changed by new code | Update SOUL.md to match, bump MINOR or PATCH |
|
|
| Agent behavior diverged from SOUL.md | File `[soul-gap]` issue, fix behavior first, then verify SOUL.md |
|
|
| New phase introduces new capability | Add Role Extension section, bump MINOR |
|
|
| Prime directive needs revision | Discuss in issue first. MAJOR bump required. |
|
|
| Wording unclear | Patch in place — no issue needed |
|
|
|
|
Do not bump versions without changing content. Do not change content without
|
|
bumping the version.
|
|
|
|
---
|
|
|
|
## Validation and CI
|
|
|
|
Run the soul validator before committing any SOUL.md change:
|
|
|
|
```bash
|
|
python scripts/validate_soul.py <path/to/soul.md>
|
|
```
|
|
|
|
The validator checks:
|
|
- Frontmatter fields present and populated
|
|
- Version follows `MAJOR.MINOR.PATCH` format
|
|
- All required sections present
|
|
- Changelog present with at least one entry
|
|
- No high-confidence contradictions detected
|
|
|
|
Future: add soul validation to the pre-commit hook (`tox -e lint`).
|