opencode-overclock 0.3.0 → 0.5.0

package/src/v2/loader.ts

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview OpenCode V2 Plugin Resolution and Loading
+ *
+ * Provides resolution, dynamic importation, and execution of V2 plugins
+ * on top of a synthetic V2 `PluginContext`.
+ *
+ * Supported plugin formats:
+ *  - Direct instances: `{ id, setup(context) }` or `{ id, effect(context) }`
+ *  - File paths: `./plugins/custom.ts`, `/absolute/path/plugin.js`, `file:///...`
+ *  - Npm packages: bare module specifiers resolved via node/bun module resolution
+ *  - Tuples: `[specifier, pluginOptions]` for supplying per-plugin options
+ */
+
+import { resolve, isAbsolute } from "path"
+import { pathToFileURL, fileURLToPath } from "url"
+import type { Plugin as V2Plugin, PluginOptions } from "@opencode-ai/plugin/v2/promise"
+import type { Disposer, V2ContextHandle } from "./context.ts"
+
+/**
+ * Union of accepted V2 plugin declaration formats:
+ *  - String specifier: file path or package name
+ *  - Tuple: `[specifier, options]`
+ *  - Plugin instance conforming to V2 interface
+ *  - Wrapper object: `{ plugin, options }`
+ */
+export type V2PluginSpec =
+  string | [string, PluginOptions] | V2Plugin | { plugin: V2Plugin; options?: PluginOptions }
+
+/**
+ * Validates whether an unknown value conforms to the OpenCode V2 plugin contract:
+ * requires non-empty string `id`, and either an async `setup` method or an `effect` function.
+ */
+export function isV2Plugin(value: unknown): value is V2Plugin {
+  if (!value || typeof value !== "object") return false
+  const p = value as Record<string, unknown>
+  if (typeof p.id !== "string" || !p.id.trim()) return false
+  return typeof p.setup === "function" || typeof (p as any).effect === "function"
+}
+
+/**
+ * Resolves a file path or URL specifier against the workspace directory.
+ * Preserves bare package names for standard Node/Bun module resolution.
+ */
+export function resolvePluginPath(spec: string, baseDir: string): string {
+  if (spec.startsWith("file://")) return fileURLToPath(spec)
+  if (isAbsolute(spec)) return spec
+  if (spec.startsWith(".")) return resolve(baseDir, spec)
+  return spec
+}
+
+/**
+ * Resolves a V2 plugin specifier into a concrete V2Plugin object and its associated options.
+ * Dynamically imports file paths or npm packages if necessary.
+ */
+export async function resolveV2Plugin(
+  spec: V2PluginSpec,
+  baseDir: string,
+): Promise<{ plugin: V2Plugin; options: PluginOptions } | null> {
+  // Case 1: Already an instantiated V2Plugin object
+  if (isV2Plugin(spec)) {
+    return { plugin: spec, options: {} }
+  }
+
+  // Case 2: Wrapped { plugin, options } object
+  if (
+    typeof spec === "object" &&
+    spec !== null &&
+    "plugin" in spec &&
+    isV2Plugin((spec as any).plugin)
+  ) {
+    return {
+      plugin: (spec as any).plugin,
+      options: (spec as any).options ?? {},
+    }
+  }
+
+  // Case 3: Specifier string or [string, options] tuple
+  let moduleSpec: string
+  let options: PluginOptions = {}
+
+  if (Array.isArray(spec)) {
+    moduleSpec = spec[0]
+    options = spec[1] ?? {}
+  } else if (typeof spec === "string") {
+    moduleSpec = spec
+  } else {
+    return null
+  }
+
+  const resolved = resolvePluginPath(moduleSpec, baseDir)
+  const importTarget = resolved.startsWith("/") ? pathToFileURL(resolved).href : resolved
+
+  try {
+    const mod = await import(importTarget)
+    const candidate = mod?.default ?? mod
+    if (isV2Plugin(candidate)) {
+      return { plugin: candidate, options }
+    }
+    // Check named exports for a V2 plugin definition
+    for (const val of Object.values(mod)) {
+      if (isV2Plugin(val)) {
+        return { plugin: val, options }
+      }
+    }
+    console.warn(
+      `[overclock] v2: module '${moduleSpec}' does not export a valid V2 plugin ({ id, setup/effect })`,
+    )
+    return null
+  } catch (e) {
+    console.warn(`[overclock] v2: failed to import plugin '${moduleSpec}': ${e}`)
+    return null
+  }
+}
+
+/**
+ * Loads and initializes a V2 plugin against the synthetic context.
+ * Creates a scoped context, handles Effect vs Promise lifecycle, and tracks disposers.
+ * Returns the plugin ID if loaded successfully, or null on error.
+ */
+export async function loadV2Plugin(
+  spec: V2PluginSpec,
+  baseDir: string,
+  handle: V2ContextHandle,
+): Promise<string | null> {
+  const resolved = await resolveV2Plugin(spec, baseDir)
+  if (!resolved) return null
+
+  const { plugin, options } = resolved
+  const pluginDisposers = new Set<Disposer>()
+  const scopedCtx = handle.scopedContext(options, pluginDisposers)
+
+  handle.state.activePlugins.set(plugin.id, {
+    plugin,
+    disposers: pluginDisposers,
+  })
+
+  try {
+    if (typeof (plugin as any).effect === "function") {
+      const { runPromise } = await import("effect/Effect")
+      await runPromise((plugin as any).effect(scopedCtx))
+    } else if (typeof plugin.setup === "function") {
+      await plugin.setup(scopedCtx)
+    }
+    return plugin.id
+  } catch (e) {
+    console.warn(`[overclock] v2: plugin '${plugin.id}' failed during setup: ${e}`)
+    await handle.context.plugin.remove(plugin.id)
+    return null
+  }
+}

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/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/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.
+`

package/src/workflow/agents/test-engineer.ts

@@ -0,0 +1,28 @@
+export const TEST_ENGINEER_PROMPT = `You are an experienced QA and Test Strategy Engineer.
+Your sole responsibility is auditing test coverage, identifying missing edge cases, evaluating test seam placement, and ensuring verification rigor.
+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. Test Seam & Level:
+   - Are tests placed at the correct public seams rather than coupled to internal implementation details?
+   - Is logic tested at the lowest appropriate level (unit for pure logic, integration for boundaries, e2e for critical flows)?
+2. The Prove-It Pattern for Defects:
+   - For bug fixes, does the test reproduce the exact defect before the fix is applied?
+   - Does the test fail for the right reason, or is it a false-negative syntax error?
+3. Test Quality & Oracle Independence:
+   - Are expected values calculated independently, or are they tautological copies of the implementation logic?
+   - Are assertions meaningful (Beyoncé Rule: "If you liked it, then you should have put a test on it")?
+   - Are tests DAMP over DRY: readable top-to-bottom without obscure fixture indirection?
+4. Edge Cases & Boundary Conditions:
+   - Empty collections, null/undefined, min/max values, zero, negative numbers.
+   - Network failure, timeout, disconnection, race conditions, rapid concurrent calls.
+5. Mocking Boundaries:
+   - Are mocks restricted to external third-party boundaries (HTTP APIs, payment gateways)?
+   - Flag any test mocking internal domain entities or the system under test.
+
+Format findings:
+- [COVERAGE-GAP]: Critical missing test scenario or unexercised edge case.
+- [BRITTLE-TEST]: Test coupled to private implementation details rather than public behavior.
+- [TAUTOLOGICAL-TEST]: Test that mirrors implementation flawed logic or never truly asserts behavior.
+- [RECOMMENDED-TEST]: Concrete test specification with Given/When/Then scenarios.
+`

package/src/workflow/catalog.ts

@@ -0,0 +1,210 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { dirname, basename, resolve } from "node:path"
+import YAML from "yaml"
+
+export interface SkillMetadata {
+  name: string
+  description: string
+  pack?: string
+  license?: string
+  attribution?: string
+  references?: string[]
+  [key: string]: unknown
+}
+
+export interface ParsedSkill {
+  filePath: string
+  directory: string
+  metadata: SkillMetadata
+  body: string
+  rawFrontmatter: string
+}
+
+export interface SkillValidationError {
+  filePath: string
+  message: string
+}
+
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/
+
+/**
+ * Extracts and parses YAML frontmatter with strict duplicate key checking.
+ */
+export function parseFrontmatter(
+  content: string,
+  filePath = "<string>",
+): { metadata: SkillMetadata; body: string; rawFrontmatter: string } {
+  const match = content.match(FRONTMATTER_REGEX)
+  if (!match) {
+    throw new Error(`Missing frontmatter delimiter (---) in ${filePath}`)
+  }
+
+  const rawFrontmatter = match[1]!
+  const body = match[2]!
+
+  let parsed: unknown
+  try {
+    parsed = YAML.parse(rawFrontmatter, { uniqueKeys: true })
+  } catch (err: any) {
+    throw new Error(`Invalid YAML frontmatter in ${filePath}: ${err?.message ?? String(err)}`)
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Frontmatter must be a key-value mapping in ${filePath}`)
+  }
+
+  const data = parsed as Record<string, unknown>
+
+  if (typeof data.name !== "string" || !data.name.trim()) {
+    throw new Error(`Skill frontmatter missing required string "name" in ${filePath}`)
+  }
+
+  const name = data.name.trim()
+  if (!/^[a-z0-9_-]+$/.test(name)) {
+    throw new Error(
+      `Invalid skill name "${name}" in ${filePath}: must be lowercase alphanumeric with dashes or underscores`,
+    )
+  }
+
+  if (typeof data.description !== "string" || data.description.trim().length < 10) {
+    throw new Error(
+      `Skill frontmatter "description" in ${filePath} must be a descriptive string (at least 10 characters)`,
+    )
+  }
+
+  const metadata: SkillMetadata = {
+    ...data,
+    name,
+    description: data.description.trim(),
+  }
+
+  return { metadata, body, rawFrontmatter }
+}
+
+/**
+ * Validates a single SKILL.md file for schema compliance, directory matching,
+ * and relative reference closure.
+ */
+export function validateSkillFile(filePath: string): {
+  valid: boolean
+  errors: string[]
+  skill?: ParsedSkill
+} {
+  const errors: string[] = []
+
+  if (!existsSync(filePath)) {
+    return { valid: false, errors: [`File does not exist: ${filePath}`] }
+  }
+
+  let content = ""
+  try {
+    content = readFileSync(filePath, "utf-8")
+  } catch (err: any) {
+    return { valid: false, errors: [`Failed to read file ${filePath}: ${err?.message}`] }
+  }
+
+  let parsed: { metadata: SkillMetadata; body: string; rawFrontmatter: string }
+  try {
+    parsed = parseFrontmatter(content, filePath)
+  } catch (err: any) {
+    return { valid: false, errors: [err?.message ?? String(err)] }
+  }
+
+  const skillDir = dirname(filePath)
+  const dirName = basename(skillDir)
+
+  if (parsed.metadata.name !== dirName) {
+    errors.push(
+      `Skill name mismatch in ${filePath}: declared "${parsed.metadata.name}" but parent directory is "${dirName}"`,
+    )
+  }
+
+  // Validate declared references
+  if (parsed.metadata.references) {
+    if (!Array.isArray(parsed.metadata.references)) {
+      errors.push(`"references" in ${filePath} must be an array of relative paths`)
+    } else {
+      for (const ref of parsed.metadata.references) {
+        if (typeof ref !== "string") {
+          errors.push(`Invalid reference in ${filePath}: expected string, got ${typeof ref}`)
+          continue
+        }
+        const resolvedRef = resolve(skillDir, ref)
+        if (!existsSync(resolvedRef)) {
+          errors.push(`Declared reference not found in ${filePath}: "${ref}" -> ${resolvedRef}`)
+        }
+      }
+    }
+  }
+
+  // Check markdown links to local files (dependency closure)
+  const linkRegex = /\[[^\]]+\]\((?!https?:\/\/|#|mailto:)([^)#?]+)\)/g
+  let match: RegExpExecArray | null
+  while ((match = linkRegex.exec(parsed.body)) !== null) {
+    const target = match[1]?.trim()
+    if (!target) continue
+    const resolvedLink = resolve(skillDir, target)
+    if (!existsSync(resolvedLink)) {
+      errors.push(`Broken local markdown link in ${filePath}: "${target}" -> ${resolvedLink}`)
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors }
+  }
+
+  return {
+    valid: true,
+    errors: [],
+    skill: {
+      filePath,
+      directory: skillDir,
+      metadata: parsed.metadata,
+      body: parsed.body,
+      rawFrontmatter: parsed.rawFrontmatter,
+    },
+  }
+}
+
+/**
+ * Validates all skills within the bundled skills directory.
+ */
+export function validateAllSkills(skillsDir: string): {
+  valid: boolean
+  errors: SkillValidationError[]
+  skills: ParsedSkill[]
+} {
+  const errors: SkillValidationError[] = []
+  const skills: ParsedSkill[] = []
+
+  if (!existsSync(skillsDir)) {
+    return {
+      valid: false,
+      errors: [{ filePath: skillsDir, message: `Skills directory does not exist: ${skillsDir}` }],
+      skills: [],
+    }
+  }
+
+  const entries = readdirSync(skillsDir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const skillFile = resolve(skillsDir, entry.name, "SKILL.md")
+      if (existsSync(skillFile)) {
+        const result = validateSkillFile(skillFile)
+        if (result.valid && result.skill) {
+          skills.push(result.skill)
+        } else {
+          for (const err of result.errors) {
+            errors.push({ filePath: skillFile, message: err })
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    skills,
+  }
+}

package/src/workflow/templates/build.ts

@@ -0,0 +1,47 @@
+export const BUILD_TEMPLATE = `---
+description: Test-driven implementation loop with stop-the-line tripwires and incremental verification.
+---
+# Lifecycle Phase 3: Build
+
+Execute tasks from \`tasks/plan.md\` (or the specific task requested: $ARGUMENTS).
+
+## Autonomous Mode ($ARGUMENTS contains "auto") vs Single-Slice Mode
+- **With \`auto\`:** Iteratively execute all unblocked tasks from \`tasks/plan.md\` sequentially until all are complete or a tripwire triggers.
+- **Without \`auto\` (Default):** Execute only the next unblocked task on the frontier, verify, and pause for human review.
+
+---
+
+## The Increment Cycle (Per Task)
+
+For each task on the frontier:
+
+1. **RED (Prove Capability Missing):**
+   - Write a focused test at the declared public seam before touching implementation code.
+   - Use an **independent test oracle**: never compute expected results with the same logic used in production code.
+   - Run the test suite: confirm the test fails for the expected reason (missing capability, not a syntax error).
+   - *Prove-It Pattern:* If fixing a bug, the test MUST reproduce the reported defect before touching the fix.
+
+2. **GREEN (Minimal Implementation):**
+   - Write the minimal code required to make the test pass clean.
+   - Do NOT add speculative abstractions or unrequested features.
+   - Never use error suppressions (\`@ts-ignore\`, \`eslint-disable\`, \`# noqa\`) or test skips (\`.skip\`). Overclock's floor-guard will flag them.
+
+3. **REFACTOR (Clean While Green):**
+   - Refactor only while all tests are green.
+   - Remove duplication, simplify names, and polish structure. Re-verify tests pass after every refactoring edit.
+
+4. **VERIFY:**
+   - Run project linters and typecheckers to confirm zero regressions.
+
+5. **UPDATE PLAN:**
+   - Mark the completed task in \`tasks/plan.md\` and update \`todowrite\`.
+   - If git commits are used, stage ONLY the files modified for this slice with a descriptive commit message.
+
+---
+
+## Stop-The-Line Tripwires (Immediate Halt)
+Halt execution and alert the user immediately if:
+- **Test Failure Loop:** A test fails to pass after 3 consecutive fix attempts.
+- **Irreversible Boundary:** The task requires altering production database schemas, payment processing, or secret keys.
+- **Specification Ambiguity:** An unhandled edge case is discovered that contradicts \`SPEC.md\` or requires human judgment.
+`