openhermes 4.3.0 → 4.11.2

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

@@ -1,15 +1,7 @@
 ---
 name: oh-grill
-description: "Stress-test plans and designs through relentless Socratic questioning. Sharpens assumptions, flags blind spots, updates domain docs."
+description: "Stress-tests plans through Socratic questioning to surface assumptions and blind spots"
 tier: 3
-benefits-from: [oh-expert, oh-planner]
-triggers:
-  - "stress test this plan"
-  - "challenge this plan"
-  - "grill me on this"
-  - "poke holes in this plan"
-  - "interrogate this plan"
-  - "stress test this design"
 route:
   pass: oh-planner
   fail: oh-expert
@@ -18,64 +10,21 @@ route:
 
 # oh-grill
 
-Stress-tests plans and designs through relentless Socratic questioning. Two modes: plain interrogate (quick) or interrogate + update domain docs (thorough).
+Stress-tests plans through relentless Socratic questioning. Two modes.
 
-## When to Use
-Before committing to a plan or design. When the user says "it is writing exactly what I asked for and it is still wrong" — the design concept is not shared yet. Cheaper to resolve in conversation than in code.
+## Steps
 
-## Modes
-
-### Mode A: Grill (quick)
-Challenge the plan without touching files.
-
-1. Read the plan or design doc
-2. Interview the user one decision at a time — each answer reveals new branches
-3. Resolve each branch before moving on
-4. Surface: contradictions, blind spots, unstated assumptions, ambiguous terms
-5. Propose a recommended answer for each decision
-6. Output: verified, stress-tested plan with flagged ambiguities
-
-### Mode B: Grill with Docs (thorough)
-Same as Mode A, but persists decisions to CONTEXT.md and ADRs, and extracts a DDD ubiquitous-language glossary.
-
-1. Load existing CONTEXT.md and ADRs
-2. Grill through the decision tree — each resolved decision may:
-   - Update CONTEXT.md domain terms (sharpen fuzzy language)
-   - Create a new ADR for architectural decisions
-   - Flag an ambiguity in the domain glossary
-3. **Ubiquitous Language extraction** — after the decision tree resolves, scan the conversation for domain-relevant nouns, verbs, and concepts:
-   - Identify problems: same word for different concepts (ambiguity), different words for same concept (synonyms), vague or overloaded terms
-   - Propose a canonical glossary with grouped tables (by subdomain, lifecycle, or actor)
-   - Write an example dialogue (3-5 exchanges) between dev and domain expert showing natural term usage
-   - Write flagged ambiguities section
-4. Persist changes to CONTEXT.md immediately as language firms up
-5. Output: updated CONTEXT.md + new ADRs + UBIQUITOUS_LANGUAGE.md (if significant terms emerged) + verified plan with resolution trail
-
-## Technique
-
-- Ask one question at a time
-- Propose a recommended answer for each decision
-- Walk the full decision tree before accepting the design
-- Reference domain glossary from CONTEXT.md when terms are ambiguous
-- Cross-reference with existing ADRs when architecture is at stake
-
-## When NOT to Use
-- When you already have a clear, vetted plan and need execution
-- When the user needs a builder, not a critic
-- For trivial decisions that don't change the design's shape
-
-## Anti-patterns
-- Grilling for the sake of grilling (redundant with existing reviews)
-- Asking questions you could answer by reading the plan or codebase
-- Creating ADRs for trivial decisions (not every choice is architecture)
-- Polishing CONTEXT.md prose before concepts are settled
-- Updating domain terms mid-discussion — let the conversation resolve first
-- Not distinguishing between "must resolve now" vs "figure out later"
+1. Read the plan or design document fully
+2. Interview decisions one at a time — each answer reveals new branches
+3. Resolve each branch before moving to the next decision
+4. Surface contradictions, blind spots, unstated assumptions, ambiguous terms
+5. Propose recommended answer per decision
+6. Output verified plan with flagged ambiguities
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → oh-planner (revise plan based on feedback) |
-| fail | → oh-expert (resolve confusion or blind spot) |
-| blocker | → surface to user |
+| pass | → oh-planner |
+| fail | → oh-expert |
+| blocker | → surface |

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

@@ -0,0 +1,19 @@
+# oh-guard — Deep Reference
+
+## When to Use
+
+When user says "be careful," "don't break anything," or context involves production, destructive changes, or irreversible actions.
+
+## What Triggers a Guard Check
+
+- File deletion or rename
+- Git destructive operations (reset, rebase, force push)
+- Dependency changes (add/remove/upgrade)
+- Configuration changes affecting auth, network, data
+- Any command with `--force`, `-f`, `--hard`, or destructive flags
+
+## Anti-patterns
+
+- Guarding trivial operations (wastes time)
+- Forgetting to ask on genuinely destructive operations
+- Asking for confirmation on reads or analysis steps

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

@@ -1,11 +1,7 @@
 ---
 name: oh-guard
-description: "Safety confirmation mode — warn before destructive operations"
+description: "Safety confirmation mode that warns before destructive operations."
 tier: 2
-triggers:
-  - "confirm before"
-  - "safety confirmation"
-  - "guard mode"
 route:
   pass: mode
   fail: mode
@@ -14,29 +10,19 @@ route:
 
 # 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,11 +1,7 @@
 ---
 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
-triggers:
-  - "session handoff"
-  - "handoff to another agent"
-  - "handoff the session"
 route:
   pass: done
   fail: surface
@@ -14,29 +10,23 @@ route:
 
 # 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,14 +1,7 @@
 ---
 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 the codebase"
-  - "code quality check"
-  - "quality dashboard"
-  - "how healthy is the codebase"
-  - "run all project checks"
-  - "code health"
 route:
   pass: surface
   fail: oh-investigate
@@ -17,78 +10,22 @@ route:
 
 # 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/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/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)