Skip to content

feat(system-prompt): add PREAMBLE.md workspace file as template variable for prompt profiles #887

Description

@Cstewart-HC

Summary

Add PREAMBLE.md workspace file support to the prompt profile system, enabling per-agent custom opening text via the existing {{template_variable}} mechanism introduced in #466.

Motivation

PR #466 introduces a comprehensive prompt profile system with template variables, section toggles, and model-based profile routing. A PREAMBLE.md workspace file (following the existing SOUL.md, BOOT.md, TOOLS.md pattern) would allow users to define custom preamble text as a file-based override, which is then exposed as a {{preamble}} template variable inside any prompt profile.

This was originally developed on feat/configurable-preamble but conflicts with #466's builder rewrite. Re-implementing as a template variable within the profile system is the correct architectural fit.

Requirements

moltis-config

  • Add preamble_path() to crates/config/src/loader.rs — returns data_dir().join("PREAMBLE.md")
  • Add load_preamble_md() and load_preamble_md_for_agent(agent_id) to crates/config/src/loader/workspace.rs — follows existing load_soul_md / load_boot_md fallback pattern:
    1. agents/{id}/PREAMBLE.md (agent-specific override)
    2. PREAMBLE.md (global fallback)
  • Export from crates/config/src/lib.rs

moltis-agents

  • Add preamble to PROMPT_TEMPLATE_VARIABLES array in crates/agents/src/prompt.rs
  • Wire preamble text into PromptRenderContext and build_template_values() so {{preamble}} resolves at render time
  • Add "preamble" to PromptSectionId enum if section-toggle support is desired

moltis-chat

  • Add preamble_text: Option<String> to PromptPersona in crates/chat/src/types.rs
  • Load preamble in crates/chat/src/prompt.rs via moltis_config::load_preamble_md_for_agent(agent_id)
  • Thread preamble text through to the builder when calling build_system_prompt_with_profile

Tests

  • Unit tests in moltis-agents for {{preamble}} template variable resolution
  • Unit tests in moltis-config for file loading fallback chain (agent override → global)
  • Integration test: preamble absent → default profile behavior unchanged

Documentation

  • Add PREAMBLE.md to the workspace file documentation alongside SOUL.md, BOOT.md, etc.

Dependencies

Design Notes

  • The preamble file is user-editable (like all workspace markdown files)
  • Fallback chain mirrors SOUL.md and BOOT.md: agent-level file takes priority over global
  • When no PREAMBLE.md exists, the {{preamble}} variable resolves to empty string — no behavior change
  • The existing load_preamble_md() / load_preamble_md_for_agent() implementations from the aborted feat/configurable-preamble branch can be reused directly (zero conflict with feat(system-prompt): add prompt profiles with CRUD, section options, and model overrides #466)

Original Branch

feat/configurable-preamble — archived after conflict analysis with #466. Conflict analysis saved at CONFLICT_ANALYSIS_PR466.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions