{“content”:”---\nname: writing-plans\ndescription: Use when you have a spec or requirements for a multi-step task. Creates comprehensive implementation plans with bite-sized tasks, exact file paths, and complete code examples.\nversion: 1.1.0\nauthor: Hermes Agent (adapted from obra/superpowers)\nlicense: MIT\nmetadata:\n hermes:\n tags: [planning, design, implementation, workflow, documentation]\n related_skills: [subagent-driven-development, test-driven-development, requesting-code-review]\n---\n\n# Writing Implementation Plans\n\n## Overview\n\nWrite 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.\n\nAssume 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.\n\nCore principle: A good plan makes implementation obvious. If someone has to guess, the plan is incomplete.\n\n## When to Use\n\nAlways use before:\n- Implementing multi-step features\n- Breaking down complex requirements\n- Delegating to subagents via subagent-driven-development\n\nDon’t skip when:\n- Feature seems simple (assumptions cause bugs)\n- You plan to implement it yourself (future you needs guidance)\n- Working alone (documentation matters)\n\n## Bite-Sized Task Granularity\n\nEach task = 2-5 minutes of focused work.\n\nEvery step is one action:\n- “Write the failing test” — step\n- “Run it to make sure it fails” — step\n- “Implement the minimal code to make the test pass” — step\n- “Run the tests and make sure they pass” — step\n- “Commit” — step\n\nToo big:\nmarkdown\n### Task 1: Build authentication system\n[50 lines of code across 5 files]\n\n\nRight size:\nmarkdown\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## Plan Document Structure\n\n### Header (Required)\n\nEvery plan MUST start with:\n\nmarkdown\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 Structure\n\nEach task follows this format:\n\nmarkdown\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\n```python\ndef test_specific_behavior():\n result = function(input)\n assert result == expected\n```\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\n```python\ndef function(input):\n return expected\n```\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```bash\ngit add tests/path/test.py src/path/file.py\ngit commit -m \"feat: add specific feature\"\n```\n\n\n## Writing Process\n\n### Step 1: Understand Requirements\n\nRead and understand:\n- Feature requirements\n- Design documents or user description\n- Acceptance criteria\n- Constraints\n\n### Step 2: Explore the Codebase\n\nUse Hermes tools to understand the project:\n\npython\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:\n- Architecture pattern\n- File organization\n- Dependencies needed\n- Testing strategy\n\n### Step 4: Write Tasks\n\nCreate tasks in order:\n1. Setup/infrastructure\n2. Core functionality (TDD for each)\n3. Edge cases\n4. Integration\n5. Cleanup/documentation\n\n### Step 5: Add Complete Details\n\nFor each task, include:\n- Exact file paths (not “the config file” but src/config/settings.py)\n- Complete code examples (not “add validation” but the actual code)\n- Exact commands with expected output\n- Verification steps that prove the task works\n\n### Step 6: Review the Plan\n\nCheck:\n- [ ] Tasks are sequential and logical\n- [ ] Each task is bite-sized (2-5 min)\n- [ ] File paths are exact\n- [ ] Code examples are complete (copy-pasteable)\n- [ ] Commands are exact with expected output\n- [ ] No missing context\n- [ ] DRY, YAGNI, TDD principles applied\n\n### Step 7: Save the Plan\n\nbash\nmkdir -p docs/plans\n# Save plan to docs/plans/YYYY-MM-DD-feature-name.md\ngit add docs/plans/\ngit commit -m \"docs: add implementation plan for [feature]\"\n\n\n## Principles\n\n### DRY (Don’t Repeat Yourself)\n\nBad: Copy-paste validation in 3 places\nGood: Extract validation function, use everywhere\n\n### YAGNI (You Aren’t Gonna Need It)\n\nBad: Add “flexibility” for future requirements\nGood: Implement only what’s needed now\n\npython\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### TDD (Test-Driven Development)\n\nEvery task that produces code should include the full TDD cycle:\n1. Write failing test\n2. Run to verify failure\n3. Write minimal code\n4. Run to verify pass\n\nSee test-driven-development skill for details.\n\n### Frequent Commits\n\nCommit after every task:\nbash\ngit add [files]\ngit commit -m \"type: description\"\n\n\n## Common Mistakes\n\n### Vague Tasks\n\nBad: “Add authentication”\nGood: “Create User model with email and password_hash fields”\n\n### Incomplete Code\n\nBad: “Step 1: Add validation function”\nGood: “Step 1: Add validation function” followed by the complete function code\n\n### Missing Verification\n\nBad: “Step 3: Test it works”\nGood: “Step 3: Run pytest tests/test_auth.py -v, expected: 3 passed”\n\n### Missing File Paths\n\nBad: “Create the model file”\nGood: “Create: src/models/user.py”\n\n## Execution Handoff\n\nAfter saving the plan, offer the execution approach:\n\n**“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?”\n\nWhen executing, use the subagent-driven-development skill:\n- Fresh delegate_task per task with full context\n- Spec compliance review after each task\n- Code quality review after spec passes\n- Proceed only when both reviews approve\n\n## Remember\n\n\nBite-sized tasks (2-5 min each)\nExact file paths\nComplete code (copy-pasteable)\nExact commands with expected output\nVerification steps\nDRY, YAGNI, TDD\nFrequent commits\n\n\nA good plan makes implementation obvious.**\n”}