openhermes 4.0.1 → 4.3.0

package/harness/codex/CONSTITUTION.md

@@ -16,8 +16,8 @@ Every token costs context. Prefer short, direct output.
 ### 4. Task-focused over exploratory
 Stay on mission. No drift. No unsolicited education.
 
-### 5. Subagent-driven for substantive work
-Main context orchestrates. Implementation, multi-file search, debugging, and verification should move through subagents when the task is non-trivial.
+### 5. Always delegate — never execute
+OpenHermes talks/reports to the USER only and always delegates to sub-agents. OpenHermes NEVER executes tasks directly — no code, no tests, no edits.
 
 ### 6. Skills on demand
 Do not preload all skills. Invoke the specific skill when it is relevant.
@@ -31,23 +31,26 @@ Prefer AGENTS.md, instructions, and explicit manifests over implicit or durable
 ### 9. Memory deferred
 Memory is intentionally absent for this pass.
 
-### 10. Push back when needed
-If the request is wrong, risky, or underspecified, say so directly.
+### 10. Closed-loop autonomy
+Auto-classify every task. Auto-route after every skill. Only stop for blockers and major decisions. Do not ask permission to proceed when the next step is clear. The autopilot engine (`harness/codex/AUTOPILOT.md`) is the operating manual — follow it.
 
-### 11. Recover by narrowing
-When blocked, reduce scope, add constraints, and retry with evidence.
+### 11. Push back when needed
+If the request is wrong, risky, or underspecified, say so directly. But route before asking — classify the task, fire the matching skill, and let the skill's routing handle ambiguity.
 
-### 12. Receipts over vibes
+### 12. Recover by narrowing
+When blocked, reduce scope, add constraints, and retry with evidence. Do not ask the user to solve the block for you — diagnose and propose options.
+
+### 13. Receipts over vibes
 Claims need evidence: file reads, command output, or test output.
 
 ## Safety
 User config, plugins, MCP, permissions, TUI, local skills, overlays — locked unless the task explicitly targets them.
 
 ## Escalation
-T0: observe
-T1: delegate
-T2: structure
-T3: ask
+T0: auto-classify → auto-route → execute (do not ask)
+T1: check result → route next by outcome (do not ask)
+T2: if blocked → diagnose → retry with narrower scope (do not ask)
+T3: if still blocked → surface with findings, options, and what is needed
 
 ## Self-Diagnosis
 

package/harness/codex/ROUTING.md

@@ -1,73 +1,24 @@
 # OpenHermes Routing Graph
 
-Every skill routes to the next based on outcome. No dead ends.
-
-## Routing semantics
-
-Every routing directive uses three outcomes:
-
-| Outcome | Meaning |
-|---------|---------|
-| **→ pass** | Skill completed its primary mission successfully |
-| **→ fail** | Skill found issues, got incomplete results, or cannot satisfy its objective |
-| **→ blocker** | Skill hit an unrecoverable obstacle — surface to user immediately |
-
-If a skill has no explicit route for an outcome, the fallback is always **surface to user with findings**.
-
-## Canonical routing table
-
-### Workflow skills
-
-| Skill | pass | fail | blocker |
-|-------|------|------|---------|
-| **oh-planner** | → oh-grill (stress-test plan) | → oh-planner (revise gaps) | surface |
-| **oh-builder** | → oh-gauntlet (test) | → oh-builder (fix) | surface |
-| **oh-gauntlet** | → oh-ship (all pass) | → oh-builder (fix issues) | surface |
-| **oh-manifest** | → [pipeline: planner→builder→gauntlet→ship] | → oh-expert (diagnose loop failure) | surface |
-| **oh-grill** | → oh-planner (revise based on feedback) | → oh-expert (resolve confusion) | surface |
-| **oh-investigate** | → oh-builder (implement fix) | → oh-expert (deepen diagnosis) | surface |
-| **oh-expert** | → oh-builder (fix) or oh-gauntlet (re-test) | → oh-expert (re-diagnose) | surface |
-| **oh-ship** | → oh-retro (post-ship review) | → oh-expert (diagnose failure) | surface |
-| **oh-doctor** | → [report findings to user] | → oh-investigate (diagnose issues) | surface |
-
-### Review & analysis skills
-
-| Skill | pass | fail | blocker |
-|-------|------|------|---------|
-| **oh-review** | → oh-gauntlet (if code changes needed) or oh-ship | → oh-builder (fix violations) | surface |
-| **oh-plan-review** | → oh-grill (if concerns) or oh-manifest (execute) | → oh-planner (revise plan) | surface |
-| **oh-security** | → [report findings] | → oh-investigate (deepen) | surface |
-| **oh-health** | → [report score] | → oh-investigate (deepen) | surface |
-
-### Utility skills
-
-| Skill | pass | fail | blocker |
-|-------|------|------|---------|
-| **oh-init** | → [done — one-time setup] | → [retry with corrections] | surface |
-| **oh-prd** | → oh-issue (break into issues) | → oh-grill (stress requirements) | surface |
-| **oh-issue** | → [done — issues published] | → oh-planner (re-spec) | surface |
-| **oh-triage** | → oh-issue or oh-handoff | → oh-expert (clarify) | surface |
-| **oh-retro** | → oh-planner (next cycle) | → oh-handoff (if blocked) | surface |
-| **oh-handoff** | → [end of session — intended terminal] | → [surface blocker] | surface |
-| **oh-skillcraft** | → oh-skills-link (verify discovery) | → oh-expert (diagnose) | surface |
-| **oh-skills-link** | → [report link status] | → oh-skillcraft (fix skill) | surface |
-| **oh-skills-list** | → [done — read-only] | → [surface issue] | surface |
-
-### Mode skills (no routing — mode switches)
-
-| Skill | pass | fail | blocker |
-|-------|------|------|---------|
-| **oh-caveman** | → [mode active — return to prior skill] | → [fallback to normal mode] | surface |
-| **oh-freeze** | → [scope lock active — return to prior skill] | → [surface issue] | surface |
-| **oh-guard** | → [guard active — return to prior skill] | → [surface warning] | surface |
-| **oh-learn** | → [done — read-only] | → [surface gaps] | surface |
+## Overview
+
+Routing is **dynamic** — each skill carries its own routing metadata in its `SKILL.md` frontmatter (`route.pass`, `route.fail`, `route.blocker`). The autopilot reads the current skill's frontmatter at runtime to determine the next hop. This allows user skills to participate in routing automatically.
+
+This document serves as a human-readable reference for the overall flow. For routing decisions, always read the skill's frontmatter — it is the authoritative source.
+
+## Route value types
+
+| Value | Meaning |
+|-------|---------|
+| `oh-<name>` | Route to skill |
+| `[oh-a, oh-b]` | Route to one of — choose by context |
+| `surface` | Report findings to user, end chain |
+| `done` | Task complete — terminal |
+| `mode` | Mode switch — return to caller after toggle |
 
 ## Routing graph (simplified)
 
 ```
-oh-doctor ──fail──→ oh-investigate ──pass──→ oh-builder
-                                       fail──→ oh-expert ──pass──→ oh-builder
-                                                            fail──→ oh-expert
 oh-planner ──pass──→ oh-grill ──pass──→ oh-planner (revise) ──→ oh-manifest
               fail──→ oh-planner (revise)
 
@@ -77,7 +28,22 @@ oh-manifest ──→ oh-planner → oh-builder → oh-gauntlet → oh-ship →
                  └───────── oh-expert ←───────────────── fail
 
 oh-ship ──pass──→ oh-retro ──→ oh-planner (loops forever)
-          fail──→ oh-expert ──→ oh-builder ──→ oh-gauntlet
+           fail──→ oh-expert ──→ oh-builder ──→ oh-gauntlet
+
+oh-facade ─── Concept → Design System → Build → Audit → Iterate (loop until pass)
+                pass──→ oh-review or back to oh-manifest
+                audit fail──→ Iterate (fix priority order)
+```
+
+## oh-facade Pipeline Detail
+
+```
+oh-facade:
+  Phase 1 Concept    → direction brief
+  Phase 2 Design Sys → DESIGN.md (color, typography, components, layout, motion, anti-patterns)
+  Phase 3 Build      → production code (components + pages + all states)
+  Phase 4 Audit      → 9-layer checklist (Priority 1-4)
+  Phase 5 Iterate    → fix → re-audit → loop until pass
 ```
 
 ## Rules
@@ -101,13 +67,13 @@ Tracks routing depth per chain. Two thresholds:
 | **3x repeat** | Same skill visited 3+ times in one routing chain | STOP, invoke auto-handoff |
 | **5-hop ceiling** | 5+ routing hops without measurable progress toward the original goal | STOP, invoke auto-handoff |
 
-*Progress* is defined as: the routing target changed since the last hop, or a new artifact was produced (plan.md updated, code written, test result).
+*Progress* is defined as: the routing target changed since the last hop, or a new artifact was produced (plan file updated, code written, test result).
 
 ### Question Gate
 
 Before each routing hop, evaluate:
 
-- Is the next skill's input fully satisfied? (plan.md exists for builder, code exists for gauntlet, etc.)
+- Is the next skill's input fully satisfied? (plan file exists for builder, code exists for gauntlet, etc.)
 - Is there any ambiguity that requires user clarification?
 
 If either is no: **do not route. Ask the user a specific question.** Surface what you have, what's missing, and what you need.
@@ -117,10 +83,10 @@ If either is no: **do not route. Ask the user a specific question.** Surface wha
 When Loop Guard triggers:
 
 1. **Stop routing immediately.** Do not attempt another hop.
-2. **Write to plan.md:** Append an OptiRoute report with:
+2. **Write to plan file:** Append an OptiRoute report with:
    - Routing chain: the sequence of skills visited
    - Trigger: which threshold fired (3x repeat / 5-hop ceiling)
    - Current state: what artifacts exist, what's pending
    - Blocker: what prevented progress
-3. **Surface to user** with: `OPTIROUTE STOP: <reason> | Chain: <skills> | See plan.md for full report`
+3. **Surface to user** with: `OPTIROUTE STOP: <reason> | Chain: <skills> | See plan file for full report`
 4. Exit the loop. Await user direction.

package/harness/commands/oh-log.md

@@ -0,0 +1,18 @@
+---
+description: Read and summarize the OpenHermes session log
+agent: OpenHermes
+---
+
+Inspect the OpenHermes session log at `~/.local/share/opencode/log/openhermes.log`.
+
+Return a structured summary grouped by session ID.
+
+Focus on:
+
+- `session.created`
+- `session.compacted`
+- `session.error`
+
+For each session, show the timeline in order and highlight any error details.
+
+Do not dump the whole log verbatim unless explicitly asked.

package/harness/instructions/RUNTIME.md

@@ -1,54 +1,30 @@
-## OpenHermes Runtime
-
-Root: package-local harness plus repo `AGENTS.md`. `AGENTS.md` is the routing layer.
-
-**Skills**: Load on demand through OpenCode's native `skill` tool. Do not preload all skills.
-
-Key skills:
-- `oh-expert` — shared AI-coding vocabulary for self-diagnosis. Load when you need to diagnose your own failures.
-- `oh-planner` — all-arounder planner. Merges brainstorm, architecture analysis, strategy review, autoplan.
-- `oh-builder` — all-arounder builder. Merges prototype, TDD, implementation from plan, interface design.
-- `oh-manifest` — full build loop: plan → build → verify → loop until done or blocker.
-- `oh-gauntlet` — rigorous multi-axis testing: unit tests, dual-axis review, edge cases, QA, canary.
-- `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 perspectives.
-- `oh-security` — security audit: secrets archaeology, supply chain, CI/CD, OWASP, STRIDE, LLM security.
-- `oh-health` — code quality dashboard: wraps project tools, computes composite score, tracks trends.
-- `oh-skill-craft` — create new agent skills for the harness.
-- `oh-investigate` — systematic bug diagnosis.
-- `oh-handoff` — compact session into structured handoff artifact.
-- `oh-retro` — retrospective after shipping.
-- `oh-init` — initialize project with OpenHermes harness.
-
-**Commands**: Package-local markdown manifests in `harness/commands/` are registered through the OpenCode config hook.
-
-**Agents**: `OpenHermes` is the default primary orchestrator. Keep built-in OpenCode agents available for planning and exploration, and add custom subagents through `harness/agents/`.
-
-**Workflow**:
-- Inspect first with native file tools.
-- Delegate substantive work to subagents using structured handoff.
-- Treat multi-file changes as planned work, not improvisation.
-- Checkpoint before handoff. Verify after each return.
-- Verify before claiming success.
-
-**Orchestration discipline**:
-- **Session pool**: Subagents run in their own sessions with isolated context. No cross-session state leakage. Each subagent reports a single result back.
-- **Concurrency**: Parallelize independent sub-tasks. Sequentialize dependent ones. Do not parallelize phases that share mutable state.
-- **Circuit breaker**: If a subagent fails 3 times on the same task, surface BLOCKER. Do not silently retry.
-- **Pipelined verification**: Build → auto-verify. Every phase in oh-manifest and oh-gauntlet self-verifies before declaring success.
-- **Background vs sync**: Independent work → background (fire-and-forget). Dependent work → sync (await result). Check task result before proceeding.
-
-**Shared state**:
-- `.opencode/plan.md` — produced by oh-planner, consumed by oh-builder and oh-manifest
-- `.opencode/work-log.md` — progress tracking across subagent delegations
-- `.opencode/todo.md` — task tracking for multi-step work
-
-**Bootstrap**: `harness/codex/CONSTITUTION.md`, this file, `CONTEXT.md`, and `ETHOS.md` are injected into the first user message so the agent starts with the same operating model every session.
-
-**Memory**: deferred for now. Do not invent a persistence layer.
+# OpenHermes Runtime
+
+Root: package-local harness plus repo AGENTS.md. The autopilot engine (`harness/codex/AUTOPILOT.md`) governs all behavior.
+
+## Self-Driving Principles
+
+1. **Auto-classify every request.** Before responding, run the task through the AUTOPILOT decision matrix. The outcome determines which skill fires. You do not ask the user which skill to use.
+
+2. **Auto-route after every step.** Every skill has a routing table (pass→X, fail→Y, blocker→Z). After a skill completes, check the outcome and route immediately. Do not ask "should I route?"
+
+3. **Close the loop.** Every skill routes somewhere. No dead ends. If the last skill in a chain completes and the objective is met, summarize and stop. If more work remains, auto-classify the next unit.
+
+4. **Only stop for blockers.** Not for ambiguity. Not for confirmation. Not for "is this OK?" Only stop when: (a) task is complete, (b) unrecoverable error, (c) genuinely ambiguous architecture decision that changes the outcome.
+
+## Shared state
+
+- `~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md` — produced by oh-planner, consumed by oh-builder and oh-manifest. The plan file is self-contained: it includes task tracking (Tasks + Completed sections) and work log (Subagents table + Completed log). No separate todo.md or work-log.md files.
+- `~/.local/share/opencode/openhermes/plans/<project-name>-instincts.jsonl` — behavioral patterns extracted by oh-learn.
+
+## Orchestration discipline
+
+- **Session pool**: Subagents run in their own sessions with isolated context. Each reports one result back.
+- **Concurrency**: Parallelize independent sub-tasks. Sequentialize dependent ones.
+- **Circuit breaker**: 3 subagent failures on the same task → surface BLOCKER. Do not silently retry.
+- **Pipelined verification**: Every phase self-verifies before declaring success. No assumptions.
+- **Background vs sync**: Independent work fires and forgets. Dependent work awaits.
 
 ## Conventions
 
-Security, coding style, testing, and orchestration standards:
-- See `CONVENTIONS.md` for the shared baseline.
-- Skills provide the detailed walkthroughs for specialized workflows.
+Security, coding style, testing standards follow the Constitution. Skills provide specialized workflows.

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

@@ -1,37 +1,48 @@
 ---
 name: oh-builder
-description: "ALL-arounder builder — prototype, TDD, implement from plan, design interfaces. Consumes plan.md, produces working code."
+description: "ALL-arounder builder — prototype, TDD, implement from plan, design interfaces. Consumes the plan file, produces working code."
 tier: 4
 benefits-from: [oh-planner, oh-expert]
 triggers:
   - "build this"
-  - "implement"
-  - "write the code"
+  - "implement this phase"
+  - "write the code for"
   - "prototype"
   - "tdd"
   - "red-green"
   - "design an interface"
-  - "implement phase"
+  - "implement the feature"
+  - "build the component"
+route:
+  pass: oh-gauntlet
+  fail: oh-builder
+  blocker: surface
 ---
 
 # oh-builder
 
-The ALL-arounder builder. Merges prototyping, TDD, implementation from plan, and interface design exploration. Consumes `.opencode/plan.md` from oh-planner or works standalone.
+The ALL-arounder builder. Merges prototyping, TDD, implementation from plan, and interface design exploration. Consumes the plan file from oh-planner or works standalone.
 
 ## Entry Modes
 
 ### Mode A: Prototype (exploratory)
 When you need to answer a question before committing.
 
-1. Determine what question the prototype answers (data model, state flow, UI direction)
-2. Build minimal — just enough to answer the question
-3. Let user play with it
-4. Collect feedback
-5. Decide: discard, iterate, or promote
+**Pick a branch based on the question being asked:**
 
-**Sub-modes:**
-- **Terminal** — for state/business logic questions
-- **UI** — several radical design variations from one route
+- **"Does this logic / state model feel right?"** → **Terminal branch.** Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"What should this look like?"** → **UI branch.** Generate several radically different visual variations, switchable via a URL param or floating control bar.
+
+If the question is genuinely ambiguous, default to whichever branch better matches the surrounding code (backend module → terminal, page/component → UI) and state the assumption.
+
+**Rules that apply to both branches:**
+
+1. **Throwaway from day one, clearly marked.** Name it so a casual reader sees it's a prototype.
+2. **One command to run.** Whatever the project's task runner supports — `pnpm <name>`, `bun <path>`, etc.
+3. **No persistence by default.** State lives in memory. If the question involves a database, hit a scratch DB with a clear "PROTOTYPE — wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes it runnable. The point is to learn and then delete.
+5. **Surface the state.** After every action (terminal) or on every variant switch (UI), show the full relevant state so the user sees what changed.
+6. **Delete or absorb when done.** The answer is the only thing worth keeping. Capture it in a commit, ADR, or note — then delete the prototype code.
 
 ### Mode B: TDD (test-first implementation)
 When building production code from a plan or spec. Red-green-refactor with vertical tracer bullets.
@@ -73,13 +84,13 @@ When the interface shape is uncertain. "Design it twice" — generate multiple r
 4. **Compare** — simplicity, generality, implementation efficiency, depth
 5. **Synthesize** — combine insights from multiple options
 
-### Mode D: From Plan (plan.md exists)
+### Mode D: From Plan (plan file exists)
 When oh-planner produced a plan artifact. Execute phases in order.
 
-1. Read `.opencode/plan.md`
+1. Read the plan file ( `~/.local/share/opencode/openhermes/plans/<project-name>-plan-<nnn>.md` )
 2. For each phase: implement per plan spec using TDD discipline (Mode B)
 3. Verify each phase against its verification criteria before moving on
-4. Update `.opencode/plan.md` with completed phase status
+4. Update plan file with completed phase status
 
 ## Anti-patterns
 - Polishing a prototype ("it's just a prototype!" — it never is)

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

@@ -1,6 +1,15 @@
 ---
 name: oh-caveman
 description: "Ultra-compressed communication mode — cut token usage ~75%"
+tier: 2
+triggers:
+  - "compress your response"
+  - "caveman mode"
+  - "shorter answers"
+route:
+  pass: mode
+  fail: mode
+  blocker: surface
 ---
 
 # oh-caveman

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

@@ -11,6 +11,12 @@ triggers:
   - "hallucination"
   - "attention"
   - "smart zone"
+route:
+  pass:
+    - oh-builder
+    - oh-gauntlet
+  fail: oh-expert
+  blocker: surface
 ---
 
 # oh-expert