opendevbrowser-best-practices

star 11

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.

freshtechbro By freshtechbro schedule Updated 6/7/2026
play_arrow Run Skill in Manus View GitHub

name: opendevbrowser-best-practices 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.6.0

OpenDevBrowser Best Practices

This is the primary battery pack for OpenDevBrowser operations.

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.

For frontend, design-system, screenshot-to-code, or /canvas composition tasks, load opendevbrowser-design-agent immediately after this pack so the work is design-contract-first instead of operations-only.

Pack Contents

  • 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//canvas//cdp surface map plus cross-agent skill-sync targets.
  • artifacts/canvas-governance-playbook.md - /canvas preflight, blocker, and feedback-evaluation guidance.
  • artifacts/skill-runtime-surface-matrix.md - canonical skill-pack and runtime-family inventory for real-task audits.
  • 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.
  • assets/templates/skill-runtime-pack-matrix.json - machine-readable canonical skill/runtime matrix for the audit runner.
  • assets/templates/canvas-handshake-example.json - canonical /canvas handshake example.
  • assets/templates/canvas-generation-plan.v1.json - required canvas.plan.set request skeleton.
  • assets/templates/canvas-feedback-eval.json - target-attributed feedback evaluation checklist.
  • assets/templates/canvas-blocker-checklist.json - machine-readable blocker and warning audit map.
  • 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.

Quick Start

  1. Validate the skill pack:
./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
  1. Pick a workflow:
./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh provider-crawl

  1. Execute the printed sequence with session-specific values.

  2. Surface full controls directly from CLI help when auditing runtime accessibility:

npx opendevbrowser --help
npx opendevbrowser help
  1. Run robustness coverage checks across workflow skills:
./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh
  1. Pair with the dedicated design pack for frontend work:
./skills/opendevbrowser-design-agent/scripts/validate-skill-assets.sh
./skills/opendevbrowser-design-agent/scripts/design-workflow.sh contract-first

Help-Led Surface Discovery

Start every surface audit with generated help so the capability map reflects the currently shipped runtime:

  • Browser replay: screencast-start, screencast-stop
  • Desktop observation: desktop-status, desktop-windows, desktop-active-window, desktop-capture-desktop, desktop-capture-window, desktop-accessibility-snapshot
  • Desktop-assisted browser review: review-desktop
  • Browser-scoped computer use: --challenge-automation-mode off|browser|browser_with_helper, status-capabilities, session-inspector-plan, session-inspector-audit, plus manager-owned review, session-inspector, and workflow fallback metadata

Boundary rules:

  • desktop observation is public and read-only
  • the optional helper remains browser-scoped and is not a desktop agent
  • generated help, docs/CLI.md, and docs/SURFACE_REFERENCE.md must stay aligned whenever this wording changes

Validated Capability Lanes

Load this section directly with:

opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"

Current validated lanes:

When --output-dir or --out is omitted, inspect .opendevbrowser/<workflow>/<runId> for workflow artifacts before publishing claims.

  1. Public-first YouTube transcript retrieval.
node scripts/youtube-transcript-live-probe.mjs --url "https://www.youtube.com/watch?v=aircAruvnKk" --youtube-mode auto --out artifacts/capability-fix/youtube-transcript-auto.json

Rules:

  • keep transcript runs public-first
  • browser-assisted transcript fallback is opt-in only
  • if browser fallback is enabled, use an isolated automation profile instead of a daily logged-in Google profile
  1. Evidence-gated research primitive with explicit public source families.
npx opendevbrowser research run --topic "Chrome extension debugging workflows" --days 30 --sources web,community --browser-mode managed --mode json --output-format json

Rules:

  • load opendevbrowser-research before research tasks so planning, evidence review, confidence, and limitations stay skill-guided
  • treat research run as provider-constrained and low-level; inspect summary.md, report.md, records.json, context.json, meta.json, and bundle-manifest.json before publishing claims
  • use --source-selection only to explain selector semantics; use explicit --sources web,community for public topical examples
  • add shopping only with --source-selection shopping or explicit --sources ...shopping... when the task is deliberately commercial
  • in the current contract, auto and all both resolve to web, community, and social, but neither value guarantees reliability
  1. Deterministic shopping reruns with explicit providers.
npx opendevbrowser shopping run --query "wireless ergonomic mouse" --providers shopping/bestbuy,shopping/ebay --budget 150 --browser-mode managed --use-cookies --challenge-automation-mode browser_with_helper --mode json --output-format json
npx opendevbrowser shopping run --query "27 inch 4k monitor" --providers shopping/bestbuy,shopping/ebay --budget 350 --sort lowest_price --browser-mode managed --use-cookies --challenge-automation-mode browser_with_helper --mode json --output-format json
npx opendevbrowser shopping run --query "wireless earbuds" --providers shopping/amazon --region us --browser-mode managed --use-cookies --challenge-automation-mode browser_with_helper --mode json --output-format json

Rules:

  • use explicit providers plus --browser-mode managed for the most reproducible reruns
  • treat --region as advisory unless meta.selection.region_authoritative=true
  • inspect meta.primaryConstraintSummary first on no-offer runs
  • if meta.primaryConstraint.guidance is present, follow meta.primaryConstraint.guidance.reason and meta.primaryConstraint.guidance.recommendedNextCommands[]
  • if guidance is absent, inspect meta.offerFilterDiagnostics before calling a no-offer run a provider outage
  1. Design-contract synthesis with repeated public references.
npx opendevbrowser inspiredesign run --brief "Design a premium docs workspace" --url "https://example.com/reference-a" --url "https://example.com/reference-b" --browser-mode managed --use-cookies --challenge-automation-mode browser_with_helper --include-prototype-guidance --mode json --output-format json
npx opendevbrowser inspiredesign harvest --brief "Design a premium docs workspace" --query "best docs product landing pages" --provider web/default --max-references 5 --visual-evidence required --browser-mode managed --mode path --output-format json
npx opendevbrowser inspiredesign harvest --brief "Premium digital photography studio landing page" --query "Pinterest premium digital photography studio landing page cinematic parallax portfolio" --provider social/pinterest --max-references 5 --visual-evidence required --browser-mode extension --use-cookies --cookie-policy required --challenge-automation-mode browser_with_helper --mode json --output-format json
npx opendevbrowser inspiredesign harvest --brief "Premium digital photography studio landing page" --provider social/pinterest --url "https://www.pinterest.com/pin/<pin-id>/" --max-references 1 --visual-evidence required --browser-mode extension --use-cookies --cookie-policy required --challenge-automation-mode browser_with_helper --mode json --output-format json --output-dir "artifacts/pinterest-harvest/<pin-id>"

Rules:

  • keep inspiredesign references public-first; explicit-url inspiredesign run --url ... uses deep capture for DOM/layout evidence, while Pinterest harvest/recovery commands keep captureMode=off for byte-backed pin-media extraction; --visual-evidence required controls screenshot evidence when the selected strategy explicitly calls for screenshots and does not enable deep capture for canonical pin-media harvest
  • use repeated --url flags instead of packed URL strings
  • provide --query or at least one --url for inspiredesign harvest; use --query when provider discovery is part of the task
  • use inspiredesign harvest when visual reference discovery, screenshot PNG artifacts, ranked references, metadata-only visual JSON, deterministic media-analysis.json, meta-prompt.md, or motion-design follow-through is required
  • treat social/pinterest as a browser-native site recipe, not a default full social provider; use extension mode, cookies, and --cookie-policy required for logged-in Pinterest search
  • for multi-pin Pinterest design harvests, treat search-to-canonical-pin capture as an agent pattern over inspiredesign harvest, not as a separate workflow: run query discovery with --query ... --provider social/pinterest, read meta.discovery.acceptedUrls from the JSON output or artifact metadata, keep only canonical https://www.pinterest.com/pin/<id>/ URLs, then run one canonical harvest command per selected pin
  • canonical Pinterest pin harvests and recovery paths in extension mode use captureMode=off and open the exact canonical pin in the extension before byte-backed pin-media extraction, which is required for reliable GIF and video pin capture in live sessions
  • trust multi-pin Pinterest harvest outputs only when nextStepGuidance.readiness=ready, ranked-references.json is non-empty, and pin-media-index.json, screenshot-index.json, or motion-evidence.json proves manifest-backed authority for the selected pin
  • treat media-analysis.json as a deterministic design-fact surface from trusted saved pin media, not as readiness authority; pin-media-index.json remains the only pin-media readiness and provenance authority
  • use media-analysis.json for palette, tone, layout, OCR-free typography structure, text-region layout, sampled motion facts, limitations, and non-goals; do not claim readable text extraction, exact copy, font families, OCR, model vision, Tesseract, OpenCV, Sharp, browser canvas analysis, new dependencies, or raw mediaAnalysis in canvas-plan.request.json
  • inspect nextStepGuidance.readiness, reasonCode, primaryAction, paramsExamples, validationChecks, and doNotProceedIf before continuing from any harvest
  • visual harvest must not bypass policy_blocked, unresolved auth_required, challenge_detected, or rate_limited; inspect diagnostics instead of forcing screenshots through blocked references
  • if readiness is needs_recovery, blocked, or diagnostic_only, follow the recovery-first command examples and do not continue to Canvas
  • after a ready run or harvest, read advanced-brief.md first, inspect ranked-references.json, media-analysis.json, visual-evidence.json, screenshot-index.json, motion-evidence.json, pin-media-evidence.json, pin-media-index.json, and meta-prompt.md when present, load opendevbrowser_skill_load opendevbrowser-best-practices "quick start", opendevbrowser_skill_load opendevbrowser-design-agent "canvas-contract", and opendevbrowser_skill_load opendevbrowser-motion-design "quick start", open a Canvas session, fill the ids in canvas-plan.request.json, run opendevbrowser canvas --command canvas.plan.set --params-file ./canvas-plan.request.json --output-format json, confirm planStatus=accepted, then patch only the governance blocks listed in design-agent-handoff.json. Treat Pinterest pin-media as design-ready only when pin-media-index.json proves persisted first-party bytes; remote media URLs and media-analysis.json alone are not proof
  • pair this lane with opendevbrowser-design-agent when the brief moves from contract synthesis into implementation or /canvas

Agent Sync Targets

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 fallback ~/.claude/skills, project ./.claude/skills)
  • ampcli ($AMP_CLI_HOME/skills fallback ~/.amp/skills, project ./.amp/skills)

Install and update refresh managed copies of these canonical packs; uninstall removes managed canonical packs and only prunes empty legacy research or shopping leftovers.

Required Operating Rules

  • 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.
  • Before daemon-backed workflows, run opendevbrowser status --daemon --output-format json and require data.fingerprintCurrent === true.
  • For extension readiness, require data.fingerprintCurrent === true, data.relay.extensionConnected === true, and data.relay.extensionHandshakeComplete === true.
  • Treat data.relay.opsConnected, data.relay.canvasConnected, and data.relay.cdpConnected as diagnostic or lane-specific presence fields; data.relay.cdpConnected is active-legacy-session-only.
  • Treat missing or false data.fingerprintCurrent as not current; use the matching binary, restart from the current install, or isolate shared runs with OPENCODE_CONFIG_DIR, OPENCODE_CACHE_DIR, and unique daemon or relay ports.
  • Do not conflate daemon_fingerprint_mismatch with native messaging host drift.
  • 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 direct-run 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.

Parallel Operations (Reliable As-Is)

  • 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 --output-format json and require data.fingerprintCurrent === true, data.relay.extensionConnected === true, and data.relay.extensionHandshakeComplete === true; do not require data.relay.opsConnected, data.relay.canvasConnected, or data.relay.cdpConnected unless that lane is actively in use.

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)

Known-Issue Robustness Baseline

  • Source matrix: artifacts/browser-agent-known-issues-matrix.md
  • Reusable checklist: assets/templates/robustness-checklist.json
  • Coverage validator: scripts/run-robustness-audit.sh

Use issue IDs from the matrix in each workflow skill (ISSUE-01 ... ISSUE-12) so robustness checks stay machine-verifiable and DRY.

Provider Workflows (Codified)

Provider Search Workflow

Goal: deterministic query + extraction from one provider.

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.

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.

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>"

Use browser replay when timing matters:

opendevbrowser_screencast_start sessionId="<session-id>" outputDir="./artifacts/qa-replay"
# run the suspect flow
opendevbrowser_screencast_stop sessionId="<session-id>" screencastId="<screencast-id>"

Read-Only Social Validation Workflow

Goal: validate authenticated read/search capability without posting.

  1. Connect and verify extension readiness with JSON status: data.fingerprintCurrent === true, data.relay.extensionConnected === true, and data.relay.extensionHandshakeComplete === true.
  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:

./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 inspiredesign
./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 release-direct-gates
./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
./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-preflight
./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh canvas-feedback-eval
./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh skill-runtime-audit
./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh validated-capabilities

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:

npm run test -- tests/parity-matrix.test.ts

Treat tests/parity-matrix.test.ts as contract coverage only. Live release proof comes from the direct-run harnesses below. This pack is the canonical owner of direct-run release evidence policy; other docs and skill packs should point here instead of restating the full policy.

Real-world provider+mode scenario harness (soak replacement):

npm run build
node scripts/provider-direct-runs.mjs --out artifacts/provider-direct-realworld.json
node scripts/live-regression-direct.mjs --out artifacts/live-regression-direct.json

Surface inventory source of truth:

  • docs/SURFACE_REFERENCE.md (77 CLI commands, 70 tools, 59 /ops commands, 35 /canvas commands, 67 CLI-tool pairs, /cdp envelope contracts; mirrored by npx opendevbrowser --help and npx opendevbrowser help). These hardcoded counts are validator-covered and must be refreshed from generated public-surface truth whenever counts change.
  • artifacts/command-channel-reference.md (skill-pack operational digest)
  • artifacts/skill-runtime-surface-matrix.md and assets/templates/skill-runtime-pack-matrix.json (canonical pack/runtime audit inventory)

Direct-run release note:

  • scripts/live-regression-direct.mjs is the preferred release harness for /canvas, annotate, and CLI smoke. It uses temporary managed profiles for managed probes, waits for /ops drain before the legacy /cdp step, and keeps manual annotation timeouts as explicit skipped boundaries in --release-gate mode.
  • scripts/provider-direct-runs.mjs --include-high-friction --include-auth-gated is the preferred provider release harness. Treat provider-live-matrix and live-regression-matrix as debug-only helpers, not refreshed release evidence.
  • Explicit artifacts/release/vX.Y.Z/... paths are local-only release proof outputs. Normal omitted workflow outputs persist under .opendevbrowser/<workflow>/<runId>.

Skill Runtime Audit and Realignment

This pack is the canonical owner of repo-local skill runtime audit policy and skill-pack runtime realignment.

Use these assets when the task is to inventory or validate the full OpenDevBrowser skill/runtime surface:

  • artifacts/skill-runtime-surface-matrix.md
  • assets/templates/skill-runtime-pack-matrix.json
  • scripts/skill-runtime-audit.mjs

Audit runtime rule:

  • scripts/skill-runtime-audit.mjs keeps smoke mode isolated and reproducible with temp harnesses, but full mode must reuse the current configured daemon and environment for provider-direct and live-regression so extension state, cookies, and auth-backed scenarios are exercised for real when available.

Realignment rule:

  • when a pack drifts behind current runtime behavior, update the skill to match the repo reality and strengthen the workflow guidance instead of making the pack merely stop failing validation.

Canvas Governance Handshake

Use the design-canvas surface when the workflow needs persisted design documents, explicit governance state, preview tabs, or overlay selection.

Recommended command order:

  1. opendevbrowser_canvas or opendevbrowser canvas --command canvas.session.open --output-format json to get canvasSessionId, leaseId, preflightState, planStatus, governance block states, generation-plan requirements, and guidance.recommendedNextCommands.
  2. Read the handshake before mutating. The handshake is the source of truth for:
    • planStatus
    • preflightState
    • governanceRequirements.requiredBeforeMutation
    • governanceRequirements.requiredBeforeSave
    • generationPlanRequirements.requiredBeforeMutation
    • generationPlanRequirements.allowedValues
    • generationPlanIssues
    • allowedLibraries
    • mutationPolicy.allowedBeforePlan
    • guidance.recommendedNextCommands
    • guidance.reason
    • guidance.nextStepGuidance, guidance.paramsExamples, guidance.fieldExamples, guidance.validationChecks, and guidance.doNotProceedIf when a repair envelope is present
    • treat allowedLibraries.components, allowedLibraries.icons, and allowedLibraries.styling as separate policy lanes: components are reusable UI adapters such as shadcn, icons are approved icon families, styling is for utility/theme adapters such as tailwindcss
  3. Require preflightState="handshake_read" or inspect the returned invalid-plan state before moving on. If the response already carries guidance.recommendedNextCommands, follow that list instead of guessing.
  4. Submit canvas.plan.set --output-format json with all required non-empty objects:
    • targetOutcome
    • visualDirection
    • layoutStrategy
    • contentStrategy
    • componentStrategy
    • motionPosture
    • responsivePosture
    • accessibilityPosture
    • validationTargets Minimum nested fields that commonly cause generation_plan_invalid if omitted:
    • visualDirection.themeStrategy
    • layoutStrategy.navigationModel
    • componentStrategy.interactionStates
    • motionPosture.reducedMotion
    • responsivePosture.requiredViewports
    • accessibilityPosture.keyboardNavigation
    • validationTargets.requiredThemes
    • validationTargets.browserValidation
    • validationTargets.maxInteractionLatencyMs
  5. Immediately inspect the canvas.plan.set response.
    • If planStatus="accepted" or preflightState="plan_accepted", follow the returned guidance.recommendedNextCommands.
    • If the command fails with generation_plan_invalid, inspect details.missingFields, details.issues, guidance.paramsExamples, guidance.fieldExamples, guidance.validationChecks, guidance.doNotProceedIf, and the handshake generationPlanIssues, then repair the params file before resubmitting.
    • Use canvas.plan.get or canvas.capabilities.get only as diagnostics when the repair examples are not enough.
  6. Only after the plan is accepted, call canvas.document.patch.
  7. After every successful canvas.document.patch, canvas.preview.render, canvas.preview.refresh, canvas.feedback.poll, canvas.document.save, or canvas.document.export, read guidance.recommendedNextCommands and guidance.reason before deciding the next command.
  8. Use canvas.preview.render, canvas.tab.open, canvas.overlay.mount, and canvas.overlay.select when a browser-backed live view is required.
  9. Use canvas.feedback.poll for snapshot audits between mutation rounds. When the plan is still missing or invalid, expect a synthetic preflight-blocker item instead of normal stage feedback. Use canvas.feedback.subscribe -> canvas.feedback.next -> canvas.feedback.unsubscribe when a live pull-stream is needed.
  10. Use canvas.document.save or canvas.document.export to persist artifacts.

Code-sync surface:

  • canvas.session.attach joins an existing canvas session as an observer or reclaims the write lease with attachMode=lease_reclaim.
  • canvas.code.bind, canvas.code.unbind, canvas.code.pull, canvas.code.push, canvas.code.status, and canvas.code.resolve manage TSX-first document bindings when a canvas file is round-tripped to repo code.

Current /canvas parity notes:

  • All 35 public canvas.* commands are agent-callable through opendevbrowser_canvas and opendevbrowser canvas --command ....
  • canvas.feedback.subscribe live streaming is public through the CLI only: use --output-format stream-json for the built-in polling bridge.
  • Tool-driven agents can achieve the same public streaming behavior by calling canvas.feedback.subscribe, then repeating canvas.feedback.next, and finally canvas.feedback.unsubscribe.
  • canvas.tab.sync and canvas.overlay.sync are internal extension runtime helpers, not public commands.
  • canvas_html is still the default preview/export contract. bound_app_runtime is opt-in and only valid when runtime preflight and app-side instrumentation succeed.
  • Component and icon libraries currently render semantically, not package-faithfully. Treat shadcn, tailwindcss, tabler, microsoft-fluent-ui-system-icons, 3dicons, and @lobehub/fluent-emoji-3d as metadata and constrained render lanes, not as general library import/export parity.
  • Annotation remains a separate surface today, but popup and canvas both ship per-item and combined Copy / Send actions. Send now delivers directly into the active agent chat when scope is safe and degrades to stored-only annotate --stored retrieval when scope is missing, ambiguous, or relay enqueue fails.

Tailwind usage rule:

  • When allowedLibraries.styling includes tailwindcss, use it for layout, spacing, responsive, and state styling over canonical tokens/theme variables.
  • Do not treat Tailwind as a component inventory source or invent generation-plan allowlists for it; keep styling policy in allowedLibraries / libraryPolicy.
  • Preview/export should materialize a deterministic utility-class layer and stay self-contained; do not depend on a remote Tailwind CDN for canvas preview correctness.

Failure handling:

  • plan_required: immediately call canvas.plan.set.
  • generation_plan_invalid: resubmit canvas.plan.set with every required non-empty generation-plan block present, using generationPlanIssues plus details.missingFields and details.issues as the repair checklist.
  • revision_conflict: reload with canvas.document.load and replay the patch batch against the latest revision.
  • unsupported_target or restricted_url: move the preview to a normal http(s) tab or fall back to managed mode.
  • If a freshly rebuilt unpacked extension still shows old /canvas or popup behavior, reload the extension in Chrome before trusting the live result; stale MV3 runtime state can preserve old service-worker logic after npm run extension:build.

Operational references:

  • artifacts/canvas-governance-playbook.md
  • assets/templates/canvas-handshake-example.json
  • assets/templates/canvas-generation-plan.v1.json
  • assets/templates/canvas-feedback-eval.json
  • assets/templates/canvas-blocker-checklist.json

Diagnostics and Traceability

Current diagnostics tools:

  • opendevbrowser_session_inspector (session-first summary with relay health, target state, trace proof, and next-action guidance)
  • 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

Install via CLI
npx skills add https://github.com/freshtechbro/opendevbrowser --skill opendevbrowser-best-practices
Repository Details
star Stars 11
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
freshtechbro
freshtechbro Explore all skills →