openhermes 4.3.0 → 4.11.2

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

@@ -1,19 +1,7 @@
 ---
 name: oh-planner
-description: "ALL-arounder planner — brainstorm, architect, autoplan, decision pipeline. Produces a consumable plan artifact."
+description: "Use when a feature, architecture, or idea needs structured planning — from brainstorming through formal plan artifact. Produces consumable plan documents."
 tier: 3
-benefits-from: [oh-expert, oh-grill]
-triggers:
-  - "plan this"
-  - "how should I build"
-  - "plan the architecture for"
-  - "design this feature"
-  - "brainstorm"
-  - "autoplan"
-  - "strategy for this feature"
-  - "scope this feature"
-  - "create a plan for"
-  - "whats the plan for"
 route:
   pass: oh-grill
   fail: oh-planner
@@ -22,143 +10,18 @@ route:
 
 # oh-planner
 
-The ALL-arounder planner. Merges brainstorm, architecture analysis, strategy review, and automatic plan review into one skill. Produces a plan file in OpenCode's canonical storage at `~/.local/share/opencode/openhermes/plans/`.
+ALL-arounder planner: brainstorm, architecture analysis, structured plan, autoplan.
 
-## Entry Modes
+## Steps
 
-Use the mode that matches the user's starting point:
-
-### Mode A: Brainstorm (exploratory)
-When the idea is fuzzy and needs shaping.
-
-1. **Demand reality** — who specifically needs this?
-2. **Status quo** — what do they do today?
-3. **Desperate specificity** — what's the one concrete thing they can't do?
-4. **Narrowest wedge** — what's the smallest useful version?
-5. **Observation** — what will you see/hear when it works?
-6. **Future-fit** — does this compound or plateau?
-
-Output: structured design doc.
-
-### Mode B: Architecture Analysis (existing codebase)
-When the codebase feels messy or you need to understand the surface.
-
-1. **Read the domain** — load CONTEXT.md, understand the language
-2. **Map the surface** — identify modules, boundaries, dependencies
-3. **Find deepening opportunities** — duplication, over-coupling, grown-beyond-purpose functions, missing abstractions
-4. **Rank by impact** — effort vs value, dependencies, risk
-
-Output: ranked refactoring candidates.
-
-### Mode C: Structured Plan (non-trivial feature)
-When requirements exist but need a plan document.
-
-1. **Scope challenge** — before reviewing anything, answer:
-   - What existing code already partially solves each sub-problem?
-   - What is the minimum set of changes that achieves the stated goal?
-   - **Complexity check:** 8+ files or 2+ new classes/services in a single phase → smell. Propose splitting or simplifying.
-   - **Search check:** for each architectural pattern or infrastructure component the plan introduces, check whether the runtime/framework has a built-in. Search for: `{framework} {pattern} built-in`. Flag custom solutions where built-ins exist.
-   - **Completeness check:** with AI-assisted coding, completeness is 10-100x cheaper than with human teams. If the plan shortcuts something to save human hours that only saves minutes with AI, recommend the complete version.
-2. **Strategy review** — challenge premises, identify scope decisions, consider 10x alternatives
-3. **Architecture review** — data flow, component boundaries, API surface, state model
-4. **Edge case analysis** — error states, concurrency, failure modes, security implications
-5. **Dependency mapping** — what blocks what, parallelizable work
-6. **Write plan.md** — structured artifact with phases, deps, verification steps
-
-### Mode D: Autoplan (plan exists, needs full review)
-When a plan file exists and needs the full gauntlet. Auto-decides 90% of questions using decision principles. Surfaces only taste decisions at a final approval gate.
-
-Runs in order: **Strategy → Architecture → Design → Engineering → DX**
-Each phase must complete before the next begins.
-
-## Decision Principles
-
-Use these to auto-resolve intermediate questions. Only surface to the user when options are genuinely close (taste decisions):
-
-1. **Completeness over cleverness** — Choose the option that covers more cases
-2. **Boil the lake** — Fix the blast radius, not the symptom
-3. **Pragmatic over perfect** — Cleaner option that ships today wins
-4. **DRY but not premature** — Reuse over rebuild, but don't abstract before the third instance
-5. **Explicit over implicit** — Clear code over magic
-6. **Bias toward action** — When in doubt, make progress
-
-Never auto-decide: premises (need human judgment) or cases where both the plan and the alternative have strong arguments.
-
-## Plan Artifact
-
-Output goes in `~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md` (OpenCode's canonical storage, sequence-numbered per-session/project). The plan ID matches the filename.
-
-```markdown
-# PLAN: <project-name>
-
-Plan ID: <project-name>-plan-<nnn>
-Project: <project-name>
-Status: active
-Created: <local-date-time>
-Updated: <local-date-time>
-Project Path: <absolute-project-path>
-Plan Path: ~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md
-Objective: <short objective>
-
-## Current State
-
-<what exists now, what's missing>
-
-## Assumptions
-
-- <assumption 1>
-- <assumption 2>
-
-## Tasks
-
-- [ ] Task 1
-  - [ ] Subtask 1.1
-
-## Active Task
-
-<what's being worked on now>
-
-## Subagents
-
-| Agent | Purpose | Status | Findings |
-|---|---|---|---|
-
-## Completed
-
-- <what's done>
-
-## Work Log
-
-<timestamped entries for subagent handoffs>
-
-## Blockers
-
-- None
-
-## Validation
-
-- [ ] Static checks
-- [ ] Unit tests
-- [ ] Manual verification
-
-## Decisions
-
-- <decision> — <rationale>
-
-## Notes
-
-<anything else>
-```
-
-The plan file is self-contained — Tasks, Completed, Subagents, and Work Log sections eliminate the need for separate todo.md or work-log.md files.
-
-## Anti-patterns
-- Skipping strategy review for complex features (architecture mistakes compound)
-- Plans at wrong granularity — too vague to execute or too detailed to read
-- Re-opening already-decided debates ("what if we rewrite in Rust?")
-- Perfect being the enemy of shipped (progress > polish)
-- Failing to flag taste decisions to the user
-- Big bang rewrites — plan increments, not overhauls
+1. Determine mode — Mode A (brainstorm vague idea), Mode B (architecture analysis), Mode C (structured plan), or Mode D (autoplan).
+2. Clarify scope — ask 6 clarifying questions (who needs this, current workflow, capability gap, smallest version, success signals, compound vs plateau).
+3. Map code surface if applicable — module boundaries, dependencies, find deepening opportunities, rank by effort/value/risk.
+4. Challenge premises — check existing code reuse, minimum changes, complexity (8+ files = smell), framework built-ins, completeness.
+5. Analyze architecture — data flow, component boundaries, API surface, state model, edge cases (error, concurrency, failure, security), dependency mapping.
+6. Write structured plan — canonical format: Current State, Assumptions, Tasks, Active Task, Subagents, Completed, Work Log, Blockers, Validation, Decisions, Notes.
+7. Apply auto-resolution principles — completeness over cleverness, boil the lake, pragmatic over perfect, DRY at 3rd, explicit over implicit, bias toward action. Surface taste decisions.
+8. Self-review — verify spec coverage, scan for placeholders (TBD/TODO), check type consistency across tasks.
 
 ## Routing
 
@@ -166,4 +29,4 @@ The plan file is self-contained — Tasks, Completed, Subagents, and Work Log se
 |---------|-------|
 | pass | → oh-grill (stress-test plan) |
 | fail | → oh-planner (revise gaps) |
-| blocker | → surface to user |
+| blocker | → surface |

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

@@ -0,0 +1,45 @@
+# oh-prd — Deep Reference
+
+## When to Use
+
+Conversation has defined a feature well enough to write requirements. Produces a structured PRD and publishes as a GitHub issue.
+
+Triggers: write a prd, product requirements, spec this feature, feature spec.
+
+## PRD Structure
+
+```markdown
+# PRD: <feature name>
+
+## Problem Statement
+<what problem does this solve, for whom>
+
+## Success Criteria
+<measurable outcomes>
+
+## Scope
+### In scope
+- <features included>
+
+### Out of scope
+- <explicitly excluded — prevents scope creep>
+
+## Requirements
+### Functional
+- <numbered behaviors>
+
+### Non-functional
+- <performance, security, accessibility, observability>
+
+## Open Questions
+- <unresolved items>
+
+## Dependencies
+- <what must exist first>
+```
+
+## Anti-patterns
+
+- Specifying solutions instead of problems (let the builder decide how)
+- Too detailed (PRD sets direction, not implementation)
+- No open questions section (there are always open questions)

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

@@ -1,11 +1,7 @@
 ---
 name: oh-prd
-description: "Turn conversation context into a PRD and publish as GitHub issue"
+description: "Write structured PRDs from conversation context and publish as issues"
 tier: 2
-triggers:
-  - "write a prd"
-  - "product requirements"
-  - "prd for"
 route:
   pass: oh-issue
   fail: oh-grill
@@ -14,31 +10,19 @@ route:
 
 # oh-prd
 
-## When to Use
-When a feature discussion has produced enough context to write a product requirements document. Captures the decision tree and outputs a structured issue.
+Turn conversation context into a structured PRD and publish as a GitHub issue.
 
-## Workflow
-1. Extract requirements from conversation history
-2. Structure into PRD format: problem statement, target users, requirements (must/should/could), out of scope
-3. Create as GitHub issue with `gh issue create`
-4. Add triage label for prioritisation
+## Steps
 
-## PRD Structure
-- **Problem** — what problem does this solve?
-- **Target users** — who benefits?
-- **Requirements** — must have / should have / could have
-- **Out of scope** — explicitly what's NOT included
-- **Success metrics** — how will we know it works?
-
-## Anti-patterns
-- Writing PRD before understanding the problem
-- Requirements that aren't testable ("fast" vs "loads in <200ms")
-- Gold-plating — every feature is "must have"
+1. Extract requirements from conversation context
+2. Structure into formal PRD format
+3. Surface open questions to user
+4. Publish as GitHub issue via `gh issue create`
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → oh-issue (break PRD into actionable issues) |
-| fail | → oh-grill (stress-test unclear requirements) |
-| blocker | → surface to user |
+| pass | → oh-issue |
+| fail | → oh-grill |
+| blocker | → surface |

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

@@ -0,0 +1,122 @@
+# oh-refactor — Deep Reference
+
+## Golden Rules
+
+1. **Behavior preserved** — changes structure only. Changing behavior = feature, not refactor.
+2. **Small steps** — one change, verify, commit, repeat. Never batch.
+3. **Tests essential** — no safety net = editing blind. Write characterization tests first.
+4. **One thing per commit** — never mix refactoring with feature work.
+5. **Commit between safe states** — commit before starting, after each green run.
+
+## When NOT to Refactor
+- Code that works and will never change
+- Critical production code without tests (add tests first)
+- Tight deadline with no test safety net
+- "Just because" — every refactor needs a clear purpose
+
+## Workflow
+
+### Phase 1: Prepare
+Check test coverage (thin → write characterization tests). Commit current state. Create feature branch.
+
+### Phase 2: Identify
+Find code smell. Understand what code does. Plan smallest fix. If behavior unclear → delegate to oh-investigate.
+
+### Phase 3: Refactor (small steps)
+One change → run tests → commit → repeat until smell is gone.
+
+### Phase 4: Verify
+All tests pass. Manual smoke test if coverage missing. Performance unchanged or better. Diff shows structural changes only.
+
+### Phase 5: Clean Up
+Remove commented-out code, stale imports, dead paths. Update docs only if semantics changed. Final commit.
+
+## Common Code Smells & Fixes (top 6)
+
+### 1. Long Method
+```diff
+- async function processOrder(orderId) {
+-   // 50 lines: fetch  // 30 lines: validate
+-   // 40 lines: pricing // 30 lines: inventory
+-   // 20 lines: shipment // 30 lines: notifications
+- }
++ async function processOrder(orderId) {
++   const order = await fetchOrder(orderId);
++   validateOrder(order);
++   const pricing = calculatePricing(order);
++   const shipment = await createShipment(order);
++   await sendNotifications(order, pricing, shipment);
++   return { order, pricing, shipment };
++ }
+```
+
+### 2. Guard Clauses (Arrow Code)
+```diff
+- if (order) { if (order.user) { if (order.total > 0) { return processOrder(order); }}}
++ if (!order) return { error: 'No order' };
++ if (!order.user) return { error: 'No user' };
++ if (order.total <= 0) return { error: 'Invalid total' };
++ return processOrder(order);
+```
+
+### 3. Duplicated Code
+```diff
+- function calculateUserDiscount(user) { if (user.membership === 'gold') return user.total * 0.2; }
+- function calculateOrderDiscount(order) { if (order.user.membership === 'gold') return order.total * 0.2; }
++ function getDiscountRate(membership) { return { gold: 0.2, silver: 0.1 }[membership] || 0; }
+```
+
+### 4. Magic Numbers → Constants
+```diff
+- if (user.status === 2) { }
+- const discount = total * 0.15;
++ const UserStatus = { ACTIVE: 1, INACTIVE: 2 } as const;
++ const DISCOUNT_RATES = { PREMIUM: 0.15, VIP: 0.2 } as const;
+```
+
+### 5. Primitive Obsession
+```diff
+- function sendEmail(to, subject, body) { }
+- sendEmail('user@example.com', 'Hello', '...');
++ class Email {
++   private constructor(public readonly value: string) {
++     if (!Email.isValid(value)) throw new Error('Invalid email');
++   }
++   static create(v: string) { return new Email(v); }
++   static isValid(e: string) { return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e); }
++ }
+```
+
+### 6. Feature Envy
+```diff
+- class Order { calculateDiscount(user) { if (user.membershipLevel === 'gold') return this.total * 0.2; } }
++ class User { getDiscountRate(orderTotal) { const rates = { gold: 0.2, silver: 0.1 }; return rates[this.membershipLevel] || 0; } }
+```
+
+## Common Operations Reference
+
+| Operation | What it does |
+|-----------|-------------|
+| Extract Method | Turn fragment into named function |
+| Extract Class | Move related behavior to new class |
+| Rename Method/Variable | Improve clarity |
+| Introduce Parameter Object | Group related params |
+| Guard Clauses | Early returns flatten nesting |
+| Replace Magic Number | Named constants for literals |
+| Consolidate Conditional | Combine duplicate conditions |
+
+## Checklist
+
+- [ ] Functions small (< 50 lines), single-purpose
+- [ ] No duplicated code
+- [ ] Descriptive names, no magic values
+- [ ] No dead code, stale imports, commented-out code
+- [ ] Clear module boundaries, no circular deps
+- [ ] Types for all public APIs, no `any` without justification
+- [ ] All tests pass, edge cases covered
+
+## Anti-patterns
+- Refactoring without tests (behavior preservation is unverifiable)
+- Mixing behavior changes with refactoring
+- "While I'm here" scope creep
+- Large batch refactors (commit between safe states)