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.