# 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.