openhermes 4.0.1 → 4.3.0

package/ETHOS.md

@@ -1,6 +1,6 @@
 # OpenHermes Ethos
 
-Four immutable principles. Every skill, every command, every session.
+Five immutable principles. Every skill, every command, every session.
 
 ## Native First
 OpenCode-native loading over manual copying or hidden state.
@@ -11,5 +11,8 @@ Every file earns its keep. Prefer markdown when behavior is declarative.
 ## Skills Over Glue
 Behavior lives in `SKILL.md`, `commands/*.md`, and `agents/*.md`.
 
-## Delegate Hard Work
-Subagents for substantive work. Main context orchestrates and verifies.
+## Always Delegate — Never Execute
+OpenHermes orchestrates and reports. Sub-agents execute. OpenHermes never writes code, runs tests, or touches files directly.
+
+## Closed Loop
+Auto-classify. Auto-route. Auto-execute. Only stop for blockers. No dead ends, no asking permission, no wasted cycles.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 nathwn12
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 nathwn12
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,106 +1,130 @@
 <p align="center">
-  <h1 align="center">&#9764; OpenHermes</h1>
-  <p align="center"><i>Plan. Build. Ship. One plugin.</i></p>
+  <h1 align="center">⟳ OpenHermes</h1>
+  <p align="center"><b>Closed loop. Zero permission.</b><br>
+  <i>The AI orchestrator that never asks "should I continue?" — it just routes.</i></p>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/openhermes"><img src="https://img.shields.io/npm/v/openhermes?style=for-the-badge&label=version&color=FFD700" alt="npm version"></a>
   <a href="https://github.com/nathwn12/openhermes/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License: MIT"></a>
   <a href="https://opencode.ai"><img src="https://img.shields.io/badge/runs%20on-OpenCode-6366f1?style=for-the-badge" alt="Runs on OpenCode"></a>
+  <a href="https://github.com/nathwn12/openhermes"><img src="https://img.shields.io/badge/⭐%20star%20on-GitHub-181717?style=for-the-badge" alt="Star on GitHub"></a>
 </p>
 
 ---
 
-OpenHermes is an OpenCode plugin that gives your agent a complete skill system out of the box. Add one line to `opencode.json`, get 25 skills, a primary orchestrator, and a shared operating model.
+**AI coding assistants stall.** They ask permission. They lose context mid-session. They wait for you to unstick them.
+
+OpenHermes doesn't.
+
+Drop it into OpenCode. Get a self-driving pipeline: auto-classify every request, delegate to specialists, route results automatically. No "can I?", no "shall I?", no "what next?" — just execution until the job is done.
 
 ```json
 { "plugin": ["openhermes@git+https://github.com/nathwn12/openhermes.git"] }
 ```
 
-No setup. No file copying. No extra dependencies.
+To install from `dev` (latest features, may be unstable):
+
+```json
+{ "plugin": ["openhermes@git+https://github.com/nathwn12/openhermes.git#dev"] }
+```
 
 ---
 
-## What you get
+## One sentence. Nine steps.
 
-### Seven core skills
+Add the plugin. Restart. Type:
 
-| Skill | What it does |
-|---|---|
-| **oh-planner** | Brainstorm, analyze architecture, run strategy reviews, auto-decide 90% of questions with gstack decision principles. Produces a consumable plan artifact. |
-| **oh-builder** | Prototype, TDD red-green-refactor, design interfaces in parallel sub-agents, implement from plan. Vertical tracer bullets, one test at a time. |
-| **oh-manifest** | Full build loop: planner → builder → verify → loop until done or a real blocker is surfaced. Auto-resolves intermediate questions; only interrupts you for genuine blockers. |
-| **oh-gauntlet** | Multi-axis testing gauntlet: unit tests, dual-axis review (Standards + Spec in parallel sub-agents), edge case sweep, QA tier, canary post-deploy. |
+> *"Plan a CLI tool for managing dotfiles."*
 
-These seven form a pipeline: **think → plan → build → test → ship → secure → monitor**. Each produces artifacts the next consumes.
+You see output. Behind the scenes, this runs:
 
-### Twenty-five skills total
+| # | What fires | What it does |
+|---|---|---|
+| **1** | `AUTOPILOT.md` decision matrix | Multi-step, vague → `PLANNING NEEDED` |
+| **2** | `oh-planner` | Brainstorm mode: architecture, user flow, risks |
+| **3** | `oh-planner` → `oh-grill` | Plan passes → stress-test it |
+| **4** | `oh-grill` → `oh-planner` (revise) | Gaps found → planner revises |
+| **5** | `oh-planner` → `oh-manifest` | Plan solid → enter build loop |
+| **6** | `oh-planner` → `oh-builder` → `oh-gauntlet` | Implement → test → review → loop |
+| **7** | `oh-gauntlet` → `oh-ship` | Tests pass → PR pipeline |
+| **8** | `oh-ship` → `oh-retro` | Shipped → retrospective |
+| **9** | `oh-retro` → `oh-planner` | Ready for the next cycle |
 
-| Skill | Purpose |
-|---|---|
-| oh-planner, oh-builder, oh-manifest, oh-gauntlet | Core pipeline (above) |
-| oh-expert | AI self-diagnosis vocabulary — sycophancy, hallucination type, attention degradation |
-| oh-grill | Stress-test plans through Socratic questioning; optionally updates CONTEXT.md, ADRs, and extracts ubiquitous language |
-| oh-plan-review | Multi-lens plan review: Engineering, Design, DX, Strategy |
-| oh-security | Security audit: secrets archaeology, supply chain, CI/CD, OWASP, STRIDE, LLM security |
-| oh-health | Code quality dashboard: wraps tools, composite score, trend tracking |
-| oh-investigate | Systematic bug diagnosis |
-| oh-handoff | Compact session into structured handoff artifact for another agent |
-| oh-skill-craft | Create new skills for the harness (meta-skill) |
-| oh-init | Initialize project: scaffold CONTEXT.md, AGENTS.md, ADRs, issue tracker config, triage labels |
-| oh-retro | Retrospective after shipping |
-| oh-review | Two-axis review (Standards + Spec) in parallel sub-agents + architecture deepening |
-| oh-ship | PR, version bump, changelog, post-ship docs sync |
-| oh-triage | Issue triage state machine |
-| oh-issue | Break plans into vertical-slice issues |
-| oh-prd | Write structured PRDs |
-| oh-caveman | Ultra-compressed response mode |
-| oh-freeze | Freeze dependencies |
-| oh-learn | Learn patterns from the codebase |
-| oh-guard | Safety confirmations for destructive operations |
-| oh-skills-link | Verify skills discovery |
-| oh-skills-list | List available skills |
-
-### One orchestrator agent
-
-OpenHermes is the default primary agent — a hub-and-spoke commander that delegates to skills, spawns sub-agents for isolated context, and surfaces blockers instead of silently retrying.
-
-### One diagnostic command
-
-`/oh-doctor` — inspect plugin load, skills discovery, command/agent registration, and config safety.
+One sentence. Nine automated steps. Each skill loaded on demand, executed in isolation, routed to the next specialist. **Auto-classify, delegate, route, repeat.** That's the entire model.
 
 ---
 
-## How it works
+### Three safety layers
 
-OpenHermes loads through OpenCode's native plugin system. On install:
+The loop runs unsupervised because these never turn off:
 
-1. `config.skills.paths` is pointed at the package-local `harness/skills/` — skills load on demand through the `skill` tool, no preloading
-2. Commands from `harness/commands/` register as slash commands
-3. The agent manifest in `harness/agents/` sets OpenHermes as the primary orchestrator
-4. Instructions from `CONSTITUTION.md`, `RUNTIME.md`, `CONTEXT.md`, and `ETHOS.md` are injected into every session
-
-Everything is package-local. Nothing is copied into your global config.
+- **🔁 Loop Guard** — stops if the same skill fires 3+ times or 5+ hops produce no progress
+- **❓ Question Gate** — never routes into uncertainty; surfaces if input is missing
+- **📋 Auto-Handoff** — writes a structured session artifact before context switches
 
 ---
 
-## OptiRoute: Smart Auto-Routing Protocol
+## What you get
+
+| Capability | Why it matters |
+|---|---|
+| **Self-driving loop** | Type once. OpenHermes classifies, delegates, and routes — no pauses, no asking permission. |
+| **29 specialist skills** | Planning → building → testing → security → review → shipping → retro. Every dev cycle phase. |
+| **Auto-detected user skills** | Drop a skill in `~/.agents/skills/`. OpenHermes finds it. Same name as a built-in? Your version wins. Survives `npm update`. |
+| **`/oh-doctor`** | Verify plugin load, skill discovery, command registration, config safety. |
+| **`/oh-log`** | Session log — routing hops, skill loads, compaction events. |
+| **Shared operating model** | CONSTITUTION + RUNTIME + CONTEXT + ETHOS injected every session. Every interaction grounded in the same rules. |
+| **Plan file storage** | `~/.local/share/opencode/openhermes/plans/`. Survives `npm update`. |
 
-Every skill routes to the next based on outcome — pass, fail, or blocker. OptiRoute is a guard layer on top of that graph. Three rules:
+## 29 skills — three tiers
 
-**Loop guard.** Tracks routing depth. If the same skill is visited 3+ times in one chain, or 5+ hops pass without measurable progress (new artifact, changed target), routing stops. No infinite loops.
+### Tier 4 — Pipeline orchestrators
+Full multi-phase workflows:
 
-**Question gate.** Before each routing hop, the protocol checks whether the next skill's inputs are satisfied. If the task is underspecified or information is missing, it asks the user instead of routing into uncertainty.
+| Skill | Purpose |
+|---|---|
+| **oh-manifest** | Plan → build → verify → loop until done or blocker |
+| **oh-facade** | Concept → design system → build → audit → iterate (full UI pipeline) |
+| **oh-gauntlet** | Multi-axis testing: unit, integration, edge cases, dual-axis review |
+| **oh-builder** | ALL-arounder builder — prototype, TDD, implement from plan |
+| **oh-ship** | Deploy and PR pipeline: test, bump, changelog, PR, deploy, verify |
 
-**Auto-handoff.** When the loop guard triggers, it writes an OptiRoute report into `plan.md` — the routing chain, the trigger threshold, current state, and the blocker. Then it surfaces the blocker and awaits direction.
+### Tier 3 — Cross-cutting skills
+Span multiple phases and coordinate other skills:
 
-```md
-OPTIROUTE STOP: 5-hop ceiling reached, no progress
-Chain: planner → grill → planner → builder → gauntlet → planner
-See .opencode/plan.md for full report
-```
+| Skill | Purpose |
+|---|---|
+| **oh-planner** | Brainstorm, architect, autoplan, decision pipeline |
+| **oh-grill** | Stress-test plans through relentless Socratic questioning |
+| **oh-plan-review** | Multi-lens review: Engineering, Design, DX, Strategy |
+| **oh-security** | Audit: secrets, supply chain, CI/CD, OWASP, LLM security |
+| **oh-refactor** | Surgical behavior-preserving refactoring |
+| **oh-review** | Two-axis review (Standards + Spec) in parallel sub-agents |
+| **oh-fusion** | Skill ingestion pipeline: discover → analyze → adapt → fuse → integrate |
+| **oh-retro** | Weekly retrospective — analyze commit history and patterns |
+
+### Tier 2 — Focused skills
+Single-purpose, one thing well:
 
-No loops. No guessing. No silent death.
+| Skill | Purpose |
+|---|---|
+| **oh-expert** | AI self-diagnosis: sycophancy, hallucination, attention dynamics |
+| **oh-full-output** | Override truncation, ban placeholders, enforce complete generation |
+| **oh-health** | Code quality dashboard: tools, composite score, trend |
+| **oh-investigate** | Systematic bug diagnosis with root cause investigation |
+| **oh-handoff** | Compact session state → structured handoff document |
+| **oh-skill-craft** | Create new agent skills with frontmatter and bundled resources |
+| **oh-init** | Wire AGENTS.md, domain docs, issue tracker, triage labels |
+| **oh-triage** | Issue triage state machine — classify, prioritise, assign |
+| **oh-issue** | Break a plan/spec/PRD into independently-grabbable issues |
+| **oh-prd** | Conversation → PRD → GitHub issue |
+| **oh-caveman** | Ultra-compressed mode — cut token usage ~75% |
+| **oh-freeze** | Restrict file edits to a specific directory |
+| **oh-learn** | Extract, evolve, promote session learnings as instincts |
+| **oh-guard** | Safety confirmation — warn before destructive operations |
+| **oh-skills-link** | Verify OpenCode discovers the skill directory |
+| **oh-skills-list** | List all available `oh-*` skills |
 
 ---
 
@@ -108,28 +132,34 @@ No loops. No guessing. No silent death.
 
 ```
 openhermes-pkg/
-├── AGENTS.md              # Skill/command/agent inventory
-├── CONTEXT.md             # Shared language
+├── AGENTS.md              # User-side routing overlay
+├── CONTEXT.md             # Shared domain language
 ├── ETHOS.md               # Operating principles
-├── bootstrap.mjs          # Plugin loader — registers everything
-├── index.mjs              # Package entrypoint
+├── bootstrap.ts           # Plugin entry — registers everything
+├── index.ts               # Package entrypoint
+├── lib/                   # harness-resolver.ts, logger.ts
 ├── harness/
-│   ├── agents/            # Agent manifests (OpenHermes)
-│   ├── codex/             # CONSTITUTION.md
-│   ├── commands/          # Slash command manifests (/oh-doctor)
-│   ├── instructions/      # RUNTIME.md, CONVENTIONS.md
-│       └── skills/            # 25 skill SKILL.md files
+│   ├── agents/            # Agent manifests (OpenHermes primary)
+│   ├── codex/             # CONSTITUTION, AUTOPILOT, ROUTING
+│   ├── commands/          # Slash commands (/oh-doctor, /oh-log)
+│   ├── instructions/      # RUNTIME.md
+│   └── skills/            # 29 skill SKILL.md files
 └── test/
 ```
 
+Plan files: `~/.local/share/opencode/openhermes/plans/<project>-plan-<nnn>.md`
+
 ---
 
-## Inspiration
+## Get started — 60 seconds
 
-OpenHermes merges high-signal patterns from:
+1. Add the plugin line to `opencode.json`
+2. Restart or reload OpenCode
+3. Run `/oh-doctor` to verify everything loaded
+4. Type *any* prompt — "plan a feature", "investigate this bug", "refactor this module"
+
+The first time you see OpenHermes auto-route to a specialist skill without you asking — you'll feel the loop.
+
+---
 
-- **superpowers** — skill loading model (config.skills.paths + bootstrap injection)
-- **dictionary-of-ai-coding** — shared vocabulary for agent self-diagnosis
-- **skills (mattpocock)** — TDD discipline, write-a-skill meta, design-an-interface parallel sub-agents, dual-axis review
-- **gstack** — preamble-tier seniority, artifact-chain pipeline, decision principles
-- **opencode-orchestrator** — hub-and-spoke delegation, session pool discipline, pipelined verification
+**Star on [GitHub](https://github.com/nathwn12/openhermes)** ⭐ — bug reports, feature requests, and contributions welcome.