VU-1134: replace agent eval harness with tiered OpenCode runner

.github/dependabot.yml

@@ -17,6 +17,11 @@ updates:
     schedule:
       interval: weekly
 
+  - package-ecosystem: npm
+    directory: /tests/evals
+    schedule:
+      interval: weekly
+
   - package-ecosystem: cargo
     directory: /app/src-tauri
     schedule:

.github/workflows/docs.yml

@@ -8,6 +8,7 @@ on:
       - "docs/user-guide/**"
       - "docs/.vitepress/**"
       - "docs/package.json"
+      - "docs/package-lock.json"
   workflow_dispatch:
 
 permissions:
@@ -32,9 +33,12 @@ jobs:
           cache-dependency-path: docs/package-lock.json
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
         working-directory: docs
 
+      - name: Check help documentation links
+        run: node scripts/check-help-docs.mjs
+
       - name: Build
         run: npm run build
         working-directory: docs

.github/workflows/pr-ci.yml

@@ -8,12 +8,6 @@ on:
     paths-ignore:
       - '**/*.md'
       - 'LICENSE'
-  pull_request:
-    branches:
-      - main
-    paths-ignore:
-      - '**/*.md'
-      - 'LICENSE'
 
 permissions:
   contents: read

.github/workflows/pr-policy.yml

@@ -17,21 +17,45 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
+      - name: Detect relevant changes
+        id: changes
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            docs:
+              - 'docs/user-guide/**'
+              - 'docs/.vitepress/**'
+              - 'docs/package.json'
+              - 'docs/package-lock.json'
+              - 'scripts/check-help-docs.mjs'
+              - 'app/src/lib/help-urls.ts'
+
       - name: Setup Node.js
+        if: steps.changes.outputs.docs == 'true'
         uses: actions/setup-node@v6
         with:
           node-version: "20"
           cache: "npm"
           cache-dependency-path: docs/package-lock.json
 
       - name: Install docs dependencies
+        if: steps.changes.outputs.docs == 'true'
         working-directory: docs
-        run: npm install
+        run: npm ci
+
+      - name: Check help documentation links
+        if: steps.changes.outputs.docs == 'true'
+        run: node scripts/check-help-docs.mjs
 
       - name: Build user-guide site
+        if: steps.changes.outputs.docs == 'true'
         working-directory: docs
         run: npm run build
 
+      - name: Skip (no docs changes)
+        if: steps.changes.outputs.docs != 'true'
+        run: echo "No docs changes detected — skipping."
+
   agents-structural:
     name: agents-structural
     runs-on: ubuntu-latest
@@ -99,13 +123,6 @@ jobs:
           npx markdownlint-cli2
           "AGENTS.md" "CLAUDE.md" "README.md" "TEST_MANIFEST.md"
           ".claude/rules/**/*.md"
-          ".claude/skills/close-linear-issue/SKILL.md"
-          ".claude/skills/create-linear-issue/SKILL.md"
-          ".claude/skills/explaining-code/SKILL.md"
-          ".claude/skills/front-end-design/SKILL.md"
-          ".claude/skills/implement-linear-issue/SKILL.md"
-          ".claude/skills/implement-linear-issue/references/*.md"
-          ".claude/skills/playwright/SKILL.md"
           "agent-sources/**/*.md"
           "#agent-sources/plugins/vd-agent/**"
           "#agent-sources/plugins/skill-creator/skills/skill-creator/**"
@@ -116,6 +133,66 @@ jobs:
         if: steps.changes.outputs.docs != 'true'
         run: echo "No markdown/instruction-doc changes detected — skipping."
 
+  eval-harness:
+    name: eval-harness
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Detect relevant changes
+        id: changes
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            evals:
+              - 'tests/evals/**'
+
+      - name: Setup Node.js
+        if: steps.changes.outputs.evals == 'true'
+        uses: actions/setup-node@v6
+        with:
+          node-version: "lts/*"
+          cache: "npm"
+          cache-dependency-path: tests/evals/package-lock.json
+
+      - name: Install eval harness dependencies
+        if: steps.changes.outputs.evals == 'true'
+        working-directory: tests/evals
+        run: npm ci --prefer-offline
+
+      - name: Run deterministic eval harness tests
+        if: steps.changes.outputs.evals == 'true'
+        working-directory: tests/evals
+        run: npm test
+
+      - name: Skip (no eval harness changes)
+        if: steps.changes.outputs.evals != 'true'
+        run: echo "No eval harness changes detected — skipping."
+
+  script-tests:
+    name: script-tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Detect relevant changes
+        id: changes
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            scripts:
+              - 'scripts/*.mjs'
+
+      - name: Run script tests
+        if: steps.changes.outputs.scripts == 'true'
+        run: node --test scripts/*.test.mjs
+
+      - name: Skip (no script changes)
+        if: steps.changes.outputs.scripts != 'true'
+        run: echo "No script changes detected — skipping."
+
   repo-map-audit:
     name: repo-map-audit
     runs-on: ubuntu-latest
@@ -131,6 +208,9 @@ jobs:
           HEAD_SHA="${{ github.event.pull_request.head.sha }}"
 
           STRUCTURAL_DIRS=(
+            ".github/"
+            "scripts/"
+            "tests/evals/"
             "app/src-tauri/src/commands/"
             "app/src/stores/"
             "app/src/pages/"

.github/workflows/release.yml

@@ -101,6 +101,7 @@ jobs:
           open -n "$DIR/Skill Builder.app"
           SCRIPT
           chmod +x "$STAGE/run.sh"
+          node scripts/verify-release-stage.mjs "$STAGE" macos
           zip -r "${STAGE}.zip" "$STAGE"
 
       - name: Package Windows release
@@ -113,26 +114,24 @@ jobs:
           mkdir -p "$STAGE"
           cp "app/src-tauri/target/release/skill-builder.exe" "$STAGE/"
 
-          # Copy sidecar JS files (bootstrap + agent-runner + SDK)
-          # The Rust exe-relative fallback looks for {exe_dir}/sidecar/dist/...
+          # Copy sidecar JS files. The Rust exe-relative fallback looks for
+          # {exe_dir}/sidecar/dist/...
           mkdir -p "$STAGE/sidecar/dist/sdk"
           cp "app/sidecar/dist/package.json" "$STAGE/sidecar/dist/"
           cp "app/sidecar/dist/bootstrap.js" "$STAGE/sidecar/dist/"
           cp "app/sidecar/dist/agent-runner.js" "$STAGE/sidecar/dist/"
-          cp "app/sidecar/dist/sdk/cli.js" "$STAGE/sidecar/dist/sdk/"
-          cp "app/sidecar/dist/sdk/manifest.json" "$STAGE/sidecar/dist/sdk/"
+          cp "app/sidecar/dist/sdk/claude.exe" "$STAGE/sidecar/dist/sdk/"
           cp app/sidecar/dist/sdk/*.wasm "$STAGE/sidecar/dist/sdk/" 2>/dev/null || true
           if [ -d "app/sidecar/dist/sdk/vendor" ]; then
             cp -r "app/sidecar/dist/sdk/vendor" "$STAGE/sidecar/dist/sdk/"
           fi
 
-          # Copy agents and references (used by the sidecar at runtime)
-          if [ -d "agents" ]; then
-            cp -r "agents" "$STAGE/agents"
-          fi
-          if [ -d "references" ]; then
-            cp -r "references" "$STAGE/references"
-          fi
+          mkdir -p "$STAGE/agent-sources" "$STAGE/workspace"
+          cp -r "agent-sources/plugins" "$STAGE/agent-sources/plugins"
+          cp -r "agent-sources/skills" "$STAGE/agent-sources/skills"
+          cp -r "agent-sources/workspace/." "$STAGE/workspace/"
+
+          node scripts/verify-release-stage.mjs "$STAGE" windows
 
           7z a "${STAGE}.zip" "$STAGE"
 

AGENTS.md

@@ -1,6 +1,6 @@
 # Skill Builder
 
-Multi-agent workflow for creating domain-specific Claude skills. Tauri desktop app (React + Rust) orchestrates agents via a Node.js sidecar.
+Desktop app for creating domain-specific Claude Code-compatible skills. Tauri desktop app (React + Rust) orchestrates agents via a Node.js sidecar.
 
 **Maintenance rule:** This file contains architecture, conventions, and guidelines — not product details. Do not add counts, feature descriptions, or any fact that can be discovered by reading code. If it will go stale when the code changes, it doesn't belong here — point to the source file instead.
 
@@ -10,7 +10,7 @@ Use this precedence when maintaining agent guidance:
 
 1. `AGENTS.md` (canonical, cross-agent source of truth)
 2. `.claude/rules/*.md` (shared detailed rules; agent-agnostic content)
-3. `.claude/skills/*/SKILL.md` (workflow playbooks)
+3. `agent-sources/**` (runtime agent, plugin, skill, and workspace instructions)
 4. Agent-specific adapter files (for example `CLAUDE.md`) that reference canonical docs
 
 Adapter files must not duplicate canonical policy unless they are adding agent-specific behavior.
@@ -20,7 +20,7 @@ Adapter files must not duplicate canonical policy unless they are adding agent-s
 | Layer | Technology |
 |---|---|
 | Desktop framework | Tauri v2 |
-| Frontend | React 19, TypeScript strict, Vite 7 |
+| Frontend | React 19, TypeScript strict, Vite 8 |
 | Styling | Tailwind CSS 4, shadcn/ui |
 | State | Zustand, TanStack Router |
 | Icons | Lucide React |
@@ -59,7 +59,7 @@ Read these before starting any non-trivial task:
 
 | Artifact | Update when |
 |---|---|
-| `AGENTS.md` | A fact is durable, non-obvious, and won't be obvious from code · a skill is added to `.claude/skills/` |
+| `AGENTS.md` | A fact is durable, non-obvious, and won't be obvious from code |
 | `repo-map.json` | Any file added, removed, or renamed inside `commands/`, `stores/`, `pages/`, `components/`, `lib/`, `hooks/` · sub-module directory added or restructured · new Tauri command file · entrypoint or package structure change |
 | `README.md` | User-facing installation, configuration, commands, or architecture overview changes |
 | `TEST_MANIFEST.md` | Rust command file added/removed · E2E spec added/removed · shared infra file added/removed · agent artifact format changes affecting a Rust or TS parser |
@@ -96,28 +96,28 @@ Run these automatically before reporting completion when files match:
 | `app/e2e/fixtures/agent-responses/**` | `cd app && npm run test:unit` |
 | `app/src-tauri/src/contracts/**` | `cd app && npm run codegen && cd src-tauri && cargo test contracts::` |
 | `app/src/**` | `cd app && npm run test:unit` |
+| `tests/evals/**` | `cd tests/evals && npm test` |
 
 **E2E tests** use Playwright to drive the real Tauri app UI, but with mocked Tauri commands (`__TAURI_MOCK_OVERRIDES__` / `reloadWithOverrides`). They are not bare-metal system tests — the backend is always mocked.
 
 For artifact format changes (agent output + app parser + mock templates): run `test:agents:structural` and `test:unit`, then tell the user to run `test:agents:smoke` manually. The `canonical-format.test.ts` suite is the canary for format drift.
 
 For Rust and cross-layer changes, consult `TEST_MANIFEST.md` for the correct cargo filter and E2E tag. Unsure? `app/tests/run.sh` runs everything.
 
-**Never run `test:agents:smoke` autonomously** — it makes live API calls. Tell the user to run it manually.
+**Never run `test:agents:smoke` autonomously unless explicitly requested** — it makes live API/model calls through the OpenCode eval harness in `tests/evals`. The deterministic harness contract test is `cd tests/evals && npm test`.
 
 ## Issue Management
 
 - **PR title format:** `VU-XXX: short description`
 - **PR body link:** `Fixes VU-XXX`
 - **Linear project:** All issues created for this repository must be created under **Skill Builder**.
-- **Worktrees:** `../worktrees/<branchName>` relative to repo root, preserving the full branch name including the `feature/` prefix. Pre-create the parent directory before adding:
+- **Worktrees:** Use `./scripts/worktree.sh <branch-name>` as the canonical maintainer workflow for creating or attaching a repo worktree and bootstrapping it. It preserves the full branch name under `../worktrees/<branchName>` and symlinks each worktree's `tests/evals/.promptfoo` back to the source checkout so Promptfoo history/database state stays out of feature worktrees.
 
   ```bash
-  mkdir -p ../worktrees/feature
-  git worktree add ../worktrees/feature/<branch-name> <branch-name>
+  ./scripts/worktree.sh feature/<branch-name>
   ```
 
-**Pre-commit:** `markdownlint <file>` for `.md` files · `cd app && npx tsc --noEmit` · `cargo clippy --manifest-path app/src-tauri/Cargo.toml -- -D warnings` · `bash app/scripts/lint-agent-docs.sh` when editing `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, or `.claude/skills/` · `cd app && npm run test:unit` when changing event types in `app/src/lib/` or `app/sidecar/`.
+**Pre-commit:** `markdownlint <file>` for `.md` files · `cd app && npx tsc --noEmit` · `cargo clippy --manifest-path app/src-tauri/Cargo.toml -- -D warnings` · `bash app/scripts/lint-agent-docs.sh` when editing `AGENTS.md`, `CLAUDE.md`, or `.claude/rules/` · `cd app && npm run test:unit` when changing event types in `app/src/lib/` or `app/sidecar/`.
 
 **Pre-PR `repo-map.json` audit (required):** Before opening or updating a PR, verify `repo-map.json` reflects the current codebase. Check:
 

CLAUDE.md

@@ -13,7 +13,6 @@ NEVER make edits, run non-readonly tools, or create files while in plan mode. On
 ### Model tiers
 
 | Tier | Model | When |
-
 |---|---|---|
 | Reasoning | sonnet | Planning, architecture, requirements drafting |
 | Implementation | default | Coding, exploration, review, merge |