From 1e7c5a7153cc4295deeb6409e0c5e3cd63c0635d Mon Sep 17 00:00:00 2001 From: dtoro Date: Tue, 2 Jun 2026 00:54:03 +0200 Subject: [PATCH] hermes-soul: auto-provision SOUL.md from HERMES.md via setup-hermes-soul.sh - tools/setup-hermes-soul.sh: new auto-setup script (no-op on non-Hermes) - HERMES.md: canonical persona for all agent types, agent-type table - AGENTS.md: auto-setup section lists both caveman and hermes-soul - post-pull.sh runs it automatically on every sync --- AGENTS.md | 4 +++ HERMES.md | 47 ++++++++++++++++++++++---- tools/setup-hermes-soul.sh | 68 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 112 insertions(+), 7 deletions(-) create mode 100755 tools/setup-hermes-soul.sh diff --git a/AGENTS.md b/AGENTS.md index f4b0e63..94c1ad0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,6 +94,10 @@ Currently auto-setup: - **Caveman + templates** (`tools/setup-caveman.sh`): Installs Caveman npm package, wrapper scripts, and compact output templates for token-efficient CLI output. Wrapper at `~/bin/caveman_wrapper.sh`. +- **Hermes agent persona** (`tools/setup-hermes-soul.sh`): Provisions + `~/.hermes/SOUL.md` from `HERMES.md` on Hermes agents. This ensures every + Hermes agent follows the canonical homelab persona (token efficiency, source + of truth hierarchy). No-op on non-Hermes agents. To add a new auto-setup, create `tools/.setup.sh` in the repo, commit and push. All enrolled clients pick it up within 5 minutes. diff --git a/HERMES.md b/HERMES.md index 3be27b0..bb5cbf2 100644 --- a/HERMES.md +++ b/HERMES.md @@ -1,7 +1,33 @@ -# HERMES.md — Agent persona for Goose sessions on homelab clients +# HERMES.md — Agent persona for homelab clients -You are running on a machine in the **hubris** homelab. Your primary context -is `/opt/homelab-context/AGENTS.md` — read that first. +This file is the canonical agent persona for **all** AI agents running on +machines in the **hubris** homelab. It prescribes behaviour, token-efficiency +conventions, and the source-of-truth hierarchy. + +## Source of truth + +The homelab-context repo at `/opt/homelab-context/` is the single source of +truth for: +- Fleet topology (`inventory.yaml`, `hosts/*.yaml`) +- Service endpoints and credentials (via `homelab secret`) +- Agent behaviour and conventions +- Everything in this file + +When in doubt, check `/opt/homelab-context/` first. + +## Agent type — how this file gets loaded + +| Agent | Loading mechanism | +|-------|------------------| +| **Hermes** | `tools/setup-hermes-soul.sh` (auto-setup) → provisions `~/.hermes/SOUL.md` from this file | +| **Goose** | `.goosehints` symlink at `~/.config/goose/.goosehints` → `/opt/homelab-context/HERMES.md` | +| **Claude Code / Codex** | Symlink or copy this file into the project's `CLAUDES.md` / `.claude` instructions | + +**Do not edit SOUL.md or .goosehints directly.** Edit this file in the +homelab-context repo instead. Changes propagate to all clients on the next +sync (`sudo homelab sync`). + +--- ## Token efficiency (caveman skill) @@ -31,8 +57,8 @@ https://github.com/adityahimaone/hermes-agent-rtk-caveman. ### Templates Caveman templates live at `~/templates/`: -- `git_status.txt` — compact status format -- `git_log.txt` — compact log format +- `git_status.txt` — compact git status format +- `git_log.txt` — compact git log format - `lint_results.txt` — compact ESLint format - `test_results.txt` — compact vitest/jest format @@ -42,9 +68,16 @@ Caveman templates live at `~/templates/`: - Commands with no output — skip entirely - When you need the exact raw output for post-processing -## Verification +### Verification ```bash -# Check caveman is installed ls ~/bin/caveman_wrapper.sh && echo "caveman ready" ``` + +## Important note for Hermes agents + +If you are reading this as a Hermes agent, your SOUL.md was auto-provisioned +by `tools/setup-hermes-soul.sh`. This file is the canonical original — you +can verify the content matches or re-provision by running: + + bash /opt/homelab-context/tools/setup-hermes-soul.sh \ No newline at end of file diff --git a/tools/setup-hermes-soul.sh b/tools/setup-hermes-soul.sh new file mode 100755 index 0000000..ab2eb44 --- /dev/null +++ b/tools/setup-hermes-soul.sh @@ -0,0 +1,68 @@ +#!/usr/bin/env bash +# setup-hermes-soul.sh — auto-provisions Hermes SOUL.md from canonical HERMES.md. +# Runs automatically after every homelab-context git pull (via tools/post-pull.sh). +# +# What it does: +# - Detects if Hermes Agent is installed (~/.hermes/SOUL.md exists) +# - If yes, copies the canonical HERMES.md content into SOUL.md with +# an auto-generated header that declares /opt/homelab-context as source of truth +# - Idempotent — re-running re-copies if HERMES.md content changed +# +# For non-Hermes agents (Goose, Claude Code, etc.), this script is a no-op. +# Those agents use the `.goosehints` symlink mechanism instead. + +set -euo pipefail + +CONTEXT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +HERMES_MD="$CONTEXT_DIR/HERMES.md" +SOUL_MD="${HOME}/.hermes/SOUL.md" + +# Colors for output (only when connected to a terminal) +if [ -t 1 ]; then + GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m' +else + GREEN=''; YELLOW=''; NC='' +fi +ok() { echo -e "${GREEN}[hermes-soul]${NC} $1"; } +skip() { echo -e "${YELLOW}[hermes-soul]${NC} $1"; } + +# --- 1. Check if Hermes is installed --- +if [ ! -f "$SOUL_MD" ]; then + skip "hermes not installed (~/.hermes/SOUL.md not found) — skipping" + exit 0 +fi + +# --- 2. Check if canonical HERMES.md exists --- +if [ ! -f "$HERMES_MD" ]; then + echo "[hermes-soul] WARNING: $HERMES_MD not found — skipping" + exit 0 +fi + +# --- 3. Write SOUL.md with canon source header + HERMES.md content --- +{ + echo "# Hermes Agent Persona — homelab agent (${HOSTNAME:-$(hostname -s 2>/dev/null || echo 'unknown')})" + echo "" + echo "You are an AI agent running in the **hubris** homelab." + echo "" + cat << 'PRE' +## Source of truth + +The homelab-context repo at `/opt/homelab-context/` is the single source of truth for: +- Fleet topology (`inventory.yaml`, `hosts/*.yaml`) +- Service endpoints and credentials +- Agent behaviour and conventions + +This SOUL.md is auto-generated from `/opt/homelab-context/HERMES.md` by +`tools/setup-hermes-soul.sh`. Do not edit SOUL.md directly — edit HERMES.md +in the homelab-context repo instead. Changes propagate automatically on the +next sync or by running: + + sudo homelab sync + +--- + +PRE + cat "$HERMES_MD" +} > "$SOUL_MD" + +ok "SOUL.md provisioned from HERMES.md ($(wc -l < "$SOUL_MD") lines)" \ No newline at end of file