feat: add Hermes Agent support

[xiaoquisme]

What

Adds Hermes Agent as a supported OpenSpec tool using project-local skills under .hermes/skills/.

Continues the Hermes support work from #1095 and addresses the requested review changes there.

Closes #1333

Changes

• Add hermes to AI_TOOLS with skillsDir: '.hermes'
• Detect Hermes from .hermes, HERMES.md, or .hermes.md
• Do not detect Hermes from generic CONTEXT.md
• Document Hermes skill paths, user-facing /openspec-* invocation, and skills.external_dirs setup
• Add available-tools regression coverage for Hermes detection

Validation

• ./node_modules/.bin/vitest run test/core/available-tools.test.ts
• ./node_modules/.bin/tsc --noEmit
• ./node_modules/.bin/eslint src/ (passes with existing warning in src/core/references.ts)
• node build.js

Summary by CodeRabbit

• New Features
  • Added Hermes Agent to supported tools with automatic detection (e.g., HERMES.md, .hermes.md, and .hermes/) and mapping to a .hermes skills directory.
  • Hermes now shows “setup required” guidance during initialization and updates; Hermes commands are skipped since no adapter is generated.
• Documentation
  • Updated supported tools docs with Hermes configuration and how to expose project-local skills via skills.external_dirs in ~/.hermes/config.yaml.
• Tests
  • Expanded coverage for Hermes detection and for setup-required messaging across init and update flows.

[coderabbitai]

📝 Walkthrough

Walkthrough

Hermes Agent support adds tool registration and detection, skills-only initialization and updates, setup guidance, specification coverage, tests, and documentation for external skill directories.

Changes

Hermes Agent support

Layer / File(s)	Summary
Tool definition and detection src/core/config.ts, openspec/specs/ai-tool-paths/spec.md, test/core/available-tools.test.ts	Registers Hermes with .hermes skills metadata and detection paths, specifies its setup note, and tests positive and negative detection cases.
Skills-only init and update flow src/core/init.ts, src/core/update.ts, test/core/command-generation/registry.test.ts, test/core/init.test.ts, test/core/update.test.ts	Creates Hermes skills without commands and displays setup guidance during initialization, normal updates, and already-up-to-date updates.
Configuration documentation docs/supported-tools.md	Documents Hermes paths, external skill configuration, and the hermes tool ID.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1266: Adds a related skills-only tool entry and adapterless registry behavior.
• Fission-AI/OpenSpec#1350: Extends Hermes support across shared tool configuration and initialization/update behavior.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly states the main change: Hermes Agent support.
Linked Issues check	✅ Passed	The PR adds Hermes as an init option and supports the requested Hermes tool selection.
Out of Scope Changes check	✅ Passed	The changes stay focused on Hermes support, related docs, tests, and setup notes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alfred-openspec]

Hermes only scans its home skills directory unless skills.external_dirs is configured, but this PR writes project .hermes/skills and only documents the manual step, so init can report success for assets Hermes ignores by default. Please add adapterless init and registry coverage and either make the generated path usable automatically or emit a clear setup warning during init and update.

[clay-good]

Pushed aab39a3 addressing @alfred-openspec's review:

• Setup warning during init and update: AIToolOption gains a setupNote field; Hermes' note tells users to add the project .hermes/skills directory to skills.external_dirs in ~/.hermes/config.yaml. It is printed by openspec init, openspec update (both the update path and the already-up-to-date path), so init no longer reports silent success for skills Hermes ignores by default.
• Adapterless init coverage: new init test asserting .hermes/skills/openspec-*/SKILL.md is generated, no .hermes/commands directory is created, and both the "Commands skipped" and setup-note lines are shown.
• Registry coverage: registry test now pins that skills-only tools (hermes, kimi) have no command adapter; update tests cover the setup note on both update paths.
• Spec scenario extended accordingly (openspec validate --specs passes).

Verified end-to-end with the built CLI (openspec init --tools hermes and openspec update both print the setup note).

[alfred-openspec]

The remediation covers the adapterless init contract and surfaces the required Hermes external_dirs setup note during init, normal update, and the already-up-to-date path. The manual configuration limitation is now explicit, focused coverage is present, and full CI is green.

[clay-good]

Merged main into this branch (bed26f0) resolving conflicts with #1354 (the missing-core-workflows note rename) and #1208 (kimi-code migration tests) — both sides' tests kept, displaySetupNotes now runs alongside the renamed displayMissingCoreWorkflowsNote. Affected suites pass locally. @alfred-openspec please re-review.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

test/core/update.test.ts (1)

216-217: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Normalize path separators for cross-platform test reliability.

The CLI output expectation hard-codes Unix path separators (/). If the implementation logs platform-specific paths natively (using \), this test will fail on Windows. As per coding guidelines, do not hard-code Unix path separators in CLI output expectations; instead, normalize both actual and expected strings before comparing them to guarantee cross-platform consistency.

💻 Proposed fix

-      const logCalls = consoleSpy.mock.calls.flat().map(String);
-      expect(logCalls.some((entry) => entry.includes('.kimi/skills') && entry.includes('.kimi-code/skills'))).toBe(true);
+      const logCalls = consoleSpy.mock.calls.flat().map(String).map(entry => entry.replace(/\\/g, '/'));
+      expect(logCalls.some((entry) => entry.includes('.kimi/skills') && entry.includes('.kimi-code/skills'))).toBe(true);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/core/update.test.ts` around lines 216 - 217, Update the log assertion
around logCalls to normalize path separators in the captured CLI output before
checking for the .kimi/skills and .kimi-code/skills paths, and apply the same
normalization to the expected path fragments so the test passes consistently
across platforms.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@test/core/update.test.ts`:
- Around line 216-217: Update the log assertion around logCalls to normalize
path separators in the captured CLI output before checking for the .kimi/skills
and .kimi-code/skills paths, and apply the same normalization to the expected
path fragments so the test passes consistently across platforms.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f38dbbd6-28e2-4ad6-81ec-0d69bbbbcb11

📥 Commits

Reviewing files that changed from the base of the PR and between aab39a3 and bed26f0.

📒 Files selected for processing (7)

• docs/supported-tools.md
• openspec/specs/ai-tool-paths/spec.md
• src/core/config.ts
• src/core/init.ts
• src/core/update.ts
• test/core/init.test.ts
• test/core/update.test.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• src/core/init.ts
• src/core/update.ts
• openspec/specs/ai-tool-paths/spec.md
• docs/supported-tools.md
• src/core/config.ts

[alfred-openspec]

Verified the rebase keeps the Hermes adapterless init contract, skills.external_dirs setup note across init and both update paths, and focused registry/detection coverage while preserving the renamed core-workflow note and Kimi migration tests from main. The final diff is scoped, mergeable, and fully green across Windows, macOS, and Linux.