openhermes 4.0.1 → 4.3.0

package/bootstrap.ts

@@ -0,0 +1,405 @@
+import path from "node:path"
+import fs from "node:fs"
+import os from "node:os"
+import { fileURLToPath } from "node:url"
+import type { Plugin } from "@opencode-ai/plugin"
+import { createLogger } from "./lib/logger.ts"
+import { getHarnessDir, setHarnessRootForTest, resolveHarnessRoot } from "./lib/harness-resolver.ts"
+
+const log = createLogger("bootstrap")
+const sessionLog = createLogger("session")
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const BOOTSTRAP_MARKER = "OPENHERMES_BOOTSTRAP"
+const OPENHERMES_AGENT = "OpenHermes"
+
+// Canonical storage under OpenCode's data directory — survives npm updates
+let _planStorageOverride: string | undefined
+export function setPlanStorageDirForTest(dir: string | undefined): void { _planStorageOverride = dir }
+function planStorageDir(): string {
+  return _planStorageOverride ?? path.join(os.homedir(), ".local", "share", "opencode", "openhermes", "plans")
+}
+
+function getProjectName(projectDir: string): string {
+  return path.basename(projectDir)
+}
+
+// User skill directories — auto-scanned on every session, survive npm updates
+const USER_SKILL_DIRS: ReadonlyArray<string> = [
+  path.join(os.homedir(), ".agents", "skills"),
+  path.join(os.homedir(), ".config", "opencode", "skills"),
+]
+
+export { resolveHarnessRoot, setHarnessRootForTest, getHarnessDir }
+
+function parseFrontmatter(raw: string | undefined): Record<string, string> {
+  const frontmatter: Record<string, string> = {}
+  if (!raw) return frontmatter
+  for (const line of raw.split(/\r?\n/)) {
+    const idx = line.indexOf(":")
+    if (idx < 0) continue
+    const key = line.slice(0, idx).trim()
+    const value = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, "")
+    if (key) frontmatter[key] = value
+  }
+  return frontmatter
+}
+
+interface MarkdownDocument {
+  frontmatter: Record<string, string>
+  body: string
+}
+
+function readMarkdownDocument(filePath: string): MarkdownDocument | null {
+  if (!fs.existsSync(filePath)) return null
+  const source = fs.readFileSync(filePath, "utf8")
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/)
+  const frontmatter = parseFrontmatter(match?.[1] ?? "")
+  const body = (match ? match[2] : source).trim()
+  return { frontmatter, body }
+}
+
+interface DirEntry extends MarkdownDocument {
+  name: string
+}
+
+function readMarkdownDirectory(dir: string): DirEntry[] {
+  if (!fs.existsSync(dir)) return []
+  return fs.readdirSync(dir)
+    .filter(name => name.endsWith(".md") && name.toLowerCase() !== "readme.md")
+    .sort((a, b) => a.localeCompare(b))
+    .map(name => {
+      const filePath = path.join(dir, name)
+      const document = readMarkdownDocument(filePath)
+      return document ? { name: path.basename(name, ".md"), ...document } : null
+    })
+    .filter((e): e is DirEntry => e !== null)
+}
+
+interface CommandDef {
+  description: string
+  template: string
+  agent?: string
+  model?: string
+  subtask?: boolean
+}
+
+function commandDefinitions(dir: string): Record<string, CommandDef> {
+  const commands: Record<string, CommandDef> = {}
+  for (const doc of readMarkdownDirectory(dir)) {
+    const command: CommandDef = {
+      description: doc.frontmatter.description || `OpenHermes command ${doc.name}`,
+      template: doc.body,
+    }
+    if (doc.frontmatter.agent) command.agent = doc.frontmatter.agent
+    if (doc.frontmatter.model) command.model = doc.frontmatter.model
+    if (doc.frontmatter.subtask) command.subtask = doc.frontmatter.subtask === "true"
+    commands[doc.name] = command
+  }
+  return commands
+}
+
+interface AgentDef {
+  description: string
+  mode: string
+  prompt: string
+}
+
+function agentDefinitions(dir: string): Record<string, AgentDef> {
+  const agents: Record<string, AgentDef> = {}
+  for (const doc of readMarkdownDirectory(dir)) {
+    const name = doc.name === "openhermes" ? OPENHERMES_AGENT : doc.name
+    agents[name] = {
+      description: doc.frontmatter.description || (name === OPENHERMES_AGENT ? "OpenHermes primary orchestrator" : `OpenHermes agent ${name}`),
+      mode: doc.frontmatter.mode || (name === OPENHERMES_AGENT ? "primary" : "subagent"),
+      prompt: doc.body,
+    }
+  }
+  return agents
+}
+
+function uniqueStrings(existing: string[] = [], additions: string[] = []): string[] {
+  const seen = new Set(existing.filter(Boolean))
+  const merged = [...existing]
+  for (const item of additions) {
+    if (!item || seen.has(item)) continue
+    seen.add(item)
+    merged.push(item)
+  }
+  return merged
+}
+
+function readText(filePath: string): string {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : ""
+}
+
+function regexEscape(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+function findLatestPlanFile(projectDir: string): string | null {
+  const projectName = getProjectName(projectDir)
+  const storage = planStorageDir()
+  if (!fs.existsSync(storage)) return null
+  const pattern = new RegExp(`^${regexEscape(projectName)}-plan-(\\d{3})\\.md$`)
+  let latest: string | null = null
+  let highest = -1
+  try {
+    for (const entry of fs.readdirSync(storage)) {
+      const m = entry.match(pattern)
+      if (m) {
+        const n = parseInt(m[1], 10)
+        if (n > highest) {
+          highest = n
+          latest = path.join(storage, entry)
+        }
+      }
+    }
+  } catch {
+    return null
+  }
+  return latest
+}
+
+function readPlanFromFile(filePath: string): string | null {
+  if (!fs.existsSync(filePath)) return null
+  const source = fs.readFileSync(filePath, "utf8")
+  const status = source.match(/^Status:\s*(.+)$/m)?.[1]?.trim()
+  const objective = source.match(/^Objective:\s*(.+)$/m)?.[1]?.trim()
+  if (!status && !objective) return null
+  const parts = [status ? `status=${status}` : null, objective ? `objective=${objective}` : null].filter(Boolean)
+  return `Active plan: ${parts.join(" | ")}`
+}
+
+function readPlanSummary(projectDir: string): string | null {
+  const planFile = findLatestPlanFile(projectDir)
+  if (!planFile) return null
+  return readPlanFromFile(planFile)
+}
+
+function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+function countSkills(dir: string): number {
+  try {
+    return fs.readdirSync(dir).filter(e => {
+      const full = path.join(dir, e)
+      return fs.statSync(full).isDirectory() && fs.existsSync(path.join(full, "SKILL.md"))
+    }).length
+  } catch {
+    return 0
+  }
+}
+
+export function buildCompactionContext(projectDir: string): string[] {
+  const context = [
+    "OpenHermes: native-first, verify before claim, always delegate, concise over verbose.",
+    "Preserve domain terms: skill, command, agent, bootstrap, compaction.",
+    "Preserve blockers, current task, and next steps; do not invent durable state.",
+  ]
+
+  const planSummary = readPlanSummary(projectDir)
+  if (planSummary) context.push(planSummary)
+
+  return context
+}
+
+type SessionLifecycleEvent =
+  | { type: "session.created"; properties: { info: { id: string } } }
+  | { type: "session.compacted"; properties: { sessionID: string } }
+  | { type: "session.error"; properties: { sessionID?: string; error?: unknown } }
+
+function readErrorMessage(error: unknown): string {
+  if (!error || typeof error !== "object") return "unknown error"
+  const value = error as { name?: unknown; message?: unknown; data?: { message?: unknown } }
+  const name = typeof value.name === "string" && value.name ? value.name : "Error"
+  const message = typeof value.data?.message === "string" && value.data.message ? value.data.message : typeof value.message === "string" && value.message ? value.message : ""
+  return message ? `${name}: ${message}` : name
+}
+
+export function formatSessionEvent(event: SessionLifecycleEvent): { level: "info" | "error"; message: string } | null {
+  switch (event.type) {
+    case "session.created":
+      return { level: "info", message: `session.created session=${event.properties.info.id}` }
+    case "session.compacted":
+      return { level: "info", message: `session.compacted session=${event.properties.sessionID}` }
+    case "session.error":
+      return { level: "error", message: `session.error session=${event.properties.sessionID ?? "unknown"} error=${readErrorMessage(event.properties.error)}` }
+    default:
+      return null
+  }
+}
+
+function parseRouteYaml(raw: string): { pass: string; fail: string; blocker: string } {
+  const def: { pass: string; fail: string; blocker: string } = { pass: "surface", fail: "surface", blocker: "surface" }
+  const m = raw.match(/route:\n((?:  [^\n]*\n?)*)/)
+  if (!m) return def
+  const block = m[1]
+
+  const kv = (key: string): string | undefined => {
+    // Single-line:  pass: oh-builder  (horizontal whitespace only, no newlines)
+    const s = block.match(new RegExp(`  ${key}:[ \\t]*(\\S.*)`))
+    if (s) return s[1].trim()
+    // Multi-line array:  pass:\n    - oh-builder\n    - oh-gauntlet
+    const a = block.match(new RegExp(`  ${key}:\\n((?:    - .+\\n?)*)`))
+    if (a) {
+      const items = a[1].match(/    - (.+)/g)?.map(i => i.replace(/    - /, "").trim()) ?? []
+      return items.length > 0 ? `[${items.join(", ")}]` : undefined
+    }
+    return undefined
+  }
+
+  const p = kv("pass")
+  const f = kv("fail")
+  const b = kv("blocker")
+  if (p) def.pass = p
+  if (f) def.fail = f
+  if (b) def.blocker = b
+  return def
+}
+
+function buildRoutingInventory(skillDirs: string[]): string {
+  const rows: string[] = []
+  for (const dir of skillDirs) {
+    let entries: string[] = []
+    try { entries = fs.readdirSync(dir).filter(e => fs.statSync(path.join(dir, e)).isDirectory()) } catch { continue }
+    for (const name of entries.sort()) {
+      const skPath = path.join(dir, name, "SKILL.md")
+      if (!fs.existsSync(skPath)) continue
+      const raw = fs.readFileSync(skPath, "utf8").replace(/\r\n/g, "\n")
+      const fm = raw.match(/^---\n([\s\S]*?)\n---/)
+      if (!fm) continue
+      const route = parseRouteYaml(fm[1])
+      rows.push(`| **${name}** | ${route.pass} | ${route.fail} | ${route.blocker} |`)
+    }
+  }
+  if (rows.length === 0) return ""
+  const header = "## Dynamic Routing Inventory\n\nAll skills and their routes:\n\n| Skill | pass | fail | blocker |\n|---|---|---|---|\n"
+  return header + rows.join("\n")
+}
+
+function buildBootstrapContent(hDir: string, extraDirs: string[] = []): string {
+  const parts = [
+    `<${BOOTSTRAP_MARKER}>`,
+    `You are OpenHermes.`,
+    `OpenHermes is OpenCode-native: load skills on demand, always delegate, never execute tasks directly, and keep the surface small.`,
+    `Durable state is removed for now. Do not invent a persistence layer unless the user explicitly asks for one later.`,
+  ]
+
+  const autopilot = readText(path.join(hDir, "codex", "AUTOPILOT.md"))
+  const constitution = readText(path.join(hDir, "codex", "CONSTITUTION.md"))
+  const runtime = readText(path.join(hDir, "instructions", "RUNTIME.md"))
+  const context = readText(path.join(__dirname, "CONTEXT.md"))
+  const ethos = readText(path.join(__dirname, "ETHOS.md"))
+
+  if (autopilot) parts.push(`<AUTOPILOT>\n${autopilot}\n</AUTOPILOT>`)
+  if (constitution) parts.push(`<CONSTITUTION>\n${constitution}\n</CONSTITUTION>`)
+  if (runtime) parts.push(`<RUNTIME>\n${runtime}\n</RUNTIME>`)
+  if (context) parts.push(`<CONTEXT>\n${context}\n</CONTEXT>`)
+  if (ethos) parts.push(`<ETHOS>\n${ethos}\n</ETHOS>`)
+
+  // Dynamic routing inventory: built-in skills + user skills
+  const allSkillDirs = [path.join(hDir, "skills"), ...extraDirs.filter(Boolean)]
+  const inventory = buildRoutingInventory(allSkillDirs)
+  if (inventory) parts.push(inventory)
+
+  parts.push(`</${BOOTSTRAP_MARKER}>`)
+
+  return parts.join("\n\n")
+}
+
+interface OpenHermesConfig {
+  skills?: { paths?: string[] }
+  command?: Record<string, unknown>
+  agent?: Record<string, unknown>
+  instructions?: string[]
+  default_agent?: string
+}
+
+export const BootstrapPlugin: Plugin = async (ctx) => {
+  const hDir = getHarnessDir()
+  const skillsDir = path.join(hDir, "skills")
+  const commandsDir = path.join(hDir, "commands")
+  const agentsDir = path.join(hDir, "agents")
+  // Auto-detect and wire user skills from ~/.agents/skills and ~/.config/opencode/skills
+  // (Must happen before bootstrapContent is built so routing inventory includes user skills)
+  const userSkillPaths: string[] = []
+  for (const userDir of USER_SKILL_DIRS) {
+    ensureDir(userDir)
+    const count = countSkills(userDir)
+    if (count > 0) {
+      userSkillPaths.push(userDir)
+      log.info(`found ${count} user skill(s) in ${userDir}`)
+    }
+  }
+
+  const bootstrapContent = buildBootstrapContent(hDir, userSkillPaths)
+  const compactionContext = buildCompactionContext(ctx.directory)
+  const builtInCount = countSkills(skillsDir)
+  const userCount = userSkillPaths.reduce((sum, d) => sum + countSkills(d), 0)
+
+  // Ensure plan storage exists
+  ensureDir(planStorageDir())
+
+  return {
+    config: async (config: OpenHermesConfig) => {
+      config.skills = config.skills || {}
+      // Built-in paths first, user paths last → user skills override built-in on name conflict
+      const allPaths = [skillsDir, ...userSkillPaths]
+      config.skills.paths = uniqueStrings(config.skills.paths || [], allPaths)
+
+      log.info(`skills: ${builtInCount} built-in + ${userCount} user (${allPaths.length} path(s))`)
+
+      config.command = { ...(config.command ?? {}), ...commandDefinitions(commandsDir) }
+
+      const loadedAgents = agentDefinitions(agentsDir)
+      const openHermesAgent = loadedAgents[OPENHERMES_AGENT] ?? {
+        description: "OpenHermes primary orchestrator",
+        mode: "primary",
+        prompt: "You are OpenHermes.",
+      }
+
+      config.agent = {
+        ...(config.agent ?? {}),
+        ...loadedAgents,
+        [OPENHERMES_AGENT]: {
+          ...openHermesAgent,
+          description: openHermesAgent.description || "OpenHermes primary orchestrator",
+          mode: "primary",
+          permission: {
+            bash: { "*": "allow" },
+            edit: "allow",
+            read: "allow",
+            task: { "*": "allow" },
+          },
+        },
+      }
+
+      config.default_agent = OPENHERMES_AGENT
+    },
+
+    event: async ({ event }) => {
+      const record = formatSessionEvent(event as SessionLifecycleEvent)
+      if (!record) return
+      sessionLog[record.level](record.message)
+    },
+
+    "experimental.session.compacting": async (_input, output) => {
+      output.context.push(...compactionContext)
+    },
+
+    "experimental.chat.messages.transform": async (_input: unknown, output: { messages?: Array<{ info?: { role?: string }; parts?: Array<{ text?: string; type?: string }> }> }) => {
+      try {
+        if (!output.messages?.length) return
+        const firstUser = output.messages.find(m => m?.info?.role === "user")
+        if (!firstUser?.parts?.length) return
+        if (firstUser.parts.some(p => p.text?.includes(BOOTSTRAP_MARKER))) return
+        firstUser.parts.unshift({ type: "text", text: bootstrapContent })
+      } catch (err: unknown) {
+        log.error("transform error:", (err as Error)?.message)
+      }
+    },
+  }
+}

package/harness/agents/openhermes.md

@@ -1,61 +1,49 @@
 ---
-description: OpenHermes primary orchestrator
+description: OpenHermes primary orchestrator — auto-routing closed-loop hub
 mode: primary
 ---
 
 You are OpenHermes, the primary orchestrator for this package.
 
-Behavior:
+## Operating Mode: SELF-DRIVING
 
-- Use OpenCode-native skills on demand.
-- Prefer the smallest correct change.
-- Delegate substantive multi-file work to subagents.
-- Keep responses terse and evidence-based.
-- Follow the package constitution, runtime notes, shared context, and ethos.
-- Plan first, verify before claiming success, and summarize with receipts.
+This is a fully closed-loop system. You auto-classify, auto-route, and auto-execute. You do not ask for permission to proceed. You only stop for genuine blockers.
 
-## Orchestration Model
+**The autopilot engine (`harness/codex/AUTOPILOT.md`) governs every session.** Read it. Follow it. It is not optional.
 
-Hub-and-spoke. You (OpenHermes) are the hub. Delegate to specialists:
+### Ground Rules
 
-- **oh-planner** — for planning, architecture, strategy, brainstorming. Produces `.opencode/plan.md`.
-- **oh-builder** — for implementation, TDD, prototyping, interface design. Consumes plan.md.
-- **oh-manifest** — for full build loops: plan → build → verify → loop. Orchestrates planner + builder.
-- **oh-gauntlet** — for rigorous multi-axis testing: unit tests, review, edge cases, QA, canary.
-- **oh-expert** — for AI self-diagnosis (sycophancy, hallucination type, attention degradation).
-- **oh-grill** — for stress-testing plans and designs through questioning.
-- **oh-investigate** — for systematic bug diagnosis.
+1. **Auto-classify before every response.** Multi-step or aimless? → oh-planner. Bug? → oh-investigate. Security? → oh-security. Code review? → oh-review. Simple edit? → do it directly. The AUTOPILOT decision matrix is your classification authority.
+2. **Auto-route after every skill.** Pass? Route by the skill's routing table. Fail? Route by the skill's routing table. Do not ask. Do not pause. Route.
+3. **Close the loop.** No dead ends. Every skill routes somewhere. Only oh-handoff ends a session.
+4. **Stop only for:** (a) task complete, (b) real blocker, (c) major architecture decision that changes the outcome. Do NOT stop for "should I?" questions — just do the next correct thing.
 
-## Auto-Routing
+### Orchestration Model
 
-Every skill routes to the next based on outcome. No dead ends. The canonical routing graph is defined in `harness/codex/ROUTING.md`.
+Hub-and-spoke. You are the hub. Skills are loaded on demand through the skill tool. Delegate to specialists:
 
-### Entry triggers
+- **oh-planner** — planning, architecture, strategy, brainstorming. Produces `<project>-plan-<nnn>.md`.
+- **oh-builder** — implementation, TDD, prototyping, interface design. Consumes the plan file.
+- **oh-manifest** — full build loops: plan → build → verify → loop. Orchestrates planner + builder.
+- **oh-gauntlet** — multi-axis testing: unit tests, review, edge cases, QA, canary.
+- **oh-expert** — AI self-diagnosis (sycophancy, hallucination type, attention degradation).
+- **oh-grill** — stress-test plans and designs through questioning.
+- **oh-investigate** — systematic bug diagnosis.
+- **oh-review** — two-axis code and design review.
+- **oh-ship** — deploy, version bump, changelog, PR.
+- **oh-security** — security audit, threat model.
+- **oh-health** — code quality dashboard.
+- **oh-refactor** — surgical behavior-preserving refactoring.
+- **oh-facade** — full UI pipeline: concept → design system → build → audit → iterate.
+- **oh-full-output** — override LLM truncation, ban placeholder patterns, enforce complete generation.
+- **oh-fusion** — skill ingestion pipeline: discover → analyze → filter → adapt → fuse → integrate.
+- **oh-handoff** — compact session state for context switch.
 
-Evaluate the request and load the matching skill as a subagent:
+### Auto-Routing Graph
 
-| When the task is… | Load skill |
-|---|---|
-| Planning, architecture, strategy, brainstorming, scoping | oh-planner |
-| Implementation, building, prototyping, TDD, coding from spec | oh-builder |
-| Full build pipeline (plan → build → verify → loop) | oh-manifest |
-| Testing, QA, edge case sweep, validation gate, "run the gauntlet" | oh-gauntlet |
-| AI self-diagnosis, sycophancy check, hallucination check, attention check | oh-expert |
-| Stress-testing a plan, challenging assumptions, "grill me" | oh-grill |
-| Bug diagnosis, root cause investigation, "why is this broken" | oh-investigate |
-| Deploy, version bump, changelog, PR | oh-ship |
-| Security audit, threat model, vulnerability scan | oh-security |
-| Code quality dashboard, run all checks | oh-health |
-| Code review, PR review, design review | oh-review |
-| Review existing plan, architecture review | oh-plan-review |
-| Retrospective, post-ship review | oh-retro |
-| Session handoff, context switch | oh-handoff |
-| Diagnose self, check for sycophancy/hallucination | oh-expert |
-
-### Outcome-based routing
-
-After a skill completes, route to the next skill based on outcome. See `harness/codex/ROUTING.md` for the full graph. The core loop is:
+The canonical routing graph is in `harness/codex/ROUTING.md`. Follow it exactly.
 
+Core loop:
 ```
 oh-planner → oh-grill → oh-planner (revise) → oh-manifest
                                                       ↓
@@ -65,23 +53,25 @@ oh-manifest → oh-planner → oh-builder → oh-gauntlet → oh-ship → oh-ret
                 └──────── oh-expert ←── fail ──── oh-expert
 ```
 
-If a task spans multiple domains (e.g., "build and test this feature"), load the orchestrator (`oh-manifest`) which chains planner → builder → verify → ship → retro → back to planning. Do not load skills that don't match the task.
+### OptiRoute Protocol
+
+Three safety layers on top of every routing hop:
 
-### OptiRoute: Smart Auto-Routing Protocol
+**Loop Guard.** Same skill 3+ times in one chain, or 5+ hops without progress → STOP, write report to the plan file, surface to user.
 
-Three safety layers on top of every routing hop. Full spec in `harness/codex/ROUTING.md`.
+**Question Gate.** Before routing, check: "Can I proceed without guessing?" If the next skill's input is missing and you cannot create or discover it independently → surface. Do NOT route into guaranteed failure.
 
-**Loop Guard.** Track routing depth. If the same skill is visited 3+ times in one chain, or 5+ hops pass without measurable progress (new artifact, changed target) — stop, report, await user.
+**Auto-Handoff.** When Loop Guard triggers: write OptiRoute report, surface `OPTIROUTE STOP: <reason>`, exit loop.
 
-**Question Gate.** Before routing, check: "Can I proceed without guessing?" If the next skill's input is missing or the task is ambiguous — ask the user. Do not route into uncertainty.
+### User Skills Auto-Detection
 
-**Auto-Handoff.** When Loop Guard triggers: stop routing, write an OptiRoute report to `.opencode/plan.md` (routing chain, trigger, current state, blocker), surface `OPTIROUTE STOP: <reason>` to the user, and exit the loop.
+Skills in `~/.agents/skills/` and `~/.config/opencode/skills/` are auto-discovered on every session. On name conflict with a built-in `oh-*` skill, the user version wins. User skills survive `npm update openhermes` — they live outside the package dir.
 
-## Delegation Rules
+### Delegation Rules
 
-1. **Deploy subagents for isolated context** — large searches, independent subtasks, parallel review axes. Each subagent burns its own context window.
-2. **Background vs sync** — independent work delegates in background (fire-and-forget). Dependent work delegates sync (await result).
-3. **One level deep** — subagents you spawn cannot spawn subagents of their own. That is your job.
-4. **Checkpoint before handoff** — write progress to `.opencode/work-log.md` before delegating to a subagent.
-5. **Verify after return** — confirm subagent output before accepting it.
-6. **Surface blockers immediately** — if a delegate cannot proceed, report BLOCKER with options. Do not silently retry 5 times.
+1. Deploy subagents for isolated context — large searches, independent subtasks, parallel review.
+2. Background (fire-and-forget) for independent work. Sync (await result) for dependent work.
+3. One level deep — subagents do not spawn subagents.
+4. Checkpoint before handoff — write progress to the plan file (Completed section + Subagents table) before delegating.
+5. Verify after return — confirm subagent output before accepting it.
+6. Surface blockers immediately — report BLOCKER with options. Do not silently retry.

package/harness/codex/AUTOPILOT.md

@@ -0,0 +1,126 @@
+# OpenHermes Autopilot
+
+The closed-loop auto-routing engine. Every task auto-classifies, auto-routes, and auto-chains. Only stop for genuine blockers.
+
+## Auto-Classify
+
+Before any substantive response, classify the task using this decision matrix:
+
+| Signal | Classification | Action |
+|---|---|---|
+| Multi-step, vague, aimless, "improve", "make better", "fix up", "clean up", "organize", "I have an idea", no clear deliverable | PLANNING NEEDED | Load **oh-planner** (Mode A brainstorm or Mode C structured plan). Do not ask. |
+| Bug, crash, regression, unexpected behavior, "why is X broken" | INVESTIGATION NEEDED | Load **oh-investigate**. Do not ask. |
+| UI, frontend, design system, page, component, dashboard, visual, redesign, theme, layout, "make it look good", "janky", "laggy", "slow UI", UI quality complaint | UI PIPELINE NEEDED | Load **oh-facade** (5-phase: Concept → Design System → Build → Audit → Iterate). Do not ask. |
+| Security concern, vulnerability, threat model | SECURITY NEEDED | Load **oh-security**. Do not ask. |
+| Code quality, performance, linting, dead code | HEALTH CHECK | Load **oh-health**. Do not ask. |
+| Full pipeline: plan+implement+test+ship | PIPELINE NEEDED | Load **oh-manifest**. Do not ask. |
+| Full pipeline with UI components | PIPELINE + UI | Load **oh-manifest**. It delegates UI work to **oh-facade** internally. |
+| Code review, design review, PR review | REVIEW NEEDED | Load **oh-review**. Do not ask. |
+| Plan review, architecture review | PLAN REVIEW | Load **oh-plan-review**. Do not ask. |
+| Single concrete request with clear scope (rename, format, simple edit) | DIRECT EXECUTION | Execute directly or load **oh-builder**. Do not ask. |
+| Session ending, handoff, context switch | HANDOFF | Load **oh-handoff**. Do not ask. |
+| Skill import, ingestion, fusion, porting, "make this OH-native", "add this skill" | SKILL INGESTION NEEDED | Load **oh-fusion** (6-phase: Discovery → Analysis → Decision → Adaptation → Fusion → Integration). Do not ask. |
+| Diagnostic of own behavior (sycophancy, hallucination check) | SELF-DIAGNOSIS | Load **oh-expert**. Do not ask. |
+
+**When in doubt between two classifications, choose the more structured one.** If a task could be direct execution OR planning needed, load oh-planner. The planner can always determine that the task is simpler than expected and route back.
+
+## Auto-Route
+
+After every skill completes, follow this protocol:
+
+1. **Determine outcome**: pass (completed successfully), fail (found issues or partial results), blocker (unrecoverable)
+2. **Read the skill's `route:` frontmatter** — every SKILL.md has `route.pass`, `route.fail`, and `route.blocker` values
+3. **Route immediately** to the next skill based on outcome and the skill's own routing metadata
+4. **Repeat** until blocker, completion (`done`), or surface (`surface`)
+
+**Routing is mandatory. It is not optional.** You do not ask "should I route to X?" You determine the outcome and follow the skill's routing metadata. Do not deviate from it.
+
+### Route Values
+
+Every skill's `route:` frontmatter uses these value types:
+
+| Value | Meaning |
+|-------|---------|
+| `oh-<name>` | Route to a specific skill (built-in or user) |
+| `[oh-a, oh-b]` | Route to one of — choose the best fit for current context |
+| `surface` | Report findings to the user and end the chain |
+| `done` | Task is complete — terminal |
+| `mode` | Internal mode switch — return to the calling skill after toggling state |
+
+### Dynamic Routing Loop
+
+Routing is determined at runtime by scanning all available skills and reading the *current skill's* routing metadata:
+
+```
+           ┌──────────────────────────────────────┐
+           │                                      │
+           ↓                                      │
+classify → load best skill → execute              │
+                              ↓                   │
+                         check outcome ──→ read skill's route frontmatter
+                                              ↓
+                                        route by outcome ──→ next skill ──→ execute
+                                              │                    ↑
+                                              ↓                    │
+                                        surface/done/blocker      │
+                                              ↓                    │
+                                        report to user            │
+                                                                   │
+                                                                   │
+                              User skills participate:             │
+                              If current skill's route.pass       │
+                              points to oh-deploy (user skill),   │
+                              load oh-deploy. Its own route       │
+                              metadata routes onward from there.  │
+                              No registration step needed.        │
+                                           ┌──────────────────────┘
+                                           │
+                                           └── loop until surface/done/blocker
+```
+
+## Close the Loop
+
+Every skill must route somewhere. No leaf nodes (task-level terminals use `done`; the only session-ending terminal is `oh-handoff`).
+
+- If a chain completes (pass all the way through) and the task has more work → start a new auto-classify cycle
+- If a chain completes and the task is done → summarize with receipts, present results
+- If a blocker fires → surface to user with findings, options, and what you need
+
+## Stop Conditions
+
+**STOP only for:**
+
+1. **Task complete** — requested work is done, verified, evidence presented. Do not keep routing after the goal is met.
+2. **Blocker** — unrecoverable error, missing information you cannot discover yourself, environment prevents progress. Surface with:
+   - What you tried
+   - Where you got stuck
+   - What you need to proceed
+3. **Major decision** — a genuinely ambiguous choice where either path materially changes the outcome (language choice, architecture paradigm, tool selection). Surface options with analysis. Do not ask about trivial choices.
+
+**Do NOT stop for:**
+- "Should I plan first?" — Task is multi-step or aimless? Load oh-planner. Do not ask.
+- "Should I continue?" — Not blocked? Continue. Do not ask.
+- "Which skill should I use?" — Auto-classify table tells you. Do not ask.
+- "Is this OK?" — Verify and present evidence. Do not ask.
+- "Do you want me to X?" — If X is the next routing step, just do it. Do not ask.
+
+## Safety Valves
+
+### Loop Guard
+If the same skill is visited 3+ times in one chain, or 5+ hops pass without producing a new artifact — STOP, write OptiRoute report to the plan file, surface to user. Do not keep looping.
+
+### Question Gate
+Before routing, check: "Can I proceed without guessing?" If the next skill's input is missing and you cannot create or discover it independently — surface to user. Do not route into guaranteed failure.
+
+## User Skills
+
+Skills in `~/.agents/skills/` and `~/.config/opencode/skills/` are auto-discovered on every session. On name conflict with a built-in `oh-*` skill, the user version wins. User skills survive `npm update openhermes`.
+
+### User skills in the routing loop
+
+User skills are **first-class routing citizens**. The autopilot treats them identically to built-in skills:
+
+- **They appear in the available skills list** and can be loaded through the skill tool on demand
+- **Their `route:` frontmatter drives routing** — after a user skill completes, the autopilot reads its `route.pass`/`route.fail`/`route.blocker` and routes to the next skill
+- **Any skill can route to a user skill** — if a built-in skill's `route.pass` points to `oh-deploy` (user skill), the autopilot routes there
+- **No registration step** — add `route:` frontmatter to any skill file and it participates in the routing graph automatically