81 lines
3.0 KiB
Markdown
81 lines
3.0 KiB
Markdown
# CHORUS Prompts Directory
|
||
|
||
This directory holds runtime‑loaded prompt sources for agents. Mount it into containers to configure prompts without rebuilding images.
|
||
|
||
- Role prompts (S): YAML files defining agent roles and their `system_prompt`.
|
||
- Default instructions (D): A shared Markdown/TXT file applied to all agents.
|
||
- Composition: Final system prompt = S + two newlines + D.
|
||
|
||
## Mounting and Env Vars
|
||
- Bind mount (example): `-v /srv/chorus/prompts:/etc/chorus/prompts:ro`
|
||
- Env vars:
|
||
- `CHORUS_PROMPTS_DIR=/etc/chorus/prompts`
|
||
- `CHORUS_DEFAULT_INSTRUCTIONS_PATH=/etc/chorus/prompts/defaults.md` (optional)
|
||
- `CHORUS_ROLE=<role-id>` (selects which S to compose with D)
|
||
|
||
Reload: prompts are loaded at startup. Restart containers to pick up changes.
|
||
|
||
## Files and Structure
|
||
- `defaults.md` (or `defaults.txt`): global Default Instructions D
|
||
- `roles.yaml` (optional): multiple roles in one file
|
||
- `*.yaml` / `*.yml`: one or more files; all are merged by role ID
|
||
|
||
Example layout:
|
||
```
|
||
/etc/chorus/prompts/
|
||
defaults.md
|
||
roles.yaml
|
||
ops.yaml
|
||
analysts.yaml
|
||
```
|
||
|
||
## Role YAML Schema
|
||
Top-level key: `roles`. Each role is keyed by its role ID (used with `CHORUS_ROLE`).
|
||
|
||
```yaml
|
||
roles:
|
||
arbiter:
|
||
name: "Arbiter"
|
||
description: "Coordination lead for cross-agent planning and consensus."
|
||
tags: [coordination, planning]
|
||
system_prompt: |
|
||
You are Arbiter, a precise coordination lead...
|
||
defaults:
|
||
models: ["meta/llama-3.1-8b-instruct"]
|
||
capabilities: ["coordination","planning","dependency-analysis"]
|
||
expertise: []
|
||
max_tasks: 3
|
||
```
|
||
|
||
Notes:
|
||
- Role IDs must be unique across files; later files overwrite earlier definitions of the same ID.
|
||
- `system_prompt` is required to meaningfully customize an agent.
|
||
- `defaults` are advisory and can be used by orchestration; runtime currently composes only the prompt string (S + D).
|
||
|
||
## Default Instructions (D)
|
||
Provide generic guidance for all agents, including:
|
||
- When/how to use HMMM (collaborative reasoning), COOEE (coordination), UCXL (context), BACKBEAT (timing/phase telemetry)
|
||
- JSON envelopes for each message type
|
||
- Safety, auditability, and UCXL citation policy
|
||
|
||
File can be Markdown or plain text. Example: `defaults.md`.
|
||
|
||
## Composition Logic
|
||
- If `CHORUS_ROLE` is set and a matching role exists: final system prompt = role.system_prompt + "\n\n" + defaults
|
||
- Else, if defaults present: final = defaults
|
||
- Else: fallback to a minimal built‑in default
|
||
|
||
## Validation Tips
|
||
- Ensure mounted path and env vars are set in your compose/stack.
|
||
- Role ID used in `CHORUS_ROLE` must exist in the merged set.
|
||
- Restart the container after updating files.
|
||
|
||
## BACKBEAT Standards
|
||
Include clear guidance in `defaults.md` on:
|
||
- Phases: `prepare|plan|exec|verify|publish`
|
||
- Events: `start|heartbeat|complete`
|
||
- Correlation: `team_id`, `session_id`, `operation_id`, link to COOEE/HMMM IDs
|
||
- Budgets/latency, error reporting, and UCXL citations for escalations
|
||
|
||
See the repository’s `prompts/defaults.md` for a complete example.
|