Sam & Claude
815c482a7d
Pull durable knowledge out of agent session memory into the cross-harness contract so every harness/agent honors it, not just this session: - USER.md: new Conventions & voice section (EU date format DD.mon.YYYY, positive instruction framing, plain-language naming + detection not sniffing, lean/current docs). Colibri fact 12 -> 13 crates, MIT, v0.11.0. - AGENTS.md: two operating rules (verify on the forge not local git status; CI dormant by choice, merges ride local gates, domedog stays Docker-free). - HOST-MATRIX.md + AGENTS.md matrix: domedog isolation Docker -> host (no Docker), matching the probe in HOST-MATRIX section 3. - curated/: colibri 13 crates/MIT/0.11.0 + vault, python3=3.11 policy, real Docker layout (debby only; domedog Docker-free), hermes-bsd row. Validated: scripts/layered_soul.py validate . -> OK. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
91 lines
5.6 KiB
Markdown
91 lines
5.6 KiB
Markdown
# Layered Soul Agent Rules
|
|
|
|
- Do not commit secrets, API keys, auth tokens, browser profiles, or raw credential files.
|
|
- Do not import raw sessions into another harness by default.
|
|
- Curate memories before adding them under `memories/curated/`.
|
|
- Keep Hermes-native runtime configuration in `hermes-soul`; this repository is the cross-harness contract.
|
|
- Public examples may reference private source repositories by URL/name, but must not quote or copy their private contents.
|
|
- Use `scripts/layered_soul.py validate .` before committing structural changes.
|
|
- Pull before editing hot shared files (`AGENTS.md`, `docs/HOST-MATRIX.md`, `docs/CAPABILITY-ROUTING.md`); keep history linear and re-check after rebases.
|
|
- Verify on the forge, not local status: "pushed/landed" is confirmed against Forgejo (API or a fresh `git fetch --prune` of origin), never a clean `git status`. An empty working tree only means it matches local HEAD — durability holds only once commits reach origin. `git status -sb` shows "ahead N" when commits are unpushed.
|
|
- CI is dormant by choice: no Forgejo Actions runner is registered, so checks sit `pending` — merges ride local-green gates (format/clippy/test/drift checks), and `pending` CI is expected, not a blocker. domedog stays Docker-free; don't propose a Docker runner on it.
|
|
- When adapting for Colibri: reviewed skills map to `system_skills`, curated memory maps to `system_brain`, converted task manifests map to `system_ops`.
|
|
- When adapting for Hermes (upstream, Linux): load as profile context (SOUL.md + USER.md + IDENTITY.md). Hermes-native config and cron stay in `hermes-soul`.
|
|
- When adapting for hermes-osa (FreeBSD-native Hermes, clean-room MIT via `hermes-bsd`): same profile-context load; FreeBSD-specific gaps (voice, clipboard) are known and tracked in `docs/CLAWDIE-HERMES-FREEBSD-INTEGRATION.md`.
|
|
- When adapting for Pi/Codex/Claude Code/Zot: render the prompt bundle (`render-prompt`) and inject as task-scoped context. Durable findings flow back through reviewed commits.
|
|
|
|
## Quota exhaustion policy (cross-harness)
|
|
|
|
When any agent hits an API quota limit (429 / rate-limit):
|
|
|
|
1. **Calculate reset time** with `scripts/quota_reset_eta.py` — parses provider error
|
|
messages and converts to UTC/CEST correctly. Handles Beijing time (Z.AI/DeepSeek),
|
|
UTC (OpenRouter), and PDT (Anthropic/OpenAI).
|
|
|
|
2. **Check if task already resolved** with `scripts/task_dedup_before_retry.py` —
|
|
queries Colibri task board, checks git activity since block time. Skips retry
|
|
if another agent or operator already completed the work.
|
|
|
|
3. **Schedule retry** — create a one-shot cron at reset time + 60s buffer.
|
|
Never retry immediately (429 means quota, not transient).
|
|
|
|
4. **Report** — log to glasspane: provider, reset time, task status, action taken.
|
|
|
|
Rule: **never retry a quota-blocked task without checking whether it was
|
|
already solved.** Tokens are money. A solved task retried is waste.
|
|
|
|
## Active infrastructure
|
|
|
|
- Forgejo: code.smilepowered.org (SSH port 2222)
|
|
- Vaultwarden: vault.smilepowered.org (SSL)
|
|
- Tailscale: debby=${DEBBY_TS_IP}, domedog=${DOMEDOG_TS_IP}, osa=${OSA_TS_IP}
|
|
- Commit identity: `hello@clawdie.si` for all project commits
|
|
|
|
### Topology & channel masking (do not commit real values)
|
|
|
|
Real Tailscale IPs and Telegram bot handles **never go into committed files** — they
|
|
were leaked once; not again. Committed docs reference variable names only
|
|
(`${OSA_TS_IP}`, `${HERMES_BOT}`, …). To resolve them:
|
|
|
|
- **IPs** are live-discoverable any time with `tailscale status`.
|
|
- **Handles + IPs** are stored in `fleet.env` (gitignored). Copy `fleet.env.example` →
|
|
`fleet.env` and fill from `tailscale status` / Vaultwarden, then `source fleet.env`.
|
|
|
|
When editing docs: if you're about to paste a `100.x` IP or an `@…_bot` handle, stop and
|
|
use the placeholder instead.
|
|
|
|
## Agent matrix (5 agents across 3 hosts, 2 OS families)
|
|
|
|
| Agent | Host | Harness | OS | Isolation | Role |
|
|
| ---------- | ------- | ----------------------- | ---------- | ------------------ | ------------------------- |
|
|
| hermes-osa | osa | Hermes Agent (FreeBSD) | FreeBSD 15 | host service first | **Orchestrator + board host (always-on VPS)** |
|
|
| Hermes | debby | Hermes Agent (upstream) | Debian 13 | Docker | Secondary agent + soul backup (intermittent laptop) |
|
|
| Zot | debby | Zot RPC | Debian 13 | Docker | Coding, media workflows |
|
|
| Claude | domedog | Claude Code | Linux | host (no Docker) | Verification, review |
|
|
| Codex | osa | Codex CLI | FreeBSD 15 | Bastille jail | ISO builds, validation |
|
|
|
|
**Survivability**: Linux/Docker and FreeBSD/jails are complementary safeguards.
|
|
A vulnerability that kills one platform cannot kill the other. Agents can be
|
|
relocated across platforms in minutes via layered-soul identity injection.
|
|
|
|
## Private sources
|
|
|
|
- `hermes-soul`: git@code.smilepowered.org:clawdie/hermes-soul.git (private, operator access only)
|
|
- `hermes-bsd`: git@code.smilepowered.org:clawdie/hermes-bsd.git (public, MIT-licensed FreeBSD patches)
|
|
- `clawdie-ai`: git@code.smilepowered.org:clawdie/clawdie-ai.git (private)
|
|
- `clawdie-iso`: git@code.smilepowered.org:clawdie/clawdie-iso.git (private)
|
|
|
|
## Quick reference
|
|
|
|
```sh
|
|
# Validate
|
|
python3 scripts/layered_soul.py validate .
|
|
|
|
# See what's available from hermes-soul
|
|
python3 scripts/layered_soul.py plan-private-source \
|
|
examples/private-sources/hermes-soul.example.json \
|
|
--source-root ~/hermes-soul
|
|
|
|
# Render for a harness
|
|
python3 scripts/layered_soul.py render-prompt . --output /tmp/soul-prompt.md
|
|
```
|