From ff10d956f0041b93d7d037d9a768d5314aae5a36 Mon Sep 17 00:00:00 2001 From: Jon Langevin Date: Mon, 29 Jun 2026 22:24:52 -0400 Subject: [PATCH] feat: add Hermes Agent support - Create .hermes/INSTALL.md with installation instructions - Create .hermes/plugin.json manifest (version-synced) - Create AGENTS.md for project-level Hermes context injection - Add hermes-agent as recognized host in writing-skills/SKILL.md - Update cross-llm-coverage.md with Hermes Agent capability row - Update README.md with Hermes Agent installation section and table row - Update version-check.sh and bump-version.sh to track .hermes/plugin.json - Update release-tag.yml to watch .hermes/plugin.json changes - Add blocks to skills with host-specific sections: brainstorming, executing-plans, alignment-check, subagent-driven-development, pr-monitoring, post-merge-retrospective --- .github/workflows/release-tag.yml | 1 + .hermes/INSTALL.md | 104 ++++++++++++++++++++ .hermes/plugin.json | 18 ++++ AGENTS.md | 48 +++++++++ README.md | 34 ++++++- docs/cross-llm-coverage.md | 28 +++--- scripts/bump-version.sh | 1 + skills/alignment-check/SKILL.md | 4 + skills/brainstorming/SKILL.md | 5 + skills/executing-plans/SKILL.md | 4 + skills/post-merge-retrospective/SKILL.md | 4 + skills/pr-monitoring/SKILL.md | 25 +++++ skills/subagent-driven-development/SKILL.md | 18 ++++ skills/writing-skills/SKILL.md | 7 +- tests/version-check.sh | 1 + 15 files changed, 284 insertions(+), 18 deletions(-) create mode 100644 .hermes/INSTALL.md create mode 100644 .hermes/plugin.json create mode 100644 AGENTS.md diff --git a/.github/workflows/release-tag.yml b/.github/workflows/release-tag.yml index f909360..826a464 100644 --- a/.github/workflows/release-tag.yml +++ b/.github/workflows/release-tag.yml @@ -6,6 +6,7 @@ on: - main paths: - '.claude-plugin/plugin.json' + - '.hermes/plugin.json' workflow_dispatch: concurrency: diff --git a/.hermes/INSTALL.md b/.hermes/INSTALL.md new file mode 100644 index 0000000..be9746f --- /dev/null +++ b/.hermes/INSTALL.md @@ -0,0 +1,104 @@ +# Installing Autonomous Dev Kit for Hermes Agent + +Enable autodev skills in Hermes Agent via native skill discovery. + +## Prerequisites + +- [Hermes Agent](https://hermes-agent.nousresearch.com/docs) installed +- Git installed + +## Installation + +### Option 1: Clone and Symlink (Recommended) + +```bash +# Clone the autodev repository +git clone https://github.com/GoCodeAlone/autonomous-dev-kit.git ~/.hermes/autodev + +# Create the skills symlink so Hermes discovers autodev skills +mkdir -p ~/.hermes/skills +ln -s ~/.hermes/autodev/skills ~/.hermes/skills/autodev +``` + +**Windows (PowerShell):** +```powershell +git clone https://github.com/GoCodeAlone/autonomous-dev-kit.git "$env:USERPROFILE\.hermes\autodev" +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.hermes\skills" +cmd /c mklink /J "$env:USERPROFILE\.hermes\skills\autodev" "$env:USERPROFILE\.hermes\autodev\skills" +``` + +### Option 2: Skills CLI (if available) + +```bash +npx skills add GoCodeAlone/autonomous-dev-kit -a hermes-agent --skill '*' -y +``` + +### Option 3: Direct SKILL.md install via Hermes CLI + +```bash +# Install individual skills from the repository +hermes skills install https://raw.githubusercontent.com/GoCodeAlone/autonomous-dev-kit/main/skills/brainstorming/SKILL.md +hermes skills install https://raw.githubusercontent.com/GoCodeAlone/autonomous-dev-kit/main/skills/writing-plans/SKILL.md +# ... repeat for each skill you want +``` + +## Verify Installation + +Start a new Hermes session and ask for something that should trigger a skill: + +``` +help me plan this feature +``` + +Hermes should automatically invoke the `autodev/brainstorming` skill. + +Verify skills are discovered: + +```bash +ls -la ~/.hermes/skills/autodev +``` + +You should see the skills directory symlinked to your autodev checkout. + +## Updating + +```bash +cd ~/.hermes/autodev && git pull +``` + +Skills update instantly through the symlink. + +## Uninstalling + +```bash +rm ~/.hermes/skills/autodev +``` + +Optionally delete the clone: `rm -rf ~/.hermes/autodev`. + +## Cross-LLM Behavior + +Autonomous Dev Kit skills use `` blocks to gate Claude Code-only content. Hermes Agent skips those blocks automatically; no configuration needed. + +To enable host-conditional logic inside skills (so skills can adapt behavior per host), Hermes Agent auto-detects itself as the host. Skills that inspect the host context will use it to pick the right execution path. + +## Tool Mapping + +When skills reference Claude Code tools, Hermes Agent maps them as follows: + +| Claude Code Tool | Hermes Agent Equivalent | +|---|---| +| `TodoWrite` | `todo` tool (built-in) | +| `Agent` (subagent) | `delegate_task` tool | +| `Task` with subagents | `delegate_task` with `goal` + `context` | +| `TeamCreate` / `TeamDelete` | Not applicable — Hermes uses sequential `delegate_task` | +| `SendMessage` (team DM) | Not applicable — Hermes returns subagent results directly | +| `EnterPlanMode` | Prose planning in chat | +| `Skill` tool | `skill_view` / `skills_list` | +| File operations | `read_file`, `write_file`, `patch`, `search_files` | +| `Bash` | `terminal` tool | +| `AskUserQuestion` | `clarify` tool | + +## Host Declaration + +Hermes Agent identifies itself automatically. No manual host declaration is needed. diff --git a/.hermes/plugin.json b/.hermes/plugin.json new file mode 100644 index 0000000..898e0b8 --- /dev/null +++ b/.hermes/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "autodev", + "displayName": "Autonomous Dev Kit", + "description": "Autonomous development workflow skills for coding agents", + "version": "6.5.10", + "author": { + "name": "Jon Langevin", + "email": "jon@gocodealone.com" + }, + "homepage": "https://github.com/GoCodeAlone/autonomous-dev-kit", + "repository": "https://github.com/GoCodeAlone/autonomous-dev-kit", + "license": "MIT", + "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows", "agents", "autonomous-development"], + "skills": "./skills/", + "agents": "./agents/", + "commands": "./commands/", + "hooks": "./hooks/hooks.json" +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d0b1bb9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# Autonomous Dev Kit + +This repository contains the Autonomous Dev Kit — a plugin bundling skills, hooks, agents, and commands for coding agents (Claude Code, Codex, OpenCode, Cursor, and Hermes Agent). + +## Project Structure + +- `skills/` — SKILL.md files (the core reusable workflows) +- `hooks/` — Shell scripts that fire at session/tool lifecycle events +- `agents/` — Agent role definitions and team conventions +- `commands/` — Slash command definitions +- `tests/` — Test scripts for skill content, hooks, and contracts +- `.claude-plugin/` — Claude Code plugin manifest +- `.cursor-plugin/` — Cursor plugin manifest +- `.codex/` — Codex installation instructions +- `.opencode/` — OpenCode installation instructions +- `.hermes/` — Hermes Agent installation instructions +- `.github/workflows/` — CI pipelines + +## Building and Testing + +Run the test scripts before committing: + +```bash +# Skill content checks (host-neutrality, path canonicalization, cross-refs) +bash tests/skill-content-grep.sh +bash tests/adk-path-canonicalization.sh +bash tests/pipeline-evidence-doc-sync.sh +bash tests/skill-cross-refs.sh + +# Hook contract tests +bash tests/hook-contracts.sh +bash tests/hook-stdout-discipline.sh +bash tests/plan-scope-check-contracts.sh + +# Version consistency +bash tests/version-check.sh +``` + +## Adding Skills + +Follow `skills/writing-skills/SKILL.md` for the complete guide. Key rules: +- Skills use `` blocks to gate host-specific content +- Forbidden tokens (TodoWrite, TeamCreate, Sonnet, etc.) must only appear inside `` blocks +- Recognized hosts: `claude-code`, `codex`, `opencode`, `cursor`, `hermes-agent` + +## Versioning + +All plugin manifests must declare the same version. Use `scripts/bump-version.sh ` to update all manifests at once. diff --git a/README.md b/README.md index cbcc366..ebd51e5 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,38 @@ Autonomous Dev Kit originated as a fork of Jesse Vincent's [Superpowers](https:/ ## Installation -**Note:** Installation differs by platform. Claude Code or Cursor have built-in plugin marketplaces. Codex can use the open `skills` CLI (`npx skills add`) or manual setup. OpenCode currently uses manual setup. +**Note:** Installation differs by platform. Claude Code or Cursor have built-in plugin marketplaces. Codex can use the open `skills` CLI (`npx skills add`) or manual setup. OpenCode and Hermes Agent currently use manual setup. + +### Hermes Agent + +From your project root or home directory: + +```bash +# Clone the autodev repository +git clone https://github.com/GoCodeAlone/autonomous-dev-kit.git ~/.hermes/autodev + +# Create the skills symlink so Hermes discovers autodev skills +mkdir -p ~/.hermes/skills +ln -s ~/.hermes/autodev/skills ~/.hermes/skills/autodev +``` + +**Windows (PowerShell):** +```powershell +git clone https://github.com/GoCodeAlone/autonomous-dev-kit.git "$env:USERPROFILE\.hermes\autodev" +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.hermes\skills" +cmd /c mklink /J "$env:USERPROFILE\.hermes\skills\autodev" "$env:USERPROFILE\.hermes\autodev\skills" +``` + +Then restart Hermes (start a new session) so it discovers the skills. + +**Updating:** +```bash +cd ~/.hermes/autodev && git pull +``` + +Skills update instantly through the symlink. + +**Detailed docs:** [`.hermes/INSTALL.md`](.hermes/INSTALL.md) ### Claude Code (via Plugin Marketplace) @@ -130,6 +161,7 @@ Autonomous Dev Kit skills run on any host that supports the SKILL.md format. Hos | Codex | `~/.agents/skills/autodev/` | yes | Sequential sub-agent dispatch; `/plan` slash; `/agent` switching | | OpenCode | `~/.config/opencode/skills/autodev/` | yes | Tool mapping documented in `.opencode/INSTALL.md` | | Cursor | `/plugin-add autodev` | yes (via plugin) | Plugin manifest defines skills/agents/commands/hooks | +| Hermes Agent | `~/.hermes/skills/autodev/` | yes | `delegate_task` for subagents; `todo` for task tracking; `clarify` for user questions | Full capability matrix: [docs/cross-llm-coverage.md](docs/cross-llm-coverage.md) Per-skill host-conditional audit: [tests/cross-llm-coverage.md](tests/cross-llm-coverage.md) diff --git a/docs/cross-llm-coverage.md b/docs/cross-llm-coverage.md index 64e5dbf..47a743c 100644 --- a/docs/cross-llm-coverage.md +++ b/docs/cross-llm-coverage.md @@ -4,20 +4,20 @@ Host-by-host capability matrix for the Autonomous Dev Kit skills system. `✅` = fully supported `⚠️` = partial / workaround required `❌` = not supported -| Capability | Claude Code | Codex CLI | OpenCode | Cursor | -|---|---|---|---|---| -| SKILL.md import | ✅ native | ✅ native | ✅ native | ✅ plugin manifest defines skills/agents/commands/hooks; install via `/plugin-add autodev` | -| Sub-agent dispatch | ✅ `Agent` tool | ✅ natural language | ⚠️ `@mention` to peer sessions | ❌ not documented | -| Agent Teams (persistent multi-agent DM) | ✅ experimental flag | ❌ | ❌ | ❌ | -| Background agents | ✅ `run_in_background` | ⚠️ thread-based; no explicit background flag | ❌ not documented | ❌ not documented | -| MCP servers | ✅ | ✅ `config.toml` | ✅ | ⚠️ partial | -| Slash commands | ✅ | ✅ 30+ built-ins incl. `/plan`, `/agent`, `/review` | ✅ | ✅ | -| Plan mode | ✅ `EnterPlanMode` + Shift-Tab | ✅ `/plan` slash | ⚠️ not documented; use prose planning | ⚠️ built-in Composer; not slash-invokable | -| Task list / TodoWrite | ✅ built-in | ❌ no documented equivalent | ⚠️ `update_plan` mapping (see `.opencode/INSTALL.md`) | ⚠️ unknown | -| AGENTS.md / project context | CLAUDE.md | AGENTS.md (+ `.override.md`) | AGENTS.md | n/a | -| Host declaration for skill conditionals | `Host: claude-code` in CLAUDE.md | `Host: codex` in `~/.codex/AGENTS.md` | `Host: opencode` in `~/.config/opencode/AGENTS.md` | n/a | -| Skill discovery path (user scope) | `~/.claude/skills/` (personal skills); autodev installed to `~/.claude/plugins/marketplace/autodev/` via marketplace | `~/.agents/skills/` | `~/.config/opencode/skills/` | via plugin (no manual symlink) | -| Model tier vocabulary | role names → `haiku`/`sonnet`/`opus` (see `agents/model-tiers.md`) | role names → `gpt-5.4-mini`/`gpt-5.4`/`gpt-5.5` | role names → host-pass-through | role names → host-pass-through | +| Capability | Claude Code | Codex CLI | OpenCode | Cursor | Hermes Agent | +|---|---|---|---|---|---| +| SKILL.md import | ✅ native | ✅ native | ✅ native | ✅ plugin manifest defines skills/agents/commands/hooks; install via `/plugin-add autodev` | ✅ native via `~/.hermes/skills/` symlink or `hermes skills install` | +| Sub-agent dispatch | ✅ `Agent` tool | ✅ natural language | ⚠️ `@mention` to peer sessions | ❌ not documented | ✅ `delegate_task` tool | +| Agent Teams (persistent multi-agent DM) | ✅ experimental flag | ❌ | ❌ | ❌ | ❌ (uses sequential `delegate_task`) | +| Background agents | ✅ `run_in_background` | ⚠️ thread-based; no explicit background flag | ❌ not documented | ❌ not documented | ✅ `terminal(background=true)` | +| MCP servers | ✅ | ✅ `config.toml` | ✅ | ⚠️ partial | ✅ `hermes mcp` | +| Slash commands | ✅ | ✅ 30+ built-ins incl. `/plan`, `/agent`, `/review` | ✅ | ✅ | ✅ 40+ built-ins | +| Plan mode | ✅ `EnterPlanMode` + Shift-Tab | ✅ `/plan` slash | ⚠️ not documented; use prose planning | ⚠️ built-in Composer; not slash-invokable | ⚠️ prose planning in chat | +| Task list / TodoWrite | ✅ built-in | ❌ no documented equivalent | ⚠️ `update_plan` mapping (see `.opencode/INSTALL.md`) | ⚠️ unknown | ✅ `todo` tool (built-in) | +| AGENTS.md / project context | CLAUDE.md | AGENTS.md (+ `.override.md`) | AGENTS.md | n/a | AGENTS.md (cwd only), `.hermes.md` (parent walk) | +| Host declaration for skill conditionals | `Host: claude-code` in CLAUDE.md | `Host: codex` in `~/.codex/AGENTS.md` | `Host: opencode` in `~/.config/opencode/AGENTS.md` | n/a | Auto-detected as `hermes-agent` | +| Skill discovery path (user scope) | `~/.claude/skills/` (personal skills); autodev installed to `~/.claude/plugins/marketplace/autodev/` via marketplace | `~/.agents/skills/` | `~/.config/opencode/skills/` | via plugin (no manual symlink) | `~/.hermes/skills/` (symlink or `hermes skills install`) | +| Model tier vocabulary | role names → `haiku`/`sonnet`/`opus` (see `agents/model-tiers.md`) | role names → `gpt-5.4-mini`/`gpt-5.4`/`gpt-5.5` | role names → host-pass-through | role names → host-pass-through | role names → config model (provider-agnostic) | ## Notes diff --git a/scripts/bump-version.sh b/scripts/bump-version.sh index 441ce04..ce1cea8 100755 --- a/scripts/bump-version.sh +++ b/scripts/bump-version.sh @@ -23,6 +23,7 @@ VERSION_FILES=( ".claude-plugin/plugin.json" ".claude-plugin/marketplace.json" ".cursor-plugin/plugin.json" + ".hermes/plugin.json" ) usage() { diff --git a/skills/alignment-check/SKILL.md b/skills/alignment-check/SKILL.md index 841da3e..7790ca6 100644 --- a/skills/alignment-check/SKILL.md +++ b/skills/alignment-check/SKILL.md @@ -119,6 +119,10 @@ Agent tool (general-purpose, model: balanced): Run the alignment check inline: read both documents, perform the forward and reverse traces using the Comparison Procedure above, and produce the Alignment Report. + +Dispatch a subagent using `delegate_task` with a `goal` describing the alignment verification and both document paths in `context`. Use the same report format specified above. + + ## On FAIL Feed drift items back to `writing-plans` for revision: diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index a615338..16eb066 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -88,6 +88,11 @@ digraph brainstorming { - Group no more than 3 questions per turn to avoid overloading the chat + + - Use the `clarify` tool for multiple-choice questions (up to 4 options) + - Group no more than 3 questions per turn to avoid overloading the chat + + - Focus on understanding: purpose, constraints, success criteria **Exploring approaches:** diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 5862853..bc36bd2 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -31,6 +31,10 @@ Use TodoWrite — one entry per plan task. If your environment has no built-in task system, maintain a numbered checklist tracking each task as pending, in-progress, or completed. + +Use the `todo` tool — one entry per plan task. + + ### Step 2: Execute Batch **Default: First 3 tasks** diff --git a/skills/post-merge-retrospective/SKILL.md b/skills/post-merge-retrospective/SKILL.md index 1a88ebd..c007a48 100644 --- a/skills/post-merge-retrospective/SKILL.md +++ b/skills/post-merge-retrospective/SKILL.md @@ -141,6 +141,10 @@ This is short, structured analysis work — one pass over the artifacts. Run inl Run inline. The lead agent has the context already. The retro is a structured artifact, not a long-running task — produce the markdown directly. + +Run inline. The lead agent has the context already. The retro is a structured artifact, not a long-running task — produce the markdown directly. + + ## Why this skill exists `pr-monitoring` exits when CI is green and reviews are resolved. That's the end of the in-flight pipeline, but it's not the end of the loop. Without `post-merge-retrospective`, the plugin has no organic way to know which gates are actually pulling their weight. With it, every merged PR produces a small piece of evidence that gets compared across PRs over time. That's how the gate set sharpens. diff --git a/skills/pr-monitoring/SKILL.md b/skills/pr-monitoring/SKILL.md index 626a1ee..6d26e80 100644 --- a/skills/pr-monitoring/SKILL.md +++ b/skills/pr-monitoring/SKILL.md @@ -61,6 +61,13 @@ per turn and re-check on the next turn. This loses fire-on-event but is reliable dispatch a background Agent expecting it to block on a sleep-loop. + +Use `terminal(background=true, notify_on_complete=true)` with a bounded bash sleep-loop +(same pattern as the Claude Code bash poll-loop above) that polls `gh pr checks ` +until settled. The Hermes `terminal` tool genuinely blocks to completion in background mode. +Use `process(action='poll')` to check status and `process(action='log')` to read results. + + **Fallback (all hosts):** the background-Agent monitor in "The Process" below remains the tool for multi-PR review-comment handling that needs active fix-and-push; note its early-exit failure mode and prefer the poll-loop / self-poll for a pure CI-wait. @@ -290,6 +297,24 @@ retro and exit cleanly. + + +Use `terminal` to run `gh pr checks ` and fix failing CI checks. For +background monitoring, use `terminal(background=true, notify_on_complete=true)` +with a bounded sleep-loop (same pattern as the Claude Code bash poll-loop above). +Use `process(action='poll')` and `process(action='log')` to read results. + +Follow the same poll cycle: 10-minute wait between full cycles, 60-minute total +session cap. Use a separate worktree per branch so you never switch branches +mid-session. + +When a PR has merged with green base-branch CI and a design + plan exist in +`docs/plans/` for its branch, invoke `autodev:post-merge-retrospective` to +write a retro in `docs/retros/`. If the PR was closed without merge, skip the +retro and exit cleanly. + + + ## Safety Limits diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index a9c5c33..f861c8e 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -244,6 +244,12 @@ Use Sequential Mode — see the [Sequential Mode](#sequential-mode) section belo + + +**Sequential Subagents** — Hermes Agent uses `delegate_task` to spawn one subagent per task. Each subagent gets its own conversation, terminal session, and toolset. Pass the full plan task text in the `goal` or `context` parameters. See [Sequential Mode](#sequential-mode). + + + --- ## Sequential Mode @@ -400,6 +406,12 @@ Hooks are not documented on this host. Apply the pattern manually: at the start + + +Hooks are not documented on this host. Apply the pattern manually: at the start of every reply that follows a context compaction, scroll back to the first user message in your visible transcript, re-state the task to yourself, then proceed. Use `session_search` to re-orient on the current session's goal and progress. + + + ### 2. Watchdog cadence (every 5–10 minutes) When you have one or more subagents running in the background, check on them on a 5–10 minute cadence. Don't fire-and-forget. @@ -432,6 +444,12 @@ Use `@mention` to peer sessions to ping each background subagent for a status re + + +Use `process(action='poll')` to check background subagent status, `process(action='log')` to read recent output. To send corrective input, use `process(action='submit')` with the message. To terminate a stuck subagent, use `process(action='kill')`. When using `terminal(background=true)` to pace a self-paced run, factor watchdog checks into the cadence. + + + ### 3. Quality-based rotation (replace consistently-failing teammates) Subagents are teammates, not infrastructure. If one keeps producing low-quality output, replace it instead of re-prompting forever. diff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.md index bb32a1e..b0b928d 100644 --- a/skills/writing-skills/SKILL.md +++ b/skills/writing-skills/SKILL.md @@ -95,7 +95,7 @@ skills/ ## Host-Conditional Sections Skills may need different content per host (Claude Code, Codex, OpenCode, -Cursor). Use `` markers to gate host-specific prose. Markers must +Cursor, Hermes Agent). Use `` markers to gate host-specific prose. Markers must appear on their own lines (the guard only recognises them at line start, after optional whitespace). Sections without a marker apply to every host. @@ -106,8 +106,8 @@ optional whitespace). Sections without a marker apply to every host. …content for Claude Code only… - -…content shared between Codex and OpenCode… + +…content shared between Codex, OpenCode, Cursor and Hermes Agent… ``` @@ -134,6 +134,7 @@ misspelled or unclosed. Visibility is the safer trade-off. - `codex` — OpenAI Codex CLI - `opencode` — OpenCode.ai - `cursor` — Cursor +- `hermes-agent` — Hermes Agent (Nous Research) Use exactly these strings. Adding a new host means updating this list, the grep guard's skip logic, and `agents/model-tiers.md`. diff --git a/tests/version-check.sh b/tests/version-check.sh index dad2089..8e5d122 100755 --- a/tests/version-check.sh +++ b/tests/version-check.sh @@ -24,6 +24,7 @@ VERSION_FILES=( ".claude-plugin/plugin.json" ".claude-plugin/marketplace.json" ".cursor-plugin/plugin.json" + ".hermes/plugin.json" ) extract_version() {