openhermes 4.3.0 → 4.9.2

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

@@ -1,14 +1,7 @@
 ---
 name: oh-init
-description: "Initialize project for OpenHermes: wire AGENTS.md, configure domain docs, issue tracker, and triage labels. Does NOT create .opencode/ directory."
+description: "Sets up AGENTS.md, domain docs, issue tracker, and triage labels"
 tier: 2
-triggers:
-  - "init this project for oh"
-  - "setup project for openhermes"
-  - "initialize openhermes setup"
-  - "onboard this project"
-  - "scaffold project setup"
-  - "oh takeover this project"
 route:
   pass: done
   fail: oh-init
@@ -17,129 +10,22 @@ route:
 
 # oh-init
 
-Per-repo setup for OpenHermes-assisted development. Run once per repo. Wires AGENTS.md, configures domain docs, issue tracker, and triage labels. Does NOT create a `.opencode/` directory — plan files go to `~/.local/share/opencode/openhermes/plans/`.
+Wire AGENTS.md, domain docs, issue tracker, and triage labels for a new OpenHermes project.
 
-Complements OpenCode's built-in `/init` command (which creates `AGENTS.md` with project build/test/architecture notes). Run oh-init after or instead — they serve different layers.
+## Steps
 
-## Process
-
-### Phase 0: Check Existing State
-Before writing anything, detect what already exists:
-
-- ☐ `AGENTS.md` exists? (If yes, was it created by OpenCode `/init` or manually?)
-- ☐ `opencode.json` / `opencode.jsonc` present?
-- ☐ Canonical plan files (`~/.local/share/opencode/openhermes/plans/<project-name>-plan-*.md`)?
-- ☐ `CONTEXT.md` exists?
-- ☐ `docs/agents/` directory exists?
-
-Report findings. If everything exists, offer to skip or verify and exit.
-
-### Phase 1: AGENTS.md Wiring
-
-Check if AGENTS.md exists:
-
-**If AGENTS.md does not exist:**
-Create it with OpenHermes orchestrator header + prompts for project info:
-
-```markdown
-# <project-name>
-
-OpenHermes is the primary orchestrator. All routing, planning, and delegation flows through oh-* skills.
-
-## Project Context
-
-- **Language**: <fill in>
-- **Package manager**: <fill in>
-- **Build command**: <fill in>
-- **Test command**: <fill in>
-- **Lint/type check**: <fill in>
-
-## Key Directives
-
-- Plan first. Write to `~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md` before multi-file changes.
-- **OpenHermes never executes tasks directly. It talks/reports to the user and delegates everything to sub-agents.**
-- Verify before claiming success. Read files, run commands, confirm output.
-- Never write code, run tests, or edit files in the main context — always delegate.
-- Use oh-* skills on demand. Load via OpenCode's skill tool when relevant.
-- Plan file is self-contained (Tasks, Completed, Work Log sections).
-```
-
-Then ask the user to fill in the Project Context fields. Offer to auto-detect from package manifests.
-
-**If AGENTS.md exists** (e.g., created by OpenCode `/init`):
-Append an `## OpenHermes Orchestrator` section to the end:
-
-```markdown
-## OpenHermes Orchestrator
-
-OpenHermes is the primary orchestrator for this session.
-
-- **Orchestrator**: OpenHermes — hub-and-spoke routing through oh-* skills
-- **Plan**: `~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md` — always check before starting work
-- **Never execute**: OpenHermes talks/reports to the user and delegates everything to sub-agents
-- **Verify before claim**: read files, run commands, confirm output
-```
-
-### Phase 2: Issue Tracker
-Detect the git hosting platform:
-- **GitHub** — `gh` CLI
-- **GitLab** — `glab` CLI
-- **Local markdown** — files under `.scratch/<feature>/`
-- **Other** — freeform workflow description
-
-Confirm with the user. Write the result to `docs/agents/issue-tracker.md`.
-
-### Phase 3: Triage Labels
-The `triage` skill uses these label strings to move issues through a state machine:
-- `needs-triage` — maintainer needs to evaluate
-- `needs-info` — waiting on reporter
-- `ready-for-agent` — fully specified, AFK-ready
-- `ready-for-human` — needs human implementation
-- `wontfix` — will not be actioned
-
-If the repo already has different label names, map them. Write to `docs/agents/triage-labels.md`.
-
-### Phase 4: Domain Docs
-Configure how the project organizes domain language:
-- **Single-context** — one `CONTEXT.md` + `docs/adr/` at repo root
-- **Multi-context** — `CONTEXT-MAP.md` pointing to per-context files
-
-Scaffold `CONTEXT.md` with project name, domain description, and placeholder glossary terms. Create `docs/adr/` directory with ADR template.
-
-Write to `docs/agents/domain.md`.
-
-### Phase 5: Agent Skills Block
-Add a `## Agent skills` section to `AGENTS.md` (or `CLAUDE.md` if it exists):
-
-```markdown
-## Agent skills
-
-### Issue tracker
-<summary>. See docs/agents/issue-tracker.md.
-
-### Triage labels
-<summary>. See docs/agents/triage-labels.md.
-
-### Domain docs
-<summary>. See docs/agents/domain.md.
-```
-
-### Phase 6: Decision Record
-Record: "oh-init completed for project <name> on <date>."
-
-## Anti-patterns
-- Running init without understanding the project domain
-- Scaffolding CONTEXT.md without populating any terms
-- Creating ADR directory but never writing ADRs
-- Creating both AGENTS.md and CLAUDE.md — edit the one that exists
-- Overwriting an existing AGENTS.md created by OpenCode `/init` (append instead)
-- Creating `.opencode/` directory — plan files go to OpenCode's canonical storage, not a hidden project dir
-- Empty instinct file never getting populated (run oh-learn extract periodically)
+1. Check existing state (AGENTS.md, opencode.json, plan files, CONTEXT.md, docs/agents/)
+2. Create AGENTS.md with OH orchestrator header or append OH section to existing
+3. Detect issue tracker platform, confirm with user, write to docs/agents/issue-tracker.md
+4. Define triage labels (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix), write to docs/agents/triage-labels.md
+5. Scaffold CONTEXT.md with project name, domain, glossary placeholders; create docs/adr/ with ADR template; write to docs/agents/domain.md
+6. Append Agent skills block referencing tracker, triage, and domain docs
+7. Record decision artifact
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [done — one-time project setup] |
-| fail | → [retry with user corrections] |
-| blocker | → surface to user |
+| pass | → done |
+| fail | → oh-init |
+| blocker | → surface |

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

@@ -0,0 +1,171 @@
+# oh-investigate — Deep Reference
+
+## The Iron Law
+
+> **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Surface fixes compound into technical debt.**
+
+If you haven't completed root cause investigation, you cannot propose fixes. Violating this process is violating the spirit of debugging.
+
+## Phase 0 — Build a feedback loop
+
+**This is the actual skill. Everything else is mechanical.**
+
+A fast, deterministic, agent-runnable pass/fail signal = you find the cause. Without one, staring at code won't save you.
+
+### Ways to construct a loop (try in order)
+1. Failing test at the bug's seam
+2. Curl/HTTP script against dev server
+3. CLI invocation + fixture, diff stdout
+4. Headless browser — assert on DOM/console/network
+5. Replay captured trace in isolation
+6. Throwaway harness — minimal subset exercising the bug path
+7. Property/fuzz loop — 1000 random inputs
+8. Bisection harness — `git bisect run`-able
+9. Differential loop — old vs new version output diff
+10. HITL script — drive human with structured loop
+
+**Sharpen the loop:** Faster? Sharper signal (specific symptom, not "didn't crash")? More deterministic (pin time, seed RNG, isolate FS)? A 2s deterministic loop is a superpower.
+
+**Non-deterministic:** Goal = higher reproduction rate. Loop 100×, parallelize, add stress. 50% flake is debuggable; 1% is not.
+
+**Cannot build a loop?** Stop. Say so. List what you tried. Do NOT hypothesise without a loop.
+
+## Workflow
+
+Complete each phase before proceeding. Each phase consumes the feedback loop built in Phase 0.
+
+### Phase 1 — Root Cause Investigation
+
+**Before attempting ANY fix:**
+
+1. **Reproduce** — Loop confirms the described failure. Exact steps? Every time?
+2. **Read Error Messages** — Read stack traces completely. Note line numbers and error codes.
+3. **Check Recent Changes** — Git diff, recent commits, new dependencies, env differences.
+4. **Minimise** — Strip unrelated code. Remove noise until only the failure path remains.
+5. **Gather Evidence** — One probe per hypothesis. Change one variable. Use unique debug prefixes.
+6. **Trace Data Flow** — If error is deep in call stack, trace backward.
+
+### Phase 2 — Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples** — Locate similar working code. What works that's analogous?
+2. **Compare Against References** — Read reference implementation completely. Don't skim.
+3. **Identify Differences** — List every difference between working and broken. Don't dismiss anything.
+4. **Understand Dependencies** — What components, config, or environment does this depend on?
+
+### Phase 3 — Hypothesis & Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis** — "I think X is root cause because Y." Be specific, not vague.
+2. **Test Minimally** — Smallest change to test hypothesis. One variable. Don't fix multiple things.
+3. **Verify** — Prediction held? → Phase 4. No → new hypothesis. DON'T stack more fixes.
+
+### Phase 4 — Implementation
+
+**Fix root cause, not symptom:**
+
+1. **Create Failing Test** — Simplest reproduction. Automated if possible. Must fail before fix.
+2. **Implement Single Fix** — Address root cause. ONE change. No "while I'm here" improvements.
+3. **Verify Fix** — Failing test passes? No other tests broken? Phase 0 loop confirms resolution?
+4. **Regression Test** — Verify existing behavior. No regression seam = architecture gap (flag it).
+5. **Document** — Log root cause + fix. State which hypothesis was correct. What was the trigger?
+
+## Root Cause Tracing
+
+Bugs manifest deep in call stacks. Fixing at the symptom treats the wrong layer. **Trace backward through the call chain to find the original trigger.**
+
+1. **Observe symptom** — Error at point of failure.
+2. **Find immediate cause** — What code directly produces this error?
+3. **What called this?** — Step one level up the call chain.
+4. **Keep tracing up** — What value was passed? Where from?
+5. **Find original trigger** — Root source of bad state. Fix here, not at symptom.
+
+**Stack trace instrumentation:**
+```
+const stack = new Error().stack;
+console.error('DEBUG <component>:', { directory, cwd, stack });
+```
+Use `console.error()` (logger may be suppressed in tests). Grep output. **Never fix just where the error appears** — trace back and add validation at each layer.
+
+## Multi-Component Diagnostics
+
+**In multi-component systems (CI → build → signing, API → service → database), add instrumentation at each boundary BEFORE proposing fixes:**
+
+- Log data entering and exiting each component
+- Verify environment/config propagation across layers
+- Check state at each layer
+
+Run once to gather evidence, identify the failing component, THEN investigate it.
+
+**Example (build pipeline):** Layer 1 (workflow → secrets?), Layer 2 (build → env vars?), Layer 3 (signing → keychain?), Layer 4 (actual signing). Reveals which layer fails in one pass.
+
+## Red Flags
+
+**If you catch yourself thinking any of these, STOP. Return to Phase 1.**
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" (when already tried 2+)
+- Each fix reveals new problem in different place
+- "Here are the main problems: [lists fixes without investigation]"
+- "Issue is simple, don't need the full process"
+
+**All of these mean: STOP. Return to investigation.**
+
+## 3+ Fix Failure Rule
+
+**After 3 failed fix attempts, STOP and question the architecture.**
+
+Three failed fixes signals an architectural problem:
+- Each fix reveals new shared state/coupling in a different place
+- Fixes require "massive refactoring" to implement
+- Each fix creates new symptoms elsewhere
+
+**Do not attempt Fix #4 without architectural discussion:**
+- Is this pattern fundamentally sound?
+- Are we sticking with it through inertia?
+- Should we refactor architecture vs. continue fixing symptoms?
+
+This is NOT a failed hypothesis — this is a wrong architecture.
+
+## Partner Signal Monitoring
+
+**When your human partner says these, they mean you're guessing, not debugging:**
+
+| Phrase | Meaning |
+|--------|---------|
+| "Is that happening?" | You assumed without verifying |
+| "Will it show us...?" | You skipped evidence gathering |
+| "Stop guessing" | You're proposing fixes without understanding |
+| "We're stuck?" | Your approach isn't working |
+
+**When you see any of these: STOP. Return to Phase 1.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple bugs have root causes too. Process is fast. |
+| "Emergency, no time for process" | Systematic is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves bug. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read fully. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Stop fixing. |
+
+## Anti-patterns
+
+- Fixing symptoms (same bug reappears)
+- Changing code without reproducing
+- Shotgun debugging (multiple changes hoping one sticks)
+- Not documenting root cause
+- Hypothesizing without a feedback loop

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

@@ -1,12 +1,7 @@
 ---
 name: oh-investigate
-description: "Systematic bug diagnosis with root cause investigation"
+description: "Use when debugging any bug, test failure, or unexpected behavior. Finds root cause systematically before attempting fixes."
 tier: 2
-triggers:
-  - "investigate this bug"
-  - "debug this"
-  - "why is this broken"
-  - "root cause"
 route:
   pass: oh-builder
   fail: oh-expert
@@ -15,70 +10,22 @@ route:
 
 # oh-investigate
 
-## When to Use
-When a bug is reported, a test fails, or unexpected behavior occurs. Use this before attempting any fix.
+Systematic bug diagnosis: build a feedback loop, trace root cause, fix with evidence.
 
-## Phase 0 — Build a feedback loop
+## Steps
 
-**This is the actual skill. Everything else is mechanical.**
-
-If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation are just consuming that signal. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
-
-### Ways to construct a feedback loop (try in this order)
-
-1. **Failing test** at whatever seam reaches the bug.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** — drive the UI, assert on DOM/console/network.
-5. **Replay a captured trace** — save a real payload/event log, replay it in isolation.
-6. **Throwaway harness** — minimal subset of the system exercising the bug code path with a single call.
-7. **Property / fuzz loop** — run 1000 random inputs, look for the failure mode.
-8. **Bisection harness** — automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop** — run same input through old-version vs new-version, diff outputs.
-10. **HITL script** — last resort. Drive a human with a structured loop.
-
-### Iterate on the loop itself
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows. A 50%-flake bug is debuggable; 1% is not.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Do **not** proceed to hypothesise without a loop.
-
-## Workflow (consumes the loop)
-
-1. **Reproduce** — run the loop, confirm the bug appears. The loop must match the user's described failure, not a different nearby failure.
-2. **Minimise** — strip away unrelated code until the minimal reproduction remains.
-3. **Hypothesise** — generate 3–5 ranked falsifiable hypotheses before testing any. Each must state a prediction: "If X is the cause, then changing Y will make the bug disappear".
-4. **Instrument** — one probe per hypothesis. Change one variable at a time. Tag every debug log with a unique prefix (e.g. `[DEBUG-a4f2]`) for easy cleanup.
-5. **Fix** — write the regression test at a correct seam first. Watch it fail. Apply the smallest correct change. Watch it pass. Re-run the Phase 0 loop against the original scenario.
-6. **Regression test** — verify fix doesn't break existing behavior. If no correct seam exists for a regression test, that itself is a finding — flag the architecture gap.
-7. **Document** — log the root cause and fix in the handoff, issue, or relevant docs. State which hypothesis was correct so the next debugger learns.
-
-## Iron Law
-No fixes without root cause. Surface-level fixes compound into technical debt.
-
-## Anti-patterns
-- Fixing symptoms instead of causes (the same bug reappears next week)
-- Changing code without reproducing the bug first
-- "Shotgun" debugging — changing multiple things hoping one sticks
-- Not documenting root cause for future reference
-- Proceeding to hypothesise without a feedback loop
+1. Build a feedback loop — failing test, curl, CLI, headless browser, or throwaway harness. Must be fast, deterministic, and agent-runnable.
+2. Apply the Iron Law — NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Surface fixes compound into technical debt.
+3. Reproduce and trace — confirm failure, read stack traces, check recent changes, minimise to failure path, gather evidence one probe per hypothesis.
+4. Trace backward — from symptom through call chain to original trigger. Instrument boundaries with debug logging.
+5. Find working pattern — locate similar working code, compare against references, list every difference.
+6. Form single hypothesis — "I think X is root cause because Y." Test with minimal change. One variable.
+7. Implement fix — create failing test first, apply one fix, verify resolution, regression test, document root cause.
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → oh-builder (implement the fix) |
-| fail | → oh-expert (deepen diagnosis) |
-| blocker | → surface to user |
+| pass | → oh-builder (fix) |
+| fail | → oh-expert (deepen) |
+| blocker | → surface |

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

@@ -0,0 +1,21 @@
+# oh-issue — Deep Reference
+
+## When to Use
+
+Plan/PRD needs breaking into actionable issues. Vertical tracer-bullet slices.
+
+Triggers: break into issues, create issues from plan, issue breakdown.
+
+## Issue Structure
+
+- **Title**: action-oriented ("Add user auth API")
+- **AC**: concrete, testable ("User signs up with email + password")
+- **Notes**: pointers for implementer
+- **Deps**: what must come first
+- **Labels**: type, priority, area
+
+## Anti-patterns
+
+- Horizontal slicing (no one ships "DB layer" alone)
+- Issues too large (3+ days) or too small (<1 hour)
+- Missing acceptance criteria

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

@@ -1,11 +1,7 @@
 ---
 name: oh-issue
-description: "Break a plan, spec, or PRD into independently-grabbable GitHub issues"
+description: "Break plans/PRDs into independently-grabbable GitHub issues"
 tier: 2
-triggers:
-  - "break into issues"
-  - "create issues from plan"
-  - "issue breakdown"
 route:
   pass: done
   fail: oh-planner
@@ -14,32 +10,20 @@ route:
 
 # oh-issue
 
-## When to Use
-When a plan exists and needs to be broken into actionable issues. Uses tracer-bullet vertical slices for independent work items.
+Break plans/PRDs into vertical-slice issues with acceptance criteria and dependencies.
 
-## Workflow
-1. Read the plan or PRD
-2. Identify vertical slices — self-contained features that ship independently
-3. Write each issue with: clear title, acceptance criteria, implementation notes, dependencies
-4. Use `gh issue create` to publish each issue
-5. Label and milestone each issue appropriately
+## Steps
 
-## Issue Structure
-- **Title**: action-oriented ("Add user authentication API")
-- **Acceptance criteria**: concrete, testable ("User can sign up with email + password")
-- **Implementation notes**: pointers for the implementer
-- **Dependencies**: what must be done first
-- **Labels**: type, priority, area
-
-## Anti-patterns
-- Horizontal slicing (DB layer / API layer / UI layer — no one ships a layer)
-- Issues too large (3+ days) or too small (< 1 hour)
-- Writing issues without acceptance criteria
+1. Read plan or PRD
+2. Identify vertical slices — self-contained, independently shippable
+3. Write each issue with title, acceptance criteria, implementation notes, and dependencies
+4. Publish issues via `gh issue create`
+5. Apply labels and milestone
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [done — issues published to tracker] |
-| fail | → oh-planner (re-spec unclear slices) |
-| blocker | → surface to user |
+| pass | → done |
+| fail | → oh-planner |
+| blocker | → surface |

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

@@ -0,0 +1,44 @@
+# oh-learn — Deep Reference
+
+## When to Use
+
+Session learnings should be captured, reviewed, or promoted as reusable instincts for future work.
+
+Triggers: learn from session, extract patterns, run oh-learn.
+
+## Instinct Data Model
+
+JSONL at `~/.local/share/opencode/openhermes/plans/<project>-instincts.jsonl`:
+
+```json
+{"trigger": "specific situation", "action": "recommended response", "confidence": 0.5, "applications": 1, "successes": 1, "category": "coding", "source": "oh-learn:extract", "ts": "2026-05-15T12:00:00Z"}
+```
+
+**Trigger:** specific, matchable (not general advice). **Action:** executable (not belief). **Confidence:** starts 0.5, +0.05 per success, -0.02/day decay. **Category:** coding, testing, security, git, planning, orchestration, debugging, ux.
+
+## Workflows
+
+### Extract
+
+Scan session for repeated decisions. For each: write instinct. Check existing file for near-duplicates. Merge (max confidence, increment applications) or append.
+
+### Evolve
+
+Read all instincts. Group by category then topic. ≥5 instincts with avg confidence ≥ 0.7 → oh-skill-craft spec. 3-4 with confidence ≥ 0.8 → suggest update to existing skill.
+
+### Promote
+
+Instincts with confidence ≥ 0.85 AND applications ≥ 10 → filter project-specific → append to global `%USERPROFILE%\.config\opencode\instincts.jsonl`. Tag promoted.
+
+### Review / Search / Prune / Export
+
+Review: totals + distributions. Search: by topic, trigger, category, confidence. Prune: stale >30d with confidence < 0.3. Export: portable JSON.
+
+## Anti-patterns
+
+- Hoarding every observation (most aren't learnings)
+- Never pruning
+- Storing what not why
+- Over-promoting to global
+- Extracting without applying
+- Ignoring confidence

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

@@ -1,11 +1,7 @@
 ---
 name: oh-learn
-description: "Extract, evolve, and promote session learnings as instincts. Review, search, prune, export."
+description: "Capture, review, and promote session learnings as reusable instincts"
 tier: 2
-triggers:
-  - "learn from session"
-  - "extract patterns"
-  - "run oh-learn"
 route:
   pass: done
   fail: surface
@@ -14,88 +10,21 @@ route:
 
 # 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.
+Distill session patterns into instincts, cluster into skill candidates, and promote high-signal patterns.
 
-## Instinct Data Model
+## Steps
 
-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
-
-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
+1. Scan session for repeated decisions
+2. Write instinct for each pattern — trigger, action, confidence
+3. Check existing file for near-duplicates; merge or append
+4. Group instincts by category and topic
+5. Promote high-confidence instincts (≥0.85, ≥10 applications) to global scope
+6. Prune stale low-confidence instincts (<0.3, >30 days)
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [done — report summary] |
-| fail | → [surface gaps to user] |
-| blocker | → surface to user |
+| pass | → done |
+| fail | → surface |
+| blocker | → surface |