Add README + Quickstart sections for agent execution

2026-06-28 13:49:06 -04:00
parent 6a8a2c61da
commit 94b3bf84b4
3 changed files with 194 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Prose Contracts — Syslog Solution LLC
+
+Operating contracts for Hermes agents. Each `.prose.md` file defines a **responsibility** (recurring duty) or **template** (scaffold) that agents can execute via OpenProse or follow manually.
+
+## How Agents Run These Contracts
+
+### Option A: Via OpenProse CLI (preferred)
+
+```bash
+prose run <contract-name> [param1=value1 param2=value2 ...]
+```
+
+**Examples:**
+
+```bash
+# Run a memory audit with default parameters
+prose run memory-audit-maintenance
+
+# Run a memory audit with custom threshold
+prose run memory-audit-maintenance memory_threshold=90 verify_configs=true
+
+# Configure a new agent with the template
+prose run hermes-config-template agent_name=syslog-devops default_model=claude-sonnet-4
+
+# Configure an agent with a different auxiliary model
+prose run hermes-config-template agent_name=syslog-code default_model=qwen3.6-27B-code auxiliary_model=gemma-4-12b
+```
+
+### Option B: Manual Execution
+
+If `prose` CLI isn't available, any agent can:
+1. Fetch the raw contract: `curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/<filename>`
+2. Read the **Execution** section
+3. Follow the steps
+
+**Example for fetching:**
+```bash
+curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/memory-audit-maintenance.prose.md
+```
+
+## Available Contracts
+
+### Responsibilities (Recurring Duties)
+
+| Contract | What It Does | When To Run |
+|---|---|---|
+| `memory-audit-maintenance` | Audits & reorganizes an agent's native memory (MEMORY.md, USER.md). Categorizes entries, moves rules to skills, verifies configs, frees up char budget. | Memory >85% usage or user request: "memory audit" |
+| `zulip-health` | Checks Zulip connectivity, message flow, and bot responsiveness. | On Zulip issues or periodic health check |
+| `litellm-health` | Verifies LiteLLM proxy connectivity, model availability, and key rotation. | On inference failures or periodic check |
+| `litellm-self-heal` | Attempts to fix common LiteLLM issues (key rotation, restart, config reload). | When litellm-health reports failures |
+| `zulip-mention-reliability` | Diagnoses and fixes @mention detection issues in Zulip. | On missed @mention reports |
+| `pm2-self-heal` | Restarts crashed PM2 processes and verifies recovery. | On PM2 process failure |
+
+### Templates (Scaffolds)
+
+| Contract | What It Does | Parameters |
+|---|---|---|
+| `hermes-config-template` | Generates a standard Hermes config for any agent. Enforces shared infra (Firecrawl, SearXNG, RA-H OS MCP, LiteLLM) while keeping model choices flexible. | `agent_name` (required), `default_model`, `default_provider`, `fallback_model`, `auxiliary_model` |
+
+### Scripts
+
+| File | What It Does |
+|---|---|
+| `pm2-self-heal.sh` | Shell script to restart crashed PM2 processes (companion to the prose contract) |
+
+## Contract Structure
+
+Every `.prose.md` file has the same structure:
+
+```
+---
+kind: <responsibility | template>
+name: <unique-name>
+description: ...
+---
+
+## Maintains        — What state the contract tracks
+## Parameters       — Tunable inputs (with defaults)
+## Continuity       — When to run (triggers & cadence)
+## Success Criteria — How to know it worked
+## Remembers        — What to learn between runs
+## <Type> Rules     — Inviolable rules for execution
+## Execution        — Step-by-step instructions
+## Example Output   — What a good run looks like
+```
+
+## Adding New Contracts
+
+1. Create a `.prose.md` file following the structure above
+2. Push to this repo
+3. The contract is immediately available for any agent to `prose run`
+
+## Repository
+
+- **URL:** https://git.sysloggh.net/SyslogSolution/prose-contracts
+- **Branch:** master
+- **Auth:** mumuni-bot (write access via PAT)