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