mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-07 02:51:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

refactor: enhance software-development skills with Hermes integration

Browse source 
Improvements to all 5 skills adapted from obra/superpowers:

- Restored anti-rationalization tables and red flags from originals
  (key behavioral guardrails that prevent LLMs from taking shortcuts)
- Restored 'Rule of Three' for debugging (3+ failed fixes = question
  architecture, not keep fixing)
- Restored Pattern Analysis and Hypothesis Testing phases in debugging
- Restored 'Why Order Matters' rebuttals and verification checklist in TDD
- Added proper Hermes delegate_task integration with real parameter examples
  and toolset specifications throughout
- Added Hermes tool usage (search_files, read_file, terminal) for
  investigation and verification steps
- Removed references to non-existent skills (brainstorming,
  finishing-a-development-branch, executing-plans, using-git-worktrees)
- Removed generic language-specific sections (Go, Rust, Jest) that
  added bulk without agent value
- Tightened prose — cut ~430 lines while adding more actionable content
- Added execution handoff section to writing-plans
- Consistent cross-references between the 5 skills
This commit is contained in:
teknium1 2026-03-03 04:08:56 -08:00
parent 0e1723ef74
commit de0af4df66
5 changed files with 879 additions and 1312 deletions
Download patch file Download diff file Expand all files Collapse all files

521
skills/software-development/writing-plans/SKILL.md
View file

@ -1,8 +1,8 @@
---
name: writing-plans
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.
version: 1.0.0
author: Hermes Agent (adapted from Superpowers)
version: 1.1.0
author: Hermes Agent (adapted from obra/superpowers)
license: MIT
metadata:
hermes:
@ -14,112 +14,34 @@ metadata:
## Overview
Transform specifications into actionable implementation plans. Write comprehensive plans that any developer can follow - even with zero context about your codebase.
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.
**Core principle:** Document everything: exact file paths, complete code, test commands, verification steps.
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.
**Assume the implementer:**
- Is a skilled developer
- Knows almost nothing about your codebase
- Has questionable taste in code style
- Needs explicit guidance
**Core principle:** A good plan makes implementation obvious. If someone has to guess, the plan is incomplete.
## When to Use
**Always use this skill:**
- Before implementing multi-step features
- After design approval (from brainstorming)
- When breaking down complex requirements
- Before delegating to subagents
**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 yourself (future you needs guidance)
- You plan to implement it yourself (future you needs guidance)
- Working alone (documentation matters)
## Plan Document Structure
## Bite-Sized Task Granularity
### Header (Required)
**Each task = 2-5 minutes of focused work.**
Every plan MUST start with:
```markdown
# [Feature Name] Implementation Plan
> **For Hermes:** Use subagent-driven-development or executing-plans skill to implement this plan.
**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:
```markdown
### 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`
**Implementation Steps:**
**Step 1: [Action description]**
```python
# Complete code to write
class NewClass:
def __init__(self):
self.value = None
def process(self, input):
return input.upper()
```
**Step 2: [Action description]**
```bash
# Command to run
pytest tests/test_new.py -v
```
Expected: Tests pass with 3 green dots
**Step 3: [Action description]**
```python
# More code if needed
```
**Verification:**
- [ ] Test passes
- [ ] Function returns expected output
- [ ] No syntax errors
**Commit:**
```bash
git add src/new_file.py tests/test_new.py
git commit -m "feat: add new feature component"
```
```
## Task Granularity
**Each task = 2-5 minutes of work**
**Break down:**
- "Write failing test" - one task
- "Run test to verify it fails" - one task
- "Implement minimal code" - one task
- "Run test to verify pass" - one task
- "Commit" - one task
**Examples:**
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:**
```markdown
@ -139,6 +61,146 @@ git commit -m "feat: add new feature component"
[15 lines, 1 file]
```
## Plan Document Structure
### Header (Required)
Every plan MUST start with:
```markdown
# [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:
````markdown
### 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:
```python
# 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:
1. Setup/infrastructure
2. Core functionality (TDD for each)
3. Edge cases
4. Integration
5. 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
```bash
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)
@ -146,35 +208,21 @@ git commit -m "feat: add new feature component"
**Bad:** Copy-paste validation in 3 places
**Good:** Extract validation function, use everywhere
```python
# Good - DRY
def validate_email(email):
if not re.match(r'^[^@]+@[^@]+$', email):
raise ValueError("Invalid email")
return email
# Use everywhere
validate_email(user_input)
validate_email(config_email)
validate_email(imported_data)
```
### YAGNI (You Aren't Gonna Need It)
**Bad:** Add "flexibility" for future requirements
**Good:** Implement only what's needed now
```python
# Bad - YAGNI violation
# 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!
self.settings = {} # Not needed yet!
# Good - YAGNI
# Good — YAGNI
class User:
def __init__(self, name, email):
self.name = name
@ -183,7 +231,7 @@ class User:
### TDD (Test-Driven Development)
Every task that produces code should include:
Every task that produces code should include the full TDD cycle:
1. Write failing test
2. Run to verify failure
3. Write minimal code
@ -199,255 +247,50 @@ git add [files]
git commit -m "type: description"
```
## Writing Process
### Step 1: Understand Requirements
Read and understand:
- Feature requirements
- Design documents
- Acceptance criteria
- Constraints
### Step 2: Explore Codebase
```bash
# Understand project structure
find src -type f -name "*.py" | head -20
# Look at similar features
grep -r "similar_pattern" src/
# Check existing tests
ls tests/
```
### Step 3: Design Approach
Decide:
- Architecture pattern
- File organization
- Dependencies needed
- Testing strategy
### Step 4: Write Tasks
Create tasks in order:
1. Setup/infrastructure
2. Core functionality
3. Edge cases
4. Integration
5. Cleanup
### Step 5: Add Details
For each task, add:
- Exact file paths
- Complete code examples
- Exact commands
- Expected outputs
- Verification steps
### Step 6: Review Plan
Check:
- [ ] Tasks are sequential and logical
- [ ] Each task is bite-sized (2-5 min)
- [ ] File paths are exact
- [ ] Code examples are complete
- [ ] Commands are exact with expected output
- [ ] No missing context
### Step 7: Save Plan
```bash
# Create plans directory
mkdir -p docs/plans
# Save plan
cat > docs/plans/YYYY-MM-DD-feature-name.md << 'EOF'
[plan content]
EOF
# Commit plan
git add docs/plans/YYYY-MM-DD-feature-name.md
git commit -m "docs: add implementation plan for feature"
```
## Example Plan
```markdown
# User Authentication Implementation Plan
> **For Hermes:** Use subagent-driven-development to implement this plan.
**Goal:** Add JWT-based user authentication to the Flask API
**Architecture:** Use PyJWT for tokens, bcrypt for hashing. Middleware validates tokens on protected routes.
**Tech Stack:** Python, Flask, PyJWT, bcrypt
---
### Task 1: Create User model
**Objective:** Define User model with email and hashed password
**Files:**
- Create: `src/models/user.py`
- Test: `tests/models/test_user.py`
**Step 1: Write failing test**
```python
def test_user_creation():
user = User(email="test@example.com", password="secret123")
assert user.email == "test@example.com"
assert user.password_hash is not None
assert user.password_hash != "secret123" # Should be hashed
```
**Step 2: Run to verify failure**
```bash
pytest tests/models/test_user.py -v
```
Expected: FAIL - User class not defined
**Step 3: Implement User model**
```python
import bcrypt
class User:
def __init__(self, email, password):
self.email = email
self.password_hash = bcrypt.hashpw(
password.encode(),
bcrypt.gensalt()
)
```
**Step 4: Run to verify pass**
```bash
pytest tests/models/test_user.py -v
```
Expected: PASS
**Commit:**
```bash
git add src/models/user.py tests/models/test_user.py
git commit -m "feat: add User model with password hashing"
```
### Task 2: Create login endpoint
**Objective:** Add POST /login endpoint that returns JWT
**Files:**
- Modify: `src/app.py`
- Test: `tests/test_login.py`
[Continue...]
```
## Common Mistakes
### Vague Tasks
**Bad:**
```markdown
### Task 1: Add authentication
```
**Good:**
```markdown
### Task 1: Create User model with email and password_hash fields
```
**Bad:** "Add authentication"
**Good:** "Create User model with email and password_hash fields"
### Incomplete Code
**Bad:**
```markdown
Step 1: Add validation function
```
**Good:**
```markdown
Step 1: Add validation function
```python
def validate_email(email):
"""Validate email format."""
import re
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
if not re.match(pattern, email):
raise ValueError(f"Invalid email: {email}")
return email
```
**Bad:** "Step 1: Add validation function"
**Good:** "Step 1: Add validation function" followed by the complete function code
### Missing Verification
**Bad:**
```markdown
Step 3: Test it works
```
**Bad:** "Step 3: Test it works"
**Good:** "Step 3: Run `pytest tests/test_auth.py -v`, expected: 3 passed"
**Good:**
```markdown
Step 3: Verify authentication
```bash
curl -X POST http://localhost:5000/login \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","password":"secret123"}'
```
Expected: Returns 200 with JWT token in response
```
### Missing File Paths
## Integration with Other Skills
**Bad:** "Create the model file"
**Good:** "Create: `src/models/user.py`"
### With brainstorming
## Execution Handoff
**Sequence:**
1. brainstorming → Explore and refine design
2. writing-plans → Create implementation plan
3. subagent-driven-development → Execute plan
After saving the plan, offer the execution approach:
### With subagent-driven-development
**"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?"**
Plans feed into subagent-driven-development:
- Subagents implement each task
- Two-stage review ensures quality
- Plan provides context and requirements
### With test-driven-development
Every code-producing task should follow TDD:
1. Write failing test
2. Verify failure
3. Write minimal code
4. Verify pass
## Success Checklist
Before considering a plan complete:
- [ ] Header with goal, architecture, tech stack
- [ ] All tasks are bite-sized (2-5 min each)
- [ ] Exact file paths for every file
- [ ] Complete code examples (not partial)
- [ ] Exact commands with expected output
- [ ] Verification steps for each task
- [ ] Commit commands included
- [ ] DRY, YAGNI, TDD principles applied
- [ ] Tasks are sequential and logical
- [ ] Plan saved to docs/plans/
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
Bite-sized tasks (2-5 min each)
Exact file paths
Complete code
Exact commands
Complete code (copy-pasteable)
Exact commands with expected output
Verification steps
DRY, YAGNI, TDD
Frequent commits
```
**A good plan makes implementation obvious.**