openhermes 4.3.0 → 4.11.2

package/harness/skills/oh-refactor/SKILL.md

@@ -1,426 +1,33 @@
 ---
 name: oh-refactor
-description: "Surgical, behavior-preserving code refactoring. Extract functions, eliminate duplication, improve type safety, remove dead code, simplify conditionals. Use when code is hard to maintain, functions are too long, code smells accumulate, or user asks to clean up/improve/refactor code."
+description: "Use when code is hard to maintain, functions are too long, code smells accumulate, or the user asks to clean up, improve, or refactor code. Behavior-preserving refactoring — extract, deduplicate, simplify, improve types."
 tier: 3
-benefits-from: [oh-investigate, oh-review]
-triggers:
-  - "refactor"
-  - "clean up"
-  - "improve this code"
-  - "code smell"
-  - "make this better"
-  - "extract method"
-  - "reduce duplication"
-  - "fix this mess"
-  - "technical debt"
-  - "god function"
-  - "long method"
-  - "nested conditionals"
 route:
   pass: oh-gauntlet
-  fail: oh-planner
+  fail:
+    - oh-planner
+    - oh-investigate
+    - oh-builder
   blocker: surface
 ---
 
 # oh-refactor
 
-Improve code structure and readability **without changing external behavior**. Refactoring is gradual evolution, not revolution.
+Improve code structure without changing external behavior.
 
-## When to Use
+## Steps
 
-- Code is hard to understand or maintain
-- Functions/classes are too large
-- Code smells need addressing
-- Adding features is difficult due to code structure
-- User asks "clean up this code", "refactor this", "improve this"
-- Technical debt has accumulated to the point it slows development
-
-## Refactoring Principles
-
-### Golden Rules
-
-1. **Behavior is preserved** — Refactoring doesn't change what the code does, only how. If the goal changes behavior, that's a feature, not a refactor.
-2. **Small steps** — Make one change, verify, commit, repeat. Never batch refactoring changes.
-3. **Tests are essential** — Without a fast, reliable test, you're not refactoring, you're editing blind. Write tests first if they don't exist.
-4. **One thing at a time** — Never mix refactoring with feature changes in the same commit.
-5. **Commit between safe states** — Commit before starting, commit after each green test run.
-
-### When NOT to Refactor
-
-- Code that works and will never change again
-- Critical production code without tests (add tests first)
-- Under a tight deadline with no test safety net
-- "Just because" — every refactor needs a clear purpose
-
-## Workflow
-
-### Phase 1: Prepare
-
-1. **Check test coverage** — run existing tests. If coverage is thin, write characterization tests that lock down current behavior before touching anything.
-2. **Commit current state** — `git commit` so you can diff and revert cleanly.
-3. **Create a feature branch** — isolate refactoring work from other changes.
-
-### Phase 2: Identify
-
-1. Find the code smell to address (see [Code Smells](#common-code-smells--fixes) below).
-2. Understand what the code actually does — trace all code paths.
-3. Plan the smallest refactoring that makes the problem better.
-4. If behavior is unclear, delegate to `oh-investigate` before refactoring.
-
-### Phase 3: Refactor (small steps)
-
-1. Make one small change.
-2. Run tests.
-3. Commit if tests pass.
-4. Repeat until the smell is gone.
-
-### Phase 4: Verify
-
-1. All tests pass.
-2. Manual smoke test if full coverage is missing.
-3. Performance unchanged or improved.
-4. Diff shows only structural changes — no logic changes.
-
-### Phase 5: Clean Up
-
-1. Remove commented-out code, stale imports, dead paths.
-2. Update inline docs only if behavior semantics changed.
-3. Final commit.
-4. Optionally route to `oh-review` for post-refactor quality gate.
-
-## Common Code Smells & Fixes
-
-### 1. Long Method/Function
-
-```diff
-# BAD: 200-line function that does everything
-- async function processOrder(orderId) {
--   // 50 lines: fetch order
--   // 30 lines: validate order
--   // 40 lines: calculate pricing
--   // 30 lines: update inventory
--   // 20 lines: create shipment
--   // 30 lines: send notifications
-- }
-
-# GOOD: Broken into focused functions
-+ async function processOrder(orderId) {
-+   const order = await fetchOrder(orderId);
-+   validateOrder(order);
-+   const pricing = calculatePricing(order);
-+   await updateInventory(order);
-+   const shipment = await createShipment(order);
-+   await sendNotifications(order, pricing, shipment);
-+   return { order, pricing, shipment };
-+ }
-```
-
-### 2. Duplicated Code
-
-```diff
-# BAD: Same logic in multiple places
-- function calculateUserDiscount(user) {
--   if (user.membership === 'gold') return user.total * 0.2;
--   if (user.membership === 'silver') return user.total * 0.1;
--   return 0;
-- }
-- function calculateOrderDiscount(order) {
--   if (order.user.membership === 'gold') return order.total * 0.2;
--   if (order.user.membership === 'silver') return order.total * 0.1;
--   return 0;
-- }
-
-# GOOD: Extract common logic
-+ function getMembershipDiscountRate(membership) {
-+   const rates = { gold: 0.2, silver: 0.1 };
-+   return rates[membership] || 0;
-+ }
-+ function calculateUserDiscount(user) {
-+   return user.total * getMembershipDiscountRate(user.membership);
-+ }
-+ function calculateOrderDiscount(order) {
-+   return order.total * getMembershipDiscountRate(order.user.membership);
-+ }
-```
-
-### 3. Large Class/Module (God Object)
-
-```diff
-# BAD: God object that knows too much
-- class UserManager {
--   createUser() { /* ... */ }
--   updateUser() { /* ... */ }
--   deleteUser() { /* ... */ }
--   sendEmail() { /* ... */ }
--   generateReport() { /* ... */ }
--   handlePayment() { /* ... */ }
--   validateAddress() { /* ... */ }
-- }
-
-# GOOD: Single responsibility per class
-+ class UserService {
-+   create(data) { /* ... */ }
-+   update(id, data) { /* ... */ }
-+   delete(id) { /* ... */ }
-+ }
-+ class EmailService {
-+   send(to, subject, body) { /* ... */ }
-+ }
-+ class ReportService {
-+   generate(type, params) { /* ... */ }
-+ }
-+ class PaymentService {
-+   process(amount, method) { /* ... */ }
-+ }
-```
-
-### 4. Long Parameter List
-
-```diff
-# BAD: Too many parameters
-- function createUser(email, password, name, age, address, city, country, phone) { }
-
-# GOOD: Group related parameters
-+ interface UserData {
-+   email: string;
-+   password: string;
-+   name: string;
-+   age?: number;
-+   address?: Address;
-+   phone?: string;
-+ }
-+ function createUser(data: UserData) { }
-```
-
-### 5. Feature Envy
-
-```diff
-# BAD: Method uses another object's data more than its own
-- class Order {
--   calculateDiscount(user) {
--     if (user.membershipLevel === 'gold') return this.total * 0.2;
--     if (user.accountAge > 365) return this.total * 0.1;
--     return 0;
--   }
-- }
-
-# GOOD: Move logic to the object that owns the data
-+ class User {
-+   getDiscountRate(orderTotal) {
-+     if (this.membershipLevel === 'gold') return 0.2;
-+     if (this.accountAge > 365) return 0.1;
-+     return 0;
-+   }
-+ }
-+ class Order {
-+   calculateDiscount(user) {
-+     return this.total * user.getDiscountRate(this.total);
-+   }
-+ }
-```
-
-### 6. Primitive Obsession
-
-```diff
-# BAD: Using primitives for domain concepts
-- function sendEmail(to, subject, body) { }
-- sendEmail('user@example.com', 'Hello', '...');
-
-# GOOD: Use domain types
-+ class Email {
-+   private constructor(public readonly value: string) {
-+     if (!Email.isValid(value)) throw new Error('Invalid email');
-+   }
-+   static create(value: string) { return new Email(value); }
-+   static isValid(email: string) { return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email); }
-+ }
-```
-
-### 7. Magic Numbers/Strings
-
-```diff
-# BAD: Unexplained values
-- if (user.status === 2) { }
-- const discount = total * 0.15;
-
-# GOOD: Named constants
-+ const UserStatus = { ACTIVE: 1, INACTIVE: 2, SUSPENDED: 3 } as const;
-+ const DISCOUNT_RATES = { STANDARD: 0.1, PREMIUM: 0.15, VIP: 0.2 } as const;
-+ if (user.status === UserStatus.INACTIVE) { }
-+ const discount = total * DISCOUNT_RATES.PREMIUM;
-```
-
-### 8. Nested Conditionals (Arrow Code)
-
-```diff
-# BAD: Arrow code
-- function process(order) {
--   if (order) {
--     if (order.user) {
--       if (order.user.isActive) {
--         if (order.total > 0) {
--           return processOrder(order);
--         } else { return { error: 'Invalid total' }; }
--       } else { return { error: 'User inactive' }; }
--     } else { return { error: 'No user' }; }
--   } else { return { error: 'No order' }; }
-- }
-
-# GOOD: Guard clauses / early returns
-+ function process(order) {
-+   if (!order) return { error: 'No order' };
-+   if (!order.user) return { error: 'No user' };
-+   if (!order.user.isActive) return { error: 'User inactive' };
-+   if (order.total <= 0) return { error: 'Invalid total' };
-+   return processOrder(order);
-+ }
-```
-
-### 9. Dead Code
-
-```diff
-# BAD: Unused code lingers
-- function oldImplementation() { }
-- const DEPRECATED_VALUE = 5;
-- import { unusedThing } from './somewhere';
-
-# GOOD: Remove it
-+ // Delete unused functions, imports, commented-out code
-+ // Git history has everything you need
-```
-
-### 10. Inappropriate Intimacy
-
-```diff
-# BAD: One class reaches deep into another
-- class OrderProcessor {
--   process(order) {
--     order.user.profile.address.street;  // Too intimate
--   }
-- }
-
-# GOOD: Ask, don't tell
-+ class OrderProcessor {
-+   process(order) {
-+     order.getShippingAddress();  // Order knows how to get it
-+     order.save();
-+   }
-+ }
-```
-
-## Extract Method Refactoring
-
-```diff
-# Before: One long function
-- function printReport(users) {
--   console.log('USER REPORT');
--   console.log('============');
--   console.log(`Total users: ${users.length}`);
--   console.log('ACTIVE USERS');
--   const active = users.filter(u => u.isActive);
--   active.forEach(u => console.log(`- ${u.name} (${u.email})`));
--   console.log(`Active: ${active.length}`);
--   console.log('INACTIVE USERS');
--   const inactive = users.filter(u => !u.isActive);
--   inactive.forEach(u => console.log(`- ${u.name} (${u.email})`));
--   console.log(`Inactive: ${inactive.length}`);
-- }
-
-# After: Extracted methods
-+ function printReport(users) {
-+   printHeader('USER REPORT');
-+   console.log(`Total users: ${users.length}\n`);
-+   printUserSection('ACTIVE USERS', users.filter(u => u.isActive));
-+   printUserSection('INACTIVE USERS', users.filter(u => !u.isActive));
-+ }
-+ function printHeader(title) {
-+   const line = '='.repeat(title.length);
-+   console.log(title); console.log(line); console.log('');
-+ }
-+ function printUserSection(title, users) {
-+   console.log(title);
-+   console.log('-'.repeat(title.length));
-+   users.forEach(u => console.log(`- ${u.name} (${u.email})`));
-+   console.log(`${title.split(' ')[0]}: ${users.length}`);
-+ }
-```
-
-## Design Patterns for Refactoring
-
-### Strategy Pattern
-
-Replace conditional branching with composable strategies:
-
-```diff
-- function calculateShipping(order, method) {
--   if (method === 'standard') return order.total > 50 ? 0 : 5.99;
--   else if (method === 'express') return order.total > 100 ? 9.99 : 14.99;
--   else if (method === 'overnight') return 29.99;
-- }
-
-+ interface ShippingStrategy { calculate(order: Order): number; }
-+ class StandardShipping implements ShippingStrategy {
-+   calculate(order: Order) { return order.total > 50 ? 0 : 5.99; }
-+ }
-+ class ExpressShipping implements ShippingStrategy {
-+   calculate(order: Order) { return order.total > 100 ? 9.99 : 14.99; }
-+ }
-+ function calculateShipping(order: Order, strategy: ShippingStrategy) {
-+   return strategy.calculate(order);
-+ }
-```
-
-### Guard Clauses
-
-Replace nested conditions with early returns. This is the single highest-ROI refactoring pattern — it flattens deeply nested code immediately.
-
-## Common Refactoring Operations
-
-| Operation | Description |
-|---|---|
-| Extract Method | Turn code fragment into named function |
-| Extract Class | Move related behavior to new class |
-| Inline Method | Move method body back to single caller |
-| Rename Method/Variable | Improve clarity |
-| Introduce Parameter Object | Group related parameters |
-| Replace Conditional with Polymorphism | Dispatch by type instead of if/switch |
-| Replace Magic Number with Constant | Named constants for literals |
-| Decompose Conditional | Break complex conditions into named predicates |
-| Consolidate Conditional | Combine duplicate conditions |
-| Replace Nested Conditional with Guard Clauses | Early returns |
-| Replace Inheritance with Delegation | Composition over inheritance |
-
-## Refactoring Checklist
-
-### Code Quality
-- [ ] Functions are small (< 50 lines)
-- [ ] Functions do one thing
-- [ ] No duplicated code
-- [ ] Descriptive names (variables, functions, classes)
-- [ ] No magic numbers/strings
-- [ ] Dead code removed
-
-### Structure
-- [ ] Related code is together
-- [ ] Clear module boundaries
-- [ ] Dependencies flow in one direction
-- [ ] No circular dependencies
-
-### Type Safety
-- [ ] Types defined for all public APIs
-- [ ] No `any` types without justification
-- [ ] Nullable types explicitly marked
-
-### Testing
-- [ ] Refactored code is tested
-- [ ] Tests cover edge cases
-- [ ] All tests pass
+1. Prepare — check test coverage. Write characterization tests if thin. Commit current state. Create feature branch.
+2. Identify — find code smell. Understand what the code does. Plan the smallest fix.
+3. Refactor in small steps — one change, run tests, commit. Repeat until smell is gone.
+4. Verify — all tests pass, manual smoke test if coverage missing, performance unchanged, diff shows structural changes only.
+5. Clean up — remove commented-out code, stale imports, dead paths. Update docs only if semantics changed.
 
 ## Routing
 
 | Outcome | Route |
-|---|---|
-| pass | -> oh-review (post-refactor quality gate) |
-| behavior unclear | -> oh-investigate (diagnose before refactoring) |
-| test gap found | -> oh-builder TDD mode (add characterization tests first) |
-| blocker | -> surface to user |
+|---------|-------|
+| pass | → oh-gauntlet (test integrity) |
+| behavior unclear | → oh-investigate |
+| test gap found | → oh-builder (TDD mode) |
+| blocker | → surface |

package/harness/skills/oh-retro/DEEP.md

@@ -0,0 +1,26 @@
+# oh-retro — Deep Reference
+
+## When to Use
+
+End of sprint or work week. Analyze shipped work, how it went, what to improve.
+
+## Workflow
+
+1. Read git log since last retro
+2. Categorize: features, fixes, refactors, docs, chores
+3. Pattern analysis: recurring themes, bottlenecks, bug types
+4. Praise: good work, patterns, decisions
+5. Growth areas: specific suggestions for improvement
+6. Trend tracking: compare to previous retros
+
+## Output
+
+Structured retro: shipped items, metrics, praise, growth areas, action items.
+
+**Example:** End of sprint. Read git log → categorize (features, fixes, refactors) → pattern analysis → praise → growth areas → action items.
+
+## Anti-patterns
+
+- Blame-focused (process, not people)
+- Action items without owners
+- Same retro every week (nothing changed → why?)

package/harness/skills/oh-retro/SKILL.md

@@ -1,11 +1,7 @@
 ---
 name: oh-retro
-description: "Weekly engineering retrospective — analyze commit history and work patterns"
+description: "Use at the end of a sprint or milestone to analyze commit history, work patterns, and extract actionable insights for the next cycle."
 tier: 3
-triggers:
-  - "retrospective"
-  - "retro for"
-  - "post-ship review"
 route:
   pass: oh-planner
   fail: oh-handoff
@@ -14,29 +10,21 @@ route:
 
 # oh-retro
 
-## When to Use
-At the end of a sprint or work week. Analyzes what was shipped, how it went, and what to improve.
+Analyze shipped work and extract actionable insights for the next cycle.
 
-## Workflow
-1. **Analyze commits** — read git log since last retro
-2. **Categorize work** — features, fixes, refactors, docs, chores
-3. **Pattern analysis** — recurring themes, bottlenecks, types of bugs
-4. **Praise** — call out good work, good patterns, good decisions
-5. **Growth areas** — what could be better, with specific suggestions
-6. **Trend tracking** — compare against previous retros
+## Steps
 
-## Output
-Structured retro report with: shipped items, metrics, praise, growth areas, action items.
-
-## Anti-patterns
-- Blame-focused retro (it's about process, not people)
-- Action items without owners (no follow-through)
-- Same retro every week (if nothing changed, why?)
+1. Read git log since last retro
+2. Categorize commits: features, fixes, refactors, docs, chores
+3. Analyze recurring themes, bottlenecks, and bug types
+4. Document praise: good work, patterns, decisions
+5. Identify growth areas with specific improvement suggestions
+6. Track trends against previous retros
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → oh-planner (start next cycle with retro insights) |
-| fail | → oh-handoff (document blockers for next session) |
-| blocker | → surface to user |
+| pass | → oh-planner |
+| fail | → oh-handoff |
+| blocker | → surface |

package/harness/skills/oh-review/DEEP.md

@@ -0,0 +1,87 @@
+# oh-review — Deep Reference
+
+## Mode A: Diff Review
+
+### 1. Pin Fixed Point
+User provides branch/commit/tag. Capture `git diff <fixed>...HEAD` + `git log <fixed>..HEAD --oneline`.
+
+### 2. Find Spec Source (order)
+1. Issue refs in commit messages (`#123`, `Closes #45`)
+2. User-provided path
+3. `docs/`, `specs/`, `.scratch/` files
+4. Ask user
+
+No spec found → spec sub-agent reports "no spec available."
+
+### 3. Find Standards Sources
+AGENTS.md, CLAUDE.md, CONTRIBUTING.md, CONTEXT.md, ADRs, eslint/biome/prettier config (note tool-enforced — don't re-check).
+
+### 4. Spawn Sub-Agents (parallel)
+- **Standards** — Read standards + diff. Per-file/hunk: violations citing standard + rule. Distinguish hard violations from judgment calls. Skip tool-enforced.
+- **Spec** — Read spec + diff. Report: missing/partial requirements, scope creep, wrong implementations. Quote spec line.
+
+### 5. Aggregate
+Present under `## Standards` / `## Spec`. Do not merge. End with total + worst issue.
+
+### Safety Check (inline before spawning)
+- SQL injection, LLM trust boundary violations, conditional side effects (test vs prod), hardcoded secrets
+- Block immediately if critical — do not spawn sub-agents.
+
+## Mode B: Architecture Deepening
+
+Surface refactoring opportunities using the **deletion test**: deleting a shallow module concentrates complexity; a deep module's complexity vanishes.
+
+### Vocabulary
+- **Module** — interface + implementation
+- **Depth** — leverage at interface (lots of behavior, small interface)
+- **Seam** — where interface lives; place to alter behavior without in-place edit
+- **Leverage** — what callers get from depth
+- **Locality** — change concentrated in one place
+
+### Process
+1. **Explore** — Read CONTEXT.md, ADRs. Walk codebase for friction (bouncing between modules, shallow interfaces, deletion test candidates).
+2. **Present candidates** — Numbered. Files, problem, solution, locality/leverage benefits. Flag ADR conflicts.
+3. **Grilling loop** — Walk design tree. Update CONTEXT.md for new terms. Offer ADRs for rejected candidates.
+4. **Output** — Ranked refactoring candidates with collision warnings.
+
+## Mode C: Receiving Review Feedback
+
+**Pattern:** READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
+
+### Banned Responses
+Never: "You're absolutely right!", "Great point!", "Excellent feedback!", any gratitude. Instead: restate technical requirement, ask clarifying questions, or just implement.
+
+### Source-Specific Handling
+- **Partner (trusted):** Still verify. No performative agreement. Skip to action or technical acknowledgment.
+- **External reviewer (skeptical):** Check 5 things before implementing — technically correct? Breaks existing? Full context? Cross-platform? Conflicts with prior decisions?
+
+### YAGNI Check
+If reviewer says "implement properly", grep for actual usage. Unused → propose removal. Used → implement.
+
+### Implementation Order
+1. Clarify unclear items FIRST (partial understanding = wrong implementation)
+2. Blocker fixes (breaks, security)
+3. Simple fixes (typos, imports)
+4. Complex fixes (refactoring, logic)
+5. Test each individually, verify no regressions
+
+### When to Push Back
+Suggestion breaks existing functionality, reviewer lacks context, violates YAGNI, technically incorrect for this stack, conflicts with architecture decisions. Use technical reasoning, not defensiveness.
+
+### Graceful Correction
+If you pushed back and were wrong: state factually — "You were right, checked [X], it does [Y]. Fixing now." No long apologies, no defending, no over-explaining.
+
+## Scoring
+- Critical safety → block before sub-agents
+- Structural concern / spec deviation → changes requested
+- Style/nit → follow-up note
+
+## Anti-patterns
+- Style before safety
+- Rubber-stamping without reading diff
+- Subjective preference changes
+- Merging Standards + Spec findings (one axis masks the other)
+- Proposing interfaces before user picks a candidate
+- Performative agreement (thanking reviewer before verifying)
+- Blind implementation of reviewer suggestions
+- Mixing feedback handling modes