openhermes 4.1.0 → 4.9.2

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

@@ -1,154 +1,27 @@
 ---
 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"
-  - "architecture"
-  - "design this feature"
-  - "brainstorm"
-  - "autoplan"
-  - "strategy"
-  - "scope this"
+route:
+  pass: oh-grill
+  fail: oh-planner
+  blocker: surface
 ---
 
 # oh-planner
 
-The ALL-arounder planner. Merges brainstorm, architecture analysis, strategy review, and automatic plan review into one skill. Produces `.opencode/plan.md` that oh-builder consumes.
+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 `.opencode/plan.md` (per-project, overwritten each session) with this structure (matching the global AGENTS.md schema).
-
-**Then save a copy** to `%USERPROFILE%/.config/opencode/task/<project-name>-plan-<nnn>.md` (global, incrementing, persistent) per AGENTS.md persistent plan rules.
-
-```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: .opencode/plan.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>
-
-## Blockers
-
-- None
-
-## Validation
-
-- [ ] Static checks
-- [ ] Unit tests
-- [ ] Manual verification
-
-## Decisions
-
-- <decision> — <rationale>
-
-## Notes
-
-<anything else>
-```
-
-## 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
 
@@ -156,4 +29,4 @@ Objective: <short objective>
 |---------|-------|
 | 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,35 +1,28 @@
 ---
 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
+route:
+  pass: oh-issue
+  fail: oh-grill
+  blocker: surface
 ---
 
 # 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)

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

@@ -0,0 +1,33 @@
+---
+name: oh-refactor
+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
+route:
+  pass: oh-gauntlet
+  fail:
+    - oh-planner
+    - oh-investigate
+    - oh-builder
+  blocker: surface
+---
+
+# oh-refactor
+
+Improve code structure without changing external behavior.
+
+## Steps
+
+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-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,33 +1,30 @@
 ---
 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
+route:
+  pass: oh-planner
+  fail: oh-handoff
+  blocker: surface
 ---
 
 # 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