CHORUS/prompts

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

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.