openhermes 4.0.1 → 4.3.0

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

@@ -1,28 +1,101 @@
 ---
 name: oh-learn
-description: "Review, search, prune, and export session learnings"
+description: "Extract, evolve, and promote session learnings as instincts. Review, search, prune, export."
+tier: 2
+triggers:
+  - "learn from session"
+  - "extract patterns"
+  - "run oh-learn"
+route:
+  pass: done
+  fail: surface
+  blocker: surface
 ---
 
 # oh-learn
 
+Learning engine for the harness. Distills patterns from sessions into **instincts** (trigger-action pairs with confidence), clusters them into skill candidates, and graduates high-signal patterns from project to global scope.
+
+## Instinct Data Model
+
+Every learning stored as one JSONL line in `~/.local/share/opencode/openhermes/plans/<project-name>-instincts.jsonl`:
+
+```json
+{ "trigger": "situation pattern", "action": "recommended response", "confidence": 0.5, "applications": 1, "successes": 1, "category": "coding", "source": "oh-learn:extract", "ts": "2026-05-15T12:00:00Z" }
+```
+
+**Rules:**
+- **Trigger** — specific, matchable situation. *Not* general advice.
+- **Action** — executable response. *Not* a belief.
+- **Confidence** — starts at 0.5, increments +0.05 per successful application, decays -0.02 per day without use.
+- **Category** — one of: `coding`, `testing`, `security`, `git`, `planning`, `orchestration`, `debugging`, `ux`.
+
 ## When to Use
-To review what the agent has learned across sessions, search for specific patterns, prune stale knowledge, or export learnings for documentation.
 
-## Workflow
-1. **Review** — show recent learnings with context
-2. **Search** — find learnings matching specific topics or patterns
-3. **Prune** — remove stale, redundant, or superseded learnings
-4. **Export** — format learnings for documentation or sharing
+After completing a significant piece of work, at session handoff, or when you notice the same pattern repeat 2+ times in one session. Also on explicit user request.
+
+## Workflows
+
+### Extract
+Mine the current session for reusable patterns.
+
+1. Scan recent conversation + code changes for repeated decision patterns
+2. For each distinct pattern write an instinct: trigger, action, confidence=0.5, category
+3. Read existing `~/.local/share/opencode/openhermes/plans/<project-name>-instincts.jsonl`, check for near-duplicate triggers
+4. If duplicate found: merge — `confidence = max(existing, 0.8 × new)`, increment applications
+5. If new: append line to file
+
+**Good instinct:** trigger=`"tsc --noEmit shows 10+ errors after batch edit"`, action=`"Fix errors one at a time, re-running tsc after each, rather than batch-fixing"`, category=`"debugging"`
+
+**Bad instinct:** `"Write clean code"` — too vague to trigger on.
+
+### Evolve
+Cluster related instincts into skill/command/agent candidates.
+
+1. Read all instincts from `~/.local/share/opencode/openhermes/plans/<project-name>-instincts.jsonl`
+2. Group by `category`, then by trigger topic similarity
+3. **If cluster ≥ 5 instincts AND avg confidence ≥ 0.7** → generate `oh-skill-craft` spec for a new skill
+4. **If cluster 3-4 instincts with confidence ≥ 0.8** → suggest update to existing skill
+5. Output candidate summary with trigger list and extracted core pattern
+
+### Promote
+Graduate high-confidence instincts from project to global scope.
+
+1. Scan `~/.local/share/opencode/openhermes/plans/<project-name>-instincts.jsonl` for instincts with `confidence >= 0.85 AND applications >= 10`
+2. Filter out project-specific patterns (reference paths, local APIs, domain terms)
+3. Append filtered candidates to `%USERPROFILE%\.config\opencode\instincts.jsonl` (global)
+4. Tag promoted instincts with `"promoted": true` in project file
+5. Report: "Promoted N instincts to global scope"
+
+### Review
+Show instinct summary: total count, confidence distribution, category breakdown, recently promoted.
+
+### Search
+Find instincts by topic, trigger fragment, category, or confidence range.
+
+### Prune
+Remove instincts stale for 30+ days with confidence < 0.3, or superseded by a higher-confidence instinct covering the same trigger.
+
+### Export
+Serialize instincts to portable JSON for sharing across projects or teams:
+
+```json
+{ "version": 1, "exported": "2026-05-15T12:00:00Z", "instincts": [...] }
+```
 
 ## Anti-patterns
+
 - Hoarding every observation (most things aren't learnings)
 - Never pruning (stale knowledge is worse than no knowledge)
 - Storing what, not why (context-less facts are forgettable)
+- Over-promoting: not every pattern is globally useful
+- Extracting without applying: instincts that never trigger are noise
+- Ignoring confidence: treating all instincts as equally reliable
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [done — read-only report] |
+| pass | → [done — report summary] |
 | fail | → [surface gaps to user] |
 | blocker | → surface to user |

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

@@ -4,37 +4,53 @@ description: "Full build loop: plan → build → verify → loop until done or
 tier: 4
 benefits-from: [oh-planner, oh-builder, oh-expert]
 triggers:
-  - "manifest"
-  - "full build"
+  - "run the full build"
+  - "full build pipeline"
   - "build loop"
   - "build until done"
-  - "orchestrate"
-  - "pipeline"
+  - "orchestrate this build"
+  - "pipeline from plan"
   - "run the plan"
+  - "manifest this"
+route:
+  pass: oh-planner
+  fail: oh-expert
+  blocker: surface
 ---
 
 # oh-manifest
 
-Full build orchestration loop. Runs planner → builder → verify → repeat until done or a blocker is surfaced. Uses gstack decision principles to auto-resolve intermediate questions. Only interrupts the user for genuine blockers.
+Full build orchestration loop. Runs pre-flight checks → planner → builder → verify → repeat until done or a blocker is surfaced. Uses decision principles to auto-resolve intermediate questions. Only interrupts the user for genuine blockers.
 
 ## Pipeline
 
+### Phase 0: Pre-Flight
+
+Before any work begins, ALL of these MUST pass:
+
+- ☐ **Quality baseline** — existing tests pass (if any). Capture output for before/after comparison.
+- ☐ **Rollback path** — clean `git stash` or a committed state you can return to.
+- ☐ **Branch isolation** — confirm you are on a working branch, not main/master.
+- ☐ **Scope documented** — plan or task description exists and is unambiguous.
+
+If any check fails → **STOP**. Report which check failed and why. Do not proceed to Phase 1 until the blocker is resolved.
+
 ### Step 1: Plan
-- If `.opencode/plan.md` exists, load and verify it is current
+- If a plan file (`~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md`) exists, load and verify it is current
 - If not, run `oh-planner` (Mode A, B, or C depending on context)
 - Auto-decide minor scope decisions using decision principles
 - Surface only: premises that need human judgment, or plan/alternative conflicts
 
 ### Step 2: Build
-- For each phase in plan.md, run `oh-builder` (Mode D: From Plan)
+- For each phase in the plan file, run `oh-builder` (Mode D: From Plan)
 - Implements phases in dependency order
 - Parallelizable phases may be delegated to sub-agents
 - Auto-decide implementation choices using decision principles
 
 ### Step 3: Verify
-- Check each phase against its verification criteria in plan.md
+- Check each phase against its verification criteria in the plan file
 - Run tests if they exist
-- If phase passes: mark complete in plan.md, proceed to next
+- If phase passes: mark complete in plan file, proceed to next
 - If phase fails: diagnose (use oh-expert self-diagnosis), fix, re-verify
 - If fix is impossible within scope: surface blocker
 
@@ -43,6 +59,32 @@ Full build orchestration loop. Runs planner → builder → verify → repeat un
 - Phase failed and cannot be fixed → BLOCKER (surface to user with context)
 - Phase passed but new work discovered → add to plan, continue loop
 
+## Loop Patterns
+
+Select a pattern based on the nature of the work:
+
+| Pattern | Use When | Behavior |
+|---------|----------|----------|
+| **sequential** | Normal feature work | One phase at a time, verify each before next |
+| **continuous-pr** | Multi-step refactors | Each phase is its own PR — commit, push, PR per phase |
+| **infinite** | Watch mode, CI repair | Continue until external stop signal or budget exhausted |
+| **rfc-dag** | Complex dependency chains | Resolve phase ordering by DAG; parallelize independent branches |
+
+Default is **sequential**. Switch patterns only when the work structure demands it.
+
+## Escalation Triggers
+
+These conditions cause the loop to **pause** and surface to the user:
+
+| Trigger | Condition | Action |
+|---------|-----------|--------|
+| **Stall** | 2 consecutive checkpoints with zero measurable progress | Pause. Report what was attempted, what blocked. |
+| **Retry storm** | Same error message 3+ times in the loop | Stop retrying. Surface error with attempted fixes. |
+| **Cost drift** | Cumulative changes exceed scope documented in pre-flight | Pause. Show diff between planned and actual scope. |
+| **Quality regression** | Verify phase scores lower than pre-flight baseline | Pause. Report degraded metrics. Do not push through. |
+
+These are not optional suggestions. When a trigger fires, the loop **must** pause and report.
+
 ## Decision Principles
 
 Auto-resolve these without asking the user:
@@ -69,11 +111,13 @@ When a blocker is encountered:
 4. **Wait for user decision** before continuing
 
 ## Anti-patterns
+- Skipping pre-flight (every loop needs a baseline and a rollback plan)
 - Auto-deciding premises (fundamental assumptions need user input)
 - Pushing through blockers (surface immediately, don't try 5 workarounds silently)
 - Skipping verification (verify every phase, not just the final result)
-- Parallelizing dependent phases (respect the dependency order in plan.md)
-- Forgetting to update plan.md with completion status
+- Parallelizing dependent phases (respect the dependency order in the plan file)
+- Forgetting to update the plan file with completion status
+- Ignoring escalation triggers (stall means pause, not try harder)
 
 ## Routing
 

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

@@ -4,15 +4,22 @@ description: "Multi-lens plan review: 4 perspectives in one skill. Choose Engine
 tier: 3
 benefits-from: [oh-planner, oh-expert]
 triggers:
-  - "plan review"
-  - "review the plan"
-  - "architecture review"
-  - "design review"
-  - "ux review"
-  - "dx review"
+  - "review this plan"
+  - "review the plan file"
+  - "architecture review of"
+  - "design review the plan"
+  - "ux review this plan"
+  - "dx review the plan"
   - "strategy review"
-  - "eng review"
+  - "engineering review"
   - "ceo review"
+  - "review plan from"
+route:
+  pass:
+    - oh-grill
+    - oh-manifest
+  fail: oh-planner
+  blocker: surface
 ---
 
 # oh-plan-review
@@ -110,7 +117,7 @@ Product/CEO review with 4 scope modes.
 
 ## Output
 
-After each lens, the plan file (`/.opencode/plan.md`) is updated with findings and decisions. The user reviews and accepts changes interactively.
+After each lens, the plan file (`~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md`) is updated with findings and decisions. The user reviews and accepts changes interactively.
 
 ## Rules
 

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

@@ -6,17 +6,23 @@ benefits-from: [oh-expert, oh-grill]
 triggers:
   - "plan this"
   - "how should I build"
-  - "architecture"
+  - "plan the architecture for"
   - "design this feature"
   - "brainstorm"
   - "autoplan"
-  - "strategy"
-  - "scope this"
+  - "strategy for this feature"
+  - "scope this feature"
+  - "create a plan for"
+  - "whats the plan for"
+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.
+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/`.
 
 ## Entry Modes
 
@@ -80,9 +86,7 @@ Never auto-decide: premises (need human judgment) or cases where both the plan a
 
 ## Plan Artifact
 
-Output goes in `.opencode/plan.md` with this structure (matching the global AGENTS.md schema).
-
-**Then save a copy** to `%USERPROFILE%/.config/opencode/task/<project-name>-plan-<nnn>.md` per AGENTS.md persistent plan rules.
+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>
@@ -93,7 +97,7 @@ Status: active
 Created: <local-date-time>
 Updated: <local-date-time>
 Project Path: <absolute-project-path>
-Plan Path: .opencode/plan.md
+Plan Path: ~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md
 Objective: <short objective>
 
 ## Current State
@@ -123,6 +127,10 @@ Objective: <short objective>
 
 - <what's done>
 
+## Work Log
+
+<timestamped entries for subagent handoffs>
+
 ## Blockers
 
 - None
@@ -142,6 +150,8 @@ Objective: <short objective>
 <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

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

@@ -1,6 +1,15 @@
 ---
 name: oh-prd
 description: "Turn conversation context into a PRD and publish as GitHub issue"
+tier: 2
+triggers:
+  - "write a prd"
+  - "product requirements"
+  - "prd for"
+route:
+  pass: oh-issue
+  fail: oh-grill
+  blocker: surface
 ---
 
 # oh-prd