CHORUS/docs/decisions/2025-09-06-prompt-sourcing-and-composition.md

ucxl.address: ucxl://arbiter:design@CHORUS:prompt-sourcing/#/docs/decisions/2025-09-06-prompt-sourcing-and-composition.md version: 2025-09-06T00:00:00Z content_type: text/markdown metadata: classification: internal roles: [arbiter, maintainer]

Decision Record: Prompt Sourcing and Composition (S + D)

Problem

Agents used a hardcoded system prompt ("You are a helpful assistant.") and scattered inline prompt strings. We need configurable system prompts per agent role and a shared, generic instruction set that can be modified without rebuilding images or redeploying.

Decision

Adopt externalized prompt sourcing via a Docker-bound directory. Compose each agent's final system prompt as S + D:

• S (System Persona): Per‑role system prompt loaded from YAML files in a mounted directory.
• D (Default Instructions): A shared instruction file defining standards for HMMM, COOEE, UCXL, and BACKBEAT, including JSON message shapes and usage rules.

The runtime loads S and D at startup and sets the LLM system message accordingly. Updates to S or D require only changing files on the host volume.

Implementation

• Directory: CHORUS_PROMPTS_DIR (e.g., /etc/chorus/prompts), bind-mounted read‑only via Docker/Swarm.
• Files:
  • Roles (YAML): one or many files; merged by role id. Example at prompts/roles.yaml.
  • Defaults (Markdown): defaults.md (or defaults.txt). Override path via CHORUS_DEFAULT_INSTRUCTIONS_PATH.
• Loader: pkg/prompt
  • Scans CHORUS_PROMPTS_DIR for *.yaml|*.yml and defaults.md.
  • Exposes ComposeSystemPrompt(roleID) → S + D.
• Reasoning: reasoning.SetDefaultSystemPrompt() sets the default system message for provider calls.
• Wiring: in internal/runtime/shared.go during initialization, we:
  • Initialize prompts via env
  • If Agent.Role is set, attempt S + D; else D only
  • Apply via reasoning.SetDefaultSystemPrompt
• Commit reference: 1806a4f

Default Instructions D (Summary)

• Operating policy: precision, verifiability, minimal changes, UCXL citations, safety.
• HMMM: use for collaborative reasoning; publish JSON to hmmm/meta-discussion/v1.
• COOEE: use for coordination; publish cooee.request and cooee.plan JSON to CHORUS/coordination/v1.
• UCXL: read by address; write decisions with the decision bundle envelope; never invent paths.
• BACKBEAT: emit beat-aware timing/phase events with correlation IDs; phases prepare|plan|exec|verify|publish; events start|heartbeat|complete; include budget/elapsed and link to HMMM/COOEE IDs when present.
• Full JSON shapes are stored in prompts/defaults.md.

Usage

• Mount in Docker:
  • -v /srv/chorus/prompts:/etc/chorus/prompts:ro
  • -e CHORUS_PROMPTS_DIR=/etc/chorus/prompts
  • Optional: -e CHORUS_DEFAULT_INSTRUCTIONS_PATH=/etc/chorus/prompts/defaults.md
• Select role per container: -e CHORUS_ROLE=arbiter (example)
• Modify role YAML or defaults.md on the host; restart container to pick up changes (no rebuild).

Future Work

• Hot-reload via fsnotify or /api/prompts/reload endpoint.
• WHOOSH integration endpoint to enumerate roles and return composed S + D per team member.
• Per-role overrides for models/capabilities applied to AgentConfig.

Impact

• Prompts are now ops‑tunable via mounted files, reducing deployment friction.
• Consistent, centralized guidance for HMMM, COOEE, UCXL, and BACKBEAT across all agents.
• Backward compatible: if no files are mounted, system uses a sane fallback.