opendevbrowser 0.0.12 → 0.0.15

package/skills/login-automation/SKILL.md

@@ -1,98 +1,108 @@
 ---
 name: login-automation
-description: Best practices for automating login flows and authentication testing with OpenDevBrowser.
-version: 1.0.0
+description: This skill should be used when the user asks to "automate login", "test authentication", "sign in programmatically", "validate login errors", or "verify session persistence" with OpenDevBrowser.
+version: 1.1.0
 ---
 
 # Login Automation Skill
 
-## Credential Handling
+Use this guide for deterministic login flows and authentication checks.
 
-Store credentials securely using environment variables or config files outside the repository.
+## Secure Credential Handling
 
-Never hardcode credentials in test scripts or skill files.
+Handle credentials outside skill files and source code:
 
-Use `opendevbrowser_type` with `sensitive: true` (if available) for password fields.
+- Resolve credentials from environment variables or a secret manager in the orchestration layer.
+- Pass resolved values at runtime only.
+- Avoid logging secrets in transcripts, fixtures, or screenshots.
 
-## Form Detection Workflow
+## Preflight Checklist
 
-1. Take a snapshot to identify login form elements:
-   ```
-   opendevbrowser_snapshot
-   ```
+Before typing credentials:
 
-2. Look for common patterns:
-   - Input fields with `type="email"`, `type="text"`, `name="username"`
-   - Input fields with `type="password"`
-   - Submit buttons with text containing "Sign in", "Log in", "Submit"
+1. Launch or connect to the intended session mode.
+2. Navigate to the login URL.
+3. Wait for page readiness.
+4. Capture a fresh snapshot and identify refs.
 
-3. Use refs to target form elements reliably.
+```text
+opendevbrowser_goto sessionId="<session-id>" url="https://example.com/login"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+```
 
-## Authentication Flow
+## Canonical Login Flow
 
-1. Navigate to login page:
-   ```
-   opendevbrowser_goto url="https://example.com/login"
-   ```
+Execute login in a strict order:
 
-2. Wait for form to load:
-   ```
-   opendevbrowser_wait state="networkidle"
-   ```
+1. Type identifier into email/username ref.
+2. Type password into password ref.
+3. Click submit.
+4. Wait for navigation or authenticated UI state.
+5. Re-snapshot for post-login verification.
 
-3. Take snapshot to get refs:
-   ```
-   opendevbrowser_snapshot
-   ```
+```text
+opendevbrowser_type sessionId="<session-id>" ref="<identifier-ref>" text="<resolved-identifier>"
+opendevbrowser_type sessionId="<session-id>" ref="<password-ref>" text="<resolved-password>"
+opendevbrowser_click sessionId="<session-id>" ref="<submit-ref>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+```
 
-4. Enter username/email:
-   ```
-   opendevbrowser_type ref="[email-input-ref]" text="user@example.com"
-   ```
+## Success Validation
 
-5. Enter password:
-   ```
-   opendevbrowser_type ref="[password-input-ref]" text="password123"
-   ```
+Validate more than one signal:
 
-6. Click submit:
-   ```
-   opendevbrowser_click ref="[submit-button-ref]"
-   ```
+- URL or route changed to expected authenticated location.
+- Authenticated-only UI ref becomes visible.
+- Login request in `opendevbrowser_network_poll` returns expected status.
 
-7. Wait for navigation:
-   ```
-   opendevbrowser_wait state="networkidle"
-   ```
+```text
+opendevbrowser_network_poll sessionId="<session-id>" max=50
+```
 
-## Error Handling
+Use `opendevbrowser_is_visible` or `opendevbrowser_get_attr` for deterministic assertions.
 
-After login attempt, verify success:
+## Error and Recovery Handling
 
-1. Check URL changed to expected destination
-2. Look for error messages in snapshot
-3. Verify session cookies are set via network poll
+Handle common blockers explicitly:
 
-Common failure patterns:
-- "Invalid credentials" messages
-- CAPTCHA challenges
-- Multi-factor authentication prompts
-- Rate limiting or lockout
+- Invalid credentials: assert error banner text near form.
+- CAPTCHA/challenge: classify as manual checkpoint.
+- MFA prompt: continue with second-factor workflow if test account supports it.
+- Lockout/rate limit: stop retries and rotate test account or cooldown window.
 
-## MFA Handling
+After any failure, re-snapshot before retrying to avoid stale refs.
 
-For TOTP-based MFA:
-1. Generate code using appropriate library
-2. Wait for MFA input field to appear
-3. Enter the code
-4. Submit
+## MFA Flow Pattern
 
-For SMS/Email MFA:
-- Requires manual intervention or test account bypass
+For MFA-capable test flows:
 
-## Session Persistence
+1. Submit primary credentials.
+2. Wait for MFA input ref.
+3. Enter OTP/ref-based code.
+4. Submit and validate authenticated state.
 
-Use persistent browser profiles to maintain sessions across runs:
+```text
+opendevbrowser_wait sessionId="<session-id>" ref="<mfa-input-ref>" state="visible"
+opendevbrowser_type sessionId="<session-id>" ref="<mfa-input-ref>" text="<resolved-otp>"
+opendevbrowser_click sessionId="<session-id>" ref="<mfa-submit-ref>"
 ```
-opendevbrowser_launch profile="test-user" persistProfile=true
+
+## Session Persistence Checks
+
+Use persistent profiles when verifying remembered sessions:
+
+```text
+opendevbrowser_launch profile="auth-test" persistProfile=true noExtension=true
+```
+
+Then reopen and verify whether re-authentication is required.
+
+## Batch Script Pattern
+
+Use `opendevbrowser_run` for compact, repeatable flows:
+
+```text
+opendevbrowser_run sessionId="<session-id>" steps=[{"action":"goto","args":{"url":"https://example.com/login"}},{"action":"wait","args":{"until":"networkidle"}},{"action":"snapshot","args":{"format":"actionables"}},{"action":"type","args":{"ref":"<identifier-ref>","text":"<resolved-identifier>"}},{"action":"type","args":{"ref":"<password-ref>","text":"<resolved-password>"}},{"action":"click","args":{"ref":"<submit-ref>"}},{"action":"wait","args":{"until":"networkidle"}},{"action":"snapshot","args":{"format":"outline"}}]
 ```

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

@@ -1,81 +1,122 @@
 ---
 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 "automate a browser flow", "write an OpenDevBrowser script", "use snapshot refs", "extract page content", or "debug browser automation".
+version: 1.1.0
 ---
 
 # OpenDevBrowser Best Practices
 
-Use this guide to generate fast, reliable, script-first workflows without bloating tools or output.
+Use this guide to produce reliable, script-first automation with minimal retries and predictable output.
 
-## Core Workflow (Snapshot -> Refs -> Actions)
+## Core Operating Model
 
-Prefer the snapshot/ref loop as the primary interaction model:
+Follow the loop strictly:
 
-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.
+1. Establish or attach a session.
+2. Capture `opendevbrowser_snapshot`.
+3. Select refs from that snapshot.
+4. Execute one or more actions using refs.
+5. Re-snapshot after navigation or major DOM change.
 
-Use refs instead of raw selectors whenever possible.
+Prefer refs over raw selectors. Refs are more stable across dynamic UI changes.
 
-## Script-First Execution
+## Session Strategy
 
-Batch related actions in a single run to reduce round-trips:
+Choose mode deliberately:
 
-- Use `opendevbrowser_run` for multi-step actions.
-- Keep steps small and deterministic.
-- End each run with a state check (snapshot or targeted extraction).
+- Use managed mode for deterministic, isolated runs.
+- Use extension mode when existing logged-in tabs or profile state are required.
+- Use CDP connect mode only when attaching to a pre-launched browser is required.
 
-Match the arguments used in the single-action tools.
+Example launch patterns:
 
-## Waiting and Stability
+```text
+opendevbrowser_launch noExtension=true
+opendevbrowser_launch waitForExtension=true
+opendevbrowser_connect wsEndpoint="ws://127.0.0.1:9222/devtools/browser/<id>"
+```
 
-Stabilize the page before acting:
+## Snapshot Discipline
 
-- 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.
+Capture snapshots in the format needed by the current task:
 
-## Token-Efficient Extraction
+- Use `format="outline"` for broad page state.
+- Use `format="actionables"` for interaction planning.
+- Use `maxChars` and `cursor` to page large pages instead of requesting oversized snapshots.
 
-Keep outputs small and scoped:
+```text
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+```
 
-- 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.
+## Action Sequencing
 
-## Debug Signals (Lightweight)
+Stabilize before interacting:
 
-Use polling tools only when needed:
+- After `goto` or click-driven navigation, run `opendevbrowser_wait`.
+- Wait on `until="networkidle"` for API-heavy pages.
+- Wait on `ref` + `state` for specific element readiness.
 
-- Use `opendevbrowser_console_poll` to check for runtime errors.
-- Use `opendevbrowser_network_poll` to confirm API calls and statuses.
+```text
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_wait sessionId="<session-id>" ref="<target-ref>" state="visible"
+```
 
-## Example Patterns
+For multi-step interactions, batch deterministic steps with `opendevbrowser_run`.
 
-### Login Flow (Batch)
+```text
+opendevbrowser_run sessionId="<session-id>" steps=[{"action":"goto","args":{"url":"https://example.com"}},{"action":"wait","args":{"until":"networkidle"}},{"action":"snapshot","args":{"format":"actionables"}}]
+```
 
-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.
+## Extraction and Output Control
 
-### Targeted Extraction
+Keep output scoped and cheap:
 
-1. `snapshot` to get ref for the desired element.
-2. `dom_get_text` on that ref.
+- Extract only the needed node text with `opendevbrowser_dom_get_text`.
+- Use `opendevbrowser_dom_get_html` only for small targeted fragments.
+- Use `opendevbrowser_get_attr` and `opendevbrowser_get_value` for structured field data.
 
-## Mode Guidance
+```text
+opendevbrowser_dom_get_text sessionId="<session-id>" ref="<content-ref>"
+opendevbrowser_get_attr sessionId="<session-id>" ref="<input-ref>" name="aria-invalid"
+```
 
-- Use Mode A (managed) by default for zero-config operation.
-- Use Mode C (extension) only when existing logged-in tabs are required.
+## Lightweight Diagnostics
 
-## Safe Defaults
+Inspect runtime behavior only when required:
 
-- Keep CDP local-only by default.
-- Redact secrets in snapshot output.
-- Avoid raw CDP unless explicitly enabled.
+- Use `opendevbrowser_console_poll` to detect script/runtime errors.
+- Use `opendevbrowser_network_poll` to verify request outcomes.
+- Use `opendevbrowser_screenshot` for visual debugging artifacts.
+
+```text
+opendevbrowser_console_poll sessionId="<session-id>"
+opendevbrowser_network_poll sessionId="<session-id>" max=50
+```
+
+## Failure Recovery Order
+
+When a step fails, recover in this order:
+
+1. Re-snapshot to refresh refs.
+2. Re-wait for load or element state.
+3. Retry action once with fresh refs.
+4. Change mode (managed vs extension) only if failure is mode-specific.
+
+Avoid blind repeated retries against stale refs.
+
+## Security and Safety Defaults
+
+- Keep CDP and relay endpoints local-only by default.
+- Do not place secrets in scripts, skill files, or logs.
+- Prefer minimal extraction over full-page dumps when handling sensitive pages.
+
+## Ready-to-Use Flow Template
+
+```text
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="https://example.com"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+# interact with refs
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+```

package/skills/opendevbrowser-continuity-ledger/SKILL.md

@@ -1,45 +1,79 @@
 ---
 name: opendevbrowser-continuity-ledger
-description: Maintain an OpenDevBrowser continuity ledger in opendevbrowser_continuity.md for long-running tasks and resumable work.
-version: 1.0.0
+description: This skill should be used when the user asks to "track continuity", "resume a long task", "maintain CONTINUITY.md", or run multi-step work that may span context compaction.
+version: 1.1.0
 ---
 
 # OpenDevBrowser Continuity Ledger
 
-Use a lightweight ledger to keep long-running tasks on track across sessions or context compaction.
+Use this guide to maintain compaction-safe project state in `CONTINUITY.md`.
 
-## When to use
-- Multi-step work that spans several actions
-- Refactors, migrations, or release work
-- Investigations with multiple findings
-- Any task likely to resume later
+## Ownership Rules
 
-## Ledger file
-- Always use `opendevbrowser_continuity.md` at the repo root.
-- Create it if it does not exist.
-- Keep it short and factual.
+Apply these rules exactly:
 
-## Exact template (copy as-is)
+- Allow only the main orchestrator agent to edit `CONTINUITY.md`.
+- Instruct sub-agents to never edit `CONTINUITY.md`.
+- Require sub-agents to append their outcomes to `sub_continuity.md`.
+- If `CONTINUITY.md` is modified incorrectly by another agent, restore it immediately and continue.
 
-```markdown
-# OpenDevBrowser Continuity Ledger
+## Start-of-Turn Protocol
+
+Run this sequence at the beginning of each turn:
+
+1. Read `CONTINUITY.md`.
+2. Read `sub_continuity.md`.
+3. Update `CONTINUITY.md` to reflect the current goal, constraints, decisions, and execution state.
+4. Proceed with implementation.
+
+If recall is incomplete, rebuild from visible context, mark gaps `UNCONFIRMED`, then continue.
 
+## Required Ledger Template
+
+Maintain these headings and sections:
+
+```markdown
 Goal (incl. success criteria):
 - Constraints/Assumptions:
 - Key decisions:
 - State:
   - Done:
   - Now:
-  - Next:
+  - Next: at least 4 next tasks/subtasks each with a brief description. must be detailed with a clear action item and expected outcome and files to be impacted
 - Open questions (UNCONFIRMED if needed):
+  - When you have open questions, do your research in the codebase (and on the internet for best practices) to understand the existing patterns and constraints. Choose answers that are consistent with the existing patterns and constraints and best-practice and research all synchronized into logical recommendations. You must research codebase + external sources first, state the recommended option with brief rationale, and explicitly list any items that still require user input.
 - Working set (files/ids/commands):
+- Key learnings: what worked; what didn't work, best approach identified for next time
 ```
 
-## Update rules
-1. At the start of a long task, read the ledger and refresh Goal/Now/Next.
-2. Update the ledger when goals, decisions, or progress state change.
-3. Record important tool outcomes briefly.
-4. If context is lost, rebuild the ledger from visible state and mark gaps as `UNCONFIRMED`.
+## Update Triggers
+
+Update `CONTINUITY.md` whenever one of these changes:
+
+- Goal or success criteria
+- Constraints or assumptions
+- Key decisions
+- Progress state (`Done`, `Now`, `Next`)
+- Important command/tool outcomes
+
+Keep entries factual and concise. Avoid transcript-style logging.
+
+## Handling Open Questions
+
+When uncertainty exists:
+
+1. Research codebase patterns first.
+2. Research external best practices where relevant.
+3. Recommend a preferred option with rationale.
+4. List only unresolved user-input decisions.
+5. Mark unknown facts as `UNCONFIRMED`.
+
+## Reply Pattern
+
+Start response messages with a short ledger snapshot:
+
+- Goal
+- Now/Next
+- Open questions + recommended option
 
-## Reply pattern
-Start replies with a short "Ledger Snapshot" (Goal + Now/Next + Open questions) when the ledger is in use.
+Print the full ledger only when it materially changes or when requested.