61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
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.
|
||
|