Hermes Setup

This repository ships a Hermes adapter for planning-with-files.

The adapter has two parts:

• .hermes/skills/planning-with-files/ contains the Hermes-facing workflow skill and its bundled templates/scripts
• .hermes/plugins/planning-with-files/ contains the project plugin that provides planning tools and context injection

What the Adapter Provides

• planning_with_files_init creates task_plan.md, findings.md, and progress.md in the target project
• planning_with_files_status summarizes the current planning state
• planning_with_files_check_complete runs the completion check helper
• The project plugin injects active planning context on later turns and reminds the agent to update planning files after write-like actions

Install

1. Enable project plugins

export HERMES_ENABLE_PROJECT_PLUGINS=1

2. Install the Hermes skill bundle

Add the skill directory to your Hermes profile. The skill bundle includes SKILL.md, templates/, and scripts/.

skills:
  external_dirs:
    - /absolute/path/to/planning-with-files/.hermes/skills

3. Install the Hermes project plugin

Copy .hermes/plugins/planning-with-files/ into the target profile or repository so Hermes can load the Python adapter.

4. Start Hermes from the target project directory

The project plugin lives under .hermes/plugins/planning-with-files/. Hermes discovers it automatically when project plugins are enabled and the working directory is this repository.

Usage

• Run /plan to start the planning workflow in the current project
• Run /plan-status to inspect the current planning state
• Load planning-with-files directly when you want the workflow instructions without the command wrapper

Validation

python3 -m unittest tests/test_hermes_adapter.py

Integration Notes

This section is for users who have installed the Hermes adapter and are comparing its behavior to hook-native platforms such as Claude Code.

What works today

The adapter provides reliable support for the following:

• Initialization. planning_with_files_init creates task_plan.md, findings.md, and progress.md in the target project and sets up the planning scaffold correctly.
• Status queries. planning_with_files_status summarizes current planning state and surfaces which phases are active or blocked.
• Completion checks. planning_with_files_check_complete runs the completion check helper and returns a structured result the agent can act on.
• Context injection. The project plugin injects active planning context on later turns and reminds the agent to update planning files after write-like actions. This keeps planning state visible across a multi-step workflow.
• Explicit planning commands. /plan and /plan-status work as expected when the skill is loaded and the project plugin is active.

What is not a full equivalent of hook-native platforms

Hermes does not expose a native hook or lifecycle API comparable to the stop and pre-tool hooks available on Claude Code. The consequences are:

• Stop/block enforcement is adapter-driven, not platform-native. On Claude Code, a stop hook can interrupt execution at the platform level before the agent takes an action. On Hermes, completion checks and blocking reminders are delivered as tool responses and context injections. The agent can receive and act on them, but there is no platform-level gate that halts execution unconditionally.
• No pre-tool or post-tool lifecycle callbacks. The project plugin injects reminders, but it cannot intercept a tool call mid-flight or force a rollback the way a hook middleware can.
• More manual setup. Hook-native platforms wire lifecycle callbacks automatically once the plugin is installed. On Hermes you must explicitly enable project plugins, add the skill bundle to your profile, and start Hermes from the correct working directory (see Install above).

If you are migrating from a Claude Code workflow and expecting the same stop/block behavior you observed there, you will need to adjust your expectations and your integration pattern accordingly.

Recommended integration pattern

1. Enable project plugins before starting Hermes (HERMES_ENABLE_PROJECT_PLUGINS=1).
2. Load the planning-with-files skill at the start of each session, either via a profile default or an explicit /load planning-with-files command.
3. Call planning_with_files_init once per project to create the planning files. Do not skip this step even if you are resuming an existing project, because the plugin uses the presence of these files to decide whether to inject context.
4. Rely on the explicit planning tools (/plan, /plan-status, planning_with_files_check_complete) as your primary control points rather than assuming platform-level enforcement.
5. Treat completion checks as advisory signals. Build your workflow so the agent calls planning_with_files_check_complete at natural checkpoints and acts on the result, rather than expecting the platform to block progress automatically.
6. Use context injection as a substitute for hook reminders. The project plugin is designed to keep planning discipline visible throughout a conversation. If you find the agent drifting from the plan, a manual /plan-status call will re-anchor it.

Tradeoffs