software-development-writing-plans
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.
- License 许可
- MIT
- 最近更新
- 2026-10-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- software-development-writing-plans
- author
- Hermes Agent (adapted from obra/superpowers)
- license
- MIT
- version
- 1.1.0
- metadata
- { "hermes": { "tags": [ "planning", "design", "implementation", "workflow", "documentation" ], "related_skills": [ "subagent-driven-development", "test-driven-development", "requesting-code-review" ] } }
- description
- 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.
03 SKILL.md 正文
Writing Implementation Plans
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 to Use
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
Step 7: Save the Plan
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]"
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_taskper 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.
04 同仓库更多 Skills
youtube-clipper
YouTube 视频智能剪辑工具。下载视频和字幕,AI 分析生成精细章节(几分钟级别), 用户选择片段后自动剪辑、翻译字幕为中英双语、烧录字幕到视频,并生成总结文案。 使用场景:当用户需要剪辑 YouTube 视频、生成短视频片段、制作双语字幕版本时。 关键词:视频剪辑、YouTube、字幕翻译、双语字幕、视频下载、clip video
yao-meta-skill
Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
ui-test
AI-powered adversarial UI testing via the browse CLI. Analyzes git diffs to test only what changed, or explores the full app to find bugs. Tests functional correctness, accessibility, responsive layout, and UX heuristics. Use when the user asks to test UI changes, QA a pull request, audit accessibility, or run exploratory testing. Supports local browser (localhost) and remote Browserbase (deployed sites).
technical-seo-checker
Use when the user asks to "technical SEO audit", "check page speed", "crawl issues", "Core Web Vitals", "site indexing problems", "my site is slow", "Google cannot crawl my site", "mobile issues", or "indexing problems". Performs technical SEO audits covering site speed, crawlability, indexability, mobile-friendliness, security, and structured data. Identifies technical issues preventing optimal search performance. For content and heading element issues, see on-page-seo-auditor. For link architecture, see internal-linking-optimizer.