mirror of
https://github.com/github/spec-kit.git
synced 2026-07-07 06:35:06 +08:00
feat: add Hermes Agent integration (with review fixes) (#2651)
* feat: add Hermes Agent integration * feat: add Hermes Agent integration * feat: add Hermes Agent integration * feat: add Hermes Agent integration (with review fixes) - Full SkillsIntegration subclass with dual install strategy (project-local .hermes/skills/ + global ~/.hermes/skills/) - CLI fix: integration_uninstall now calls integration.teardown() instead of manifest.uninstall() directly, allowing custom cleanup - Fix Copilot review issues: - Docstring now reflects both -Q (quiet) and -q (query) flags - Empty command guard prevents passing empty skill names - Add catalog entry for hermes in integrations/catalog.json Co-authored-by: Zhaoxiaoguang001 <3357983213@qq.com> * feat: write Hermes skills directly to global ~/.hermes/skills/ Hermes loads skills from the global ~/.hermes/skills/ directory, not from project-local paths. The old dual-install strategy copied SKILL.md files to both locations — project-local (for manifest tracking) and global (for Hermes discovery). This change removes the project-local copies entirely: - setup() writes directly to ~/.hermes/skills/speckit-*/SKILL.md - An empty .hermes/skills/ marker directory is created in the project so extension commands (e.g. git) can detect Hermes as an active integration via register_commands_for_all_agents() - teardown() cleans both the global speckit-* dirs and the local marker - import yaml moved to local import inside setup() Tests updated: Hermes-specific tests now assert global skill location, and shared SkillsIntegrationTests that assumed project-local files are overridden with Hermes-appropriate assertions. Co-authored-by: Zhaoxiaoguang001 <3357983213@qq.com> * fix: address Copilot review feedback on Hermes integration Addresses all 6 review comments from copilot-pull-request-reviewer: 1. Hard-fail on missing integration key → fall back to manifest.uninstall() with a warning instead of raising an error. Allows users to always remove stale integration files even when the integration class is missing from the registry. 2. HOME isolation in tests → every test that calls setup() or CliRunner now monkeypatches Path.home() to a temp directory, keeping the test suite hermetic and non-destructive. 3. HermesIntegration.teardown() now delegates to manifest.uninstall() for project-local tracked files (scripts, manifest), merging results with global cleanup. 4. Global skills cleanup gated behind force=True to avoid destroying speckit-* skills shared across multiple Spec Kit projects when running 'specify integration uninstall hermes' without --force. 5. Line 160 isolation (CLI test test_complete_file_inventory_sh). 6. Line 258 isolation (Path.home assertion in test_ai_hermes_without_ai_skills_auto_promotes). * fix: address second Copilot review round — 6 remaining observations - Move to module scope (was inside per-template loop) - Add safety checks in setup() matching standard - Fix docstrings: global skills always removed on uninstall (standard) - Fix removal tracking: only report after successful rmtree - Override shared test_modified_file_survives_uninstall with Hermes-appropriate behaviour (global skills always removed, no hash tracking) - Update PR description to match implementation (global-only skills + marker) * fix: add first-class global/home-based agent dir support in CommandRegistrar Resolves Copilot HIGH concern (discussion_r3312194525): HermesIntegration.registrar_config.dir was '.hermes/skills' (project- relative), but skills live in ~/.hermes/skills/ (global). Extensions and presets registering commands for the 'hermes' agent via CommandRegistrar would write to the project-local marker directory instead of the real global skills directory, making those commands invisible to Hermes. Fix consists of three parts: 1. CommandRegistrar._resolve_agent_dir now supports '~/'-prefixed and absolute paths in agent_config['dir']. Relative paths still resolve against project_root as before — zero change for existing agents (Claude, Codex, Gemini, etc.). 2. HermesIntegration.registrar_config.dir changed from '.hermes/skills' to '~/.hermes/skills', so extensions/presets write directly to the global directory Hermes searches at runtime. 3. Two inline project_root / agent_config['dir'] calls in the extension update backup/restore paths (src/specify_cli/__init__.py) now delegate to _resolve_agent_dir, giving them the same global-dir support plus the legacy_dir fallback they were missing (improvement for all agents). Test side-effect: test_update_failure_rolls_back_registry_hooks_and_commands was constructing verification paths with project_dir / '~/.hermes/skills' (literal tilde) — fixed to use _resolve_agent_dir and monkeypatch Path.home() so Hermes' global dir doesn't leak into the real filesystem. * fix: address remaining 3 Copilot review observations (round 3) - teardown docstring: clarify marker removal is conditional (if empty) - test_pre_existing_skills_not_removed: now actually calls teardown() to verify foreign skills survive uninstall (was only running setup) - integration_switch Phase 1: replaced old_manifest.uninstall() + remove_context_section() with current_integration.teardown(), matching the pattern already used in integration_uninstall. This ensures custom teardown logic (e.g. Hermes global skills cleanup) runs during switches. * fix: address Copilot round 4 — home-relative dir resolution + project-local detection 1. _resolve_agent_dir(): expand ~/... via Path.home() + slice instead of expanduser(), so tests that monkeypatch Path.home() properly isolate the home directory (Copilot r3312731595, r3312731729) 2. Add detect_dir field to registrar_config: Hermes declares detect_dir='.hermes/skills' (project-local marker). CommandRegistrar checks detect_dir before resolving the output dir, preventing global dirs like ~/.hermes/skills from causing false detection in every project (Copilot r3312731682) 3. test_update_failure_rolls_back: no additional changes needed — the _resolve_agent_dir fix makes the existing Path.home() monkeypatch effective, so ~/.hermes/skills is not found in the fake home and Hermes is properly skipped. Tests: 2236 passed (2009 integration + 195 extension + 32 hermes) --------- Co-authored-by: Zhaoxiaoguang001 <3357983213@qq.com> Co-authored-by: majordave <majordave@users.noreply.github.com>
This commit is contained in:
Dave Majors Stark
committed by
GitHub
GitHub
parent
0a8f31ef18
commit
5a50b75adb
@@ -1218,11 +1218,14 @@ def integration_uninstall(
|
||||
console.print(f"[dim]Details:[/dim] {exc}")
|
||||
raise typer.Exit(1)
|
||||
|
||||
removed, skipped = manifest.uninstall(project_root, force=force)
|
||||
|
||||
# Remove managed context section from the agent context file
|
||||
if integration:
|
||||
integration.remove_context_section(project_root)
|
||||
if not integration:
|
||||
console.print(
|
||||
f"[yellow]Warning:[/yellow] Integration '{key}' not found "
|
||||
"in registry. Falling back to manifest-based cleanup."
|
||||
)
|
||||
removed, skipped = manifest.uninstall(project_root, force=force)
|
||||
else:
|
||||
removed, skipped = integration.teardown(project_root, manifest, force=force)
|
||||
|
||||
remaining = [installed for installed in installed_keys if installed != key]
|
||||
new_default = default_key if default_key != key else (remaining[0] if remaining else None)
|
||||
@@ -1364,8 +1367,9 @@ def integration_switch(
|
||||
f"run [cyan]specify integration uninstall {installed_key}[/cyan], then retry."
|
||||
)
|
||||
raise typer.Exit(1)
|
||||
removed, skipped = old_manifest.uninstall(project_root, force=force)
|
||||
current_integration.remove_context_section(project_root)
|
||||
removed, skipped = current_integration.teardown(
|
||||
project_root, old_manifest, force=force,
|
||||
)
|
||||
if removed:
|
||||
console.print(f" Removed {len(removed)} file(s)")
|
||||
if skipped:
|
||||
@@ -3601,7 +3605,9 @@ def extension_update(
|
||||
if agent_name not in registrar.AGENT_CONFIGS:
|
||||
continue
|
||||
agent_config = registrar.AGENT_CONFIGS[agent_name]
|
||||
commands_dir = project_root / agent_config["dir"]
|
||||
commands_dir = _AgentReg._resolve_agent_dir(
|
||||
agent_name, agent_config, project_root
|
||||
)
|
||||
|
||||
for cmd_name in cmd_names:
|
||||
output_name = _AgentReg._compute_output_name(agent_name, cmd_name, agent_config)
|
||||
@@ -3762,7 +3768,9 @@ def extension_update(
|
||||
if agent_name not in registrar.AGENT_CONFIGS:
|
||||
continue
|
||||
agent_config = registrar.AGENT_CONFIGS[agent_name]
|
||||
commands_dir = project_root / agent_config["dir"]
|
||||
commands_dir = _AgentReg._resolve_agent_dir(
|
||||
agent_name, agent_config, project_root
|
||||
)
|
||||
|
||||
for cmd_name in cmd_names:
|
||||
output_name = _AgentReg._compute_output_name(agent_name, cmd_name, agent_config)
|
||||
|
||||
@@ -654,15 +654,28 @@ class CommandRegistrar:
|
||||
) -> Path:
|
||||
"""Return the agent command directory, falling back to legacy_dir.
|
||||
|
||||
When the canonical directory (``agent_config["dir"]``) does not
|
||||
exist but a ``legacy_dir`` is configured and present on disk,
|
||||
returns the legacy path and emits a deprecation warning advising
|
||||
the user to upgrade.
|
||||
Supports project-relative paths (e.g. ``.claude/skills/``),
|
||||
home-relative paths (e.g. ``~/.hermes/skills``), and absolute
|
||||
paths — the ``agent_config["dir"]`` value is resolved verbatim
|
||||
when absolute or starting with ``~/``, or joined with
|
||||
``project_root`` when relative.
|
||||
|
||||
When the canonical directory does not exist but a ``legacy_dir``
|
||||
is configured and present on disk, returns the legacy path and
|
||||
emits a deprecation warning advising the user to upgrade.
|
||||
|
||||
Integrations that do not declare ``legacy_dir`` get the canonical
|
||||
path unconditionally — no fallback, no warning.
|
||||
"""
|
||||
agent_dir = project_root / agent_config["dir"]
|
||||
dir_str = agent_config["dir"]
|
||||
if dir_str.startswith("~"):
|
||||
# Use Path.home() + remainder instead of expanduser() so tests
|
||||
# that monkeypatch Path.home() can properly isolate the home dir.
|
||||
# expanduser() uses OS env/user lookup and ignores monkeypatches.
|
||||
agent_dir = Path.home() / dir_str[1:].lstrip("/")
|
||||
else:
|
||||
p = Path(dir_str)
|
||||
agent_dir = p if p.is_absolute() else project_root / p
|
||||
if not agent_dir.exists():
|
||||
legacy = agent_config.get("legacy_dir")
|
||||
if legacy:
|
||||
@@ -704,6 +717,15 @@ class CommandRegistrar:
|
||||
|
||||
self._ensure_configs()
|
||||
for agent_name, agent_config in self.AGENT_CONFIGS.items():
|
||||
# Check detect_dir first (project-local marker) if configured,
|
||||
# falling back to the resolved dir for output. This prevents
|
||||
# global dirs (e.g. ~/.hermes/skills) from causing false
|
||||
# detection in every project.
|
||||
detect_dir_str = agent_config.get("detect_dir")
|
||||
if detect_dir_str:
|
||||
detect_path = project_root / detect_dir_str
|
||||
if not detect_path.exists():
|
||||
continue
|
||||
agent_dir = self._resolve_agent_dir(
|
||||
agent_name, agent_config, project_root,
|
||||
)
|
||||
@@ -755,6 +777,11 @@ class CommandRegistrar:
|
||||
for agent_name, agent_config in self.AGENT_CONFIGS.items():
|
||||
if agent_config.get("extension") == "/SKILL.md":
|
||||
continue
|
||||
detect_dir_str = agent_config.get("detect_dir")
|
||||
if detect_dir_str:
|
||||
detect_path = project_root / detect_dir_str
|
||||
if not detect_path.exists():
|
||||
continue
|
||||
agent_dir = self._resolve_agent_dir(
|
||||
agent_name, agent_config, project_root,
|
||||
)
|
||||
|
||||
@@ -61,6 +61,7 @@ def _register_builtins() -> None:
|
||||
from .gemini import GeminiIntegration
|
||||
from .generic import GenericIntegration
|
||||
from .goose import GooseIntegration
|
||||
from .hermes import HermesIntegration
|
||||
from .iflow import IflowIntegration
|
||||
from .junie import JunieIntegration
|
||||
from .kilocode import KilocodeIntegration
|
||||
@@ -93,6 +94,7 @@ def _register_builtins() -> None:
|
||||
_register(GeminiIntegration())
|
||||
_register(GenericIntegration())
|
||||
_register(GooseIntegration())
|
||||
_register(HermesIntegration())
|
||||
_register(IflowIntegration())
|
||||
_register(JunieIntegration())
|
||||
_register(KilocodeIntegration())
|
||||
|
||||
278
src/specify_cli/integrations/hermes/__init__.py
Normal file
278
src/specify_cli/integrations/hermes/__init__.py
Normal file
@@ -0,0 +1,278 @@
|
||||
"""Hermes Agent integration — skills-based agent.
|
||||
|
||||
Hermes Agent (https://github.com/NousResearch/hermes-agent) is an open-source
|
||||
AI agent framework by Nous Research. It stores skills in
|
||||
``~/.hermes/skills/`` (user-global) rather than a project-local directory.
|
||||
|
||||
Usage::
|
||||
|
||||
specify init my-project --integration hermes
|
||||
specify init --here --ai hermes
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from pathlib import Path
|
||||
from shutil import rmtree
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from ..base import IntegrationOption, SkillsIntegration
|
||||
from ..manifest import IntegrationManifest
|
||||
|
||||
|
||||
class HermesIntegration(SkillsIntegration):
|
||||
"""Integration for Hermes Agent skills.
|
||||
|
||||
Hermes loads skills from ``~/.hermes/skills/`` (user home directory)
|
||||
rather than a project-local path. Skills are installed directly to
|
||||
the global directory — no project-local copies are created since
|
||||
Hermes discovers them globally. A project-local marker directory
|
||||
(``.hermes/skills/`` empty) is created so extension commands (e.g.
|
||||
git) can detect Hermes as an active integration. Uninstall removes
|
||||
both the marker and all global ``speckit-*`` skills, matching the
|
||||
standard integration teardown behaviour.
|
||||
"""
|
||||
|
||||
key = "hermes"
|
||||
config = {
|
||||
"name": "Hermes Agent",
|
||||
"folder": ".hermes/",
|
||||
"commands_subdir": "skills",
|
||||
"install_url": "https://github.com/NousResearch/hermes-agent",
|
||||
"requires_cli": True,
|
||||
}
|
||||
registrar_config = {
|
||||
"dir": "~/.hermes/skills",
|
||||
"detect_dir": ".hermes/skills",
|
||||
"format": "markdown",
|
||||
"args": "$ARGUMENTS",
|
||||
"extension": "/SKILL.md",
|
||||
}
|
||||
context_file = "AGENTS.md"
|
||||
|
||||
# -- Helpers -----------------------------------------------------------
|
||||
|
||||
@staticmethod
|
||||
def _hermes_home_skills_dir() -> Path:
|
||||
"""Return ``~/.hermes/skills/`` — the global skills directory."""
|
||||
return Path.home() / ".hermes" / "skills"
|
||||
|
||||
# -- Options -----------------------------------------------------------
|
||||
|
||||
@classmethod
|
||||
def options(cls) -> list[IntegrationOption]:
|
||||
return [
|
||||
IntegrationOption(
|
||||
"--skills",
|
||||
is_flag=True,
|
||||
default=True,
|
||||
help="Install as agent skills (default for Hermes Agent)",
|
||||
),
|
||||
]
|
||||
|
||||
# -- Setup -------------------------------------------------------------
|
||||
|
||||
def setup(
|
||||
self,
|
||||
project_root: Path,
|
||||
manifest: IntegrationManifest,
|
||||
parsed_options: dict[str, Any] | None = None,
|
||||
**opts: Any,
|
||||
) -> list[Path]:
|
||||
"""Install command templates as global Hermes skills.
|
||||
|
||||
Writes each skill directly to
|
||||
``~/.hermes/skills/speckit-<name>/SKILL.md`` where Hermes
|
||||
discovers them at runtime. No project-local SKILL.md copies are
|
||||
created — the global directory is the single source of truth.
|
||||
A project-local marker (``.hermes/skills/`` empty) is created
|
||||
so extension commands (e.g. git) can detect Hermes as an active
|
||||
integration.
|
||||
"""
|
||||
templates = self.list_command_templates()
|
||||
if not templates:
|
||||
return []
|
||||
|
||||
# Safety check: verify manifest project_root matches (standard pattern)
|
||||
project_root_resolved = project_root.resolve()
|
||||
if manifest.project_root != project_root_resolved:
|
||||
raise ValueError(
|
||||
f"manifest.project_root ({manifest.project_root}) does not match "
|
||||
f"project_root ({project_root_resolved})"
|
||||
)
|
||||
|
||||
script_type = opts.get("script_type", "sh")
|
||||
arg_placeholder = (
|
||||
self.registrar_config.get("args", "$ARGUMENTS")
|
||||
if self.registrar_config
|
||||
else "$ARGUMENTS"
|
||||
)
|
||||
|
||||
global_skills_dir = self._hermes_home_skills_dir()
|
||||
global_skills_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
created: list[Path] = []
|
||||
|
||||
for src_file in templates:
|
||||
raw = src_file.read_text(encoding="utf-8")
|
||||
|
||||
# Derive the skill name from the template stem
|
||||
command_name = src_file.stem # e.g. "plan"
|
||||
skill_name = f"speckit-{command_name.replace('.', '-')}"
|
||||
|
||||
# Parse frontmatter for description
|
||||
frontmatter: dict[str, Any] = {}
|
||||
if raw.startswith("---"):
|
||||
parts = raw.split("---", 2)
|
||||
if len(parts) >= 3:
|
||||
try:
|
||||
fm = yaml.safe_load(parts[1])
|
||||
if isinstance(fm, dict):
|
||||
frontmatter = fm
|
||||
except yaml.YAMLError:
|
||||
pass
|
||||
|
||||
# Process body through the standard template pipeline
|
||||
processed_body = self.process_template(
|
||||
raw,
|
||||
self.key,
|
||||
script_type,
|
||||
arg_placeholder,
|
||||
context_file=self.context_file or "",
|
||||
invoke_separator=self.invoke_separator,
|
||||
)
|
||||
# Strip the processed frontmatter — we rebuild it for skills.
|
||||
if processed_body.startswith("---"):
|
||||
parts = processed_body.split("---", 2)
|
||||
if len(parts) >= 3:
|
||||
processed_body = parts[2]
|
||||
|
||||
# Select description
|
||||
description = frontmatter.get("description", "")
|
||||
if not description:
|
||||
description = f"Spec Kit: {command_name} workflow"
|
||||
|
||||
# Build SKILL.md with manually formatted frontmatter
|
||||
def _quote(v: str) -> str:
|
||||
escaped = v.replace("\\", "\\\\").replace('"', '\\"')
|
||||
return f'"{escaped}"'
|
||||
|
||||
skill_content = (
|
||||
f"---\n"
|
||||
f"name: {_quote(skill_name)}\n"
|
||||
f"description: {_quote(description)}\n"
|
||||
f"compatibility: "
|
||||
f"{_quote('Requires spec-kit project structure with .specify/ directory')}\n"
|
||||
f"metadata:\n"
|
||||
f" author: {_quote('github-spec-kit')}\n"
|
||||
f" source: {_quote('templates/commands/' + src_file.name)}\n"
|
||||
f"---\n"
|
||||
f"{processed_body}"
|
||||
)
|
||||
|
||||
# Write directly to global ~/.hermes/skills/speckit-<name>/SKILL.md
|
||||
skill_dir = global_skills_dir / skill_name
|
||||
skill_dir.mkdir(parents=True, exist_ok=True)
|
||||
skill_file = skill_dir / "SKILL.md"
|
||||
normalized = skill_content.replace("\r\n", "\n")
|
||||
skill_file.write_bytes(normalized.encode("utf-8"))
|
||||
created.append(skill_file)
|
||||
|
||||
# Upsert managed context section into the agent context file
|
||||
self.upsert_context_section(project_root)
|
||||
|
||||
# Create project-local marker directory so extension commands
|
||||
# (e.g. git) can detect Hermes as an active integration.
|
||||
# Hermes itself ignores this directory — skills live globally.
|
||||
(project_root / ".hermes" / "skills").mkdir(parents=True, exist_ok=True)
|
||||
|
||||
return created
|
||||
|
||||
# -- Uninstall ---------------------------------------------------------
|
||||
|
||||
def teardown(
|
||||
self,
|
||||
project_root: Path,
|
||||
manifest: IntegrationManifest,
|
||||
*,
|
||||
force: bool = False,
|
||||
) -> tuple[list[Path], list[Path]]:
|
||||
"""Uninstall integration files including global Hermes skills.
|
||||
|
||||
Removes the managed context section from AGENTS.md, removes the
|
||||
project-local marker directory (if empty), delegates to
|
||||
``manifest.uninstall()`` for project-local tracked files, and
|
||||
removes all ``speckit-*`` skills under ``~/.hermes/skills/``.
|
||||
|
||||
Global skills are always removed on teardown — this matches the
|
||||
standard integration behaviour where all files created by the
|
||||
integration are removed on ``specify integration uninstall``.
|
||||
"""
|
||||
# Remove managed context section from AGENTS.md
|
||||
self.remove_context_section(project_root)
|
||||
|
||||
# Delegate to manifest for project-local tracked files (scripts,
|
||||
# templates, context entries tracked in the manifest).
|
||||
removed, skipped = manifest.uninstall(project_root, force=force)
|
||||
|
||||
# Remove project-local marker directory if empty
|
||||
local_skills_dir = project_root / ".hermes" / "skills"
|
||||
if local_skills_dir.is_dir() and not any(local_skills_dir.iterdir()):
|
||||
local_skills_dir.rmdir()
|
||||
hermes_dir = project_root / ".hermes"
|
||||
if hermes_dir.is_dir() and not any(hermes_dir.iterdir()):
|
||||
hermes_dir.rmdir()
|
||||
|
||||
# Remove all global Hermes skills for speckit — these are always
|
||||
# removed on uninstall regardless of the force flag, matching the
|
||||
# standard behaviour where all integration files are cleaned up.
|
||||
global_skills_dir = self._hermes_home_skills_dir()
|
||||
if global_skills_dir.is_dir():
|
||||
for skill_dir in sorted(global_skills_dir.iterdir()):
|
||||
if skill_dir.is_dir() and skill_dir.name.startswith("speckit-"):
|
||||
try:
|
||||
rmtree(skill_dir)
|
||||
removed.append(skill_dir)
|
||||
except OSError:
|
||||
skipped.append(skill_dir)
|
||||
|
||||
return removed, skipped
|
||||
|
||||
# -- CLI dispatch ------------------------------------------------------
|
||||
|
||||
def build_exec_args(
|
||||
self,
|
||||
prompt: str,
|
||||
*,
|
||||
model: str | None = None,
|
||||
output_json: bool = True,
|
||||
) -> list[str] | None:
|
||||
"""Build Hermes CLI invocation for programmatic dispatch.
|
||||
|
||||
Uses ``hermes chat -Q -q`` for one-shot queries in quiet mode,
|
||||
mapping slash-command invocations to the appropriate skill-based
|
||||
dispatch.
|
||||
"""
|
||||
args = [self.key, "chat", "-Q"]
|
||||
|
||||
if model:
|
||||
args.extend(["-m", model])
|
||||
if output_json:
|
||||
args.append("--json")
|
||||
|
||||
# If prompt starts with a slash command, pass it directly
|
||||
# so Hermes can dispatch to the appropriate skill.
|
||||
if prompt.startswith("/"):
|
||||
command, _, remainder = prompt[1:].partition(" ")
|
||||
if command:
|
||||
args.extend(["-s", command])
|
||||
if remainder:
|
||||
args.extend(["-q", remainder])
|
||||
else:
|
||||
args.extend(["-q", prompt])
|
||||
else:
|
||||
args.extend(["-q", prompt])
|
||||
|
||||
return args
|
||||
Reference in New Issue
Block a user