openhermes 4.1.0 → 4.9.2

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

@@ -1,33 +1,28 @@
 ---
 name: oh-guard
-description: "Safety confirmation mode — warn before destructive operations"
+description: "Safety confirmation mode that warns before destructive operations."
+tier: 2
+route:
+  pass: mode
+  fail: mode
+  blocker: surface
 ---
 
 # oh-guard
 
-## When to Use
-When touching production, running destructive commands, or working in shared environments. Combines warning prompts with directory-scoped edit locks.
+Require confirmation before destructive operations.
 
-## Workflow
-1. **Enable guard mode** — set safety level (careful / freeze / full guard)
-2. **Destructive command warnings** — intercept rm -rf, DROP TABLE, force-push, git reset --hard, kubectl delete
-3. **Directory scope lock** — restrict file edits to specified directory (freeze)
-4. **User override** — user can approve or deny each operation
+## Steps
 
-## Modes
-- **Careful** — warn before destructive commands
-- **Freeze** — restrict edits to one directory
-- **Guard** — both careful + freeze
-
-## Anti-patterns
-- Disabling guard because "I know what I'm doing" (narrator: they didn't)
-- Running prod commands outside guard mode
-- Ignoring warnings about irreversible operations
+1. Identify the planned write/edit/delete operation
+2. State the planned operation to the user
+3. Ask for explicit confirmation
+4. Proceed only on receiving explicit approval
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [return to prior skill — guard mode active] |
-| fail | → [surface warning — operation denied] |
-| blocker | → surface to user |
+| pass | → mode |
+| fail | → mode |
+| blocker | → surface |

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

@@ -0,0 +1,48 @@
+# oh-handoff — Deep Reference
+
+## When to Use
+
+Session ending, context switch, passing work to another agent, or user says "handoff." Produces a structured document the next session/agent can consume without re-reading the conversation.
+
+## Anti-patterns
+
+- Writing a transcript instead of a structured summary
+- Including irrelevant context or raw logs
+- Omitting key decisions or blockers
+- Over 500 tokens (handoff must be compact)
+
+## Output Template
+
+```markdown
+## Goal
+<what this session was trying to achieve>
+
+## Progress
+### Done
+- <completed items>
+
+### In Progress
+- <current work>
+
+### Blocked
+- <blockers>
+
+## Key Decisions
+- <decision> — <rationale>
+
+## Critical Context
+<bare essentials the next session MUST know>
+
+## Relevant Files
+- <file> — <why it matters>
+
+## Next Steps
+- <immediate next action>
+```
+
+## Rules
+
+- Keep under 500 tokens if possible
+- Only what the next session needs to continue — not a transcript
+- Reference plan files by path, don't duplicate content
+- If blockers exist, state what's needed to resolve

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

@@ -1,33 +1,32 @@
 ---
 name: oh-handoff
-description: "Compact session state into a structured handoff document"
+description: "Compact session state into a structured handoff document for transfer"
+tier: 2
+route:
+  pass: done
+  fail: surface
+  blocker: surface
 ---
 
 # oh-handoff
 
-## When to Use
-When switching contexts, ending a session, or passing work to another agent or developer. Produces a compact summary that captures everything needed to resume.
+Compact session state into a structured handoff document the next agent can consume without replay.
 
-## Handoff Document Structure
-- **Context** — what were we doing?
-- **State** — what's done, what's pending, what's blocked?
-- **Decisions** — key decisions made this session
-- **Artifacts** — files changed, created, or referenced
-- **Next steps** — ordered list of what to do next
-- **Risks** — things to be aware of
+## Steps
 
-## Output
-A `HANDOFF.md` or structured text block with all resume-relevant information.
-
-## Anti-patterns
-- Writing a novel (handoff should be scannable in 30 seconds)
-- Omitting decisions (why we chose X over Y is critical context)
-- No next steps ("figure it out" is not a handoff)
+1. Identify session goal and current progress
+2. List completed items
+3. List in-progress items
+4. List blockers with what's needed to resolve
+5. Document key decisions with rationale
+6. Extract critical context — bare essentials only
+7. List relevant files with why they matter
+8. Write immediate next steps
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [end of session — intentional terminal] |
-| fail | → [surface blocker — handoff incomplete] |
+| pass | → done — session end |
+| fail | → surface gaps to user |
 | blocker | → surface to user |

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

@@ -0,0 +1,74 @@
+# oh-health — Deep Reference
+
+## When to Use
+
+Use when you need a code quality health check. Read-only dashboard — no fixes.
+
+## Verification Discipline
+
+Before making any completion claim based on health results, run the Gate:
+
+1. **IDENTIFY** — What specific command/check proves this claim?
+2. **RUN** — Execute the full command fresh
+3. **READ** — Full output, exit code, failure count
+4. **VERIFY** — Does output confirm the claim?
+5. **CLAIM** — Only after verification
+
+No completion claims without fresh verification evidence.
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check |
+| Build succeeds | Build command: exit 0 | Linter passing |
+| All checks pass | Each tool run fresh | Aggregated from memory |
+
+## Scoring Table
+
+| Category | Weight | 10 | 7 | 4 | 0 |
+|----------|--------|----|----|----|----|
+| Type check | 22% | Clean | <10 err | <50 err | 50+ |
+| Lint | 18% | Clean | <5 warn | <20 warn | 20+ |
+| Tests | 28% | All pass | >95% | >80% | <=80% |
+| Dead code | 13% | Clean | <5 items | <20 items | 20+ |
+| Shell lint | 9% | Clean | <5 | 5+ | N/A |
+| Framework | 10% | Native | Config override | Manual | Unmanaged |
+
+Skip unavailable → redistribute weight proportionally.
+
+## Dashboard Template
+
+```
+Category    Score   Status    Details
+Type check  10/10   CLEAN     0 errors
+Lint         8/10   WARNING   3 warnings
+Tests       10/10   CLEAN     47/47 pass
+Dead code    7/10   WARNING   4 unused
+
+COMPOSITE: 9.1 / 10
+```
+
+Status: 10=CLEAN, 7-9=WARNING, 4-6=NEEDS WORK, 0-3=CRITICAL.
+
+## History Persistence
+
+Append JSONL to `.opencode/health-history.jsonl`:
+```json
+{"ts":"...","branch":"main","score":9.1,"typecheck":10,"lint":8,"test":10,"deadcode":7,"duration_s":23}
+```
+
+## Trend Analysis
+
+Read last 10 entries. Trend table. Identify declining categories. Rank improvements by impact (weight × score deficit).
+
+## Rules
+
+- Read-only. No fixes. Wrap, don't replace (run project's tools).
+- Skipped ≠ failed (tool not installed → redistribute weight).
+- Show raw output for failures.
+- First run: "No trend data yet."
+
+## Anti-patterns
+
+- Claiming results without re-running checks.
+- Aggregating from memory instead of running fresh.

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

@@ -1,90 +1,31 @@
 ---
 name: oh-health
-description: "Code quality dashboard: runs project tools (typecheck, lint, test, dead code detection), computes weighted composite 0-10 score, persists history, shows trend. Read-only — no fixes."
+description: "Code quality health check — runs all project tools, scores 0-10, shows trends"
 tier: 2
-triggers:
-  - "health check"
-  - "code quality"
-  - "quality dashboard"
-  - "how healthy is the codebase"
-  - "run all checks"
-  - "health"
+route:
+  pass: surface
+  fail: oh-investigate
+  blocker: surface
 ---
 
 # oh-health
 
-Staff Engineer who owns the CI dashboard. Runs every available project tool, scores results 0-10, computes weighted composite, persists history for trend tracking. Read-only — the user decides what to act on.
+Run all available project tools, score 0-10, and surface a composite dashboard with trend history.
 
-## Process
+## Steps
 
-### Step 1: Detect Health Stack
-Auto-detect available tools:
-- **Type checker** — `tsc --noEmit` (tsconfig.json present), `mypy` (pyproject.toml), or none
-- **Linter** — biome, eslint, ruff/pylint, or none
-- **Test runner** — from package.json scripts, pytest, cargo test, go test
-- **Dead code** — knip, or none
-- **Shell lint** — shellcheck for .sh files
-
-Present detected tools. Optionally persist to CLAUDE.md as `## Health Stack` section for future runs.
-
-### Step 2: Run Tools
-Run each tool sequentially (some share resources). Capture exit code + output summary for each.
-
-### Step 3: Score Each Category
-
-| Category | Weight | 10 | 7 | 4 | 0 |
-|---|---|---|---|---|---|
-| Type check | 22% | Clean | <10 errors | <50 errors | 50+ |
-| Lint | 18% | Clean | <5 warnings | <20 warnings | 20+ |
-| Tests | 28% | All pass | >95% pass | >80% pass | <=80% |
-| Dead code | 13% | Clean | <5 unused | <20 unused | 20+ |
-| Shell lint | 9% | Clean | <5 issues | 5+ issues | N/A |
-| Framework | 10% | Native default | Config override | Manual | Unmanaged |
-
-Skip unavailable categories and redistribute weight proportionally among remaining.
-
-### Step 4: Present Dashboard
-
-```
-CODE HEALTH DASHBOARD
-═════════════════════
-Project: <name>
-Branch:  <branch>
-Date:    <date>
-
-Category      Score   Status     Details
-──────────    ─────   ────────   ───────
-Type check    10/10   CLEAN      0 errors
-Lint           8/10   WARNING    3 warnings
-Tests         10/10   CLEAN      47/47 passed
-Dead code      7/10   WARNING    4 unused exports
-
-COMPOSITE: 9.1 / 10
-```
-
-Status labels: 10=CLEAN, 7-9=WARNING, 4-6=NEEDS WORK, 0-3=CRITICAL.
-
-### Step 5: Persist History
-Append one JSONL line to `.opencode/health-history.jsonl`:
-```json
-{"ts":"2026-05-14T14:30:00Z","branch":"main","score":9.1,"typecheck":10,"lint":8,"test":10,"deadcode":7,"duration_s":23}
-```
-
-### Step 6: Trend Analysis + Recommendations
-Read last 10 history entries. Show trend table. For regressions, identify declining categories and specific errors. Rank improvement suggestions by impact (weight × score deficit).
-
-## Rules
-
-- **Read-only.** No fixes. Dashboard and recommendations only.
-- **Wrap, don't replace.** Run the project's own tools. Never substitute your own analysis.
-- **Skipped is not failed.** Tool not installed → skip gracefully, redistribute weight.
-- **Show raw output for failures.** Include tool output so user can act without re-running.
-- **Trends require history.** First run: "No trend data yet. Run again after changes to track progress."
+1. Detect available health tools (typecheck, lint, test runner, dead code, shell lint, framework)
+2. Run each detected tool sequentially, capture exit code and output summary
+3. Score each category using the weighted table (Type check 22%, Lint 18%, Tests 28%, Dead code 13%, Shell lint 9%, Framework 10%)
+4. Build composite score with status bands: 10=CLEAN, 7-9=WARNING, 4-6=NEEDS WORK, 0-3=CRITICAL
+5. Persist result to `.opencode/health-history.jsonl`
+6. Read last 10 entries and produce trend analysis
+7. Surface the dashboard with per-category scores, composite score, and trend
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [report score to user] |
-| fail | → oh-investigate (deepen on degraded metrics) |
-| blocker | → surface to user |
+| pass | → surface |
+| fail | → oh-investigate |
+| blocker | → surface |

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

@@ -0,0 +1,85 @@
+# oh-init — Deep Reference
+
+## When to Use
+
+Per-repo OpenHermes setup. One-time. Complements OpenCode's `/init` (run after or instead).
+
+## Workflow / Phases
+
+### Phase 0: Check Existing State
+
+Detect: AGENTS.md, opencode.json, plan files, CONTEXT.md, `docs/agents/`. Report findings. All exist → offer skip/verify.
+
+### Phase 1: AGENTS.md
+
+**Not exists:** Create with OH orchestrator header + project context prompts:
+
+```markdown
+# <project>
+
+OpenHermes is the primary orchestrator. All routing, planning, and delegation flows through oh-* skills.
+
+## Project Context
+- **Language**: <fill or auto-detect>
+- **Package manager**: <fill or auto-detect>
+- **Build command**: <fill or auto-detect>
+- **Test command**: <fill or auto-detect>
+
+## Key Directives
+- Plan first. Write to `~/.local/share/opencode/openhermes/plans/<project>-plan-<nnn>.md` before multi-file changes.
+- OpenHermes delegates everything to sub-agents — never executes directly.
+- Verify before claiming success. Read files, run commands, confirm output.
+- Use oh-* skills on demand via the skill tool.
+- Plan file is self-contained (Tasks, Completed, Work Log sections).
+```
+
+Ask user to fill or auto-detect from manifests.
+
+**Exists:** Append this `## OpenHermes Orchestrator` section:
+
+```markdown
+## OpenHermes Orchestrator
+OpenHermes is the primary orchestrator.
+- **Plan**: `~/.local/share/opencode/openhermes/plans/<project>-plan-<nnn>.md`
+- **Never execute**: delegates everything to sub-agents
+- **Verify before claim**: read files, run commands, confirm output
+```
+
+### Phase 2: Issue Tracker
+
+Detect platform (GitHub → gh, GitLab → glab, local markdown, other). Confirm with user. Write to `docs/agents/issue-tracker.md`.
+
+### Phase 3: Triage Labels
+
+States: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. Map to existing labels. Write to `docs/agents/triage-labels.md`.
+
+### Phase 4: Domain Docs
+
+Single-context (CONTEXT.md + docs/adr/) or multi-context (CONTEXT-MAP.md). Scaffold CONTEXT.md with project name, domain, glossary placeholders. Create `docs/adr/` with ADR template. Write to `docs/agents/domain.md`.
+
+### Phase 5: Agent Skills Block
+
+Append to AGENTS.md:
+
+```markdown
+## Agent skills
+### Issue tracker
+See `docs/agents/issue-tracker.md`.
+### Triage labels
+See `docs/agents/triage-labels.md`.
+### Domain docs
+See `docs/agents/domain.md`.
+```
+
+### Phase 6: Decision Record
+
+"oh-init completed for project <name> on <date>."
+
+## Anti-patterns
+
+- Running without understanding domain
+- Empty CONTEXT.md (populate terms)
+- ADR dir without ADRs
+- Both AGENTS.md and CLAUDE.md (edit the one that exists)
+- Overwriting existing AGENTS.md (append)
+- Creating .opencode/ dir (plan files go to canonical storage)

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

@@ -1,211 +1,31 @@
 ---
 name: oh-init
-description: "Initialize project for OpenHermes takeover: scaffold .opencode/ runtime skeleton, wire AGENTS.md, configure domain docs, issue tracker, and triage labels."
+description: "Sets up AGENTS.md, domain docs, issue tracker, and triage labels"
 tier: 2
-triggers:
-  - "init project"
-  - "setup project"
-  - "initialize"
-  - "onboard"
-  - "scaffold"
-  - "takeover"
+route:
+  pass: done
+  fail: oh-init
+  blocker: surface
 ---
 
 # oh-init
 
-Per-repo setup for OpenHermes-assisted development. Run once per repo. Wires the `.opencode/` runtime skeleton, connects `AGENTS.md` to the orchestrator, then walks through domain/issue configuration decisions one at a time.
+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:
-
-- ☐ `.opencode/` directory present?
-- ☐ `.opencode/plan.md` exists?
-- ☐ `.opencode/todo.md` exists?
-- ☐ `.opencode/work-log.md` exists?
-- ☐ `.opencode/instincts.jsonl` exists?
-- ☐ `AGENTS.md` exists? (If yes, was it created by OpenCode `/init` or manually?)
-- ☐ `opencode.json` / `opencode.jsonc` present?
-
-Report findings. If everything exists, offer to skip or verify and exit.
-
-### Phase 1: .opencode/ Runtime Skeleton
-Create `.opencode/` directory if missing. Scaffold shared state files:
-
-**`.opencode/plan.md`** — working plan for the current session. Uses the same format as the global permanent plan directory (`%USERPROFILE%/.config/opencode/task/<project>-plan-<nnn>.md`). When a plan is completed, copy to the global directory with sequenced naming for permanent archive.
-
-```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
-
-## Assumptions
-
-## Tasks
-
-- [ ] Task 1
-  - [ ] Subtask 1.1
-
-## Active Task
-
-## Subagents
-
-| Agent | Purpose | Status | Findings |
-|---|---|---|---|
-
-## Completed
-
-## Blockers
-
-- None
-
-## Validation
-
-- [ ] Static checks
-- [ ] Formatting checks
-- [ ] Type checks
-- [ ] Unit tests
-- [ ] Integration checks
-- [ ] Manual verification
-
-## Decisions
-
-## Notes
-```
-
-**`.opencode/todo.md`** — task tracking for multi-step work (start empty).
-
-**`.opencode/work-log.md`** — progress tracking across subagent delegations:
-```markdown
-# Work Log
-
-## <date> — <description>
-- Started: <time>
-- Completed: <task>
-- Next: <next task>
-```
-
-**`.opencode/instincts.jsonl`** — behavioral pattern store for oh-learn (start as empty file). Will grow organically as the agent extracts patterns from sessions.
-
-### Phase 2: 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 `.opencode/plan.md` before multi-file changes.
-- Verify before claiming success. Read files, run commands, confirm output.
-- Delegate substantive work to subagents — main context orchestrates.
-- Use oh-* skills on demand. Load via OpenCode's skill tool when relevant.
-- Shared state lives in `.opencode/` (plan.md, todo.md, work-log.md, instincts.jsonl).
-```
-
-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**: `.opencode/plan.md` — always check before starting work
-- **Shared state**: `.opencode/todo.md`, `.opencode/work-log.md`, `.opencode/instincts.jsonl`
-- **Verify before claim**: read files, run commands, confirm output
-- **Delegate**: subagents for implementation, main context orchestrates
-```
-
-### Phase 3: 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 4: 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 5: 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 6: 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 7: 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)
-- Scaffolding `.opencode/` files that already exist (check first, skip duplicates)
-- Empty instinct file never getting populated (run oh-learn extract periodically)
-- Never archiving completed plans to the global task directory (completed plans rot in `.opencode/` instead of becoming permanent records)
+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 |