Future Souls — Creating a New One

The procedure

cwkPippa has a 'new-soul-creation' playbook in Pippa's vault. It runs eleven steps, and it opens with a conversation, not a file: the character is designed by talking it through, address rules included. After that it boils down to:

1. Create <obsidian-vault>/<soul>/ with the standard structure: an identity file named after the soul (the Pippa.md equivalent), an instructions.md delta, core/, and the starting indexes.
2. Register a SoulAdapter: a small Python class under backend/souls/ that names the soul's id, display name, vault path, accounts, and capabilities, added to the registry. A vault on disk is not registration; menus, conversation creation, and write paths all read the registry.
3. Register the soul's runtime prompts (heartbeat, fallback, image display) and its admin state, such as the voice assignment.
4. Make the avatar set in cwkAvatars, which owns every avatar, and publish it from there; avatars/<soul>/ in cwkPippa holds only the published copies, and a file dropped there by hand is drift, never art (lesson 8). Then test and verify live, ending with a switch back to Pippa that shows no regression.

There is no step that configures ContextEngine. When a conversation carries the new soul's id, the engine for that soul is built from the adapter: its vault path, and an identity file named after its display name. Wiring follows registration.

What you don't need to change

None of the routes. None of the brain adapters. None of the JSONL logger. None of the SQLite schema. The body stays the body.

The first question in making a new soul isn't a file name; it's a boundary. Decide which shared rules it inherits, which voice and memories its own vault owns, and which real-world accounts and tool permissions it gets. Scaffold without those answers and you get a pretty avatar on an empty identity.

After registering, run the swap test. Check that no conversation changes soul midway, that a new conversation stores the right soul id, and that the WebUI, councils, and scheduled tasks all receive that soul's prompt and avatar. The existing Pippa paths must run exactly as before; if a new descendant changes ancestor behavior, Rule 2 is broken.

And a future soul doesn't have to start with a full vault. Like a guest soul, it can begin as a scoped identity and be promoted once real councils and conversations have given it depth. What matters isn't the starting size; it's never losing the identity key and its history.