Hermes Agent Plan Skill: Write Markdown Plans Without Execution

{ "TITLE": "Hermes Plan Creator Reference", "BODY": "# Hermes Plan Creator Reference\n\n## Purpose\n\nThe Plan Creator produces a detailed, actionable implementation plan saved as a markdown file. It does not execute any code or make changes to the project. The plan is intended for a developer who will implement the feature later, possibly using subagent-driven-development.\n\n## When to Use\n\nUse the Plan Creator in these situations:\n\n- The user explicitly requests a plan instead of execution (e.g., via /plan command).\n- The task involves multi-step features, complex requirements, or delegation to subagents.\n- A feature seems simple but assumptions could cause bugs.\n- You plan to implement the feature yourself later and need documentation.\n- You are working alone and need to document the approach.\n\n## Capabilities\n\nThe Plan Creator can:\n\n- Inspect the repository and context using read-only commands and tools.\n- Write a markdown plan file to .hermes/plans/ with a timestamped filename.\n- Infer the task from the current conversation context if no explicit instruction accompanies /plan.\n- Ask clarifying questions when the request is genuinely underspecified.\n- Produce plans that include: goal, current context/assumptions, proposed approach, step-by-step plan, files likely to change, tests/validation, risks/tradeoffs/open questions.\n- Include exact file paths, likely test targets, and verification steps for code-related tasks.\n- Structure plans with a header (feature name, goal, architecture, tech stack) and bite-sized tasks (2-5 minutes each).\n- Each task includes: objective, exact file paths (create/modify/test), complete code examples, exact commands with expected output, verification steps, and commit instructions.\n- Apply DRY, YAGNI, and TDD principles in the plan. The TDD principle is also known as test-driven-development.\n- Offer to execute the plan using subagent-driven-development after saving.\n\n## Parameters\n\n| Parameter | Meaning | Required |\n|-----------|---------|----------|\n| target_path | Exact file path for saving the plan; if not provided, a timestamped filename under .hermes/plans/ is created. | No |\n| task_description | The feature or problem to plan; inferred from conversation if not explicitly given. | No |\n\n## Constraints and Caveats\n\n- Do not implement any code.\n- Do not edit project files except the plan markdown file.\n- Do not run mutating terminal commands, commit, push, or perform external actions.\n- Only read-only commands/tools may be used for inspection.\n- The plan must be concrete and actionable.\n- Each task must be 2-5 minutes of focused work.\n- Every code-producing task must follow the full TDD cycle: write failing test, run to verify failure, write minimal code, run to verify pass.\n- Commit after every task.\n- Assume the implementer has zero context for the codebase and questionable taste.\n- Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain.\n- Assume the implementer does not know good test design well.\n- The plan must make implementation obvious; if someone has to guess, the plan is incomplete.\n- Do not add flexibility for future requirements (YAGNI).\n- Do not repeat yourself (DRY).\n- If the request is genuinely underspecified, ask a brief clarifying question instead of guessing.\n\n## Failure Modes\n\n- Plan is vague or incomplete, causing implementer to guess.\n- Tasks are too large (more than 5 minutes each).\n- File paths are missing or inexact.\n- Code examples are incomplete or not copy-pasteable.\n- Commands lack expected output for verification.\n- Missing verification steps.\n- TDD cycle is skipped for code tasks.\n- Plan includes unnecessary features (YAGNI violation).\n- Plan duplicates code or logic (DRY violation).\n- Plan is saved to wrong location or not saved at all.\n\n## Prerequisites\n\n- Active workspace with write access to .hermes/plans/ directory.\n- Read-only access to the repository/codebase for inspection.\n- Ability to use Hermes tools (search_files, read_file, write_file).\n- Clear understanding of the feature requirements or acceptance criteria.\n- If delegating, the subagent-driven-development skill must be available.\n\n## Procedure: Create a Plan\n\n### Step 1: Understand Requirements\n\nRead feature requirements, design docs, acceptance criteria, and constraints.\n\n### Step 2: Explore the Codebase\n\nUse read-only tools to understand structure and similar features:\n\n\n# Understand project structure\nsearch_files(\"*.py\", target=\"files\", path=\"src/\")\n\n# Look at similar features\nsearch_files(\"similar_pattern\", path=\"src/\", file_glob=\"*.py\")\n\n# Check existing tests\nsearch_files(\"*.py\", target=\"files\", path=\"tests/\")\n\n# Read key files\nread_file(\"src/app.py\")\n\n\n### Step 3: Design Approach\n\nDecide architecture pattern, file organization, dependencies, and testing strategy.\n\n### Step 4: Write Tasks in Order\n\nWrite tasks in this order: setup/infrastructure, core functionality (TDD for each), edge cases, integration, cleanup/documentation.\n\n### Step 5: For Each Task, Add Required Details\n\nEach task must include:\n- Exact file paths\n- Complete code examples\n- Exact commands with expected output\n- Verification steps\n\n### Step 6: Review the Plan\n\nCheck that:\n- Tasks are sequential and logical\n- Each is bite-sized (2-5 min)\n- File paths are exact\n- Code examples are complete\n- Commands are exact with expected output\n- No missing context\n- DRY, YAGNI, test-driven-development are applied\n\n### Step 7: Save the Plan\n\nUse write_file to save the plan to .hermes/plans/YYYY-MM-DD_HHMMSS-.md (or use provided exact path).\n\n### Step 8: Reply Briefly\n\nReply with what was planned and the saved path.\n\n### Step 9: Offer to Execute\n\nOffer to execute using subagent-driven-development.\n\n## Plan Structure\n\n### Header\n\n\n# [Feature Name] Implementation Plan\n\n> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.\n\n**Goal:** [One sentence describing what this builds]\n\n**Architecture:** [2-3 sentences about approach]\n\n**Tech Stack:** [Key technologies/libraries]\n\n---\n\n\n### Task Template\n\n\n### Task N: [Descriptive Name]\n\n**Objective:** What this task accomplishes (one sentence)\n\n**Files:**\n- Create: `exact/path/to/new_file.py`\n- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)\n- Test: `tests/path/to/test_file.py`\n\n**Step 1: Write failing test**\n[code]\n\n**Step 2: Run test to verify failure**\n\nRun: `pytest tests/path/test.py::test_specific_behavior -v`\nExpected: FAIL — \"function not defined\"\n\n**Step 3: Write minimal implementation**\n[code]\n\n**Step 4: Run test to verify pass**\n\nRun: `pytest tests/path/test.py::test_specific_behavior -v`\nExpected: PASS\n\n**Step 5: Commit**\n\n\n### Commit Instruction Template\n\n\ngit add [files]\ngit commit -m \"type: description\"\n\n\n## Examples\n\n### Example 1: Authentication System (Single Task)\n\n\n### Task 1: Build authentication system\n[50 lines of code across 5 files]\n\n\n### Example 2: Authentication System (Broken Down)\n\n\n### Task 1: Create User model with email field\n[10 lines, 1 file]\n\n### Task 2: Add password hash field to User\n[8 lines, 1 file]\n\n### Task 3: Create password hashing utility\n[15 lines, 1 file]\n\n\n### Example 3: YAGNI Application\n\n\n# Bad — YAGNI violation\nclass User:\n def __init__(self, name, email):\n self.name = name\n self.email = email\n self.preferences = {} # Not needed yet!\n self.metadata = {} # Not needed yet!\n\n# Good — YAGNI\nclass User:\n def __init__(self, name, email):\n self.name = name\n self.email = email\n\n\n## Key Principles\n\n- Bite-sized tasks (2-5 min each)\n- Exact file paths\n- Complete code (copy-pasteable)\n- Exact commands with expected output\n- Verification steps\n- DRY, YAGNI, test-driven-development\n- Frequent commits\n\n## Typical Exploration Commands\n\n\n# Understand project structure\nsearch_files(\"*.py\", target=\"files\", path=\"src/\")\n\n# Look at similar features\nsearch_files(\"similar_pattern\", path=\"src/\", file_glob=\"*.py\")\n\n# Check existing tests\nsearch_files(\"*.py\", target=\"files\", path=\"tests/\")\n\n# Read key files\nread_file(\"src/app.py\")\n\n\n## Common File Paths in Plans\n\n- exact/path/to/new_file.py\n- exact/path/to/existing.py:45-67\n- tests/path/to/test_file.py\n- src/config/settings.py\n- src/models/user.py\n\n## Common Test Commands\n\n- pytest tests/path/test.py::test_specific_behavior -v\n- pytest tests/test_auth.py -v\n\n## Delegation\n\nAfter saving the plan, offer to execute using subagent-driven-development with the delegate_task tool." }