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.
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)
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]
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]
---
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"
```
Read and understand: - Feature requirements - Design documents or user description - Acceptance criteria - Constraints
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")
Decide: - Architecture pattern - File organization - Dependencies needed - Testing strategy
Create tasks in order: 1. Setup/infrastructure 2. Core functionality (TDD for each) 3. Edge cases 4. Integration 5. Cleanup/documentation
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
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
mkdir -p docs/plans
# Save plan to docs/plans/YYYY-MM-DD-feature-name.md
git add docs/plans/
git commit -m "docs: add implementation plan for [feature]"
Bad: Copy-paste validation in 3 places Good: Extract validation function, use everywhere
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
Every task that produces code should include the full TDD cycle: 1. Write failing test 2. Run to verify failure 3. Write minimal code 4. Run to verify pass
See test-driven-development skill for details.
Commit after every task:
git add [files]
git commit -m "type: description"
When the user asks to "go through this from the start," "revisit the planning," or says a previous plan brushed over the important parts, do not jump straight into scaffolding or tactical tasks. First re-read the conversation context, restate the core product/architecture decision, identify explicit tradeoffs and decision gates, then save a strategy plan before implementation. For product/infrastructure planning, the right deliverable may be a strategy roadmap with phases, risks, economics, and gates rather than only bite-sized coding tasks.
Bad: "Add authentication" Good: "Create User model with email and password_hash fields"
Bad: "Step 1: Add validation function" Good: "Step 1: Add validation function" followed by the complete function code
Bad: "Step 3: Test it works"
Good: "Step 3: Run pytest tests/test_auth.py -v, expected: 3 passed"
Bad: "Create the model file"
Good: "Create: src/models/user.py"
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
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.