@nockdev/awf 6.2.0 → 6.2.1

package/.agent/skills/tooling/api-protocols/data/trpc-patterns.yaml

@@ -0,0 +1,97 @@
+# tRPC Patterns - HSA API Protocols Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: api-protocols
+  domain: trpc
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 7
+
+patterns:
+  - id: trpc001
+    name: router_setup
+    category: architecture
+    description: tRPC router with procedures and middleware
+    text: router setup procedure query mutation middleware
+    example: |
+      const appRouter = router({
+        user: router({
+          getById: publicProcedure
+            .input(z.object({ id: z.string() }))
+            .query(({ input }) => db.user.findUnique({ where: { id: input.id } })),
+          create: protectedProcedure
+            .input(createUserSchema)
+            .mutation(({ input, ctx }) => db.user.create({ data: input })),
+        }),
+      });
+      export type AppRouter = typeof appRouter;
+
+  - id: trpc002
+    name: middleware
+    category: architecture
+    description: tRPC middleware for auth, logging, rate limiting
+    text: middleware auth logging rate limiting procedure context
+    example: |
+      const isAuthed = t.middleware(({ ctx, next }) => {
+        if (!ctx.session) throw new TRPCError({ code: "UNAUTHORIZED" });
+        return next({ ctx: { ...ctx, user: ctx.session.user } });
+      });
+      const protectedProcedure = t.procedure.use(isAuthed);
+
+  - id: trpc003
+    name: nextjs_integration
+    category: integration
+    description: tRPC with Next.js App Router
+    text: nextjs app router integration server client component
+    example: |
+      // app/api/trpc/[trpc]/route.ts
+      const handler = fetchRequestHandler({ router: appRouter, createContext });
+      export { handler as GET, handler as POST };
+
+  - id: trpc004
+    name: react_query
+    category: client
+    description: tRPC React Query integration with automatic cache
+    text: react query client hook cache invalidation optimistic
+    example: |
+      const { data } = trpc.user.getById.useQuery({ id: "123" });
+      const utils = trpc.useUtils();
+      // Invalidate cache after mutation
+      await utils.user.getById.invalidate({ id: "123" });
+
+  - id: trpc005
+    name: monorepo_setup
+    category: architecture
+    description: tRPC in monorepo with shared types
+    text: monorepo shared types package workspace turborepo
+    example: |
+      // packages/api/src/router.ts — define router
+      // apps/web/src/trpc.ts — import AppRouter type
+      // Result: full type inference across packages
+
+  - id: trpc006
+    name: error_handling
+    category: design
+    description: tRPC error handling with typed errors
+    text: error handling TRPCError code message cause
+    example: |
+      throw new TRPCError({
+        code: "NOT_FOUND",
+        message: "User not found",
+        cause: originalError
+      });
+
+  - id: trpc007
+    name: subscription
+    category: realtime
+    description: tRPC subscriptions for real-time data
+    text: subscription real-time websocket observable
+    example: |
+      subscription: t.procedure.subscription(() => {
+        return observable<Message>((emit) => {
+          const onMessage = (msg: Message) => emit.next(msg);
+          ee.on("message", onMessage);
+          return () => ee.off("message", onMessage);
+        });
+      })

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)_