From e67d669df95cfdd3b5d395c3e3e9923955f6c960 Mon Sep 17 00:00:00 2001
From: anthonyrawlins <anthonyrawlins@users.noreply.github.com>
Date: Sat, 6 Sep 2025 15:46:17 +1000
Subject: [PATCH] docs(prompts): add README with structure, schema, and usage

---
 prompts/README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 prompts/README.md

diff --git a/prompts/README.md b/prompts/README.md
new file mode 100644
index 0000000..5791432
--- /dev/null
+++ b/prompts/README.md
@@ -0,0 +1,80 @@
+# 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.