AGENTS.md

Always-on operating contract for AI agents working in this repository. Keep this file short: every coding turn pays its full cost via CLAUDE.md and Cursor rules. Deep ops live under docs/agent/ — open the row that matches the task, not the whole of deep-ops.md or review-ops.md.

It is not a Hermes tutorial. Per-surface knowledge lives in skills/; the authoring standard lives in CONTRIBUTING.md. Where those two disagree, CONTRIBUTING.md wins on what to write and this file wins on how to work in the repo.

Identity and non-goals

hermes-guide is a curated Hermes plugin catalog entry (hermes-guide, community tier) plus a skills tap. It inspects Hermes; it contains zero Hermes source and is not a fork of hermes-agent.

• Complement, don't duplicate. Prefer built-in hermes doctor / helpers when they already answer; trim any check that starts overlapping a built-in.
• Read-only. No config mutation, no auto-fix, no privileged capabilities: without a concrete need (tools/check_no_mutation.py).
• Never rebrand Hermes CLI output. Parse it into check envelopes; do not rewrite upstream messages as ours.
• Not core, permanently. hermes-guide will not seek to become part of Hermes core, and no change to Hermes code or behavior is filed upstream for this plugin's benefit. The exception is its own catalog listing, which lives in the upstream repository at plugin-catalog/hermes-guide.yaml under NousResearch/hermes-agent — that entry is ours to maintain, so pin bumps and disclosure edits there are ordinary maintenance reviewed like any other entry. Genuine Hermes defects found while diagnosing still go upstream as ordinary bug reports — the rule is about this plugin's scope, not about withholding real findings.

What ships

• Plugin — plugin.yaml + __init__.py / checks.py / constants.py. Registers /hermes-doctor and hermes guide (twelve read-only health checks: config, mcp, skills, commands, hooks, plugins, memories, sessions, storage, dashboard, update, gateway).
• Skills — thirty-one skills/<name>/SKILL.md files: one install guide (installing-hermes), one configuration map (hermes-configuration-guide), twenty-seven diagnosing-* playbooks, two other skills (hermes-post-update, plugin-authoring). They install separately, through the skills tap.

Catalog install: hermes plugins install hermes-guide. Skills: hermes skills tap add iap/hermes-guide. $HERMES_HOME is ~/.hermes on POSIX and %LOCALAPPDATA%\hermes on native Windows; hermes config path is ground truth.

Repo layout encyclopedia: docs/agent/layout.md.

Where a change goes

Run this before you claim done

python tools/check_gates.py          # hermetic tier — no network/Hermes; count via --list (four gates read the git index: test_skill_counts, check_doc_style, check_eol_contract, check_scope_enumeration)
python -m py_compile __init__.py checks.py constants.py
hermes plugins doctor . --ci         # needs a local Hermes; if it times out on a degraded host, record `not run` with cause

python tools/check_gates.py --list prints the tier and what it leaves to CI. Adding a skill or editing a SKILL.md also means:

python tools/render_docs.py --write  # refresh generated blocks (never hand-edit inside them)
python tools/check_skill_version_bump.py origin/master
python tools/check_skill_provenance.py

CI adds tools/test_*.py, citation integrity, install-scan parity, mypy, and bandit. Skip → say not run in the PR validation table. Full testing/security/git rules: docs/agent/deep-ops.md.

[!NOTE] Guards in tools/ read text. Executable scripts in skills/*/scripts/ need behavioral coverage in tools/test_*.py — a green guard suite is not evidence the script is correct.

Hard contracts (one line each)

Never git add -A. Stage named paths. Platform facts: three claim tiers (shared / cross-platform prose / platform-owned); WSL is its own class — see deep-ops.md. Name the verifying host in the PR Environment block.

Traps

[!IMPORTANT] Don't guess Hermes hook event names. The valid set is hermes_cli/plugins.py::VALID_HOOKS and it grows across releases — read the installed source, never a hardcoded count.

[!WARNING] Don't confuse Hermes with Claude Code or ZCode. Hermes has no standalone command files (commands come from built-ins, skills-as-slash, bundles, and plugins), hooks span four separate systems, and plugins are plugin.yaml + register(ctx) — not plugin.json. See diagnosing-commands and diagnosing-hooks.

[!WARNING] Don't confuse hermes-guide with hermes-agent. hermes-agent (NousResearch) is the assistant itself — CLI, runtime, doctor, skills engine; its bugs go upstream. hermes-guide (this repo) is a diagnostics plugin + skills tap that only inspects Hermes. Never edit ~/.hermes/hermes-agent source to fix a guide finding, and never file guide bugs upstream (or Hermes bugs here) — confirm which component is defective first (hermes --version, install directory, hermes guide output).

[!WARNING] Don't hardcode a venv path. Older checkouts carry venv/ and .venv/ side by side and project_venv_dir() resolves venv first; PM-era installs have no in-tree venv at all and project_venv_dir() returns None even when a dependency environment exists — ask PM (committed_venv() for the directory, project_python() for the interpreter, and they are not interchangeable). diagnosing-path has the resolution order and the cross-platform patterns.

[!NOTE] An untracked skills/<name>/ fails the pre-commit hook. The gates read the working tree, so a new skill directory that is not yet staged breaks the count and routing gates on every commit. git add or git stash it first.

[!TIP] Hermes configuration is YAML, never JSON. And every diagnosis should end in a concrete action: a hermes <subcommand>, or a specific file + field edit, followed by a /reload-* or a restart.

[!WARNING] On hosts whose macOS < 13, do not let a full hermes update re-resolve the node tool. Handling, pins, and upstream tracking live in deep-ops.md — Host limitation register.

Release flow (agent checklist)

Releases ship via stacked PRs and tag-gated releases. Working checklist for any release-related change (the authoritative, always-current source is CONTRIBUTING.md#cutting-a-release):

1. Confirm no skill version regressions before the bump: python tools/check_skill_version_bump.py origin/master — 0 failures. A downgraded SKILL.md version is a bug, not a release note. The version-bump PR also runs the release guard (python tools/check_no_active_release.py --version <proposed>), which refuses the bump while a release is active (latest tag created within --window-hours, default 48h) or when the proposed version is already a git tag (a redundant release). A CHANGELOG.md section for the new version is required by design and is not a refusal signal.
2. Bump the version in all five sites (plugin.yaml, __init__.py, SECURITY.md policy sentence + supported table, pyproject.toml), with the bump uncommitted.
3. Generate the section in the same checkout: python tools/gen_changelog.py --upcoming. Requires git fetch --tags — the tag half of the check is invisible without tags.
4. Commit the bump and the section together, then run python tools/check_gates.py — all hermetic gates in --list must pass locally; the gates it leaves to CI must pass in CI before merge.
5. Merge the PR, then check readiness on the merged master: python tools/check_release_readiness.py. It fails a dirty tree or a non-master branch; when the origin/master fetch fails it reports sync as an advisory, so confirm HEAD == origin/master by hand before tagging.
6. Audit the one drift direction the guard cannot see (docs/agent/deep-ops.md, "Values that drift go in constants.py"): git ls-tree -d --name-only <upstream-head>:plugins/ vs PLUGIN_SUBCATEGORY_DIRS.
7. Tag, verify, push, and re-pin: create the tag annotated and signed — git tag -s v<plugin.yaml version> master (local tag.gpgsign true makes this the default; same SSH key as commit signing — if git tag -s falls back to GPG or fails, configure gpg.format=ssh and user.signingkey first). Set git config gpg.ssh.allowedSignersFile .github/allowed_signers, then run git tag -v v<version> 1>/dev/null and confirm its first (stderr) line starts with Good "git" signature for — stdout carries the tag payload, so an unredirected check can show object ... even for a valid tag. Then push v<plugin.yaml version> to master, then re-pin the upstream catalog entry (NousResearch/hermes-agent, plugin-catalog/hermes-guide.yaml): sha = git rev-parse v<version>^{commit}, version = tag without the v. Refresh an open pin PR rather than opening a second one; run python scripts/validate_plugin_catalog.py plugin-catalog in that clone, then re-run python tools/check_release_readiness.py here.
8. Verify the release: release.yml fails closed unless the tag matches plugin.yaml, the tagged commit is on master, every tag has a changelog section, and the tag is annotated + SSH-signed (verifier line first, against .github/allowed_signers). Confirm with gh release view v<version> after creation.

The full procedure, including readiness verdicts and the drift audit, is CONTRIBUTING.md#cutting-a-release. Deep-ops reference material lives in docs/agent/deep-ops.md.

Dual-environment verification

This repo is maintained from Windows + NixOS WSL in parallel. Both targets must be verified independently:

• Windows — standard installer (curl | bash), Tier 1 (supported).
• NixOS WSL — standard installer in WSL, Tier 1 (supported). Nix bundle is Tier 2 (best-effort), immutable, uses uv2nix for build-time only.

Verify any cross-platform skill on BOTH environments. Document the verifying host in the PR Environment block. NixOS WSL standard install is mutable: the plugin is at ~/.hermes/plugins/<name>/ (NOT /nix/store/).

Before you finish

State plainly what you checked, what passed, and what you skipped. A validation table with honest not run entries is accepted; a claim that outruns the evidence is not — validate-claim.yml re-runs the hermetic gates against your PR head and fails the check if your table does not match reality.

Pre-merge cross-check (MANDATORY)

NEVER merge on green CI alone. Follow the complete procedure in docs/agent/review-ops.md#pre-merge-cross-check.

Key points: Qodo is the automatic primary — post /agentic_review only when it has never reviewed the PR, never per head; CodeRabbit full review once after Qodo's findings are resolved, then @coderabbitai review (incremental) per head until its check completes clean, never resolve threads manually. All required checks passing (not pending), Qodo has no open findings on the current head, mergeStateStatus: CLEAN, explicit merge authorization recorded, fresh green CI on fixed head.