opendevbrowser 0.0.12 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opendevbrowser",
-  "version": "0.0.12",
+  "version": "0.0.16",
   "description": "OpenCode plugin for browser automation via CDP with snapshot-refs-actions workflow",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "skills",
+    "scripts/native",
     "extension/manifest.json",
     "extension/popup.html",
     "extension/dist",
@@ -36,36 +37,44 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/cli/index.ts --format esm --dts --clean --sourcemap && node --input-type=module -e \"import { copyFileSync, existsSync } from 'node:fs';\nimport { resolve } from 'node:path';\nconst dist = resolve('dist');\nconst pairs = [\n  ['index.js', 'opendevbrowser.js'],\n  ['index.js.map', 'opendevbrowser.js.map'],\n  ['index.d.ts', 'opendevbrowser.d.ts'],\n  ['index.d.ts.map', 'opendevbrowser.d.ts.map'],\n];\nfor (const [src, dst] of pairs) {\n  const from = resolve(dist, src);\n  const to = resolve(dist, dst);\n  if (existsSync(from)) copyFileSync(from, to);\n}\"",
+    "build": "tsup src/index.ts src/cli/index.ts --format esm --clean --sourcemap && tsc --emitDeclarationOnly --declaration --declarationMap -p tsconfig.json && node --input-type=module -e \"import { copyFileSync, existsSync } from 'node:fs';\nimport { resolve } from 'node:path';\nconst dist = resolve('dist');\nconst pairs = [\n  ['index.js', 'opendevbrowser.js'],\n  ['index.js.map', 'opendevbrowser.js.map'],\n  ['index.d.ts', 'opendevbrowser.d.ts'],\n  ['index.d.ts.map', 'opendevbrowser.d.ts.map'],\n];\nfor (const [src, dst] of pairs) {\n  const from = resolve(dist, src);\n  const to = resolve(dist, dst);\n  if (existsSync(from)) copyFileSync(from, to);\n}\"",
     "dev": "tsup src/index.ts src/cli/index.ts --format esm --dts --watch",
-    "lint": "eslint \"{src,tests}/**/*.ts\"",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --coverage",
+    "test:release-gate": "node scripts/release-gate-test-groups.mjs",
+    "test:release-gate:g1": "node scripts/release-gate-test-groups.mjs --group 1",
+    "test:release-gate:g2": "node scripts/release-gate-test-groups.mjs --group 2",
+    "test:release-gate:g3": "node scripts/release-gate-test-groups.mjs --group 3",
+    "test:release-gate:g4": "node scripts/release-gate-test-groups.mjs --group 4",
+    "test:release-gate:g5": "node scripts/release-gate-test-groups.mjs --group 5",
     "extension:sync": "node scripts/sync-extension-version.mjs",
-    "extension:build": "npm run extension:sync && tsc -p extension/tsconfig.json",
+    "extension:build": "npm run extension:sync && tsc -p extension/tsconfig.json && node scripts/copy-extension-assets.mjs",
     "extension:pack": "cd extension && zip -r ../opendevbrowser-extension.zip manifest.json popup.html dist/ icons/",
+    "extension:store": "node scripts/chrome-store-publish.mjs",
     "version:check": "node scripts/verify-versions.mjs",
     "prepack": "npm run version:check && npm run build && npm run extension:build"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.0.203",
-    "@puppeteer/browsers": "^2.2.0",
+    "@opencode-ai/plugin": "^1.2.11",
+    "@puppeteer/browsers": "^2.13.0",
     "async-mutex": "^0.5.0",
     "jsonc-parser": "^3.2.0",
-    "playwright-core": "^1.49.1",
-    "ws": "^8.17.1",
-    "zod": "^3.23.8"
+    "playwright-core": "^1.58.2",
+    "ws": "^8.19.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@types/chrome": "^0.0.270",
-    "@types/node": "^20.19.27",
+    "@types/chrome": "^0.1.37",
+    "@types/node": "^20.19.35",
     "@types/ws": "^8.18.1",
-    "@typescript-eslint/eslint-plugin": "^8.9.0",
-    "@typescript-eslint/parser": "^8.9.0",
-    "@vitest/coverage-v8": "^4.0.16",
-    "eslint": "^9.12.0",
-    "happy-dom": "^20.0.11",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.3",
+    "happy-dom": "^20.7.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   }
 }

package/scripts/native/host.cjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const net = require("net");
+const crypto = require("crypto");
+const os = require("os");
+
+const IS_WINDOWS = process.platform === "win32";
+const DEFAULT_BASE_DIR = IS_WINDOWS ? os.tmpdir() : "/tmp";
+const BASE_DIR = process.env.OPD_NATIVE_BASE_DIR || DEFAULT_BASE_DIR;
+const MAX_MESSAGE_BYTES = 8 * 1024 * 1024;
+const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
+
+const buildPaths = (baseDir, pid) => {
+  const socketPath = IS_WINDOWS
+    ? `\\\\.\\pipe\\opendevbrowser-${pid}.sock`
+    : path.join(baseDir, `opendevbrowser-${pid}.sock`);
+  return {
+    tokenPath: path.join(baseDir, `opendevbrowser-${pid}.token`),
+    socketPath,
+    logPath: path.join(baseDir, "opendevbrowser-native.log")
+  };
+};
+
+const redactLogLine = (line, token) => {
+  let output = line;
+  if (token) {
+    output = output.split(token).join("[redacted]");
+  }
+  output = output.replace(/Authorization\\s*[:=]\\s*Bearer\\s+[^\\s"\']+/gi, "Authorization: Bearer [redacted]");
+  output = output.replace(/\"token\"\\s*:\\s*\"[^\"]+\"/gi, "\"token\":\"[redacted]\"");
+  return output;
+};
+
+const rotateLogIfNeeded = (logPath) => {
+  try {
+    const stat = fs.statSync(logPath);
+    if (stat.size <= LOG_ROTATE_BYTES) return false;
+    const rotated = `${logPath}.1`;
+    fs.renameSync(logPath, rotated);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const writeLog = (logPath, message, token) => {
+  rotateLogIfNeeded(logPath);
+  const line = redactLogLine(message, token);
+  fs.appendFileSync(logPath, `${line}\\n`, { encoding: "utf8" });
+};
+
+const writeTokenFile = (tokenPath) => {
+  const token = crypto.randomBytes(32).toString("hex");
+  fs.writeFileSync(tokenPath, token, { encoding: "utf8", mode: 0o600 });
+  return token;
+};
+
+const parseNativeMessages = (buffer) => {
+  const messages = [];
+  let offset = 0;
+  while (buffer.length >= offset + 4) {
+    const size = buffer.readUInt32LE(offset);
+    if (size > MAX_MESSAGE_BYTES) {
+      return { error: new Error("Message exceeds size limit"), remainder: Buffer.alloc(0) };
+    }
+    if (buffer.length < offset + 4 + size) {
+      break;
+    }
+    const slice = buffer.slice(offset + 4, offset + 4 + size);
+    offset += 4 + size;
+    try {
+      messages.push(JSON.parse(slice.toString("utf8")));
+    } catch {
+      // Ignore invalid JSON.
+    }
+  }
+  return { messages, remainder: buffer.slice(offset) };
+};
+
+const sendNativeMessage = (payload) => {
+  const json = JSON.stringify(payload);
+  const data = Buffer.from(json, "utf8");
+  if (data.length > MAX_MESSAGE_BYTES) {
+    return false;
+  }
+  const header = Buffer.alloc(4);
+  header.writeUInt32LE(data.length, 0);
+  process.stdout.write(Buffer.concat([header, data]));
+  return true;
+};
+
+const runHost = () => {
+  fs.mkdirSync(BASE_DIR, { recursive: true });
+  const { tokenPath, socketPath, logPath } = buildPaths(BASE_DIR, process.pid);
+  const token = writeTokenFile(tokenPath);
+
+  let socketClient = null;
+  let socketAuthorized = false;
+  let socketBuffer = "";
+
+  const cleanup = () => {
+    try {
+      if (socketClient) {
+        socketClient.destroy();
+      }
+    } catch {}
+    if (!IS_WINDOWS) {
+      try {
+        if (fs.existsSync(socketPath)) {
+          fs.unlinkSync(socketPath);
+        }
+      } catch {}
+    }
+    try {
+      if (fs.existsSync(tokenPath)) {
+        fs.unlinkSync(tokenPath);
+      }
+    } catch {}
+  };
+
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("exit", () => {
+    cleanup();
+  });
+
+  const server = net.createServer((socket) => {
+    if (socketClient) {
+      socketClient.destroy();
+    }
+    socketClient = socket;
+    socketAuthorized = false;
+    socketBuffer = "";
+    socket.setEncoding("utf8");
+    socket.on("data", (chunk) => {
+      socketBuffer += chunk;
+      const lines = socketBuffer.split("\\n");
+      socketBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        let message = null;
+        try {
+          message = JSON.parse(trimmed);
+        } catch {
+          socket.write(JSON.stringify({ type: "error", code: "invalid_json", message: "Invalid JSON" }) + "\\n");
+          continue;
+        }
+        if (!socketAuthorized) {
+          if (message?.type === "auth" && message?.token === token) {
+            socketAuthorized = true;
+            socket.write(JSON.stringify({ type: "auth_ok" }) + "\\n");
+            continue;
+          }
+          socket.write(JSON.stringify({ type: "error", code: "unauthorized", message: "Unauthorized" }) + "\\n");
+          socket.destroy();
+          return;
+        }
+        const encoded = Buffer.from(JSON.stringify(message), "utf8");
+        if (encoded.length > MAX_MESSAGE_BYTES) {
+          socket.write(JSON.stringify({ type: "error", code: "host_message_too_large", message: "Message too large" }) + "\\n");
+          continue;
+        }
+        sendNativeMessage(message);
+      }
+    });
+    socket.on("error", () => {});
+    socket.on("close", () => {
+      if (socketClient === socket) {
+        socketClient = null;
+        socketAuthorized = false;
+      }
+    });
+  });
+
+  server.listen(socketPath, () => {
+    if (!IS_WINDOWS) {
+      try {
+        fs.chmodSync(socketPath, 0o600);
+      } catch {}
+    }
+    writeLog(logPath, "Native host ready", token);
+  });
+
+  let nativeBuffer = Buffer.alloc(0);
+  process.stdin.on("data", (chunk) => {
+    nativeBuffer = Buffer.concat([nativeBuffer, chunk]);
+    const result = parseNativeMessages(nativeBuffer);
+    if (result.error) {
+      sendNativeMessage({ type: "error", code: "host_message_too_large", message: result.error.message });
+      nativeBuffer = Buffer.alloc(0);
+      return;
+    }
+    nativeBuffer = result.remainder;
+    for (const message of result.messages ?? []) {
+      if (message?.type === "ping" && typeof message.id === "string") {
+        sendNativeMessage({ type: "pong", id: message.id });
+        continue;
+      }
+      if (socketClient && socketAuthorized) {
+        const line = JSON.stringify(message);
+        socketClient.write(line + "\\n");
+      }
+    }
+  });
+};
+
+if (require.main === module) {
+  runHost();
+}
+
+module.exports = {
+  runHost,
+  __test__: {
+    buildPaths,
+    redactLogLine,
+    rotateLogIfNeeded,
+    writeTokenFile,
+    parseNativeMessages
+  }
+};

package/scripts/native/install.ps1

@@ -0,0 +1,73 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [string]$ExtensionId
+)
+
+if ([string]::IsNullOrWhiteSpace($ExtensionId)) {
+  Write-Error "Usage: install.ps1 <extension-id>"
+  exit 2
+}
+
+if ($ExtensionId -notmatch "^[a-p]{32}$") {
+  Write-Error "Invalid extension ID format. Expected 32 characters (a-p)."
+  exit 2
+}
+
+$localAppData = $env:LOCALAPPDATA
+if (-not $localAppData -and $env:USERPROFILE) {
+  $localAppData = Join-Path $env:USERPROFILE "AppData\\Local"
+}
+if (-not $localAppData) {
+  Write-Error "LOCALAPPDATA is not set. Unable to locate NativeMessagingHosts directory."
+  exit 3
+}
+
+$manifestDir = Join-Path $localAppData "Google\\Chrome\\User Data\\NativeMessagingHosts"
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$hostScript = Join-Path $scriptDir "host.cjs"
+
+if (-not (Test-Path $hostScript)) {
+  Write-Error "Native host script not found at $hostScript"
+  exit 4
+}
+
+$nodePath = (Get-Command node -ErrorAction SilentlyContinue).Source
+if (-not $nodePath) {
+  $candidates = @(
+    "C:\\Program Files\\nodejs\\node.exe",
+    "C:\\Program Files (x86)\\nodejs\\node.exe"
+  )
+  foreach ($candidate in $candidates) {
+    if (Test-Path $candidate) {
+      $nodePath = $candidate
+      break
+    }
+  }
+}
+if (-not $nodePath) {
+  Write-Error "Node.js not found in PATH."
+  exit 4
+}
+
+New-Item -ItemType Directory -Path $manifestDir -Force | Out-Null
+
+$wrapperPath = Join-Path $manifestDir "com.opendevbrowser.native.cmd"
+$wrapperContent = "@echo off`r`n""$nodePath"" ""$hostScript""`r`n"
+Set-Content -Path $wrapperPath -Value $wrapperContent -Encoding ASCII
+
+$manifestPath = Join-Path $manifestDir "com.opendevbrowser.native.json"
+$manifest = @{
+  name = "com.opendevbrowser.native"
+  description = "OpenDevBrowser native messaging host"
+  path = $wrapperPath
+  type = "stdio"
+  allowed_origins = @("chrome-extension://$ExtensionId/")
+} | ConvertTo-Json -Depth 3
+
+Set-Content -Path $manifestPath -Value $manifest -Encoding ASCII
+
+$regPath = "HKCU:\\Software\\Google\\Chrome\\NativeMessagingHosts\\com.opendevbrowser.native"
+New-Item -Path $regPath -Force | Out-Null
+New-ItemProperty -Path $regPath -Name "(Default)" -Value $manifestPath -PropertyType String -Force | Out-Null
+
+Write-Output "Native host installed at $manifestPath"

package/scripts/native/install.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+EXTENSION_ID="${1:-}"
+if [[ -z "${EXTENSION_ID}" ]]; then
+  echo "Usage: install.sh <extension-id>" >&2
+  exit 2
+fi
+
+if [[ ! "${EXTENSION_ID}" =~ ^[a-p]{32}$ ]]; then
+  echo "Invalid extension ID format. Expected 32 characters (a-p)." >&2
+  exit 2
+fi
+
+OS="$(uname -s)"
+if [[ "${OS}" == "Darwin" ]]; then
+  MANIFEST_DIR="${HOME}/Library/Application Support/Google/Chrome/NativeMessagingHosts"
+elif [[ "${OS}" == "Linux" ]]; then
+  MANIFEST_DIR="${HOME}/.config/google-chrome/NativeMessagingHosts"
+else
+  echo "Unsupported platform: ${OS}" >&2
+  exit 3
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOST_SCRIPT="${SCRIPT_DIR}/host.cjs"
+if [[ ! -f "${HOST_SCRIPT}" ]]; then
+  echo "Native host script not found at ${HOST_SCRIPT}" >&2
+  exit 4
+fi
+
+NODE_PATH="$(command -v node || true)"
+if [[ -z "${NODE_PATH}" && "${OS}" == "Darwin" ]]; then
+  if [[ -x "/opt/homebrew/bin/node" ]]; then
+    NODE_PATH="/opt/homebrew/bin/node"
+  elif [[ -x "/usr/local/bin/node" ]]; then
+    NODE_PATH="/usr/local/bin/node"
+  fi
+fi
+if [[ -z "${NODE_PATH}" ]]; then
+  echo "Node.js not found in PATH." >&2
+  exit 4
+fi
+
+mkdir -p "${MANIFEST_DIR}"
+
+WRAPPER_PATH="${MANIFEST_DIR}/com.opendevbrowser.native.sh"
+cat > "${WRAPPER_PATH}" <<EOF
+#!/usr/bin/env bash
+exec "${NODE_PATH}" "${HOST_SCRIPT}"
+EOF
+chmod 0755 "${WRAPPER_PATH}"
+
+MANIFEST_PATH="${MANIFEST_DIR}/com.opendevbrowser.native.json"
+cat > "${MANIFEST_PATH}" <<EOF
+{
+  "name": "com.opendevbrowser.native",
+  "description": "OpenDevBrowser native messaging host",
+  "path": "${WRAPPER_PATH}",
+  "type": "stdio",
+  "allowed_origins": ["chrome-extension://${EXTENSION_ID}/"]
+}
+EOF
+chmod 0644 "${MANIFEST_PATH}"
+
+echo "Native host installed at ${MANIFEST_PATH}"

package/scripts/native/uninstall.ps1

@@ -0,0 +1,25 @@
+$localAppData = $env:LOCALAPPDATA
+if (-not $localAppData -and $env:USERPROFILE) {
+  $localAppData = Join-Path $env:USERPROFILE "AppData\\Local"
+}
+if (-not $localAppData) {
+  Write-Error "LOCALAPPDATA is not set. Unable to locate NativeMessagingHosts directory."
+  exit 3
+}
+
+$manifestDir = Join-Path $localAppData "Google\\Chrome\\User Data\\NativeMessagingHosts"
+$manifestPath = Join-Path $manifestDir "com.opendevbrowser.native.json"
+$wrapperPath = Join-Path $manifestDir "com.opendevbrowser.native.cmd"
+
+Remove-Item -Path $manifestPath -Force -ErrorAction SilentlyContinue | Out-Null
+Remove-Item -Path $wrapperPath -Force -ErrorAction SilentlyContinue | Out-Null
+
+$regPath = "HKCU:\\Software\\Google\\Chrome\\NativeMessagingHosts\\com.opendevbrowser.native"
+Remove-Item -Path $regPath -Recurse -Force -ErrorAction SilentlyContinue | Out-Null
+
+$tempDir = [System.IO.Path]::GetTempPath()
+Get-ChildItem -Path $tempDir -Filter "opendevbrowser-*.token" -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
+Get-ChildItem -Path $tempDir -Filter "opendevbrowser-*.sock" -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
+Remove-Item -Path (Join-Path $tempDir "opendevbrowser-native.log") -Force -ErrorAction SilentlyContinue | Out-Null
+
+Write-Output "Native host uninstalled."

package/scripts/native/uninstall.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OS="$(uname -s)"
+if [[ "${OS}" == "Darwin" ]]; then
+  MANIFEST_DIR="${HOME}/Library/Application Support/Google/Chrome/NativeMessagingHosts"
+elif [[ "${OS}" == "Linux" ]]; then
+  MANIFEST_DIR="${HOME}/.config/google-chrome/NativeMessagingHosts"
+else
+  echo "Unsupported platform: ${OS}" >&2
+  exit 3
+fi
+
+MANIFEST_PATH="${MANIFEST_DIR}/com.opendevbrowser.native.json"
+WRAPPER_PATH="${MANIFEST_DIR}/com.opendevbrowser.native.sh"
+
+if [[ -f "${MANIFEST_PATH}" ]]; then
+  rm -f "${MANIFEST_PATH}"
+fi
+if [[ -f "${WRAPPER_PATH}" ]]; then
+  rm -f "${WRAPPER_PATH}"
+fi
+
+rm -f /tmp/opendevbrowser-*.sock /tmp/opendevbrowser-*.token 2>/dev/null || true
+
+echo "Native host uninstalled."

package/skills/AGENTS.md

@@ -1,36 +1,28 @@
-# Local AGENTS.md (skills/)
+# skills/ — Agent Guidelines
 
-Applies to `skills/` and subdirectories. Extends root `AGENTS.md`.
+Bundled canonical skill packs (8 total). Extends root `AGENTS.md`.
 
-## Skill Pack Architecture
-- Each skill pack lives in its own folder with `SKILL.md` as the entry point.
-- `opendevbrowser-best-practices` is the canonical prompting guide source.
-- OpenCode-native discovery is primary:
-  - Project-local: `.opencode/skill/*/SKILL.md`
-  - Global: `~/.config/opencode/skill/*/SKILL.md`
-- Compatibility-only paths: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`
-- `opendevbrowser_skill_list/load` are compatibility wrappers; OpenCode `skill` is primary.
+## Structure
 
-## Skill Pack Rules
-- `skills/opendevbrowser-best-practices/SKILL.md` is the source for prompting guide output.
-- Keep guidance short, script-first, and snapshot-first.
-- Keep examples aligned with `opendevbrowser_*` tool names.
-- Do not include secrets or captured page data in skill content.
-- If adding a consolidated skill pack, update `docs/REFACTORING_PLAN.md` and `docs/CLI.md`.
-
-## Skill Format Specification
+```
+skills/
+├── opendevbrowser-best-practices/SKILL.md
+├── opendevbrowser-continuity-ledger/SKILL.md
+├── opendevbrowser-login-automation/SKILL.md
+├── opendevbrowser-form-testing/SKILL.md
+├── opendevbrowser-data-extraction/SKILL.md
+├── opendevbrowser-research/SKILL.md
+├── opendevbrowser-shopping/SKILL.md
+└── opendevbrowser-product-presentation-asset/SKILL.md
+```
 
-### Naming Conventions (OpenCode alignment)
-- Skill names: lowercase, hyphens only, 1-64 characters
-- Directory name must match skill name in frontmatter
-- Examples: `login-automation`, `form-testing`, `data-extraction`
+## SKILL.md Format
 
-### SKILL.md Structure
 ```markdown
 ---
-name: skill-name
-description: Brief description (1-1024 chars)
-version: 1.0.0
+name: skill-name          # lowercase, hyphens, 1-64 chars
+description: Brief desc   # 1-1024 chars
+version: 1.0.0           # optional, defaults to 1.0.0
 ---
 
 # Skill Title
@@ -39,43 +31,32 @@ version: 1.0.0
 Content organized by topic for filtering.
 ```
 
-### Required Frontmatter
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Skill identifier (lowercase, hyphens) |
-| `description` | Yes | Brief description for listing |
-| `version` | No | Semantic version (defaults to 1.0.0) |
-
-## Available Skills
-
-| Skill | Purpose |
-|-------|---------|
-| `opendevbrowser-best-practices` | Core prompting guide for browser automation |
-| `opendevbrowser-continuity-ledger` | Continuity ledger guidance for long-running tasks |
-| `login-automation` | Authentication and credential handling |
-| `form-testing` | Form validation and submission testing |
-| `data-extraction` | Table extraction and pagination handling |
-
-## Custom Skill Paths
-Advanced: users can add custom search paths via `skillPaths` in `opendevbrowser.jsonc`:
-```jsonc
-{
-  "skillPaths": ["~/.config/opencode/opendevbrowser-skills"]
-}
-```
-
-## Folder Structure
-```
-skills/
-|-- opendevbrowser-best-practices/
-|   `-- SKILL.md
-|-- opendevbrowser-continuity-ledger/
-|   `-- SKILL.md
-|-- login-automation/
-|   `-- SKILL.md
-|-- form-testing/
-|   `-- SKILL.md
-|-- data-extraction/
-|   `-- SKILL.md
-`-- AGENTS.md
-```
+## Discovery Priority
+
+1. `.opencode/skill/` (project-local)
+2. `~/.config/opencode/skill/` (global)
+3. `.codex/skills/` (project compatibility)
+4. `$CODEX_HOME/skills` (global compatibility; fallback `~/.codex/skills`)
+5. `.claude/skills/` (ClaudeCode project compatibility)
+6. `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (ClaudeCode global compatibility; fallback `~/.claude/skills`)
+7. `.amp/skills/` (AmpCLI project compatibility)
+8. `$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` (AmpCLI global compatibility; fallback `~/.amp/skills`)
+9. `skillPaths` config (custom)
+
+## Constraints
+
+- Directory name must match `name` in frontmatter
+- Keep guidance short, script-first, snapshot-first
+- Examples must use `opendevbrowser_*` tool names
+- Never include secrets or page data in content
+- Keep canonical guidance in `opendevbrowser-*` packs; do not add legacy alias directories.
+- Match the snapshot → refs → actions flow in `docs/ARCHITECTURE.md` and tool list in `docs/CLI.md`.
+- Note that extension relay requires Chrome 125+ and uses hub-only relay ownership when enabled.
+- Refer to root `AGENTS.md` for connection flag/status semantics (extensionConnected, handshake, cdpConnected, pairingRequired).
+- Keep skill operational guidance aligned with release-gate scripts in `docs/CLI.md` (`provider-live-matrix --release-gate`, `live-regression-matrix --release-gate`).
+
+## Adding Skills
+
+1. Create `skills/<skill-name>/SKILL.md`
+2. Follow frontmatter format above
+3. Update `docs/CLI.md` if adding CLI-related guidance