opendevbrowser 0.0.12 → 0.0.16

package/skills/opendevbrowser-best-practices/SKILL.md

@@ -1,81 +1,228 @@
 ---
 name: opendevbrowser-best-practices
-description: Use when the user asks to write browser scripts, automate navigation, use snapshot refs, or extract DOM elements. Provides script-first, snapshot/ref guidance.
-version: 0.1.0
+description: This skill should be used when the user asks to design or run OpenDevBrowser provider workflows, scraping pipelines, QA/debug automation, parity checks across modes, or resilient browser operations with codified scripts and artifacts.
+version: 2.3.0
 ---
 
 # OpenDevBrowser Best Practices
 
-Use this guide to generate fast, reliable, script-first workflows without bloating tools or output.
+This is the primary battery pack for OpenDevBrowser operations.
 
-## Core Workflow (Snapshot -> Refs -> Actions)
+Use this skill when you need:
+- provider-oriented workflows (`web`, `community`, `social`),
+- script-first runbooks,
+- parity across `managed`, `extension`, `cdpConnect`,
+- diagnostics for QA/debug (`console`, `network`, trace context),
+- safe write flows with explicit policy notice.
 
-Prefer the snapshot/ref loop as the primary interaction model:
+## Pack Contents
 
-1. Navigate or focus the target page.
-2. Capture a snapshot to obtain stable refs.
-3. Act on refs (click, type, select, scroll).
-4. Re-snapshot after navigation or large DOM changes.
+- `artifacts/provider-workflows.md` — canonical provider execution flows.
+- `artifacts/parity-gates.md` — mode/surface parity matrix and acceptance gates.
+- `artifacts/debug-trace-playbook.md` — diagnostics workflow and trace bundle model.
+- `artifacts/fingerprint-tiers.md` — hardening tiers and when to use each.
+- `artifacts/macro-workflows.md` — macro design and expansion standards.
+- `artifacts/browser-agent-known-issues-matrix.md` — known browser-agent failure modes mapped to required controls.
+- `artifacts/command-channel-reference.md` — CLI/tool/`/ops`/`/cdp` surface map plus cross-agent skill-sync targets.
+- `assets/templates/mode-flag-matrix.json` — mode + flag verification template.
+- `assets/templates/ops-request-envelope.json` — `/ops` request envelope template.
+- `assets/templates/cdp-forward-envelope.json` — `/cdp` relay envelope template.
+- `assets/templates/robustness-checklist.json` — shared issue-status checklist for workflow robustness audits.
+- `assets/templates/surface-audit-checklist.json` — docs/surface audit checklist template.
+- `scripts/odb-workflow.sh` — prints codified command sequences by workflow.
+- `scripts/run-robustness-audit.sh` — validates workflow skill coverage against known issue IDs.
+- `scripts/validate-skill-assets.sh` — validates required artifacts/templates.
 
-Use refs instead of raw selectors whenever possible.
+## Fast Start
 
-## Script-First Execution
+1. Validate the skill pack:
 
-Batch related actions in a single run to reduce round-trips:
+```bash
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+```
 
-- Use `opendevbrowser_run` for multi-step actions.
-- Keep steps small and deterministic.
-- End each run with a state check (snapshot or targeted extraction).
+2. Pick a workflow:
 
-Match the arguments used in the single-action tools.
+```bash
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-crawl
+```
 
-## Waiting and Stability
+3. Execute the printed sequence with session-specific values.
 
-Stabilize the page before acting:
+4. Surface full controls directly from CLI help when auditing runtime accessibility:
 
-- Use `opendevbrowser_wait` after navigation and before interacting with newly rendered UI.
-- Prefer `networkidle` or `load` when the UI is fully dynamic.
-- Wait for a ref state when targeting specific elements.
+```bash
+npx opendevbrowser --help
+```
 
-## Token-Efficient Extraction
+5. Run robustness coverage checks across workflow skills:
 
-Keep outputs small and scoped:
+```bash
+./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh
+```
 
-- Use `opendevbrowser_dom_get_text` or `opendevbrowser_dom_get_html` only on specific refs.
-- Avoid dumping full page HTML.
-- Use snapshot cursor paging when content is large.
+## Agent Sync Targets
 
-## Debug Signals (Lightweight)
+Skill-pack installation and discovery are synchronized for:
+- `opencode` (`~/.config/opencode/skill`, project `./.opencode/skill`)
+- `codex` (`$CODEX_HOME/skills` fallback `~/.codex/skills`, project `./.codex/skills`)
+- `claudecode` (`$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` fallback `~/.claude/skills`, project `./.claude/skills`)
+- `ampcli` (`$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` fallback `~/.amp/skills`, project `./.amp/skills`)
 
-Use polling tools only when needed:
+Legacy compatibility aliases `claude` and `amp` are preserved in installer target metadata.
 
-- Use `opendevbrowser_console_poll` to check for runtime errors.
-- Use `opendevbrowser_network_poll` to confirm API calls and statuses.
+## Required Operating Rules
 
-## Example Patterns
+- Prefer refs from `opendevbrowser_snapshot` over raw selectors.
+- Use one action per decision loop: snapshot -> action -> snapshot.
+- Keep a single correlation context (`requestId`, `sessionId`) across a run.
+- Run the same workflow shape across all three modes before claiming parity.
+- Default to read/research workflows. Social posting probes remain disabled unless explicitly requested via matrix opt-in (`--include-social-posts`).
+- Apply rate-limit/backoff discipline (`Retry-After` aware) whenever 429 pressure appears.
+- Re-check extension readiness on resume when a run crosses idle windows.
 
-### Login Flow (Batch)
+## Parallel Operations (Reliable As-Is)
 
-1. `goto` login URL.
-2. `wait` for page load.
-3. `snapshot` to get refs.
-4. `type` email/password refs.
-5. `click` submit ref.
-6. `wait` for navigation.
-7. `snapshot` to confirm state.
+- Safe parallelism today is `session-per-worker` (one session per page/tab command stream).
+- Keep each session single-writer for target/page actions; run commands serially inside that session.
+- Do not run independent concurrent streams that alternate `target-use` within one session.
+- Use default extension `/ops` for relay-backed concurrency; use `/cdp` only for legacy compatibility paths.
+- For managed parallel runs with persisted profiles, use unique profile paths per session (or disable persistence) to avoid profile lock collisions.
+- Treat extension headless attempts (`--extension-only --headless`) as expected `unsupported_mode`; route headless workloads through managed/cdpConnect instead.
+- Before extension-mode runs, preflight `npx opendevbrowser status --daemon` and require `extensionConnected=true` plus `extensionHandshakeComplete=true`.
 
-### Targeted Extraction
+Operational references:
+- `artifacts/provider-workflows.md` (see Workflow E)
+- `scripts/odb-workflow.sh parallel-multipage-safe`
+- `docs/CLI.md` (concurrency semantics)
+- `docs/SURFACE_REFERENCE.md` (transport and policy constraints)
+- `docs/TROUBLESHOOTING.md` (parallel crosstalk and profile-lock remediation)
 
-1. `snapshot` to get ref for the desired element.
-2. `dom_get_text` on that ref.
+## Known-Issue Robustness Baseline
 
-## Mode Guidance
+- Source matrix: `artifacts/browser-agent-known-issues-matrix.md`
+- Reusable checklist: `assets/templates/robustness-checklist.json`
+- Coverage validator: `scripts/run-robustness-audit.sh`
 
-- Use Mode A (managed) by default for zero-config operation.
-- Use Mode C (extension) only when existing logged-in tabs are required.
+Use issue IDs from the matrix in each workflow skill (`ISSUE-01` ... `ISSUE-12`) so robustness checks stay machine-verifiable and DRY.
 
-## Safe Defaults
+## Provider Workflows (Codified)
 
-- Keep CDP local-only by default.
-- Redact secrets in snapshot output.
-- Avoid raw CDP unless explicitly enabled.
+### Provider Search Workflow
+
+Goal: deterministic query + extraction from one provider.
+
+```text
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<provider-search-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+# extract targeted results using refs
+opendevbrowser_network_poll sessionId="<session-id>" max=50
+```
+
+### Provider Crawl Workflow
+
+Goal: multipage fetch + extraction with bounded depth.
+
+```text
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<seed-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+# capture links/data, enqueue next pages in host logic
+opendevbrowser_scroll sessionId="<session-id>" dy=1000
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+```
+
+### QA Debug Workflow
+
+Goal: isolate frontend regressions quickly.
+
+```text
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+opendevbrowser_console_poll sessionId="<session-id>" max=100
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+opendevbrowser_screenshot sessionId="<session-id>"
+```
+
+### Read-Only Social Validation Workflow
+
+Goal: validate authenticated read/search capability without posting.
+
+1. Connect and verify extension readiness (`extensionConnected` + handshake).
+2. Navigate/search target social surface.
+3. Capture `debug-trace-snapshot` and `network-poll` evidence.
+4. Record blocker/auth status only (no write action).
+
+## Workflow Router Script
+
+Use the router script to avoid retyping flows:
+
+```bash
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-search
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-crawl
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh qa-debug
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh social-readonly-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh parity-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh surface-audit
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh ops-channel-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh cdp-channel-check
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh mode-flag-matrix
+./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh robustness-audit
+```
+
+## Modes and Surface Parity
+
+Always run acceptance on:
+- Modes: `managed`, `extension`, `cdpConnect`
+- Surfaces: tool API, CLI, daemon RPC
+
+Reference: `artifacts/parity-gates.md`
+
+Parity gate test:
+
+```bash
+npm run test -- tests/parity-matrix.test.ts
+```
+
+Real-world provider+mode scenario harness (soak replacement):
+
+```bash
+npm run build
+node scripts/provider-live-matrix.mjs --use-global-env --skip-live-regression --out artifacts/provider-live-realworld.json
+```
+
+Surface inventory source of truth:
+- `docs/SURFACE_REFERENCE.md` (55 CLI commands, 48 tools, 38 `/ops` commands, `/cdp` envelope contracts)
+- `artifacts/command-channel-reference.md` (skill-pack operational digest)
+
+## Diagnostics and Traceability
+
+Current diagnostics tools:
+- `opendevbrowser_console_poll`
+- `opendevbrowser_network_poll`
+- `opendevbrowser_debug_trace_snapshot` (combined page + console + network + exception channels)
+
+Reference: `artifacts/debug-trace-playbook.md`
+
+## Fingerprint Hardening
+
+Apply the minimum tier that meets reliability goals.
+
+- Tier 0: baseline deterministic automation.
+- Tier 1: coherence profile (default recommended).
+- Tier 2: runtime hardening.
+- Tier 3: adaptive managed hardening (optional).
+
+Reference: `artifacts/fingerprint-tiers.md`
+
+## Macro Guidance
+
+Use macros as normalized entrypoints for provider workflows.
+
+- Keep macro definitions declarative and typed.
+- Expand macros to canonical provider queries.
+- Emit provenance metadata (`macro`, `resolvedQuery`, `provider`).
+
+Reference: `artifacts/macro-workflows.md`

package/skills/opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md

@@ -0,0 +1,44 @@
+# Browser Agent Known-Issues Matrix
+
+This matrix defines the minimum robustness controls for OpenDevBrowser workflow skills.
+
+## Issue Controls
+
+| ID | Known issue | Typical signals | Required controls | Evidence to capture |
+|---|---|---|---|---|
+| `ISSUE-01` | DOM churn invalidates refs | action fails after render, detached/stale element behavior, missing ref | enforce `snapshot -> one action -> snapshot`, retry once after fresh snapshot, avoid reusing refs across navigation | before/after snapshots + failing action + retry outcome |
+| `ISSUE-02` | Frame/iframe boundaries hide interactive targets | expected refs not found in top document, challenge widget rendered in iframe | detect frame context before action, route frame-specific steps, checkpoint when cross-origin challenge frame blocks continuation | snapshot outline showing frame branch + checkpoint note |
+| `ISSUE-03` | Popup/new-tab auth flows break linear scripts | click triggers new tab/popup, current tab loses focus | detect target/page changes, rebind to active auth target, verify post-auth return target | target/page list before and after auth click |
+| `ISSUE-04` | Step-up auth and session expiry alter login path | MFA/passkey prompt appears, unexpected redirect to reauth | branch login state machine explicitly, validate >=2 independent auth success signals, validate reauth policy separately | auth signal log with URL, element, network confirmation |
+| `ISSUE-05` | Anti-bot challenge loops stall automation | repeated challenge pages/widgets, repeated 403/429 around auth/submit | treat as checkpoint, never bypass, set loop budget, escalate after repeated challenge loops | challenge checkpoint log with timestamps and outcome |
+| `ISSUE-06` | Rate-limit pressure and server backoff ignored | 429 responses, throttle banners, `Retry-After` headers | stop aggressive retries, honor `Retry-After`, bounded retry budget with cooldown windows | network poll evidence with status + backoff decision |
+| `ISSUE-07` | MV3 extension service worker suspends state | extension relay disconnects after idle, handshake drop | re-check extension readiness before critical steps, include reconnect path and resumed snapshot checkpoint | daemon status (`extensionConnected`, `extensionHandshakeComplete`) before resume |
+| `ISSUE-08` | Restricted origins and policy blocks | `chrome://` / extension pages blocked, unsupported origin errors | validate URL/domain eligibility before workflow, fail fast with actionable reason | blocked-origin decision in run log |
+| `ISSUE-09` | Pagination drift and duplicate extraction | duplicate records across pages, endless loop/no page delta | canonical dedupe keys, terminal conditions, positive delta gate, checkpoint/resume metadata | pagination state + quality-gate report |
+| `ISSUE-10` | Locale/currency parsing inconsistency | mixed currency symbols, malformed numbers | normalize currency/amount explicitly, avoid cross-currency comparison without conversion context | normalized records with currency and parse confidence |
+| `ISSUE-11` | Discount anchor is weak or misleading | anchor price missing/untrusted, “sale” not below market | separate anchor discount from market discount, tag anchor confidence, require market-baseline confirmation | market analysis with anchor coverage and warnings |
+| `ISSUE-12` | Stale price or unsupported claims in presentation assets | captured price outdated, marketing claims not traceable | enforce freshness checks, claim-to-evidence mapping, block unsupported superlatives | claims-evidence map + pricing timestamp |
+
+## Skill Coverage Targets
+
+- `opendevbrowser-login-automation`: `ISSUE-01`, `ISSUE-02`, `ISSUE-03`, `ISSUE-04`, `ISSUE-05`, `ISSUE-06`, `ISSUE-07`
+- `opendevbrowser-form-testing`: `ISSUE-01`, `ISSUE-02`, `ISSUE-05`, `ISSUE-06`, `ISSUE-08`
+- `opendevbrowser-data-extraction`: `ISSUE-01`, `ISSUE-06`, `ISSUE-08`, `ISSUE-09`, `ISSUE-10`
+- `opendevbrowser-shopping`: `ISSUE-06`, `ISSUE-09`, `ISSUE-10`, `ISSUE-11`, `ISSUE-12`
+- `opendevbrowser-product-presentation-asset`: `ISSUE-10`, `ISSUE-11`, `ISSUE-12`
+- `opendevbrowser-research`: `ISSUE-06`, `ISSUE-09`, `ISSUE-10`, `ISSUE-12`
+
+## Source Notes
+
+- Playwright best practices (locator and timing stability): https://playwright.dev/docs/best-practices
+- Playwright frames guidance: https://playwright.dev/docs/frames
+- Playwright pages/popups guidance: https://playwright.dev/docs/pages
+- Chrome extension MV3 service worker lifecycle: https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle
+- HTTP 429 semantics and `Retry-After`: https://www.rfc-editor.org/rfc/rfc6585
+- OWASP Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+- WCAG 2.2 (accessible authentication): https://www.w3.org/TR/WCAG22/
+- Cloudflare Turnstile testing keys: https://developers.cloudflare.com/turnstile/tutorials/testing/
+- reCAPTCHA testing keys: https://developers.google.com/recaptcha/docs/faq
+- hCaptcha docs: https://docs.hcaptcha.com/
+- RFC 9309 robots protocol: https://www.rfc-editor.org/rfc/rfc9309
+- FTC deceptive pricing guide: https://www.ecfr.gov/current/title-16/chapter-I/subchapter-B/part-233

package/skills/opendevbrowser-best-practices/artifacts/command-channel-reference.md

@@ -0,0 +1,95 @@
+# Command and Channel Reference
+
+## Purpose
+
+Provide a compact, operationally useful map of OpenDevBrowser command surfaces and relay channels for parity checks.
+
+## Current coverage snapshot
+
+- CLI commands: `55`
+- Plugin tools: `48`
+- `/ops` command names: `38`
+- Legacy `/cdp` relay: generic CDP forwarding (method-level)
+
+Canonical exhaustive reference: `docs/SURFACE_REFERENCE.md`.
+CLI help mirror: `npx opendevbrowser --help` (surfaces CLI + tools + `/ops` + `/cdp` controls).
+
+## Agent skill-sync coverage
+
+Skill-pack installation/discovery is synchronized for:
+- `opencode`: `~/.config/opencode/skill` and `./.opencode/skill`
+- `codex`: `$CODEX_HOME/skills` (fallback `~/.codex/skills`) and `./.codex/skills`
+- `claudecode`: `$CLAUDECODE_HOME/skills` or `$CLAUDE_HOME/skills` (fallback `~/.claude/skills`) and `./.claude/skills`
+- `ampcli`: `$AMPCLI_HOME/skills` or `$AMP_CLI_HOME/skills` or `$AMP_HOME/skills` (fallback `~/.amp/skills`) and `./.amp/skills`
+
+Legacy aliases `claude` and `amp` remain present in installer target metadata for compatibility.
+
+## CLI surface categories
+
+- Install/runtime: install, update, uninstall, help, version, serve, daemon, native, run
+- Session/connection: launch, connect, disconnect, status, cookie-import, cookie-list
+- Navigation: goto, wait, snapshot
+- Interaction: click, hover, press, check, uncheck, type, select, scroll, scroll-into-view
+- Targets/pages: targets-list, target-use, target-new, target-close, page, pages, page-close
+- DOM: dom-html, dom-text, dom-attr, dom-value, dom-visible, dom-enabled, dom-checked
+- Export/diagnostics/macro/annotation/power: clone-page, clone-component, perf, screenshot, console-poll, network-poll, debug-trace-snapshot, macro-resolve, annotate, rpc
+
+## Tool surface categories
+
+- Runtime parity tools map to the CLI runtime categories.
+- Tool-only: `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, `opendevbrowser_skill_load`.
+- CLI-only: `rpc`.
+
+## Relay channels
+
+### `/ops` (default)
+
+Namespace groups:
+- `session.*`
+- `storage.*`
+- `targets.*`
+- `page.*`
+- `nav.*`
+- `interact.*`
+- `dom.*`
+- `export.*`
+- `devtools.*`
+
+Handshake/liveness envelope types:
+- `ops_hello`, `ops_hello_ack`
+- `ops_ping`, `ops_pong`
+- `ops_request`, `ops_response`, `ops_error`
+- `ops_event`, `ops_chunk`
+
+Concurrency policy:
+- `/ops` supports multiple clients and multiple sessions.
+- Reliable parallel execution is session-scoped (`session-per-worker`).
+- Avoid concurrent independent streams that switch targets inside one session (`targets.use` races can cross-wire active target state).
+
+### `/cdp` (legacy)
+
+- Opt-in via `--extension-legacy`.
+- Forwards raw CDP commands through relay command envelopes (`id`, `method`, `params`, optional `sessionId`).
+- Use for compatibility-specific paths only.
+- Treat as a legacy/single-writer path; do not use as the primary route for concurrent automation.
+
+## Mode and flag checkpoints
+
+- Managed: `launch --no-extension`
+- Extension default: `launch` or relay-normalized `connect`
+- Extension legacy: `launch --extension-legacy` or `connect --extension-legacy`
+- Direct CDP: `connect --ws-endpoint ...` or `connect --host ... --cdp-port ...`
+
+Required readiness/status checks:
+- `extensionConnected`
+- `extensionHandshakeComplete`
+- `opsConnected`
+- `cdpConnected`
+- `pairingRequired`
+
+## Fast verification commands
+
+```bash
+npm run test -- tests/parity-matrix.test.ts
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+```

package/skills/opendevbrowser-best-practices/artifacts/debug-trace-playbook.md

@@ -0,0 +1,36 @@
+# Debug Trace Playbook
+
+## Purpose
+
+Run a repeatable debug pass and capture enough evidence to diagnose regressions quickly.
+
+## Minimum Trace Bundle
+
+- `requestId` and `sessionId`
+- snapshot output before and after key actions
+- console stream (`opendevbrowser_console_poll`)
+- network stream (`opendevbrowser_network_poll`)
+- screenshot evidence (`opendevbrowser_screenshot`)
+
+## Workflow
+
+1. Launch/connect and record `sessionId`.
+2. Reproduce issue with the smallest action sequence.
+3. Capture snapshot + console + network + screenshot at failure point.
+4. Normalize findings by `requestId` and timestamp.
+5. Re-run once in another mode (`managed` vs `extension` vs `cdpConnect`) to detect mode-specific drift.
+
+## Command Skeleton
+
+```text
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+opendevbrowser_console_poll sessionId="<session-id>" max=100
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+opendevbrowser_screenshot sessionId="<session-id>"
+```
+
+## Triage Rules
+
+- If refs fail: re-snapshot and retry one time.
+- If repeated 403/429: pause and apply cooldown/retry policy.
+- If failure reproduces in only one mode: mark as parity defect and gate release.

package/skills/opendevbrowser-best-practices/artifacts/fingerprint-tiers.md

@@ -0,0 +1,36 @@
+# Fingerprint Tiers
+
+## Purpose
+
+Choose the lowest hardening tier that keeps runs reliable; avoid unnecessary complexity.
+
+## Tiers
+
+### Tier 0 — Baseline
+
+- Default runtime behavior.
+- Use for internal pages and low-friction targets.
+
+### Tier 1 — Coherence Profile (default recommendation)
+
+- Consistent profile/session reuse.
+- Stable launch flags and deterministic workflow ordering.
+- Best default for most production automation.
+
+### Tier 2 — Runtime Hardening
+
+- Add stricter runtime controls (timeouts, retries, pacing discipline).
+- Use when targets show intermittent anti-bot or high flakiness.
+
+### Tier 3 — Adaptive Hardening (optional track)
+
+- Dynamic policy adjustments and canary validation loops.
+- Use only when Tier 1/2 cannot achieve target reliability.
+- Treat as opt-in track, not baseline release requirement.
+
+## Selection Heuristic
+
+1. Start Tier 0 for local validation.
+2. Promote to Tier 1 for shared/CI workflows.
+3. Use Tier 2 when failures are environment-dependent.
+4. Use Tier 3 only for sustained high-friction environments.

package/skills/opendevbrowser-best-practices/artifacts/macro-workflows.md

@@ -0,0 +1,43 @@
+# Macro Workflows
+
+## Purpose
+
+Define concise macro entrypoints that expand into repeatable provider workflows.
+
+## Macro Contract
+
+Each macro should declare:
+
+- `macro`: stable name
+- `provider`: `web|community|social`
+- `mode`: `managed|extension|cdpConnect`
+- `policyMode`: `read|write`
+- `requestId`: required correlation id
+
+## Recommended Macros
+
+### `provider.search`
+
+- Expands to launch/connect + goto + wait + snapshot + extract + network poll.
+- Output: normalized result set with provenance fields.
+
+### `provider.crawl`
+
+- Expands to bounded multipage loop (queue + dedupe + depth/page limits).
+- Output: `records[]`, `visited[]`, and crawl stats.
+
+### `qa.debug`
+
+- Expands to snapshot + console poll + network poll + screenshot.
+- Output: trace bundle for triage.
+
+### `safe.post`
+
+- Expands to notice + preview + explicit confirmation + single write action.
+- Output: write result and audit metadata.
+
+## Expansion Rules
+
+- Keep expansions deterministic and minimal.
+- Emit provenance metadata (`macro`, `resolvedQuery`, `provider`, `mode`).
+- Never hide write actions behind implicit macro behavior.

package/skills/opendevbrowser-best-practices/artifacts/parity-gates.md

@@ -0,0 +1,36 @@
+# Parity Gates
+
+## Purpose
+
+Define hard pass/fail gates so CLI, tool, and runtime surfaces stay aligned.
+
+## Parity Matrix
+
+| Area | Modes | Surfaces | Gate |
+|---|---|---|---|
+| Session lifecycle | managed, extension, cdpConnect | CLI + tools + runtime | `launch/connect/disconnect/status` parity |
+| Navigation + refs loop | managed, extension, cdpConnect | CLI + tools + runtime | `goto/wait/snapshot` parity |
+| Interaction | managed, extension, cdpConnect | CLI + tools + runtime | click/type/select/scroll/press/check/uncheck parity |
+| Targets + pages | managed, extension, cdpConnect | CLI + tools + runtime | target/page command parity |
+| DOM + diagnostics + export | managed, extension, cdpConnect | CLI + tools + runtime | dom/perf/screenshot/console/network/clone parity |
+| Relay channels | extension (default) + extension-legacy | `/ops` + `/cdp` | `/ops` namespace coverage + `/cdp` envelope compatibility |
+
+## Surface Rules
+
+- `rpc` is intentionally CLI-only (internal and unsafe).
+- `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, and `opendevbrowser_skill_load` are intentionally tool-only.
+- Any new stable CLI runtime command must add a matching tool unless explicitly documented as CLI-only.
+- Surface counts and command inventories are verified against `docs/SURFACE_REFERENCE.md`.
+
+## Gate Commands
+
+```bash
+npm run test -- tests/parity-matrix.test.ts
+npm run test -- tests/tools.test.ts tests/daemon-command.test.ts
+npm run test -- tests/providers-performance-gate.test.ts
+```
+
+## Release Requirement
+
+Ship only when parity tests pass and docs (`README.md`, `docs/CLI.md`, `docs/ARCHITECTURE.md`, `docs/SURFACE_REFERENCE.md`) reflect the same surface map.
+Use `docs/RELEASE_PARITY_CHECKLIST.md` as the release gate source of truth.

package/skills/opendevbrowser-best-practices/artifacts/provider-workflows.md

@@ -0,0 +1,89 @@
+# Provider Workflows
+
+## Purpose
+
+Codify minimal, repeatable workflows for provider-native automation.
+
+## Inputs
+
+- `sessionMode`: `managed|extension|cdpConnect`
+- `provider`: `web|community|social`
+- `requestId`: unique per workflow run
+- `policyMode`: `read` (default) or `write` (explicit/manual opt-in only)
+
+## Workflow A: Provider Search
+
+1. Launch/connect mode.
+2. Navigate to provider query URL.
+3. Wait for load (`networkidle` preferred).
+4. Snapshot actionables.
+5. Extract result units with refs.
+6. Poll network for request health.
+7. Emit normalized records.
+
+Expected output:
+- `items[]` with `title/url/snippet/source/ts/requestId`
+
+## Workflow B: Provider Fetch
+
+1. Launch/connect mode.
+2. Goto target URL/entity endpoint.
+3. Wait and snapshot.
+4. Extract typed fields.
+5. Poll console/network for anomalies.
+
+Expected output:
+- one normalized entity record + diagnostics metadata
+
+## Workflow C: Multipage Crawl
+
+1. Seed queue with initial URL list.
+2. Process one URL at a time:
+- goto
+- wait
+- snapshot
+- extract
+- collect outgoing links
+3. Canonicalize/dedupe links.
+4. Enqueue until `maxDepth|maxPages` reached.
+5. Persist records with page provenance.
+
+Expected output:
+- `records[]`
+- `visited[]`
+- `frontierStats`
+
+## Workflow D: Social Read-Only Validation (Default)
+
+1. Display read-only policy notice.
+2. Navigate to social target and execute search/read probes only.
+3. Capture `debug-trace-snapshot` + `network-poll`.
+4. Record auth/blocker diagnostics and provider health.
+
+Expected output:
+- `readResult` + `authBlockerDiagnostics`
+
+## Workflow E: Parallel Multipage (Reliable As-Is)
+
+1. Build a bounded frontier/queue in host logic.
+2. Allocate one session per worker (`session-1`, `session-2`, ...).
+3. In each worker session, process URLs serially:
+- goto
+- wait
+- snapshot
+- extract
+- emit records with `sessionId` + page provenance
+4. Never interleave competing `target-use` streams inside a single session.
+5. For managed persistent profiles, assign a unique profile path per worker session.
+6. Merge worker outputs deterministically (stable sort + dedupe key).
+
+Expected output:
+- `records[]` merged across workers
+- `workerStats[]` with `{ sessionId, processed, failures }`
+- `frontierStats` and checkpoint state
+
+## Failure Policy
+
+- stale refs: re-snapshot and retry once
+- repeated 403/429: stop and cooldown
+- inconsistent mode behavior: flag parity failure