openhermes 4.1.0 → 4.3.0

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

@@ -4,12 +4,19 @@ description: "Two-axis code and design review: Standards (conformance) + Spec (f
 tier: 3
 benefits-from: [oh-expert]
 triggers:
-  - "review"
-  - "code review"
-  - "review since"
-  - "review changes"
+  - "code review please"
+  - "review the code"
+  - "review the PR"
+  - "review changes since"
   - "pr review"
   - "design review"
+  - "review this code"
+route:
+  pass:
+    - oh-gauntlet
+    - oh-ship
+  fail: oh-builder
+  blocker: surface
 ---
 
 # oh-review

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

@@ -11,6 +11,10 @@ triggers:
   - "pentest"
   - "security review"
   - "cso"
+route:
+  pass: surface
+  fail: oh-investigate
+  blocker: surface
 ---
 
 # oh-security

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

@@ -1,6 +1,16 @@
 ---
 name: oh-ship
 description: "Deploy and PR pipeline — test, bump, changelog, PR, deploy, verify"
+tier: 4
+triggers:
+  - "ship this"
+  - "create a PR"
+  - "version bump"
+  - "publish"
+route:
+  pass: oh-retro
+  fail: oh-expert
+  blocker: surface
 ---
 
 # oh-ship

package/harness/skills/oh-skill-craft/SKILL.md

@@ -10,6 +10,10 @@ triggers:
   - "skill-craft"
   - "meta-skill"
   - "add a capability"
+route:
+  pass: oh-skills-link
+  fail: oh-expert
+  blocker: surface
 ---
 
 # oh-skill-craft
@@ -83,6 +87,10 @@ The description is the only thing the agent sees when deciding which skill to lo
 
 Scripts save tokens and improve reliability vs generated code.
 
+## Output Location
+
+Skills created with oh-skill-craft should be written to `~/.config/opencode/skills/` (or `~/.agents/skills/` if the user prefers). Built-in skills live in the package `harness/skills/` and get replaced on npm update. User-written skills in `~/.config/opencode/skills/` survive updates and are auto-discovered on every session. On name conflict with a built-in skill, the user version wins.
+
 ## When to Split Files
 - SKILL.md exceeds 100 lines
 - Content has distinct domains
@@ -98,10 +106,90 @@ Scripts save tokens and improve reliability vs generated code.
 - [ ] Anti-patterns documented
 - [ ] Tests still pass after adding (`npm test`)
 
+## Eval-Driven Iteration
+
+After writing the initial skill draft, iterate using test cases and evidence rather than guessing.
+
+### 1. Create Test Cases
+
+Come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Save to `evals/evals.json`:
+
+```json
+{
+  "skill_name": "oh-<name>",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "User's realistic task prompt",
+      "expected_output": "Description of expected result",
+      "files": []
+    }
+  ]
+}
+```
+
+Good test prompts are substantive multi-step tasks — not simple queries like "read this file." The model can handle simple tasks without a skill. Complex, multi-step, or specialized queries reveal whether the skill is pulling its weight.
+
+### 2. Spawn Runs
+
+For each test case, spawn two subagents in parallel:
+- **With-skill run** — load the skill, execute the task
+- **Baseline run** — same prompt without the skill (for new skills) or with the previous version (for improvements)
+
+Save outputs to `iteration-<N>/eval-<ID>/with_skill/outputs/` and `iteration-<N>/eval-<ID>/without_skill/outputs/`.
+
+### 3. Draft Assertions
+
+While runs execute, draft objectively verifiable assertions for each test case. Good assertions have descriptive names and can be checked programmatically where possible. Update `evals/evals.json` with the assertions.
+
+### 4. Grade and Compare
+
+Grade runs against assertions. Aggregate results into pass rates, timing, and token usage. Look for:
+- Assertions that always pass regardless of skill (non-discriminating — remove them)
+- High-variance evals (possibly flaky tests)
+- Time/token tradeoffs between skill and baseline
+
+### 5. Improve
+
+Based on results, revise the skill. Generalize from specific failures rather than overfitting to the test cases. The goal is a skill that works across a million different prompts, not just 2-3 examples. Keep instructions lean — remove anything not pulling its weight.
+
+### 6. Loop
+
+Rerun all test cases into a new iteration directory. Repeat until:
+- User says they're happy
+- All feedback is positive
+- No meaningful progress between iterations
+
+## Description Optimization
+
+The description field in frontmatter is the primary mechanism for skill triggering. After the skill is solid, optimize the description for accuracy.
+
+### Trigger Eval Queries
+
+Create 20 eval queries — a mix of should-trigger and should-not-trigger cases:
+
+```json
+[
+  {"query": "realistic user prompt that should trigger", "should_trigger": true},
+  {"query": "near-miss prompt that should NOT trigger", "should_trigger": false}
+]
+```
+
+Key principles:
+- **Should-trigger** (8-10): different phrasings of the same intent — formal, casual. Include edge cases and contexts where this skill competes with another but should win.
+- **Should-not-trigger** (8-10): near-misses that share keywords but need a different skill. Avoid obviously irrelevant queries — the hard cases are the adjacent ones.
+
+Queries must be realistic — what a user would actually type, with concrete details, not abstract descriptions.
+
+### Run Optimization
+
+Iterate the description: test current, propose improvements based on failures, re-test. Select the description that scores best on held-out test data. Apply the winner to the skill's frontmatter.
+
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
 | pass | → oh-skills-link (verify skill discovery) |
+| iteration data available | → oh-learn (extract patterns from eval results) |
 | fail | → oh-expert (diagnose skill creation issues) |
 | blocker | → surface to user |

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

@@ -1,6 +1,15 @@
 ---
 name: oh-skills-link
 description: "Verify that OpenCode can discover the package-local skills directory"
+tier: 2
+triggers:
+  - "verify skills"
+  - "check skill discovery"
+  - "link skills"
+route:
+  pass: surface
+  fail: oh-skill-craft
+  blocker: surface
 ---
 
 # oh-skills-link

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

@@ -1,6 +1,15 @@
 ---
 name: oh-skills-list
 description: "List all available oh-* skills with descriptions"
+tier: 2
+triggers:
+  - "list skills"
+  - "show skills"
+  - "what skills"
+route:
+  pass: done
+  fail: surface
+  blocker: surface
 ---
 
 # oh-skills-list

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

@@ -1,6 +1,17 @@
 ---
 name: oh-triage
 description: "Issue triage state machine — classify, prioritise, assign"
+tier: 2
+triggers:
+  - "triage this issue"
+  - "classify this issue"
+  - "triage the backlog"
+route:
+  pass:
+    - oh-issue
+    - oh-handoff
+  fail: oh-expert
+  blocker: surface
 ---
 
 # oh-triage

package/lib/harness-resolver.ts

@@ -8,10 +8,10 @@ import { fileURLToPath } from "node:url"
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const PKG_DIR = path.resolve(__dirname, "..")
 
-const REQUIRED_HARNESS_FILES: ReadonlyArray<[string, string, string]> = [
+const REQUIRED_HARNESS_FILES: ReadonlyArray<readonly string[]> = [
   ["codex", "CONSTITUTION.md"],
   ["instructions", "RUNTIME.md"],
-  ["skills", "oh-plan", "SKILL.md"],
+  ["skills", "oh-planner", "SKILL.md"],
 ]
 
 function ancestorDirs(start: string, limit = 6): string[] {

package/lib/logger.ts

@@ -10,7 +10,13 @@ export interface Logger {
 }
 
 const LEVELS: Record<string, number> = { debug: 0, info: 1, warn: 2, error: 3 }
-const CURRENT_LEVEL = LEVELS[process.env.OPENCODE_LOG_LEVEL?.trim().toLowerCase()] ?? (process.env.OPENHERMES_LOG_LEVEL?.trim().toLowerCase() === "debug" ? LEVELS.debug : LEVELS.warn)
+
+function resolveLevel(levelName: string | undefined): number | undefined {
+  if (!levelName) return undefined
+  return LEVELS[levelName as keyof typeof LEVELS]
+}
+
+const CURRENT_LEVEL = resolveLevel(process.env.OPENCODE_LOG_LEVEL?.trim().toLowerCase()) ?? (process.env.OPENHERMES_LOG_LEVEL?.trim().toLowerCase() === "debug" ? LEVELS.debug : LEVELS.warn)
 
 const LOG_DIR = path.join(os.homedir(), ".local", "share", "opencode", "log")
 const LOG_FILE = path.join(LOG_DIR, "openhermes.log")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openhermes",
-  "version": "4.1.0",
-  "description": "OpenCode-native skills, commands, and rules orchestration for OpenHermes.",
+  "version": "4.3.0",
+  "description": "OpenCode-native orchestration for packaged skills, commands, and agents.",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -48,5 +48,8 @@
     "url": "https://github.com/nathwn12/openhermes/issues"
   },
   "homepage": "https://github.com/nathwn12/openhermes#readme",
-  "author": "nathwn12"
+  "author": "nathwn12",
+  "devDependencies": {
+    "@types/node": "^25.8.0"
+  }
 }