opencode-overclock 0.4.0 → 0.5.1

package/src/platform/process/exec.ts

@@ -14,11 +14,239 @@ export const NON_INTERACTIVE_ENV: Record<string, string> = {
   TERM: "dumb",
 }
 
+/**
+ * Pattern matching environment variable names that typically store credentials,
+ * secrets, authentication tokens, API keys, or private keys.
+ */
+export const SENSITIVE_ENV_PATTERN =
+  /(?:KEY|SECRET|TOKEN|AUTH|PASS(?:WORD|WD)?|CREDENTIAL|PRIVATE|SIGNING|DATABASE_URL|WEBHOOK|CERT|BEARER|COOKIE)/i
+
+/**
+ * Known system and transport variables that match sensitive keywords but are
+ * necessary for everyday development operations (SSH agent socket, TLS certificates).
+ */
+export const DEFAULT_PRESERVED_ENV: readonly string[] = [
+  "SSH_AUTH_SOCK",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "NODE_EXTRA_CA_CERTS",
+  "GIT_SSH_COMMAND",
+]
+
+/**
+ * Filter an environment map to remove sensitive keys (API keys, secrets, tokens).
+ * Safe system and build variables (PATH, HOME, USER, SHELL, TEMP, LANG, etc.)
+ * as well as essential operational credentials (SSH_AUTH_SOCK, certificates) are preserved.
+ */
+export function sanitizeEnv(
+  env: Record<string, string | undefined>,
+  allowlist?: string[],
+): Record<string, string | undefined> {
+  const allowed = new Set([
+    ...DEFAULT_PRESERVED_ENV.map((k) => k.toUpperCase()),
+    ...(allowlist?.map((k) => k.toUpperCase()) ?? []),
+  ])
+  const sanitized: Record<string, string | undefined> = {}
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) continue
+    if (allowed.has(key.toUpperCase())) {
+      sanitized[key] = value
+      continue
+    }
+    if (SENSITIVE_ENV_PATTERN.test(key)) {
+      continue
+    }
+    sanitized[key] = value
+  }
+
+  return sanitized
+}
+
+/**
+ * Common regex patterns for tokens, API keys, private keys, and credential formats.
+ */
+export const SENSITIVE_OUTPUT_PATTERNS: { pattern: RegExp; replacement: string }[] = [
+  // Private keys
+  {
+    pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    replacement: "[REDACTED_PRIVATE_KEY]",
+  },
+  // JWT tokens
+  {
+    pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+\b/g,
+    replacement: "[REDACTED_JWT]",
+  },
+  // Bearer tokens
+  {
+    pattern: /\bBearer\s+[A-Za-z0-9_\-\.~+/]+=*/gi,
+    replacement: "Bearer [REDACTED_TOKEN]",
+  },
+  // OpenAI / Anthropic / AI vendor keys
+  {
+    pattern: /\b(?:sk|ant)-[a-zA-Z0-9_\-]{20,}\b/g,
+    replacement: "[REDACTED_API_KEY]",
+  },
+  // GitHub tokens (classic, fine-grained PATs, OAuth)
+  {
+    pattern: /\b(?:gh[pousr]_[A-Za-z0-9_]{36,255}|github_pat_[A-Za-z0-9_]{50,255})\b/g,
+    replacement: "[REDACTED_GITHUB_TOKEN]",
+  },
+  // AWS Access Key ID
+  {
+    pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    replacement: "[REDACTED_AWS_KEY]",
+  },
+  // Passwords in URLs (e.g. postgres://user:pass@host)
+  {
+    pattern: /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/:]+:)[^/@\s]+(@)/g,
+    replacement: "$1[REDACTED_PASSWORD]$2",
+  },
+  // Authorization headers
+  {
+    pattern: /(Authorization:\s*(?:Basic|Bearer|Token)\s+)[^\r\n]+/gi,
+    replacement: "$1[REDACTED_AUTH]",
+  },
+  // Key / secret / token assignments in key-value output (e.g. api_key="secret", token: secret)
+  {
+    pattern:
+      /((?:api[_-]?key|secret|token|password|passwd)\s*[:=]\s*["']?)[A-Za-z0-9_\-\.~+/]{8,}(["']?)/gi,
+    replacement: "$1[REDACTED]$2",
+  },
+]
+
+/**
+ * Redacts sensitive tokens, API keys, credentials, and known environment secrets
+ * from output strings to prevent data leakage.
+ */
+export function redactSensitiveOutput(text: string, additionalSecrets?: string[]): string {
+  if (!text) return text
+
+  let redacted = text
+
+  // 1. Redact known secrets from process.env (values associated with sensitive keys, length >= 6)
+  const envSecrets: string[] = []
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value && value.length >= 6 && SENSITIVE_ENV_PATTERN.test(key)) {
+      envSecrets.push(value)
+    }
+  }
+
+  const allSecrets = [...envSecrets, ...(additionalSecrets ?? [])]
+  // Sort by length descending to match longest secrets first
+  allSecrets.sort((a, b) => b.length - a.length)
+
+  for (const secret of allSecrets) {
+    if (secret && secret.length >= 6 && redacted.includes(secret)) {
+      redacted = redacted.replaceAll(secret, "[REDACTED_SECRET]")
+    }
+  }
+
+  // 2. Redact pattern matches
+  for (const { pattern, replacement } of SENSITIVE_OUTPUT_PATTERNS) {
+    redacted = redacted.replace(pattern, replacement)
+  }
+
+  return redacted
+}
+
+/**
+ * Discover all descendant PIDs of a given process by inspecting the process tree.
+ */
+export async function getDescendantPids(rootPid: number): Promise<number[]> {
+  const pids: number[] = []
+  try {
+    const proc = Bun.spawn(["ps", "-A", "-o", "pid,ppid"], {
+      stdout: "pipe",
+      stderr: "ignore",
+    })
+    const text = await new Response(proc.stdout).text()
+    await proc.exited
+
+    const parentMap = new Map<number, number[]>()
+    for (const line of text.trim().split("\n").slice(1)) {
+      const parts = line.trim().split(/\s+/)
+      if (parts.length >= 2) {
+        const pid = Number(parts[0])
+        const ppid = Number(parts[1])
+        if (!isNaN(pid) && !isNaN(ppid)) {
+          if (!parentMap.has(ppid)) parentMap.set(ppid, [])
+          parentMap.get(ppid)!.push(pid)
+        }
+      }
+    }
+
+    const queue = [rootPid]
+    while (queue.length > 0) {
+      const curr = queue.shift()!
+      const children = parentMap.get(curr) ?? []
+      for (const child of children) {
+        pids.push(child)
+        queue.push(child)
+      }
+    }
+  } catch {}
+  return pids
+}
+
+/**
+ * Kill a process and its child processes recursively on POSIX systems.
+ */
+export async function killProcessTree(
+  target: Bun.Subprocess | number,
+  signal: "SIGTERM" | "SIGKILL" = "SIGTERM",
+): Promise<void> {
+  const pid = typeof target === "number" ? target : target.pid
+  if (!pid) return
+
+  // 1. Gather all descendants in the process tree before sending signals
+  const descendants = await getDescendantPids(pid)
+
+  // 2. Try killing process group in case target is a process group leader
+  try {
+    process.kill(-pid, signal)
+  } catch {}
+
+  // 3. Kill all descendants (leaves first by iterating in reverse)
+  for (let i = descendants.length - 1; i >= 0; i--) {
+    try {
+      process.kill(descendants[i]!, signal)
+    } catch {}
+  }
+
+  // 4. Fallback pkill -P for any newly spawned direct children
+  try {
+    const pkill = Bun.spawn(["pkill", `-${signal === "SIGKILL" ? "KILL" : "TERM"}`, "-P", String(pid)], {
+      stdout: "ignore",
+      stderr: "ignore",
+    })
+    await pkill.exited
+  } catch {}
+
+  // 5. Kill the root process
+  try {
+    if (typeof target === "number") {
+      process.kill(pid, signal)
+    } else {
+      target.kill(signal)
+    }
+  } catch {}
+}
+
 export interface ExecBashOptions {
   cwd?: string
   env?: Record<string, string | undefined>
   timeoutMs?: number
   onSpawn?: (proc: Bun.Subprocess) => void
+  /**
+   * If true (default), sensitive environment variables (API keys, secrets, tokens)
+   * are scrubbed from process.env before spawning child processes.
+   */
+  sanitizeEnv?: boolean
+  /**
+   * Specific variable names to keep even if they match sensitive patterns.
+   */
+  envAllowlist?: string[]
 }
 
 export interface ExecBashResult {
@@ -30,12 +258,15 @@ export interface ExecBashResult {
 
 /**
  * Run a command via `bash -c`, capturing stdout, stderr, and exit code.
- * Ensures non-interactive environment variables with correct precedence and
- * process termination escalation.
+ * Ensures non-interactive environment variables with correct precedence,
+ * environment sanitization against secret leakage, and process termination escalation.
  */
 export async function execBash(command: string, options: ExecBashOptions = {}): Promise<ExecBashResult> {
+  const baseEnv =
+    options.sanitizeEnv === false ? process.env : sanitizeEnv(process.env, options.envAllowlist)
+
   const mergedEnv: Record<string, string | undefined> = {
-    ...process.env,
+    ...baseEnv,
     ...NON_INTERACTIVE_ENV,
     ...options.env,
   }
@@ -51,21 +282,31 @@ export async function execBash(command: string, options: ExecBashOptions = {}):
   let killEscalationTimer: ReturnType<typeof setTimeout> | undefined
   const killTimer = options.timeoutMs
     ? setTimeout(() => {
-        try {
-          proc.kill("SIGTERM")
-        } catch {}
+        void killProcessTree(proc, "SIGTERM")
         killEscalationTimer = setTimeout(() => {
-          try {
-            proc.kill("SIGKILL")
-          } catch {}
+          void killProcessTree(proc, "SIGKILL")
         }, 2000)
         killEscalationTimer.unref?.()
       }, options.timeoutMs)
     : undefined
 
+  // Protect against pipe leaks when background child processes keep stdout/stderr open
+  const streamTimeoutMs = options.timeoutMs ? options.timeoutMs + 2500 : undefined
+  const readStreamWithTimeout = (stream: ReadableStream, timeoutMs?: number): Promise<string> => {
+    const readPromise = new Response(stream).text().catch(() => "")
+    if (!timeoutMs) return readPromise
+    let timer: ReturnType<typeof setTimeout>
+    return Promise.race([
+      readPromise,
+      new Promise<string>((resolve) => {
+        timer = setTimeout(() => resolve(""), timeoutMs)
+      }),
+    ]).finally(() => clearTimeout(timer))
+  }
+
   const [stdout, stderr, code] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
+    readStreamWithTimeout(proc.stdout, streamTimeoutMs),
+    readStreamWithTimeout(proc.stderr, streamTimeoutMs),
     proc.exited,
   ])
 

package/src/platform/session/inject.ts

@@ -65,8 +65,9 @@ export async function inject(
 ): Promise<boolean> {
   try {
     const ctx = await sessionContext(client, sessionID)
-    await client.session.promptAsync({
+    const res = await (client.session.promptAsync as any)({
       path: { id: sessionID },
+      throwOnError: true,
       body: {
         parts: [{ type: "text", text }],
         ...(ctx.model ? { model: ctx.model } : {}),
@@ -74,6 +75,12 @@ export async function inject(
         ...(options?.noReply ? { noReply: true } : {}),
       },
     })
+    if (res && typeof res === "object" && "error" in res && (res as any).error) {
+      console.warn(
+        `[overclock] inject failed (session ${sessionID}): ${JSON.stringify((res as any).error)}`,
+      )
+      return false
+    }
     return true
   } catch (e) {
     console.warn(`[overclock] inject failed (session ${sessionID}): ${e}`)

package/src/platform/storage/state.ts

@@ -1,4 +1,6 @@
-import { mkdir } from "node:fs/promises"
+import { mkdir, copyFile } from "node:fs/promises"
+import { writeFileSync, renameSync, unlinkSync, mkdirSync } from "node:fs"
+import { dirname } from "node:path"
 import { shellQuote } from "../process/exec.ts"
 
 export { shellQuote }
@@ -32,16 +34,36 @@ export async function readJson<T>(path: string, fallback: T): Promise<T> {
   if (!(await file.exists())) return fallback
   try {
     return (await file.json()) as T
-  } catch {
+  } catch (e) {
+    console.warn(`[overclock] failed to parse JSON at ${path}: ${e}`)
+    try {
+      await copyFile(path, `${path}.corrupt.${Date.now()}`)
+    } catch {}
     return fallback
   }
 }
 
 /**
- * Serializes the value formatted with 2 spaces and writes to the destination path.
+ * Serializes the value formatted with 2 spaces and atomically writes to the destination path.
  */
 export async function writeJson(path: string, value: unknown): Promise<void> {
-  await Bun.write(path, JSON.stringify(value, null, 2))
+  const tmpPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`
+  const content = JSON.stringify(value, null, 2)
+  try {
+    writeFileSync(tmpPath, content)
+    renameSync(tmpPath, path)
+  } catch (err: any) {
+    if (err?.code === "ENOENT") {
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(tmpPath, content)
+      renameSync(tmpPath, path)
+      return
+    }
+    try {
+      unlinkSync(tmpPath)
+    } catch {}
+    throw err
+  }
 }
 
 /** A typed state file accessor. */

package/src/v2/host.ts

@@ -71,6 +71,7 @@ export function createV2Host(ctx: PluginInput, options: OverclockOptions = {}):
         },
 
         "experimental.chat.system.transform": async (_input, output) => {
+          if (!output || !Array.isArray(output.system)) return
           if (handle.state.references.size === 0) return
           const refLines: string[] = ["# References"]
           for (const [name, ref] of handle.state.references) {
@@ -86,14 +87,16 @@ export function createV2Host(ctx: PluginInput, options: OverclockOptions = {}):
         },
 
         "chat.params": async (input, output) => {
+          if (!output) return
           if (handle.state.aisdkHooks.sdk.size === 0) return
+          output.options = output.options ?? {}
           const sdkPayload = {
             model: {
               id: (input.model as any)?.id ?? (input.model as any)?.name ?? "unknown",
               providerID: (input.provider as any)?.id ?? "unknown",
             },
             package: "@ai-sdk/provider",
-            options: output.options ?? {},
+            options: output.options,
           }
           for (const hook of handle.state.aisdkHooks.sdk) {
             try {

package/src/workflow/agents/codebase-researcher.ts

@@ -0,0 +1,27 @@
+export const CODEBASE_RESEARCHER_PROMPT = `You are a specialized Codebase Research & Exploration Agent.
+Your sole responsibility is investigating existing architecture, tracing execution paths, discovering public seams, and mapping dependencies to answer technical questions without polluting the orchestrator's context window.
+You are a read-only terminal exploration agent. Do not attempt to edit or write files, stage/commit changes, or execute destructive commands. Provide a structured research brief only.
+
+Investigation Protocol:
+1. Ground in Evidence:
+   - Use \`glob\` and \`grep\` to locate relevant files, symbols, and patterns.
+   - Use \`read\` to inspect surrounding context, interfaces, and test fixtures.
+   - Never speculate on how a subsystem works when you can verify it directly from source files.
+2. Trace the Seams:
+   - Identify entry points, public API signatures, and event/data schemas.
+   - Trace callers and callees to map the blast radius of proposed changes.
+   - Identify existing test fixtures, mocks, and test patterns for this subsystem.
+3. Identify Dependencies:
+   - Classify dependencies per Ousterhout/Domain-Driven categories:
+     - In-Process (pure computation)
+     - Local-Substitutable (in-memory db, test clock)
+     - Remote-Owned (ports & adapters, internal APIs)
+     - True External (third-party vendor APIs)
+
+Output Format: Concise Architectural Brief (20–40 lines max):
+- **Executive Summary:** Direct answer to the technical question in 2-3 sentences.
+- **Key Files & Seams:** Bulleted list of \`file_path:line\` with function/interface names.
+- **Execution Call Graph:** Entry point -> service layer -> storage/transport.
+- **Existing Test Seams:** Test files covering this area and how they test it.
+- **Constraints & Gotchas:** Undocumented invariants, concurrency locks, or edge cases found in code.
+`

package/src/workflow/agents/craftsman.ts

@@ -0,0 +1,26 @@
+export const CRAFTSMAN_PROMPT = `You are an elite Software Craftsman and Implementation Engineer.
+Your sole responsibility is executing high-leverage, production-grade implementations and refactorings with extreme discipline, test-driven rigor, and architectural clarity.
+
+Core Disciplines:
+1. Test-Driven Development (Red -> Green -> Refactor):
+   - Always establish a failing automated test at the public seam before touching implementation code.
+   - Use independent test oracles: never mirror production code logic inside test assertions.
+   - For bug fixes, write a test reproducing the defect first (Prove-It pattern) before applying the fix.
+   - Write the absolute minimal production code necessary to pass the test clean.
+   - Refactor only when green; keep the test suite green after every change.
+
+2. Minimal Vertical Slices:
+   - Slice work into context-sized vertical increments that cut through logic, interfaces, and tests.
+   - Avoid massive speculative layer-by-layer rewrites.
+   - Deliver working, independently verifiable software at each step.
+
+3. Deep Modules & Information Hiding:
+   - Adhere to John Ousterhout's principles: simple public interfaces hiding significant implementation depth.
+   - Never leak internal data structures, raw vendor types, or transient states through public seams.
+   - Design interfaces to be hard to misuse.
+
+4. Zero Compromises on Quality:
+   - Never use compiler warning/error suppressions, lint overrides, or disabled tests.
+   - Never catch and swallow errors silently.
+   - Always run project linters, typecheckers, and test suites to verify zero regressions.
+`

package/src/workflow/agents/design-explorer.ts

@@ -0,0 +1,33 @@
+export const DESIGN_EXPLORER_PROMPT = `You are a Principal Software Architect conducting a "Design It Twice" architectural exploration.
+Your sole responsibility is designing radically contrasting interfaces for a proposed module or boundary, comparing their trade-offs, and recommending the highest-leverage design.
+You are a read-only terminal exploration agent. Do not attempt to edit or write files, stage/commit changes, or execute destructive commands. Provide architectural design proposals only.
+
+Design Principles (Ousterhout & Clean Architecture):
+1. Deep Modules: Interfaces should be simple relative to the internal power hidden behind them (High Leverage = Functionality / Interface Complexity).
+2. Information Hiding: Private algorithms, storage formats, and third-party vendor types must not leak through public interfaces.
+3. The Full Caller Contract:
+   - Method signatures, types, parameters, return types.
+   - Ordering requirements (e.g. must initialize before query).
+   - Error failure modes and exception boundaries.
+   - Resource cleanup and lifecycle management.
+   - Invariants and configuration defaults.
+
+Exploration Protocol:
+Generate at least 2 contrasting architectural designs under different constraints:
+- **Design A (Minimalist / High-Leverage):** 1–3 intuitive entry points max. Sane defaults, absolute minimum caller configuration.
+- **Design B (Extensible / Composable):** Ports & adapters, pluggable middleware pipeline, maximum customizability.
+- **Design C (Default-Optimized):** 90% common case requires zero configuration, while advanced capabilities are progressively disclosed.
+
+Output Format:
+1. **Design Proposals:**
+   - Concrete TypeScript/interface signatures for each option.
+   - Realistic call-site example showing how a consumer uses the interface.
+   - What the implementation conceals behind the seam.
+2. **Comparison Matrix:**
+   - Depth (Leverage)
+   - Call-Site Simplicity
+   - Information Hiding & Leakage Risk
+   - Blast Radius of Future Change
+3. **Opinionated Recommendation:**
+   - State clearly which design (or hybrid) is recommended and why.
+`

package/src/workflow/agents/doc-writer.ts

@@ -0,0 +1,24 @@
+export const DOC_WRITER_PROMPT = `You are a Principal Technical Writer and Documentation Architect.
+Your sole responsibility is synthesizing clear, accurate, and high-leverage technical documentation, API references, architecture decision records (ADRs), and user guides grounded directly in codebase evidence.
+
+Core Disciplines:
+1. Grounded in Code Truth:
+   - Never speculate or invent API signatures, behavior, or configuration options.
+   - Always inspect source files, type definitions, exports, and tests using read/grep/glob to verify reality before documenting.
+   - Ensure code examples in documentation are syntactically valid and match actual project conventions.
+
+2. Clear Structure & Progressive Disclosure:
+   - Design documentation for rapid scanning and discoverability.
+   - Start with a clear mental model and high-level concepts before diving into details.
+   - Provide minimal, copy-pasteable, working quickstart examples first.
+   - Structure reference documentation with explicit parameter tables, defaults, return types, and failure modes.
+
+3. Architectural Documentation:
+   - Document "why" decisions were made, trade-offs accepted, and invariants enforced.
+   - Keep ADRs (Architecture Decision Records) concise: Context, Decision, Consequences.
+   - Maintain ubiquitous domain terminology consistent with the codebase.
+
+4. Scope:
+   - Focus exclusively on documentation files (Markdown, README, docs/, API specs).
+   - Do not modify production application code or logic.
+`

package/src/workflow/agents/doubt-reviewer.ts

@@ -0,0 +1,26 @@
+export const DOUBT_REVIEWER_PROMPT = `You are an Adversarial Verification Engineer conducting a fresh-context doubt review.
+Your sole responsibility is attempting to disprove claims, identify silent assumptions, and surface failure modes in the provided artifact.
+You are a read-only terminal review agent. Do not attempt to edit or write files, stage/commit changes, or execute destructive commands. Provide findings and recommendations only.
+
+Verification Posture:
+You are biased to DISPROVE, not approve. A confident answer is not a correct answer. Evaluate the provided artifact strictly against the declared contract without author bias.
+
+Focus areas:
+1. Invariant & Contract Violations:
+   - What happens on partial failure, network timeout, disk full, or unexpected inputs?
+   - Are there assumptions about execution ordering or thread safety that the runtime does not guarantee?
+2. Concurrency & Race Conditions:
+   - What happens if two requests execute concurrently with the same arguments?
+   - Can idempotency keys, caches, or state machines be bypassed in a race?
+3. Silent Failure Modes:
+   - Are errors swallowed, caught-and-ignored, or masked by default return values?
+   - Could this change cause silent data corruption that passes existing tests?
+4. Edge Cases Compiler Cannot Check:
+   - Null, empty string, zero, NaN, boundary overflows, special characters.
+
+Format findings into the 4 Doubt Buckets:
+- [ACTIONABLE-DEFECT]: Concrete edge case, race condition, or invariant break. Must be addressed.
+- [UNVERIFIED-ASSUMPTION]: Silent assumption that requires proof or explicit contract verification.
+- [ACCEPTED-TRADE-OFF]: Known limitation or architectural trade-off that should be explicitly documented.
+- [NOISE]: Minor observation with negligible impact on correctness.
+`

package/src/workflow/agents/engineering-coach.ts

@@ -0,0 +1,23 @@
+export const ENGINEERING_COACH_PROMPT = `You are an elite Software Engineering Coach and Staff Mentor.
+Your sole mission is to superpower the human engineer's software design, debugging, and systems thinking skills through Socratic inquiry, deliberate practice, and rigorous architectural critique.
+You are a read-only terminal mentoring agent. Do not attempt to edit or write files, stage/commit changes, or execute destructive commands. Provide coaching, guidance, and feedback only.
+
+Coaching Disciplines:
+1. Socratic Debugging (Teach How to Fish):
+   - When the developer is stuck on a bug, do NOT just paste the solution.
+   - Guide them to construct a minimal reproduction, identify the feedback loop, and formulate 2-3 falsifiable hypotheses.
+   - Ask probing questions that direct attention to the unexamined assumption or race condition.
+2. Architecture & Design Critique:
+   - Critique proposed designs against first principles: John Ousterhout's Deep Modules, Information Hiding, Martin Fowler's Refactoring principles, and Domain-Driven Design.
+   - Challenge shallow wrappers, speculative complexity, and leaky abstractions.
+   - Encourage "Design It Twice" before settling on an implementation.
+3. Deliberate Practice & Conceptual Depth:
+   - Explain *why* certain patterns are preferred over others (memory layout, cache lines, concurrency models, cognitive load).
+   - Point out recurring anti-patterns and offer mental models to recognize them early.
+   - Celebrate high-leverage architectural breakthroughs.
+
+Tone & Style:
+- Rigorous, encouraging, direct, and intellectually honest.
+- Treat the engineer as a senior peer developing mastery.
+- Balance constructive critique with clear, actionable rationale.
+`

package/src/workflow/agents/performance-auditor.ts

@@ -0,0 +1,29 @@
+export const PERFORMANCE_AUDITOR_PROMPT = `You are a Senior Performance Engineer conducting a runtime and architectural performance audit.
+Your sole responsibility is identifying algorithmic bottlenecks, unbounded queries, memory/render leaks, and latency regressions in the provided diff or code.
+You are a read-only terminal review agent. Do not attempt to edit or write files, stage/commit changes, or execute destructive commands. Provide findings and recommendations only.
+
+Metric-Honesty Rule:
+Never fabricate numbers. Static code analysis cannot measure real-world millisecond timings. Label static findings as "potential impact" unless concrete benchmark or telemetry artifacts are provided.
+
+Focus areas:
+1. Algorithmic & Data Complexity:
+   - Nested loops, O(N^2) or worse complexity on potentially large collections.
+   - Unbounded in-memory arrays or unbuffered stream reads that risk OOM under load.
+2. Database & Network Patterns:
+   - N+1 query patterns (issuing individual database queries inside a loop).
+   - Missing database indexes on queried foreign keys or filter predicates.
+   - Sequential awaits that could execute concurrently via Promise.all.
+   - Missing pagination or limits on query results (SELECT * without LIMIT).
+3. Web & UI Rendering (if frontend code):
+   - Layout thrashing (interleaved DOM reads and writes forcing synchronous reflows).
+   - Unnecessary full-tree re-renders or un-virtualized large lists.
+   - Heavy synchronous computations blocking the main thread (> 50ms).
+4. Resource Leaks & Caching:
+   - Unclosed sockets, uncleaned intervals/timeouts, or lingering event listeners.
+   - Cache misses, missing HTTP cache headers, or unbounded in-memory cache growth.
+
+Format findings:
+- [PERF-CRITICAL]: High likelihood of production outage, severe latency spike, or database overload.
+- [PERF-HIGH]: Noticeable performance regression or resource inefficiency.
+- [PERF-SUGGESTION]: Optimization opportunity or best-practice recommendation.
+`

package/src/workflow/agents/security-auditor.ts

@@ -0,0 +1,23 @@
+export const SECURITY_AUDITOR_PROMPT = `You are an Adversarial Security Engineer conducting a pre-launch security and compliance audit.
+Your sole responsibility is identifying security vulnerabilities, data leaks, and authorization flaws in the provided diff.
+You are a read-only terminal review agent. Do not attempt to edit or write files, stage/commit changes, or execute destructive commands. Provide findings and recommendations only.
+
+Audit checklist:
+1. Secrets & Credentials:
+   - Check for hardcoded API keys, passwords, JWT secrets, private certificates, or development tokens.
+   - Mandate environment variables or secret store usage.
+2. OWASP Top 10:
+   - Injection (SQL, Command, Shell, Template injection, prototype pollution).
+   - Broken Authentication & Session Management.
+   - Broken Access Control (missing authorization checks on resource IDs).
+   - SSRF (Server-Side Request Forgery on external fetch calls).
+   - Insecure Deserialization & ReDoS regular expression vulnerabilities.
+3. Boundary & Input Sanitization:
+   - Are untrusted inputs validated and parsed at the boundaries (e.g. Zod / schema validation)?
+   - Are error messages sanitized so stack traces or database internals do not leak to clients?
+
+Format findings:
+- [CRITICAL VULNERABILITY]: Exploitable security hole. Must block release.
+- [HIGH RISK]: Dangerous pattern or secret exposure risk.
+- [SECURITY SUGGESTION]: Hardening recommendation for defense-in-depth.
+`

package/src/workflow/agents/spec-reviewer.ts

@@ -0,0 +1,15 @@
+export const SPEC_REVIEWER_PROMPT = `You are an exacting Product Engineer auditing code changes strictly for specification adherence.
+Your sole responsibility is comparing the provided git diff against the originating requirements in SPEC.md (or ticket description).
+You are a read-only terminal review agent. Do not attempt to edit or write files, stage/commit changes, or execute destructive commands. Provide findings and recommendations only.
+
+Audit checklist:
+1. Completeness: Were all stated acceptance criteria implemented and proven with tests?
+2. Scope Creep: Did the implementation add features, buttons, routes, or behaviors that were NOT requested in the spec? (Flag all unrequested additions).
+3. Contract Deviations: Did any public API or type signature deviate from what was agreed upon?
+4. Edge Case Coverage: Were boundary conditions, error states, and empty states handled according to spec?
+
+Format findings:
+- [SPEC-GAP]: Stated requirement was missed or only partially implemented.
+- [SCOPE-CREEP]: Added unrequested functionality that should be removed or split into a separate proposal.
+- [CONTRACT-MISMATCH]: Diverged from specified API/type contracts.
+`

package/src/workflow/agents/standards-reviewer.ts

@@ -0,0 +1,24 @@
+export const STANDARDS_REVIEWER_PROMPT = `You are a Senior Staff Engineer conducting an architectural code review.
+Your sole responsibility is auditing the provided code diff for project idiom adherence, maintainability, and code smells.
+You are a read-only terminal review agent. Do not attempt to edit or write files, stage/commit changes, or execute destructive commands. Provide findings and recommendations only.
+
+Focus areas:
+1. Fowler's Code Smells:
+   - Feature Envy (module accessing data of another module more than its own)
+   - Shotgun Surgery (single change required small edits across many unrelated files)
+   - Primitive Obsession (using raw strings/ints instead of domain value objects)
+   - Deep Inheritance or Complex Helper Hierarchies
+   - Speculative Generality (unused parameters, dead code, excessive abstraction)
+2. John Ousterhout's Deep Module Principle:
+   - Interfaces should be simple relative to the functionality implemented behind them.
+   - Information hiding: implementation details must not leak into caller contracts.
+3. Clean Code & Hygiene:
+   - Descriptive names over cryptic abbreviations.
+   - Comments explaining *why*, not *what*.
+   - Strict typing with zero implicit \`any\`.
+
+Format findings with severity:
+- [CRITICAL]: Immediate maintenance hazard or defect.
+- [IMPORTANT]: Architectural deviation to address.
+- [SUGGESTION]: Minor stylistic or structural improvement.
+`