Hermes Agent Plan Skill: Write Markdown Plans Without Execution

The Plan skill turns Hermes Agent into a planning-only assistant. When you need a concrete, actionable implementation plan before touching any code, this skill produces a markdown file saved to .hermes/plans/ and stops there. No file edits, no commits, no execution. Reach for it when you want to think through a feature, delegate to a subagent, or document an approach before committing to code.

What it does

This skill constrains Hermes to a single deliverable: a markdown plan inside the active workspace. It can inspect the codebase with read-only tools, but it will not write code, run mutating commands, or perform external actions. The output is a timestamped file under .hermes/plans/ that contains a structured, step-by-step implementation plan designed to make the actual coding obvious.

The plan follows a strict format: a header with goal, architecture, and tech stack, followed by bite-sized tasks (2-5 minutes each). Each task includes exact file paths, complete code examples, exact commands with expected output, and verification steps. The skill assumes the implementer has zero context for the codebase and questionable taste, so it documents everything they need.

Before you start

Skill path: skills/software-development/plan (bundled with Hermes Agent, no installation needed)
Version: 2.0.0
Platforms: linux, macos, windows
Prerequisites: An active Hermes Agent runtime with file write access to the workspace. The plan file is saved relative to the active working directory, which works across local, docker, ssh, modal, and daytona backends.
Permissions: The agent needs read access to inspect the codebase and write access to create files under .hermes/plans/. No other permissions are required.

How it works

When you invoke the Plan skill, Hermes enters planning-only mode. It will:

Not implement code.
Not edit project files except the plan markdown file.
Not run mutating terminal commands, commit, push, or perform external actions.
Inspect the repo or other context with read-only commands/tools when needed.
Deliver a markdown plan saved inside the active workspace under .hermes/plans/.

Output requirements

The plan must be concrete and actionable. Include, when relevant:

Goal
Current context / assumptions
Proposed approach
Step-by-step plan
Files likely to change
Tests / validation
Risks, tradeoffs, and open questions

If the task is code-related, include exact file paths, likely test targets, and verification steps.

Save location

Save the plan with write_file under:

.hermes/plans/YYYY-MM-DD_HHMMSS-.md

Treat that as relative to the active working directory / backend workspace. Hermes file tools are backend-aware, so using this relative path keeps the plan with the workspace on local, docker, ssh, modal, and daytona backends.

If the runtime provides a specific target path, use that exact path. If not, create a sensible timestamped filename yourself under .hermes/plans/.

Interaction style

If the request is clear enough, write the plan directly.
If no explicit instruction accompanies /plan, infer the task from the current conversation context.
If it is genuinely underspecified, ask a brief clarifying question instead of guessing.
After saving the plan, reply briefly with what you planned and the saved path.

Writing the Plan Well

The rest of this skill is the craft of authoring a good implementation plan, the content that goes inside the markdown file above.

Overview

Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, testing commands, docs to check, how to verify. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain. Assume they don't know good test design very well.

Core principle: A good plan makes implementation obvious. If someone has to guess, the plan is incomplete.

When a Full Implementation Plan Helps

Always use before:

Implementing multi-step features
Breaking down complex requirements
Delegating to subagents via subagent-driven-development

Don't skip when:

Feature seems simple (assumptions cause bugs)
You plan to implement it yourself (future you needs guidance)
Working alone (documentation matters)

Bite-Sized Task Granularity

Each task = 2-5 minutes of focused work.

Every step is one action:

"Write the failing test", step
"Run it to make sure it fails", step
"Implement the minimal code to make the test pass", step
"Run the tests and make sure they pass", step
"Commit", step

Too big:

### Task 1: Build authentication system
[50 lines of code across 5 files]

Right size:

### Task 1: Create User model with email field
[10 lines, 1 file]

### Task 2: Add password hash field to User
[8 lines, 1 file]

### Task 3: Create password hashing utility
[15 lines, 1 file]

Plan Document Structure

Header (Required)

Every plan MUST start with:

# [Feature Name] Implementation Plan

> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

Task Structure

Each task follows this format:

### Task N: [Descriptive Name]

**Objective:** What this task accomplishes (one sentence)

**Files:**
- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
- Test: `tests/path/to/test_file.py`

**Step 1: Write failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**Step 2: Run test to verify failure**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL — "function not defined"

**Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

**Step 4: Run test to verify pass**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: PASS

**Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

Writing Process

Step 1: Understand Requirements

Read and understand:

Feature requirements
Design documents or user description
Acceptance criteria
Constraints

Step 2: Explore the Codebase

Use Hermes tools to understand the project:

# Understand project structure
search_files("*.py", target="files", path="src/")

# Look at similar features
search_files("similar_pattern", path="src/", file_glob="*.py")

# Check existing tests
search_files("*.py", target="files", path="tests/")

# Read key files
read_file("src/app.py")

Step 3: Design Approach

Decide:

Architecture pattern
File organization
Dependencies needed
Testing strategy

Step 4: Write Tasks

Create tasks in order:

Setup/infrastructure
Core functionality (TDD for each)
Edge cases
Integration
Cleanup/documentation

Step 5: Add Complete Details

For each task, include:

Exact file paths (not "the config file" but src/config/settings.py)
Complete code examples (not "add validation" but the actual code)
Exact commands with expected output
Verification steps that prove the task works

Step 6: Review the Plan

Check:

Tasks are sequential and logical
Each task is bite-sized (2-5 min)
File paths are exact
Code examples are complete (copy-pasteable)
Commands are exact with expected output
No missing context
DRY, YAGNI, TDD principles applied

Principles

DRY (Don't Repeat Yourself)

Bad: Copy-paste validation in 3 places Good: Extract validation function, use everywhere

YAGNI (You Aren't Gonna Need It)

Bad: Add "flexibility" for future requirements Good: Implement only what's needed now

# Bad — YAGNI violation
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.preferences = {}  # Not needed yet!
        self.metadata = {}     # Not needed yet!

# Good — YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email

TDD (Test-Driven Development)

Every task that produces code should include the full TDD cycle:

Write failing test
Run to verify failure
Write minimal code
Run to verify pass

See test-driven-development skill for details.

Frequent Commits

Commit after every task:

git add [files]
git commit -m "type: description"

Common Mistakes

Vague Tasks

Bad: "Add authentication" Good: "Create User model with email and password_hash fields"

Incomplete Code

Bad: "Step 1: Add validation function" Good: "Step 1: Add validation function" followed by the complete function code

Missing Verification

Bad: "Step 3: Test it works" Good: "Step 3: Run pytest tests/test_auth.py -v, expected: 3 passed"

Missing File Paths

Bad: "Create the model file" Good: "Create: src/models/user.py"

Execution Handoff

After saving the plan, offer the execution approach:

"Plan complete and saved. Ready to execute using subagent-driven-development, I'll dispatch a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"

When executing, use the subagent-driven-development skill:

Fresh delegate_task per task with full context
Spec compliance review after each task
Code quality review after spec passes
Proceed only when both reviews approve

Remember

Bite-sized tasks (2-5 min each)
Exact file paths
Complete code (copy-pasteable)
Exact commands with expected output
Verification steps
DRY, YAGNI, TDD
Frequent commits

A good plan makes implementation obvious.

When not to use it

Do not use this skill when you need immediate execution. If the task is a simple, well-understood change (like fixing a typo or renaming a variable), writing a full plan adds overhead without benefit. The skill is also not suited for exploratory or research tasks where the outcome is unknown; the plan format assumes a clear goal and a known approach.

Limits and gotchas

The plan file is saved under .hermes/plans/ with a timestamped filename. If the runtime provides a specific target path, use that exact path. Otherwise, create a sensible timestamped filename yourself.
The skill assumes the implementer has zero context for the codebase. This means the plan must be exhaustive. If you are the implementer and already know the codebase, the level of detail may feel excessive, but the skill's design prioritises completeness over brevity.
The plan format is opinionated. Every plan must start with the required header, and each task must follow the specified structure. Deviating from this format may confuse downstream tools or subagents.
The skill does not handle ambiguous requests well. If the task is underspecified, the agent will ask a clarifying question rather than guess. This is intentional but can slow down the process if the request is vague.

What pairs with this

subagent-driven-development: The natural next step after writing a plan. This skill dispatches a fresh subagent per task with full context, performs spec compliance and code quality reviews, and proceeds only when both approve.
test-driven-development: The TDD cycle is embedded in every task. This skill provides the detailed test-first workflow.
requesting-code-review: After implementation, use this skill to get a code review on the changes.