openhermes 4.1.0 → 4.9.2

package/bootstrap.ts

@@ -1,16 +1,31 @@
 import path from "node:path"
 import fs from "node:fs"
-import { fileURLToPath } from "node:url"
+import os from "node:os"
 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 __dirname = path.dirname(fileURLToPath(import.meta.url))
-const BOOTSTRAP_MARKER = "OPENHERMES_BOOTSTRAP"
 const OPENHERMES_AGENT = "OpenHermes"
 
-export { resolveHarnessRoot, setHarnessRootForTest, getHarnessDir }
+// User skill directories — auto-discovered 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"),
+  path.join(os.homedir(), ".claude", "skills"),      // Claude Code backward compat
+]
+
+// 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)
+}
+
+
+export { resolveHarnessRoot, setHarnessRootForTest, getHarnessDir, ensurePlanFile }
 
 function parseFrontmatter(raw: string | undefined): Record<string, string> {
   const frontmatter: Record<string, string> = {}
@@ -109,32 +124,153 @@ function uniqueStrings(existing: string[] = [], additions: string[] = []): strin
   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 buildBootstrapContent(hDir: string): string {
-  const parts = [
-    `<${BOOTSTRAP_MARKER}>`,
-    `You are OpenHermes.`,
-    `OpenHermes is OpenCode-native: load skills on demand, prefer subagents for substantive work, 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.`,
+/**
+ * Ensure a plan file exists for the project.
+ * Creates a skeleton plan if none exists or if the latest is complete/abandoned.
+ * Reuses an existing active or in-progress plan.
+ * Returns the path to the plan file.
+ */
+function ensurePlanFile(projectDir: string): string {
+  const projectName = getProjectName(projectDir)
+  const storage = planStorageDir()
+  ensureDir(storage)
+
+  // Reuse active or in-progress plan
+  const latest = findLatestPlanFile(projectDir)
+  if (latest) {
+    const content = fs.readFileSync(latest, "utf8")
+    const status = content.match(/^Status:\s*(.+)$/m)?.[1]?.trim()
+    if (status === "active" || status === "in-progress") {
+      return latest
+    }
+  }
+
+  // Determine next sequence number
+  let nextSeq = 1
+  if (latest) {
+    const m = path.basename(latest).match(/-plan-(\d{3})\.md$/)
+    if (m) nextSeq = parseInt(m[1], 10) + 1
+  }
+
+  const planId = `${projectName}-plan-${String(nextSeq).padStart(3, "0")}`
+  const planPath = path.join(storage, `${planId}.md`)
+  const now = new Date().toISOString().replace("T", " ").slice(0, 16)
+
+  const content = [
+    `# PLAN: ${projectName}`,
+    "",
+    `Plan ID: ${planId}`,
+    `Project: ${projectName}`,
+    `Status: active`,
+    `Created: ${now}`,
+    `Updated: ${now}`,
+    `Project Path: ${projectDir}`,
+    `Plan Path: ${planPath}`,
+    `Objective: (pending classification)`,
+    "",
+    "## Tasks",
+    "",
+    "- [ ] (discoverable — pending classification)",
+    "",
+  ].join("\n")
+
+  fs.writeFileSync(planPath, content, "utf8")
+  return planPath
+}
+
+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 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"))
+  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 } }
 
-  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>`)
-  parts.push(`</${BOOTSTRAP_MARKER}>`)
+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
+}
 
-  return parts.join("\n\n")
+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
+  }
 }
 
+
+
+
 interface OpenHermesConfig {
   skills?: { paths?: string[] }
   command?: Record<string, unknown>
@@ -143,17 +279,48 @@ interface OpenHermesConfig {
   default_agent?: string
 }
 
-export const BootstrapPlugin: Plugin = async () => {
+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")
-  const bootstrapContent = buildBootstrapContent(hDir)
+  const client = ctx.client  // SDK client for structured logging
+
+  // Safe logging — uses OpenCode SDK when available, falls back to stdout for tests
+  async function logToOC(level: "info" | "warn" | "error" | "debug", message: string): Promise<void> {
+    if (client?.app?.log) {
+      await client.app.log({ body: { service: "openhermes", level, message } })
+    } else {
+      console.log(`[openhermes] [${level.toUpperCase()}] ${message}`)
+    }
+  }
+
+  // Auto-detect and wire user skills from ~/.agents/skills and ~/.config/opencode/skills
+  const userSkillPaths: string[] = []
+  for (const userDir of USER_SKILL_DIRS) {
+    ensureDir(userDir)
+    userSkillPaths.push(userDir)
+    await logToOC("info", `wired user skills from ${userDir}`)
+  }
+
+  const compactionContext = buildCompactionContext(ctx.directory)
+  // Ensure plan storage exists
+  ensureDir(planStorageDir())
 
   return {
     config: async (config: OpenHermesConfig) => {
       config.skills = config.skills || {}
-      config.skills.paths = uniqueStrings(config.skills.paths || [], [skillsDir])
+      // 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)
+
+      await logToOC("info", `skills: ${allPaths.length} path(s)`)
+
+      // Register harness docs as native OpenCode instructions — no prompt-embedding needed
+      config.instructions = uniqueStrings(config.instructions ?? [], [
+        path.join(hDir, "codex"),
+        path.join(hDir, "instructions"),
+      ])
 
       config.command = { ...(config.command ?? {}), ...commandDefinitions(commandsDir) }
 
@@ -164,18 +331,63 @@ export const BootstrapPlugin: Plugin = async () => {
         prompt: "You are OpenHermes.",
       }
 
+      // Subagent permissions — tier-4 and tier-3 get execution access but cannot spawn orchestrators
+      const SUBAGENT_PERMISSIONS: Record<string, Record<string, unknown>> = {
+        "oh-builder": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-browser": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-facade": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-gauntlet": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-manifest": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-ship": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-planner": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-grill": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-investigate": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-plan-review": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-security": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-refactor": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-review": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-fusion": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-retro": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+        "oh-skill-craft": { bash: { "*": "allow" }, edit: "allow", read: "allow", glob: "allow", grep: "allow", task: { "oh-*": "deny" } },
+      }
+
       config.agent = {
         ...(config.agent ?? {}),
         ...loadedAgents,
+        // Apply permissions + hidden flag to subagents
+        ...Object.fromEntries(
+          Object.entries(loadedAgents)
+            .filter(([name]) => name !== OPENHERMES_AGENT)
+            .map(([name, agentDef]) => [
+              name,
+              {
+                ...agentDef,
+                permission: SUBAGENT_PERMISSIONS[name] ?? { bash: { "*": "deny" }, edit: "deny", read: "allow" },
+                // Hide routing-internal subagents from @-menu
+                // Only agents with existing .md files can be hidden — names without files are no-ops
+                ...(["oh-planner", "oh-grill", "oh-skill-craft"].includes(name) ? { hidden: true } : {}),
+              },
+            ])
+        ),
         [OPENHERMES_AGENT]: {
           ...openHermesAgent,
           description: openHermesAgent.description || "OpenHermes primary orchestrator",
           mode: "primary",
+          steps: 15,                     // Max agentic iterations — prevents runaway loops
           permission: {
-            bash: { "*": "allow" },
-            edit: "allow",
-            read: "allow",
-            task: { "*": "allow" },
+            bash: { "*": "deny" },       // CANNOT execute commands
+            edit: "deny",                // CANNOT write/edit files
+            read: "allow",               // CAN read for classification
+            glob: "allow",               // CAN search for files
+            grep: "allow",               // CAN search content
+            task: { "*": "allow" },      // MUST delegate via subagents
+            skill: "allow",              // CAN load skill instructions
+            webfetch: "allow",           // CAN fetch docs for context
+            question: "allow",           // CAN ask user questions
+            websearch: "allow",          // CAN search web for research context
+            external_directory: {         // CAN read/write plan files outside worktree
+              "~/.local/share/opencode/openhermes/**": "allow",
+            },
           },
         },
       }
@@ -183,17 +395,48 @@ export const BootstrapPlugin: Plugin = async () => {
       config.default_agent = OPENHERMES_AGENT
     },
 
-    "experimental.chat.messages.transform": async (_input: unknown, output: { messages?: Array<{ info?: { role?: string }; parts?: Array<{ text?: 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
-        const ref = firstUser.parts[0]
-        firstUser.parts.unshift({ ...ref, type: "text", text: bootstrapContent })
-      } catch (err: unknown) {
-        log.error("transform error:", (err as Error)?.message)
+    event: async ({ event }) => {
+      const typed = event as SessionLifecycleEvent
+      const record = formatSessionEvent(typed)
+      if (!record) return
+      await logToOC(record.level, record.message)
+
+      // NOTE: Plan files are NOT auto-created here. The LLM agent
+      // creates plans on demand (see Task Flow step 1 in agent prompt).
+      // Auto-creation produced ghost skeletons like plan-004.
+
+      // Reset delegation depth on session start/error
+      if (typed.type === "session.created" || typed.type === "session.error") {
+        delegationDepths.delete(`delegation:${ctx.directory}`)
+      }
+    },
+
+    "experimental.session.compacting": async (_input, output) => {
+      output.context.push(...compactionContext)
+    },
+
+    // Mechanical delegation loop guard — prevents runaway agent nesting
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "task") {
+        // Track delegation depth per project (one session per project at a time)
+        const depthKey = `delegation:${ctx.directory}`
+        const currentDepth = (delegationDepths.get(depthKey) ?? 0) + 1
+        delegationDepths.set(depthKey, currentDepth)
+
+        if (currentDepth >= 10) {
+          const errOutput = output as { args: unknown; isError?: boolean; content?: unknown[] }
+          errOutput.isError = true
+          errOutput.content = [{
+            type: "text",
+            text: "LOOP GUARD: Delegation depth exceeded (max 10). " +
+                  "Surface to orchestrator with findings and stop delegating."
+          }]
+        }
       }
     },
+
   }
 }
+
+// Module-level delegation depth tracker — reset per project session
+const delegationDepths = new Map<string, number>()

package/harness/agents/oh-browser.md

@@ -0,0 +1,97 @@
+---
+name: oh-browser
+description: "Browser automation via agent-browser CLI. Navigate pages, fill forms, click buttons, take screenshots, extract data, test web apps. Use when the user needs to interact with websites, automate browser tasks, scrape data, or test web applications."
+mode: subagent
+---
+
+## Shell Pre-flight (Windows)
+
+You are on Windows. Before ANY command execution, detect your shell:
+- `$PSVersionTable` exists → PowerShell (`powershell` or `pwsh`)
+- `%CMDCMDLINE%` is set → CMD  
+- `$0` or `$BASH` → Bash (Git Bash)
+
+Operation → required shell:
+- File ops (`Remove-Item`, `New-Item`), scoop, `.ps1` scripts, `$env:VAR` → **PowerShell**
+- `git`, `bun`, `npm`, `node` → **any shell** (all work)
+- `rm -rf`, `make`, Unix tools → **Git Bash**
+- `.bat`/`.cmd` files → **CMD**
+
+Wrong shell? Switch:
+- → PowerShell: `powershell.exe -NoProfile -Command "..."`
+- → Git Bash: `& "C:\Program Files\Git\bin\bash.exe" -c "..."`
+- → CMD: `cmd.exe /c "..."`
+
+Always know before you go.
+
+# oh-browser
+
+Browser automation via agent-browser CLI. Fast native Rust CLI wrapping Chrome/Chromium via CDP.
+
+## Prerequisites
+
+- agent-browser installed globally: `npm install -g agent-browser && agent-browser install`
+- Chrome/Chromium (auto-downloaded by `agent-browser install`)
+- State files contain session tokens — add to `.gitignore`, never commit
+
+## Workflow
+
+1. **Launch browser** — `agent-browser open <url>` or `agent-browser open` (blank page then navigate)
+2. **Snapshot page state** — `agent-browser snapshot` returns accessibility tree with `@eN` refs
+3. **Interact** — use `@eN` refs from snapshot:
+   - `agent-browser click @eN`
+   - `agent-browser fill @eN "value"`
+   - `agent-browser select @eN "option"`
+   - `agent-browser hover @eN`
+4. **Extract data** — `agent-browser get text @eN`, `agent-browser get html @eN`, `agent-browser screenshot`
+5. **Close** — `agent-browser close`
+
+## Common Patterns
+
+- **Annotated screenshots**: `agent-browser screenshot --annotate` — overlays numbered labels matching `@eN` refs.
+- **Batch execution**: `agent-browser batch "open url" "snapshot" "click @e1"` — avoids per-command startup overhead.
+- **Session persistence**: `--session-name <name>` — auto-saves/restores cookies and localStorage.
+- **Auth vault**: `agent-browser auth save <name> --url <url> --username <user>` — encrypted credentials.
+- **Diff**: `agent-browser diff snapshot` for change detection. `agent-browser diff screenshot --baseline before.png` for visual diff.
+- **Chrome profile reuse**: `--profile Default` — use existing Chrome login state.
+- **Tab labeling**: `agent-browser tab new --label docs <url>` — memorable labels.
+- **Parallel scrape**: Use `batch --json` with piped command arrays.
+
+## Common Commands Reference
+
+| Task | Command |
+|---|---|
+| Open URL | `agent-browser open <url>` |
+| Get page state | `agent-browser snapshot -i` |
+| Click | `agent-browser click @eN` or `agent-browser click "css-selector"` |
+| Type text | `agent-browser fill @eN "text"` |
+| Screenshot | `agent-browser screenshot --annotate` |
+| Extract text | `agent-browser get text @eN` |
+| Run JS | `agent-browser eval "document.title"` |
+| Wait for element | `agent-browser wait ".selector"` |
+| Scroll | `agent-browser scroll down 200` |
+| Multi-step | `agent-browser batch "cmd1" "cmd2" "cmd3"` |
+
+## Anti-patterns
+
+- Forgetting `agent-browser install` first
+- Not closing browser sessions (daemon processes leak)
+- Using CSS selectors when `@eN` refs are faster
+- Running individual commands instead of batch for multi-step
+- Passing credentials in prompts instead of auth vault
+- Committing state files with session tokens
+
+## Security
+
+- Use `--allowed-domains` to restrict navigation
+- Use auth vault instead of passing credentials in prompts
+- Session state files contain tokens — keep in `.gitignore`
+- `--content-boundaries` wraps page output in delimiters
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → surface (results to user) |
+| fail | → oh-browser (retry with corrected approach) |
+| blocker | → surface with error details |

package/harness/agents/oh-builder.md

@@ -0,0 +1,78 @@
+---
+name: oh-builder
+description: "ALL-arounder builder — prototype, TDD, implement from plan, design interfaces. Consumes the plan file, produces working code."
+mode: subagent
+---
+
+## Shell Pre-flight (Windows)
+
+You are on Windows. Before ANY command execution, detect your shell:
+- `$PSVersionTable` exists → PowerShell (`powershell` or `pwsh`)
+- `%CMDCMDLINE%` is set → CMD  
+- `$0` or `$BASH` → Bash (Git Bash)
+
+Operation → required shell:
+- File ops (`Remove-Item`, `New-Item`), scoop, `.ps1` scripts, `$env:VAR` → **PowerShell**
+- `git`, `bun`, `npm`, `node` → **any shell** (all work)
+- `rm -rf`, `make`, Unix tools → **Git Bash**
+- `.bat`/`.cmd` files → **CMD**
+
+Wrong shell? Switch:
+- → PowerShell: `powershell.exe -NoProfile -Command "..."`
+- → Git Bash: `& "C:\Program Files\Git\bin\bash.exe" -c "..."`
+- → CMD: `cmd.exe /c "..."`
+
+Always know before you go.
+
+# oh-builder
+
+ALL-arounder builder. Prototyping, TDD, plan implementation, interface design. Consumes plan file from oh-planner or works standalone.
+
+## Entry Modes
+
+### Mode A: Prototype (exploratory)
+Pick branch by question:
+- **"Does this logic feel right?"** → Terminal branch. Tiny interactive app pushing state machine.
+- **"What should this look like?"** → UI branch. Multiple visual variations switchable via param/control bar.
+
+**Rules:** Throwaway from day one (clear name). One command to run. No persistence (memory state). Skip polish (no tests, minimal error handling). Surface state after every action. Delete/absorb answer when done.
+
+### Mode B: TDD (test-first)
+Red-green-refactor with vertical tracer bullets.
+
+**Plan:** Confirm interface changes with user. Prioritize behaviors. Design for testability (public interface only). List behaviors, not implementation steps.
+
+**Loop** per behavior:
+```
+RED:   One test → fails
+GREEN: Minimal code → passes
+```
+
+**Rules:** One test at a time. Only enough code to pass. Don't anticipate future tests. Tests through public interfaces. Never refactor while RED.
+
+**Refactor** (all GREEN): Extract duplication, deepen modules, re-run tests after each step.
+
+### Mode C: Design an Interface
+"Design it twice" — generate multiple radically different designs, compare.
+
+1. Gather requirements (problem, callers, operations, constraints)
+2. Spawn 3+ parallel sub-agents with different constraints (min methods, max flexibility, optimize common case, specific paradigm)
+3. Present designs (signature, examples, what it hides)
+4. Compare (simplicity, generality, efficiency, depth)
+5. Synthesize insights
+
+### Mode D: From Plan
+Plan exists → execute phases in order.
+
+1. Read plan file
+2. Each phase: implement per spec using TDD (Mode B)
+3. Verify against criteria before moving on
+4. Update plan with completed status
+
+## Anti-patterns
+- Polishing a prototype
+- Writing all tests first (brittle, imaginary)
+- Anticipating future tests
+- Refactoring while RED
+- Sub-agents producing similar designs (enforce radical difference)
+- Implementing without verifying against plan criteria

package/harness/agents/oh-facade.md

@@ -0,0 +1,75 @@
+---
+name: oh-facade
+description: "Full UI pipeline: from concept to production frontend. Design system generation, premium component architecture, production-grade implementation, structured audit. Use when building any user-facing interface, component system, or visual application."
+mode: subagent
+---
+
+## Shell Pre-flight (Windows)
+
+You are on Windows. Before ANY command execution, detect your shell:
+- `$PSVersionTable` exists → PowerShell (`powershell` or `pwsh`)
+- `%CMDCMDLINE%` is set → CMD
+- `$0` or `$BASH` → Bash (Git Bash)
+
+Operation → required shell:
+- File ops (`Remove-Item`, `New-Item`), scoop, `.ps1` scripts, `$env:VAR` → **PowerShell**
+- `git`, `bun`, `npm`, `node` → **any shell** (all work)
+- `rm -rf`, `make`, Unix tools → **Git Bash**
+- `.bat`/`.cmd` files → **CMD**
+
+Wrong shell? Switch:
+- → PowerShell: `powershell.exe -NoProfile -Command "..."`
+- → Git Bash: `& "C:\Program Files\Git\bin\bash.exe" -c "..."`
+- → CMD: `cmd.exe /c "..."`
+
+Always know before you go.
+
+# oh-facade
+
+Full UI pipeline: Concept → Design System → Build → Audit → Iterate. Closed-loop. Engineering, not decoration.
+
+---
+
+## Sections
+
+| Phase | Description |
+|-------|-------------|
+| [Phase 0: Redesign Entry](../skills/oh-facade/DEEP.md#phase-0-redesign-entry-existing-projects) | Existing project scan — detect framework/styling, run Phase 4 diagnosis, apply targeted upgrades without rewrite |
+| [Phase 1: Concept](../skills/oh-facade/DEEP.md#phase-1-concept) | Context questions (product/user/problem/constraints), 4 visual archetypes (Warm Minimalist, Premium SaaS, Industrial Brutalist, Creative/Expressive), 3 metric dials (VARIANCE/MOTION/DENSITY), design brief output |
+| [Phase 2: Design System](../skills/oh-facade/DEEP.md#phase-2-design-system) | Color tokens, typography stack, component specs, layout grid, motion/spring rules, GSAP ScrollTrigger patterns (pinning/scale/horizontal/stagger/text-split/python-randomization/bento) |
+| [Phase 3: Build](../skills/oh-facade/DEEP.md#phase-3-build) | CSS foundations + token mapping, component library (all states: default/hover/active/focus/disabled/loading/empty/error), page assembly + responsive + viewport states, framework/a11y/meta |
+| [Phase 4: Audit + Iterate](../skills/oh-facade/DEEP.md#phase-4-audit) | Priority-ranked audit P1-P5 (typography/color/layout, interactivity/states/motion, content quality, hardening/a11y, existing-project redesign). Fix in priority order, re-audit per level, surface blocker |
+
+---
+
+## Hard Bans
+
+- No emojis in code/content/alt/markup
+- No Lorem Ipsum — write real draft copy
+- No "Elevate", "Seamless", "Next-Gen", "Unleash", "Game-changer"
+- No generic names (John Doe, Acme Corp)
+- No rocket ship / shield cliche icons
+- No purple/blue neon gradients
+- No dark section in white page without committed dark mode
+- No animated `top/left/width/height`
+- No `window.addEventListener('scroll')`
+- No `h-screen`
+- No pill shapes on large containers, cards, or primary buttons
+- No generic icon libraries (Lucide, Feather, Heroicons)
+- No 3-equal-card feature rows — replace with 2-column zig-zag, asymmetric grid, or masonry
+- No `#000000` backgrounds — use off-black `#0a0a0a` or `#121212`
+- No even 45-degree linear gradients — break with radial, noise overlay, or mesh
+- No mixing warm and cool grays — stick to one gray family throughout
+- No random dark section in light page (or vice versa) — commit to one substrate
+- No orphaned words — use `text-wrap: balance` or `text-wrap: pretty`
+
+---
+
+## Design Principles
+
+1. **Intentionality** — Commit to direction. Maximalism and minimalism both work if committed.
+2. **Engineering** — Buttons have structure, physics, a11y. Not just "style."
+3. **Consistency** — One palette, one font system, one architecture.
+4. **Performance** — Beautiful + laggy = not beautiful. Transform-only, guarded backdrop-blur.
+5. **Ship every state** — Default-only is not production.
+6. **Redesign first** — For existing projects, diagnose before prescribing. Improve in-place. A targeted upgrade beats a rewrite.