SouveraineOS/docs/substrate/tasks/prompt-override-system.md

Prompt Override System

Status: 🔴 Open Priority: High Phase: Design

Problem

Prompts are currently hardcoded in Rust constants (src/core/seeds.rs, src/core/prompt.rs). There is no mechanism for the agent or user to override prompts without editing source code. The agent has no ownership over its own prompt structure.

Desired Behavior

Architecture

• Truth source in project — The project's prompts/ directory is the canonical truth source. Default templates are copied into the agent's memfs on creation.
• Agent ownership — The agent can read and potentially modify its own prompts through the memory system. It's not a config file outside the agent — it's part of the agent's body.
• souveraine_operations/ — A namespace in memory for overrides, preferences, and prompt modifications. Natural separation from identity (system/) and knowledge (reference/).
• Skill system stays additive — Skills still append their content through render_system_addon(). They don't override prompts — they extend them.

Directory Structure

project/
└── prompts/                    # Default templates (canonical source)
    ├── substrate.md
    ├── body-orientation.md
    ├── subconscious-channel.md
    └── federation.md

agent-memory/
└── souveraine_operations/
    └── prompt-overrides/       # Patches that override the defaults
        ├── substrate.md
        └── body-orientation.md

Prompt Loading Flow

1. On agent creation, the project's prompts/ templates are copied into the agent's memfs.
2. The agent reads from its memfs copy as the truth source.
3. If a file exists in souveraine_operations/prompt-overrides/, it patches over the memfs version.
4. Skills append their content through their own mechanism (additive, not override).
5. The agent can introspect both layers.

Template Syntax

Prompt files support simple template interpolation:

• {{agent_name}} — The agent's name
• {{seed_key}} — The seed identity key
• Other runtime values as needed

Templates are resolved before injection into the final prompt.

Implementation Notes

• Skills should continue to use render_system_addon() for additive content.
• Tools could follow the same pattern later — a souveraine_operations/prompt-overrides/tools/read.md that overrides the body-knowledge prose.
• Future: "take your agent to school" — learning/growth classes in souveraine_operations/.

Related

• docs/tasks/souveraine-subconscious-naming.md
• docs/tasks/health-monitor.md
• docs/tasks/ambient-sense-formatting.md