| name | hermes-harness |
| description | jleechanbrain / Hermes-specific harness — gateway, canary, deploy, lane backlog, staging vs prod. Use with user-scope harness-engineering. |
Hermes Harness (repository-local)
Scope: This skill applies to ~/.smartclaw (the jleechanbrain harness repo) and production/staging gateway operations. It does not replace the general protocol in ~/.claude/skills/harness-engineering/SKILL.md — it extends it for Hermes-specific failure modes.
When to use
- Gateway "down" for Slack while
curl /health is 200
- Deploy, canary, or launchd questions
lane wait exceeded / queueAhead in gateway.err.log- Staging vs prod confusion (
~/.smartclaw/ vs ~/.smartclaw_prod/)
Read first (mandatory)
- User-scope (general):
~/.claude/skills/harness-engineering/SKILL.md and ~/.claude/commands/harness.md
- Repo root:
CLAUDE.md — Gateway (Local Machine), WS churn, session locks, lane backlog
- This repo:
agent-orchestrator.yaml — reactions, evolve loop references
Hermes-specific failure classes
| Symptom | Where to look | Harness fix layer |
|---|
Slack silent, /health OK | gateway.err.log: lane wait exceeded, queueAhead | CLAUDE.md, doctor.sh + staging-canary.sh lane probe |
session file locked | Stale .jsonl.lock in $HERMES_HOME/agents/main/sessions/ | Lock cleanup + restart (see CLAUDE.md) |
| Staging missing, prod OK | launchctl print gui/$UID/ai.smartclaw.staging | Bootstrap staging plist |
| Multi-gateway orphan | pgrep -x hermes > expected | deploy.sh / CLAUDE.md single-instance |
| WS churn / pong starvation | SlackWebSocket:N high | Lower timeoutSeconds × maxConcurrent per CLAUDE.md |
Verification checklist (after any harness change)
bash scripts/doctor.sh (or HERMES_DOCTOR_SKIP_INFERENCE=1 when appropriate)bash scripts/staging-canary.sh --port 8643 for prod config path when testing prod (includes gateway.err.log lane-backlog probe; parity with doctor)- Required when diagnosing Slack connectivity or "silent gateway": send a real Slack test message — HTTP
/health alone cannot prove Slack delivery; combine with steps 1–2.
Relationship to /harness
- Global
/harness (~/.claude/commands/harness.md) — 5 Whys, failure classes, audit mode — any repo.
- Repo-local
/harness (.claude/commands/harness.md in this workspace) — short pointer + Hermes gates; wins for project-specific detail when both exist.
Anti-patterns
- Declaring "fixed" after
curl /health without checking gateway.err.log tail
- Editing
~/.smartclaw/ directly in production without deploy flow (see CLAUDE.md worktree rule) — harness fixes still go through PR unless emergency exception
