@devo-bmad-custom/agent-orchestration 1.0.6 → 1.0.7

package/src/.agents/skills/ui-ux-pro-custom/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/src/.agents/skills/ux-audit/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: ux-audit
+description: Squidhub UI/UX audit skill — design token compliance, accessibility, component reuse, layout patterns, and interaction quality review
+version: 1.0.0
+author: bmad
+tags: [ux, ui, accessibility, design-tokens, shadcn, review, audit]
+---
+
+# UX Audit Skill
+
+## Overview
+
+Load this skill when performing a UX/UI review on Squidhub frontend code. It defines the full audit methodology, checklist, finding format, and verdict rules for the `ux-designer-agent` running the UV (UI Review) lens.
+
+Use alongside `excalidraw-dark-standard` when the audit target includes new UI components that need diagramming.
+
+---
+
+## Audit Scope
+
+Target files: `.tsx`, `.jsx`, `.css` in `frontend/` (skip `dist/`, `.next/`, generated files).
+
+Auto-pass for pure backend changes (no `.tsx`/`.jsx`/`.css` in the diff).
+
+---
+
+## Audit Checklist — 7 Categories
+
+### CAT-1: Design Token Compliance
+- All colors use design tokens (`background`, `foreground`, `primary`, `secondary`, `muted`, `accent`, `border`, `muted-foreground`) — no hardcoded hex/RGB/Tailwind color classes
+- Background variants: `bg-muted/50`, `bg-primary/10` — never `bg-orange-50` or similar
+- Border: `border-muted`, `border-border` — never `border-orange-200`
+- Icon colors: `text-muted-foreground`, `text-primary` — never `text-gray-400`
+
+### CAT-2: Component Reuse (ShadCN + Squidhub catalog)
+- Check `frontend/components/ui/` for any reimplemented component
+- Spinners, badges, data tables, buttons, dialogs — must import from `@/components/ui/*`
+- New reusable components must be added to `docs/frontend/styling-standards.md`
+- Page layout must use `PageHeader` / `PageBody` / `PageHeaderTab` from `frontend/components/layout/`
+
+### CAT-3: Dialog Pattern (WCAG 2.1)
+All dialogs must use the flex-column pattern:
+```tsx
+<DialogContent className="max-w-2xl max-h-[70vh] overflow-hidden flex flex-col gap-0 p-0">
+  <DialogHeader className="flex-shrink-0 px-6 pt-6 pb-4">...</DialogHeader>
+  <div className="flex-1 overflow-y-auto px-6 py-4">...</div>
+  <DialogFooter className="flex-shrink-0 px-6 py-4">...</DialogFooter>
+</DialogContent>
+```
+Flag: missing `overflow-hidden`, missing `flex-shrink-0` on header/footer, missing `flex-1 overflow-y-auto` on body.
+
+### CAT-4: Accessibility
+- Interactive elements have `aria-label` or visible label text
+- `<img>` and `<Image>` have descriptive `alt` attributes (not empty unless decorative)
+- Tab order is logical — no `tabIndex` hacks
+- Focus states visible on interactive elements
+- Color contrast: text on background meets WCAG AA (4.5:1 normal, 3:1 large)
+- Loading states communicated to screen readers (`aria-busy`, `aria-live`)
+
+### CAT-5: Interaction & Feedback Quality
+- All async actions show loading state (spinner, disabled button, skeleton)
+- Error states displayed with actionable messages (not raw API errors)
+- Empty states have meaningful copy and a CTA where appropriate
+- Destructive actions require confirmation (delete dialogs, irreversible operations)
+- Forms validate on submit and show inline field-level errors
+
+### CAT-6: Layout & Responsiveness
+- Pages work at `sm` (640px), `md` (768px), `lg` (1024px), `xl` (1280px)
+- No content overflow without scroll handling
+- Tables on small screens: horizontal scroll or card layout
+- Grids use responsive Tailwind breakpoints (`grid-cols-1 md:grid-cols-2 lg:grid-cols-3`)
+- Modals do not overflow viewport on mobile
+
+### CAT-7: Typography & Visual Hierarchy
+- Heading levels are semantic and sequential (h1 → h2 → h3)
+- No font-size hardcoding outside of design system classes
+- Visual hierarchy is clear: primary action stands out, secondary is muted
+- Consistent spacing — uses Tailwind spacing scale, not arbitrary `px-7` or `mt-9`
+
+---
+
+## Severity Guide
+
+| Severity | Condition |
+|---|---|
+| 🔴 Critical | WCAG 2.1 AA violation; hardcoded color that breaks theming; dialog without flex-column pattern (scroll breaks); blocking interaction bug |
+| 🟡 Major | Missing loading/error state; reimplemented component; missing aria-label on important interactive element; layout broken at one breakpoint |
+| 🟢 Minor | Naming inconsistency; minor spacing irregularity; non-blocking visual improvement |
+
+---
+
+## Finding Format
+
+```
+### [UV-001] {title}
+File: {path}:{line}
+Category: CAT-{N} — {category name}
+Severity: 🔴 Critical | 🟡 Major | 🟢 Minor
+Issue: {description — what is wrong and why it matters}
+Fix: {specific fix with code snippet if helpful}
+```
+
+---
+
+## Output Format
+
+Write findings to:
+```
+_bmad-output/features/{feature-slug}/planning/uv-review-findings-{artifact_id}.md
+```
+
+Return verdict:
+```yaml
+uv_review_verdict:
+  target: {path or feature name}
+  actionable_count: {N}
+  critical: {count of 🔴}
+  major: {count of 🟡}
+  minor: {count of 🟢}
+  findings_path: _bmad-output/features/{feature-slug}/planning/uv-review-findings-{artifact_id}.md
+  status: passed | needs_fixes
+```
+
+**Status rules:**
+- `passed` — zero critical and ≤3 major findings
+- `needs_fixes` — any critical OR 4+ major findings
+
+---
+
+## Auto-Pass Conditions
+
+```yaml
+uv_review_verdict:
+  status: passed
+  note: "Pure backend change — no frontend files in diff."
+```
+
+Trigger when: diff contains zero `.tsx`, `.jsx`, `.css` files.
+
+---
+
+## Reference Documents
+
+Always read before auditing:
+- `docs/frontend/styling-standards.md` — design tokens, component catalog, dialog patterns
+- `docs/frontend/form-patterns.md` — React Hook Form, validation patterns
+- `docs/frontend/page-layout-patterns.md` — PageHeader/PageBody, tabbed routing
+
+---
+
+_v1.0 — 2026-03-14_

package/src/.agents/skills/websocket-engineer/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: websocket-engineer
+description: Use when building real-time communication systems with WebSockets or Socket.IO. Invoke for bidirectional messaging, horizontal scaling with Redis, presence tracking, room management.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: api-architecture
+  triggers: WebSocket, Socket.IO, real-time communication, bidirectional messaging, pub/sub, server push, live updates, chat systems, presence tracking
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fastapi-expert, nestjs-expert, devops-engineer, monitoring-expert, security-reviewer
+---
+
+# WebSocket Engineer
+
+## Core Workflow
+
+1. **Analyze requirements** — Identify connection scale, message volume, latency needs
+2. **Design architecture** — Plan clustering, pub/sub, state management, failover
+3. **Implement** — Build WebSocket server with authentication, rooms, events
+4. **Validate locally** — Test connection handling, auth, and room behavior before scaling (e.g., `npx wscat -c ws://localhost:3000`); confirm auth rejection on missing/invalid tokens, room join/leave events, and message delivery
+5. **Scale** — Verify Redis connection and pub/sub round-trip before enabling the adapter; configure sticky sessions and confirm with test connections across multiple instances; set up load balancing
+6. **Monitor** — Track connections, latency, throughput, error rates; add alerts for connection-count spikes and error-rate thresholds
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Protocol | `references/protocol.md` | WebSocket handshake, frames, ping/pong, close codes |
+| Scaling | `references/scaling.md` | Horizontal scaling, Redis pub/sub, sticky sessions |
+| Patterns | `references/patterns.md` | Rooms, namespaces, broadcasting, acknowledgments |
+| Security | `references/security.md` | Authentication, authorization, rate limiting, CORS |
+| Alternatives | `references/alternatives.md` | SSE, long polling, when to choose WebSockets |
+
+## Code Examples
+
+### Server Setup (Socket.IO with Auth and Room Management)
+
+```js
+import { createServer } from "http";
+import { Server } from "socket.io";
+import { createAdapter } from "@socket.io/redis-adapter";
+import { createClient } from "redis";
+import jwt from "jsonwebtoken";
+
+const httpServer = createServer();
+const io = new Server(httpServer, {
+  cors: { origin: process.env.ALLOWED_ORIGIN, credentials: true },
+  pingTimeout: 20000,
+  pingInterval: 25000,
+});
+
+// Authentication middleware — runs before connection is established
+io.use((socket, next) => {
+  const token = socket.handshake.auth.token;
+  if (!token) return next(new Error("Authentication required"));
+  try {
+    socket.data.user = jwt.verify(token, process.env.JWT_SECRET);
+    next();
+  } catch {
+    next(new Error("Invalid token"));
+  }
+});
+
+// Redis adapter for horizontal scaling
+const pubClient = createClient({ url: process.env.REDIS_URL });
+const subClient = pubClient.duplicate();
+await Promise.all([pubClient.connect(), subClient.connect()]);
+io.adapter(createAdapter(pubClient, subClient));
+
+io.on("connection", (socket) => {
+  const { userId } = socket.data.user;
+  console.log(`connected: ${userId} (${socket.id})`);
+
+  // Presence: mark user online
+  pubClient.hSet("presence", userId, socket.id);
+
+  socket.on("join-room", (roomId) => {
+    socket.join(roomId);
+    socket.to(roomId).emit("user-joined", { userId });
+  });
+
+  socket.on("message", ({ roomId, text }) => {
+    io.to(roomId).emit("message", { userId, text, ts: Date.now() });
+  });
+
+  socket.on("disconnect", () => {
+    pubClient.hDel("presence", userId);
+    console.log(`disconnected: ${userId}`);
+  });
+});
+
+httpServer.listen(3000);
+```
+
+### Client-Side Reconnection with Exponential Backoff
+
+```js
+import { io } from "socket.io-client";
+
+const socket = io("wss://api.example.com", {
+  auth: { token: getAuthToken() },
+  reconnection: true,
+  reconnectionAttempts: 10,
+  reconnectionDelay: 1000,       // initial delay (ms)
+  reconnectionDelayMax: 30000,   // cap at 30 s
+  randomizationFactor: 0.5,      // jitter to avoid thundering herd
+});
+
+// Queue messages while disconnected
+let messageQueue = [];
+
+socket.on("connect", () => {
+  console.log("connected:", socket.id);
+  // Flush queued messages
+  messageQueue.forEach((msg) => socket.emit("message", msg));
+  messageQueue = [];
+});
+
+socket.on("disconnect", (reason) => {
+  console.warn("disconnected:", reason);
+  if (reason === "io server disconnect") socket.connect(); // manual reconnect
+});
+
+socket.on("connect_error", (err) => {
+  console.error("connection error:", err.message);
+});
+
+function sendMessage(roomId, text) {
+  const msg = { roomId, text };
+  if (socket.connected) {
+    socket.emit("message", msg);
+  } else {
+    messageQueue.push(msg); // buffer until reconnected
+  }
+}
+```
+
+## Constraints
+
+### MUST DO
+- Use sticky sessions for load balancing (WebSocket connections are stateful — requests must route to the same server instance)
+- Implement heartbeat/ping-pong to detect dead connections (TCP keepalive alone is insufficient)
+- Use rooms/namespaces for message scoping rather than filtering in application logic
+- Queue messages during disconnection windows to avoid silent data loss
+- Plan connection limits per instance before scaling horizontally
+
+### MUST NOT DO
+- Store large state in memory without a clustering strategy (use Redis or an external store)
+- Mix WebSocket and HTTP on the same port without explicit upgrade handling
+- Forget to handle connection cleanup (presence records, room membership, in-flight timers)
+- Skip load testing before production — connection-count spikes behave differently from HTTP traffic spikes
+
+## Output Templates
+
+When implementing WebSocket features, provide:
+1. Server setup (Socket.IO/ws configuration)
+2. Event handlers (connection, message, disconnect)
+3. Client library (connection, events, reconnection)
+4. Brief explanation of scaling strategy
+
+## Knowledge Reference
+
+Socket.IO, ws, uWebSockets.js, Redis adapter, sticky sessions, nginx WebSocket proxy, JWT over WebSocket, rooms/namespaces, acknowledgments, binary data, compression, heartbeat, backpressure, horizontal pod autoscaling