@nockdev/awf 6.2.0 → 6.2.2

package/.agent/skills/tooling/browser-agent/ADVANCED.md

@@ -0,0 +1,242 @@
+---
+name: browser-agent-advanced
+version: "1.0.0"
+---
+
+# Browser Agent Advanced Patterns
+
+> Reference only — loaded when explicitly needed via ADVANCED.md tier.
+
+## Multi-Page Verification Workflow
+
+```
+Complete Application Verification:
+
+Page Discovery:
+  1. Navigate to root URL
+  2. browser_snapshot → find all links (role=link)
+  3. Map unique internal routes
+  4. Create page queue
+
+Per-Page Loop:
+  For each page in queue:
+    1. browser_navigate(page.url)
+    2. Run 5-phase verification flow
+    3. Collect results
+    4. Move to next page
+
+Cross-Page Tests:
+  1. Navigation consistency (same nav on all pages)
+  2. Footer consistency
+  3. Auth state persistence
+  4. Back/forward navigation
+```
+
+### Implementation
+
+```typescript
+// Multi-page verification orchestration
+async function verifyApplication(rootUrl: string) {
+  const pages = await discoverPages(rootUrl);
+  const results: PageResult[] = [];
+
+  for (const page of pages) {
+    // Phase 1: Load
+    await browser_navigate({ url: page.url });
+    await browser_wait_for({ time: 2 });
+
+    // Phase 2: Discover
+    const snapshot = await browser_snapshot();
+    const elements = parseElements(snapshot);
+
+    // Phase 3: Test each element
+    for (const element of elements) {
+      const result = await testElement(element);
+      results.push(result);
+    }
+
+    // Phase 4: Edge cases
+    await checkConsoleErrors();
+    await checkNetworkErrors();
+    await testResponsive();
+  }
+
+  // Phase 5: Report
+  return generateReport(results);
+}
+```
+
+## Complex Interaction Chains
+
+### Chain: Button → Modal → Form → Success
+
+```
+Step 1: Click "Add User" button
+  └─ browser_click(ref="add-user-btn")
+  └─ browser_snapshot() → verify dialog visible
+
+Step 2: Fill modal form
+  └─ browser_fill_form([
+       { ref: "name", type: "textbox", value: "John Doe" },
+       { ref: "email", type: "textbox", value: "john@test.com" },
+       { ref: "role", type: "combobox", value: "Admin" }
+     ])
+
+Step 3: Submit form
+  └─ browser_click(ref="submit-btn")
+  └─ browser_wait_for({ text: "Success" })
+
+Step 4: Verify success
+  └─ browser_snapshot() → modal closed
+  └─ browser_snapshot() → new user in list
+  └─ browser_take_screenshot() → visual evidence
+```
+
+### Chain: Search → Filter → Sort → Paginate
+
+```
+Step 1: Type search query
+  └─ browser_type(ref="search", text="admin")
+  └─ browser_wait_for({ text: "results" })
+
+Step 2: Apply filter
+  └─ browser_click(ref="role-filter")
+  └─ browser_select_option(ref="role-filter", values=["admin"])
+
+Step 3: Sort by column
+  └─ browser_click(ref="name-header")
+  └─ browser_snapshot() → verify sort indicator
+
+Step 4: Navigate pages
+  └─ browser_click(ref="next-page")
+  └─ browser_snapshot() → page 2 content
+```
+
+## Error Recovery Patterns
+
+### Pattern: Element Not Found Recovery
+
+```
+Attempt: browser_click(ref="submit-btn")
+Error: Element not found
+
+Recovery:
+  1. browser_snapshot() — re-read page state
+  2. Search for similar element:
+     - Look for role=button with name containing "submit"
+     - Look for button with aria-label
+  3. If found with different ref → retry with new ref
+  4. If not found → report as issue with screenshot evidence
+```
+
+### Pattern: State Transition Failure
+
+```
+Attempt: Click "Save" → expect "Saved" message
+Error: Message not appearing
+
+Recovery:
+  1. Check browser_console_messages(level="error")
+     → If JS error → report with error details
+  2. Check browser_network_requests
+     → If API 500 → report as backend issue
+  3. browser_wait_for({ time: 5 })
+     → Retry with longer timeout
+  4. If still failing → screenshot + report
+```
+
+### Pattern: Modal Won't Close
+
+```
+Attempt: browser_press_key("Escape") → modal still visible
+Recovery:
+  1. Look for close button: browser_snapshot → find X button
+  2. browser_click(ref="close-btn")
+  3. If still open → try overlay click
+  4. If still open → report as critical bug
+```
+
+## Performance Profiling via Browser Agent
+
+```
+Performance Checks:
+  1. Page load time
+     └─ browser_evaluate(() => performance.timing.loadEventEnd - performance.timing.navigationStart)
+
+  2. Largest Contentful Paint
+     └─ browser_evaluate(() => {
+          const entries = performance.getEntriesByType('largest-contentful-paint');
+          return entries[entries.length - 1]?.startTime;
+        })
+
+  3. DOM element count
+     └─ browser_evaluate(() => document.querySelectorAll('*').length)
+
+  4. Memory usage
+     └─ browser_evaluate(() => performance.memory?.usedJSHeapSize)
+```
+
+## Multi-Agent Coordination
+
+### Orchestrator Delegates to Browser Agent
+
+```
+Orchestrator receives: "Build the login page and verify it works"
+
+Step 1: Developer persona — writes login page code
+Step 2: Orchestrator delegates to Browser Agent:
+  browser_subagent(
+    TaskName: "Verify Login Page",
+    Task: "Navigate to http://localhost:3000/login.
+           1. Verify page loads (no errors)
+           2. Test email input (type, clear, validation)
+           3. Test password input (type, mask verification)
+           4. Test 'Sign in' button (click, disabled when empty)
+           5. Test form submission (valid + invalid credentials)
+           6. Test 'Forgot password' link navigation
+           Return: pass/fail table for all 6 tests",
+    RecordingName: "login_verification"
+  )
+Step 3: Orchestrator reviews results
+Step 4: If failures → Developer fixes → re-delegate to Browser Agent
+```
+
+## Advanced Subagent Task: Responsive Matrix
+
+```
+Task for browser_subagent:
+"Navigate to {URL}. Test at these viewport sizes:
+
+1. Desktop (1280x720):
+   - Take screenshot
+   - Verify navigation is horizontal
+   - Verify sidebar visible
+
+2. Tablet (768x1024):
+   - browser_resize(768, 1024)
+   - Take screenshot
+   - Verify navigation is horizontal
+   - Verify sidebar collapsed or hidden
+
+3. Mobile (375x812):
+   - browser_resize(375, 812)
+   - Take screenshot
+   - Verify hamburger menu appears
+   - Click hamburger → verify menu opens
+   - Verify content single-column
+
+Return: 3 screenshots + pass/fail for each breakpoint"
+```
+
+## Checklist
+
+- [ ] Multi-page discovery implemented?
+- [ ] Complex interaction chains tested?
+- [ ] Error recovery handled?
+- [ ] Performance metrics collected?
+- [ ] Responsive matrix verified?
+- [ ] Multi-agent coordination documented?
+
+---
+
+_DOMYH Awesome Code — Browser Agent Advanced Patterns (Reference Only)_

package/.agent/skills/tooling/browser-agent/META.yaml

@@ -0,0 +1,78 @@
+name: browser-agent
+version: "1.0.0"
+display: Browser Agent
+category: tooling
+tier: 1
+priority: 1
+
+desc: "AI browser agent verification patterns: 5-phase comprehensive testing flow, interactive element discovery, systematic interaction testing, evidence-based reporting. Forces agents to test ALL interactive elements (dropdowns, modals, buttons, hover) not just surface-level checks."
+
+  ### Data Files (5 domains, ~40 patterns)
+  - verification-flow.yaml: 5-phase comprehensive testing flow (5)
+  - subagent-patterns.yaml: Task templates for browser_subagent tool (5)
+  - element-discovery.yaml: Element categorization from accessibility tree (15)
+  - recording-patterns.yaml: WebP video recording best practices (6)
+  - reporting-patterns.yaml: Evidence-based reporting templates (4)
+
+triggers:
+  file_patterns: []
+  keywords:
+    # Core
+    - browser agent
+    - browser subagent
+    - browser_subagent
+    - verify frontend
+    - test UI
+    - check website
+    - verify implementation
+    - frontend verification
+    - browser verification
+    # Vietnamese
+    - kiểm tra frontend
+    - kiểm tra giao diện
+    - xác minh frontend
+    # Interaction-specific
+    - test dropdown
+    - test modal
+    - verify button
+    - test hover
+    - comprehensive frontend test
+    - test all interactions
+  intents:
+    - verify frontend works
+    - test the website
+    - check if UI is working
+    - comprehensive frontend test
+    - test all interactive elements
+    - verify dropdown modal button
+
+caps:
+  - 5-phase comprehensive verification flow (load → discover → test → a11y → report)
+  - Interactive element discovery from accessibility snapshot tree
+  - Systematic interaction testing for EACH discovered element
+  - Task description templates for browser_subagent tool
+  - WebP recording patterns and naming conventions
+  - Evidence-based reporting with screenshots and pass/fail
+  - Error detection via console messages and network requests
+  - Dropdown/Modal/Button/Hover verification integration
+  - Multi-page verification workflows
+  - Complex interaction chains (button → modal → form → success)
+
+data_files:
+  - data/verification-flow.yaml
+  - data/subagent-patterns.yaml
+  - data/element-discovery.yaml
+  - data/recording-patterns.yaml
+  - data/reporting-patterns.yaml
+
+related_skills:
+  - playwright
+  - testing
+  - accessibility
+
+hsa_adapter:
+  enabled: true
+  data_dir: "skills/tooling/browser-agent/data"
+  preload_data: true
+
+# _DOMYH Awesome Code • Browser Agent Skill META v1.0.0_

package/.agent/skills/tooling/browser-agent/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: browser-agent
+detect: []
+version: "1.0.0"
+---
+
+# Browser Agent Verification Patterns (2026)
+
+> AI IDE browser verification skill — forces comprehensive testing, not surface checks. Check `data/` for lookup tables.
+
+## 📦 Data Files
+
+| File                      | Content                            | Records |
+| ------------------------- | ---------------------------------- | ------- |
+| `verification-flow.yaml`  | 5-phase comprehensive testing flow | 5       |
+| `subagent-patterns.yaml`  | browser_subagent task templates    | 5       |
+| `element-discovery.yaml`  | Element categorization patterns    | 15      |
+| `recording-patterns.yaml` | WebP recording best practices      | 6       |
+| `reporting-patterns.yaml` | Evidence-based reporting templates | 4       |
+
+## 🎯 Core Problem
+
+```
+❌ AI agent says: "Page loads correctly, layout looks good ✅"
+   → MISSED: dropdown doesn't open, modal has no focus trap,
+     button submits twice, hover tooltip obscured
+
+✅ AI agent MUST: Test EVERY interactive element systematically
+   → Dropdown opens? Select works? Keyboard nav? Escape closes?
+   → Modal triggers? Focus trapped? Escape closes? Form submits?
+   → Button performs action? Disabled works? Rage-click safe?
+```
+
+## 🔄 5-Phase Comprehensive Verification Flow
+
+```
+Phase 1: Page Load ────────────────── HTTP 200? Errors? Layout OK?
+    ↓
+Phase 2: Element Discovery ────────── browser_snapshot → list ALL elements
+    ↓
+Phase 3: Systematic Testing ───────── Test EACH element by type
+    ↓
+Phase 4: Accessibility & Edge Cases ─ Keyboard nav, console, network
+    ↓
+Phase 5: Evidence Report ──────────── Screenshots + pass/fail table
+```
+
+### Phase 1: Page Load Verification
+
+| Step     | MCP Tool                   | Check           |
+| -------- | -------------------------- | --------------- |
+| Navigate | `browser_navigate`         | HTTP 200        |
+| Wait     | `browser_wait_for`         | networkidle     |
+| Errors   | `browser_console_messages` | No JS errors    |
+| Layout   | `browser_take_screenshot`  | Visual baseline |
+
+### Phase 2: Interactive Element Discovery
+
+| Step       | MCP Tool           | Output                                        |
+| ---------- | ------------------ | --------------------------------------------- |
+| Snapshot   | `browser_snapshot` | Full accessibility tree                       |
+| Parse      | —                  | List: buttons, links, inputs, selects, custom |
+| Categorize | —                  | Group by type for Phase 3                     |
+
+### Phase 3: Systematic Interaction Testing
+
+| Element Type | Tests                                | MCP Tools                                                     |
+| ------------ | ------------------------------------ | ------------------------------------------------------------- |
+| Button       | Click → action, disabled, rage-click | `browser_click`, `browser_snapshot`                           |
+| Dropdown     | Open, select, keyboard, close        | `browser_click`, `browser_select_option`, `browser_press_key` |
+| Modal        | Trigger, focus trap, Escape, form    | `browser_click`, `browser_press_key`, `browser_fill_form`     |
+| Hover        | Trigger, content, keyboard equiv     | `browser_hover`, `browser_press_key`                          |
+| Form         | Fill, submit, validate, error        | `browser_fill_form`, `browser_click`, `browser_snapshot`      |
+
+### Phase 4: Accessibility & Edge Cases
+
+| Step          | MCP Tool                          | Check                  |
+| ------------- | --------------------------------- | ---------------------- |
+| Keyboard nav  | `browser_press_key(Tab)`          | All elements reachable |
+| Focus visible | `browser_take_screenshot`         | Focus indicator shown  |
+| Console       | `browser_console_messages(error)` | No errors              |
+| Network       | `browser_network_requests`        | No 4xx/5xx             |
+| Resize        | `browser_resize`                  | Responsive at 375px    |
+
+### Phase 5: Evidence-Based Report
+
+| Item       | Content                        |
+| ---------- | ------------------------------ |
+| Screenshot | Per-element evidence           |
+| Pass/Fail  | Per-checkpoint table           |
+| Issues     | Element + expected + actual    |
+| Recording  | WebP video of interaction flow |
+
+## 🤖 browser_subagent Task Template
+
+```
+Task: "Navigate to {URL}. Wait for page load.
+
+1. Take a browser_snapshot and list ALL interactive elements
+2. For EACH button: click it, verify the action, take screenshot
+3. For EACH dropdown: open it, select an option, verify update
+4. For EACH modal trigger: open modal, test Escape close, test focus trap
+5. Check browser_console_messages for errors
+6. Check browser_network_requests for failed requests
+
+Return: List of all elements tested with pass/fail status."
+
+RecordingName: "comprehensive_verification"
+```
+
+## 🔍 Decision Tree: Playwright MCP vs browser_subagent
+
+```
+Need browser interaction?
+├─ Quick check (1-2 actions) → Use Playwright MCP tools directly
+│   browser_navigate → browser_snapshot → browser_click
+│
+├─ Comprehensive verification → Use browser_subagent
+│   Delegate entire 5-phase flow as one task
+│
+└─ Visual comparison → Use browser_subagent with screenshots
+    Take screenshots before/after changes
+```
+
+## ⚠️ Anti-Patterns
+
+| ❌ Don't                    | ✅ Do                                     |
+| --------------------------- | ----------------------------------------- |
+| "Page loads, looks good ✅" | Run 5-phase flow, test EVERY element      |
+| Test only buttons           | Test buttons + dropdowns + modals + hover |
+| Skip keyboard testing       | Test Tab/Enter/Escape on ALL elements     |
+| Just take screenshot        | Take snapshot first (accessibility tree)  |
+| Assume modal works          | Test focus trap, Escape close, overlay    |
+| Test once                   | Test at mobile (375px) + desktop (1280px) |
+
+## 📋 Quick Checklist
+
+Before reporting "frontend works":
+
+- [ ] Phase 1: Page loads without console errors?
+- [ ] Phase 2: ALL interactive elements discovered?
+- [ ] Phase 3: EACH element tested (click, select, type)?
+- [ ] Phase 4: Keyboard navigation works?
+- [ ] Phase 4: No 4xx/5xx network errors?
+- [ ] Phase 5: Evidence (screenshots) collected?
+- [ ] Responsive: Works at 375px mobile width?
+
+## 🔌 HSA Integration
+
+Data powered by HSA BM25 search engine:
+
+| Domain    | Query Examples                         |
+| --------- | -------------------------------------- |
+| Flow      | "5-phase verification flow"            |
+| Subagent  | "browser_subagent task template"       |
+| Discovery | "element discovery accessibility tree" |
+| Recording | "WebP recording naming convention"     |
+| Reporting | "evidence-based report template"       |
+
+**Data domains**: `verification-flow`, `subagent-patterns`, `element-discovery`, `recording-patterns`, `reporting-patterns`
+
+---
+
+_DOMYH Awesome Code — Browser Agent Verification Patterns (Data-Driven + HSA)_

package/.agent/skills/tooling/browser-agent/data/element-discovery.yaml

@@ -0,0 +1,208 @@
+# =============================================================================
+# element-discovery.yaml — Element Categorization from Accessibility Tree
+# =============================================================================
+
+version: "1.0.0"
+
+# How to discover and categorize interactive elements from browser_snapshot
+
+discovery_source: "browser_snapshot (accessibility tree)"
+
+element_types:
+  # =========================================================================
+  # SIMPLE INTERACTIVE ELEMENTS
+  # =========================================================================
+  interactive:
+    - type: button
+      detection:
+        roles: ["button"]
+        attributes: ["type=button", "type=submit", "type=reset"]
+        patterns: ["<button>", 'role="button"']
+      test_actions:
+        - "Click → verify action"
+        - "Check disabled state"
+        - "Verify loading state"
+        - "Tab focus + Enter activation"
+      mcp_tools: ["browser_click", "browser_press_key", "browser_snapshot"]
+      checklist_ref: "BT-F01 through BT-A04"
+
+    - type: link
+      detection:
+        roles: ["link"]
+        attributes: ["href"]
+        patterns: ["<a href>"]
+      test_actions:
+        - "Click → verify navigation"
+        - "Check target URL"
+        - "Verify opens in correct target (_blank, _self)"
+      mcp_tools: ["browser_click", "browser_snapshot"]
+
+    - type: text_input
+      detection:
+        roles: ["textbox", "searchbox"]
+        attributes: ["type=text", "type=email", "type=password", "type=search"]
+        patterns: ['<input type="text">', "<textarea>"]
+      test_actions:
+        - "Click to focus"
+        - "Type text → verify value"
+        - "Clear → verify empty"
+        - "Validation on blur"
+      mcp_tools: ["browser_click", "browser_type", "browser_snapshot"]
+
+    - type: checkbox
+      detection:
+        roles: ["checkbox"]
+        attributes: ["type=checkbox"]
+        patterns: ['<input type="checkbox">']
+      test_actions:
+        - "Click → toggle state"
+        - "Verify checked/unchecked"
+        - "Space key toggles"
+      mcp_tools: ["browser_click", "browser_press_key", "browser_snapshot"]
+
+    - type: radio
+      detection:
+        roles: ["radio"]
+        attributes: ["type=radio"]
+        patterns: ['<input type="radio">']
+      test_actions:
+        - "Click → select only one"
+        - "Arrow keys navigate group"
+        - "Verify mutual exclusivity"
+      mcp_tools: ["browser_click", "browser_press_key", "browser_snapshot"]
+
+    - type: switch
+      detection:
+        roles: ["switch"]
+        attributes: ["role=switch"]
+      test_actions:
+        - "Click → toggle on/off"
+        - "Space key toggles"
+        - "Verify visual state matches"
+      mcp_tools: ["browser_click", "browser_snapshot"]
+
+  # =========================================================================
+  # COMPOUND INTERACTIVE ELEMENTS (require multiple interactions)
+  # =========================================================================
+  compound:
+    - type: dropdown_native
+      detection:
+        roles: ["combobox", "listbox"]
+        patterns: ["<select>"]
+      test_actions:
+        - "Click → open options"
+        - "Select option → verify value"
+        - "Arrow keys navigate"
+        - "Escape closes"
+      mcp_tools: ["browser_click", "browser_select_option", "browser_press_key"]
+      checklist_ref: "DD-F01 through DD-VA03"
+
+    - type: dropdown_custom
+      detection:
+        roles: ["combobox"]
+        attributes: ["aria-haspopup=listbox", "aria-expanded"]
+      test_actions:
+        - "Click trigger → open list"
+        - "Click option → verify selection"
+        - "Keyboard: Enter open, arrows navigate, Escape close"
+        - "Search/filter (if available)"
+      mcp_tools:
+        [
+          "browser_click",
+          "browser_press_key",
+          "browser_type",
+          "browser_snapshot",
+        ]
+      checklist_ref: "DD-F01 through DD-VA03"
+
+    - type: modal
+      detection:
+        roles: ["dialog"]
+        attributes: ["aria-modal=true", "aria-haspopup=dialog"]
+      test_actions:
+        - "Click trigger → open modal"
+        - "Verify overlay and centered"
+        - "Focus trap: Tab stays inside"
+        - "Escape closes, focus returns"
+        - "Form inside: fill and submit"
+      mcp_tools:
+        [
+          "browser_click",
+          "browser_press_key",
+          "browser_fill_form",
+          "browser_snapshot",
+        ]
+      checklist_ref: "MD-TD01 through MD-FM04"
+
+    - type: accordion
+      detection:
+        attributes: ["aria-expanded"]
+        patterns: ["accordion", "collapsible"]
+      test_actions:
+        - "Click header → expand/collapse"
+        - "Verify content visibility"
+        - "Multiple open vs single open"
+      mcp_tools: ["browser_click", "browser_snapshot"]
+
+    - type: tabs
+      detection:
+        roles: ["tab", "tablist", "tabpanel"]
+      test_actions:
+        - "Click tab → show panel"
+        - "Arrow keys switch tabs"
+        - "Verify panel content"
+      mcp_tools: ["browser_click", "browser_press_key", "browser_snapshot"]
+
+    - type: menu
+      detection:
+        roles: ["menu", "menubar", "menuitem"]
+        attributes: ["aria-haspopup=menu"]
+      test_actions:
+        - "Click/hover → open menu"
+        - "Click item → action"
+        - "Arrow keys navigate"
+        - "Escape closes"
+      mcp_tools:
+        [
+          "browser_click",
+          "browser_hover",
+          "browser_press_key",
+          "browser_snapshot",
+        ]
+
+  # =========================================================================
+  # VISUAL INTERACTIVE ELEMENTS
+  # =========================================================================
+  visual:
+    - type: tooltip
+      detection:
+        attributes: ["aria-describedby", "data-tooltip"]
+        patterns: ["title="]
+      test_actions:
+        - "Hover → tooltip appears"
+        - "Focus → tooltip appears (keyboard)"
+        - "Content readable"
+        - "No layout shift"
+      mcp_tools: ["browser_hover", "browser_press_key", "browser_snapshot"]
+      checklist_ref: "HV-T01 through HV-TE02"
+
+    - type: carousel
+      detection:
+        attributes: ["role=region"]
+        patterns: ["carousel", "slider", "swiper"]
+      test_actions:
+        - "Next/prev buttons work"
+        - "Dots/indicators sync"
+        - "Auto-play pauses on hover"
+      mcp_tools: ["browser_click", "browser_hover", "browser_snapshot"]
+
+# Discovery Workflow
+workflow:
+  - step: "Call browser_snapshot"
+  - step: "Parse accessibility tree output"
+  - step: "For each element with an interactive role, add to test list"
+  - step: "For compound elements (aria-haspopup, aria-expanded), add enhanced tests"
+  - step: "Sort by priority: forms > modals > dropdowns > buttons > tooltips"
+  - step: "Generate Phase 3 test plan"
+
+# _DOMYH Awesome Code • Element Discovery Patterns v1.0.0_