| name | hermes-goals |
| metadata | {"author":"rhoai3-coding-demo","version":"1.0.0","platform-family":"hermes","platform-baseline":"repo","ocp-baseline":"repo","skill-group":"Hermes Agent"} |
| description | Use when designing or reviewing Hermes Persistent Goals (/goal) for stage 080: the judge loop, completion contracts, quality gates, background-process parking, turn budgets, and when to choose /goal vs a kanban card vs kanban --goal. Do NOT use for board orchestration (use hermes-kanban) or auxiliary.goal_judge key wiring (use hermes-configuration).
|
Hermes Persistent Goals (/goal)
Use this skill for single-session autonomous iteration — "a standing
objective that survives across turns" (Hermes' take on the Ralph loop,
independently implemented; user-facing design credited to Codex CLI's
/goal by Eric Traut).
Source Grounding
Official page (captured 2026-08-12, see references/source-capture.md):
https://hermes-agent.nousresearch.com/docs/user-guide/features/goals
Key Concepts
The loop
After each turn a lightweight judge checks the goal; if unmet, Hermes
"automatically feeds a continuation prompt back into the same session and
keeps working — until the goal is achieved, you pause or clear it, or the
turn budget runs out." The judge sees the goal text + ~4 KB of the recent
response and returns strict JSON (done | continue | wait); it is
"deliberately conservative" (marks done only on explicit confirmation)
and fail-open: "a broken judge never wedges progress" — errors count
as continue. Real user messages always preempt the loop.
Scope — one session, never the board
/goal is single-session: it "never creates a kanban card, never assigns
work to another profile, and never fans out". A kanban card created with
--goal "borrows the engine, not the board" — the same loop inside that
one card's worker session. Many tasks / dependencies / other profiles →
kanban (see hermes-kanban).
Completion contracts
A contract names "what done means, how to prove it, what not to break,
what's in scope, and when to stop". Fields (all optional): outcome,
verification, constraints, boundaries, stop_when. Two ways to set:
/goal draft <one-liner> (the goal_judge auxiliary expands it —
recommended) or inline field prefixes:
/goal Migrate auth to JWT
verify: pytest tests/auth passes
constraints: keep the /login response shape unchanged
boundaries: only touch services/auth and its tests
stop when: a DB schema migration is required
"The judge is only as good as your goal text" — write the body as
explicit acceptance criteria.
Quality gates (deterministic floor under the LLM judge)
A gate is "a deterministic shell command that must exit 0 before the goal
can complete at all" — gates "run before the judge. If any fails, the
judge is not called." Unchanged workspace (git fingerprint) skips
re-runs; each gate defaults to 3 retries / 5-minute timeout, and
exhausting retries auto-pauses the goal. Manage with /goal gate add|list|remove|clear. This is the official numeric-oracle pattern:
put the objective bar in a gate, not in judge prose.
Parking (no busy-waiting)
The judge sees live background processes and can return wait: the loop
"parks" — "no judge call, no continuation, no turn consumed" — until the
wait releases (wait_on_session, wait_on_pid, wait_for_seconds;
manual /goal wait <pid> / /goal unwait). The right shape for CI,
builds, and deploys.
Budget and controls
goals.max_turns default 20; on exhaustion the goal auto-pauses and
/goal resume "resets the counter to zero, so you can keep going in
measured chunks". Commands: /goal <text> (set/replace), /goal status|pause|resume|clear, /subgoal <text> (append acceptance criteria
mid-loop), /subgoal remove <N>. Judge model routes via
auxiliary.goal_judge (~200 output tokens/turn — "a cheap fast model is
usually the right call"; wiring in hermes-configuration).
When the judge is wrong
False negative (says continue when done) — "the turn budget catches
this." False positive (says done early) — follow up or re-set the goal
more precisely; the conservative prompt makes false positives the rarer
mode.
Workflow
- Choose the primitive first: this-chat iteration →
/goal; board
card that iterates → kanban --goal; multi-task/multi-profile →
kanban proper.
- Always attach a contract (draft or inline) — vague goal text is the
main failure mode.
- Put every objective criterion into a quality gate (test suite, lint,
build) so completion has a deterministic floor.
- For long external waits, rely on parking — never poll from goal text.
- Size
goals.max_turns to the work; resume in measured chunks rather
than raising it blindly.
- Cite the official section in the PR (stage 080 official-first rule).
Validation
/goal status # goal text, turns used, gates, wait state
/goal gate list # gates and their pass/fail state
hermes config get goals --json # effective budget
hermes config get auxiliary.goal_judge --json # judge routing
Pitfalls
- Expecting
/goal to touch the kanban board — it never does; the
overlap is deliberate and small (--goal cards borrow the engine
only).
- Relying on the judge for objective criteria — gates exist precisely
because "the judge is only as good as your goal text".
- Treating a judge error as a stop — fail-open means
continue; the
budget is the real backstop.
- Raising
max_turns instead of fixing a vague contract — the budget
catching false negatives is a feature.
- Busy-wait goal text ("keep checking CI") — use parking verdicts or
/goal wait <pid>.
- Skipping
--goal cost thinking on cheap one-shot cards — per-turn
judge overhead isn't worth it (kanban capture's own guidance).
Related Skills
hermes-kanban — the board; --goal cards and the goals-vs-kanban
decision table.hermes-configuration — goals.* and auxiliary.goal_judge wiring.hermes-delegation — fork-join subagents (a third, different
primitive).
References
references/source-capture.md
