proagents 1.0.0

package/proagents/prompts/accessibility/keyboard.md

@@ -0,0 +1,392 @@
+# Keyboard Navigation Prompt
+
+Ensure proper keyboard accessibility for interactive components.
+
+---
+
+## Prompt Template
+
+```markdown
+## Keyboard Navigation Review
+
+Review the following component for keyboard accessibility:
+
+```{{language}}
+{{code}}
+```
+
+### Check For:
+
+**Focus Management**
+- [ ] All interactive elements are focusable
+- [ ] Focus order is logical
+- [ ] Focus is visible
+- [ ] No keyboard traps
+
+**Key Handling**
+- [ ] Enter/Space activates buttons
+- [ ] Escape closes modals/dropdowns
+- [ ] Arrow keys navigate within widgets
+- [ ] Tab moves between elements
+
+**Skip Links**
+- [ ] Skip to main content available
+- [ ] Skip navigation where appropriate
+
+### Output Format:
+1. Focus issues found
+2. Missing keyboard handlers
+3. Recommended implementation
+4. Code examples
+```
+
+---
+
+## Standard Keyboard Patterns
+
+### Button
+
+```tsx
+// Native button handles keyboard automatically
+<button onClick={handleClick}>
+  Click me
+</button>
+
+// If using div (not recommended), add keyboard handling
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      handleClick();
+    }
+  }}
+>
+  Click me
+</div>
+```
+
+### Modal/Dialog
+
+```tsx
+function Modal({ isOpen, onClose, children }) {
+  const modalRef = useRef<HTMLDivElement>(null);
+  const previousFocus = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      // Store previous focus
+      previousFocus.current = document.activeElement as HTMLElement;
+      // Focus modal
+      modalRef.current?.focus();
+    } else {
+      // Restore focus
+      previousFocus.current?.focus();
+    }
+  }, [isOpen]);
+
+  // Handle Escape key
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      onClose();
+    }
+  };
+
+  if (!isOpen) return null;
+
+  return (
+    <FocusTrap>
+      <div
+        ref={modalRef}
+        role="dialog"
+        aria-modal="true"
+        tabIndex={-1}
+        onKeyDown={handleKeyDown}
+      >
+        {children}
+        <button onClick={onClose}>Close</button>
+      </div>
+    </FocusTrap>
+  );
+}
+```
+
+### Dropdown Menu
+
+```tsx
+function DropdownMenu({ items }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(-1);
+  const menuRef = useRef<HTMLUListElement>(null);
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        setActiveIndex((prev) =>
+          prev < items.length - 1 ? prev + 1 : 0
+        );
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        setActiveIndex((prev) =>
+          prev > 0 ? prev - 1 : items.length - 1
+        );
+        break;
+      case 'Escape':
+        setIsOpen(false);
+        break;
+      case 'Enter':
+      case ' ':
+        if (activeIndex >= 0) {
+          e.preventDefault();
+          items[activeIndex].onClick();
+        }
+        break;
+    }
+  };
+
+  return (
+    <div onKeyDown={handleKeyDown}>
+      <button
+        aria-expanded={isOpen}
+        aria-haspopup="menu"
+        onClick={() => setIsOpen(!isOpen)}
+      >
+        Menu
+      </button>
+      {isOpen && (
+        <ul role="menu" ref={menuRef}>
+          {items.map((item, index) => (
+            <li
+              key={item.id}
+              role="menuitem"
+              tabIndex={activeIndex === index ? 0 : -1}
+              aria-selected={activeIndex === index}
+            >
+              {item.label}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### Tabs
+
+```tsx
+function Tabs({ tabs }) {
+  const [activeTab, setActiveTab] = useState(0);
+
+  const handleKeyDown = (e: KeyboardEvent, index: number) => {
+    let newIndex = index;
+
+    switch (e.key) {
+      case 'ArrowRight':
+        newIndex = (index + 1) % tabs.length;
+        break;
+      case 'ArrowLeft':
+        newIndex = (index - 1 + tabs.length) % tabs.length;
+        break;
+      case 'Home':
+        newIndex = 0;
+        break;
+      case 'End':
+        newIndex = tabs.length - 1;
+        break;
+      default:
+        return;
+    }
+
+    e.preventDefault();
+    setActiveTab(newIndex);
+  };
+
+  return (
+    <div>
+      <div role="tablist">
+        {tabs.map((tab, index) => (
+          <button
+            key={tab.id}
+            role="tab"
+            aria-selected={activeTab === index}
+            tabIndex={activeTab === index ? 0 : -1}
+            onClick={() => setActiveTab(index)}
+            onKeyDown={(e) => handleKeyDown(e, index)}
+          >
+            {tab.label}
+          </button>
+        ))}
+      </div>
+      <div role="tabpanel">
+        {tabs[activeTab].content}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Focus Management Utilities
+
+### Focus Trap Hook
+
+```tsx
+function useFocusTrap(isActive: boolean) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isActive) return;
+
+    const container = containerRef.current;
+    if (!container) return;
+
+    const focusableElements = container.querySelectorAll(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+
+    const firstElement = focusableElements[0] as HTMLElement;
+    const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
+
+    const handleTab = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+
+      if (e.shiftKey) {
+        if (document.activeElement === firstElement) {
+          e.preventDefault();
+          lastElement.focus();
+        }
+      } else {
+        if (document.activeElement === lastElement) {
+          e.preventDefault();
+          firstElement.focus();
+        }
+      }
+    };
+
+    container.addEventListener('keydown', handleTab);
+    return () => container.removeEventListener('keydown', handleTab);
+  }, [isActive]);
+
+  return containerRef;
+}
+```
+
+### Roving TabIndex
+
+```tsx
+function useRovingTabIndex(itemCount: number) {
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown':
+      case 'ArrowRight':
+        e.preventDefault();
+        setActiveIndex((prev) => (prev + 1) % itemCount);
+        break;
+      case 'ArrowUp':
+      case 'ArrowLeft':
+        e.preventDefault();
+        setActiveIndex((prev) => (prev - 1 + itemCount) % itemCount);
+        break;
+    }
+  };
+
+  return { activeIndex, setActiveIndex, handleKeyDown };
+}
+```
+
+---
+
+## Skip Links
+
+```tsx
+// Add at the beginning of the page
+<a href="#main-content" className="skip-link">
+  Skip to main content
+</a>
+
+<nav>
+  {/* Navigation items */}
+</nav>
+
+<main id="main-content" tabIndex={-1}>
+  {/* Main content */}
+</main>
+
+// CSS for skip link
+.skip-link {
+  position: absolute;
+  left: -10000px;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+}
+
+.skip-link:focus {
+  position: static;
+  width: auto;
+  height: auto;
+}
+```
+
+---
+
+## Testing Keyboard Navigation
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+describe('Keyboard Navigation', () => {
+  it('should navigate menu with arrow keys', async () => {
+    render(<Menu items={menuItems} />);
+
+    const trigger = screen.getByRole('button');
+    await userEvent.click(trigger);
+
+    await userEvent.keyboard('{ArrowDown}');
+    expect(screen.getByRole('menuitem', { name: 'Item 1' })).toHaveFocus();
+
+    await userEvent.keyboard('{ArrowDown}');
+    expect(screen.getByRole('menuitem', { name: 'Item 2' })).toHaveFocus();
+  });
+
+  it('should close modal with Escape', async () => {
+    const onClose = jest.fn();
+    render(<Modal isOpen onClose={onClose} />);
+
+    await userEvent.keyboard('{Escape}');
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('should trap focus within modal', async () => {
+    render(<Modal isOpen><button>First</button><button>Last</button></Modal>);
+
+    const lastButton = screen.getByRole('button', { name: 'Last' });
+    lastButton.focus();
+
+    await userEvent.tab();
+    expect(screen.getByRole('button', { name: 'First' })).toHaveFocus();
+  });
+});
+```
+
+---
+
+## Common Issues Checklist
+
+- [ ] All buttons activatable with Enter and Space
+- [ ] Modal/dialogs trap focus
+- [ ] Modal/dialogs close with Escape
+- [ ] Dropdowns navigable with arrow keys
+- [ ] Tab order matches visual order
+- [ ] Focus visible on all interactive elements
+- [ ] No keyboard traps (can always Tab out)
+- [ ] Skip links available for navigation

package/proagents/prompts/accessibility/wcag.md

@@ -0,0 +1,189 @@
+# WCAG Compliance Check Prompt
+
+Check component or page for WCAG 2.1 compliance.
+
+---
+
+## Prompt Template
+
+```markdown
+## WCAG Compliance Check
+
+Please check the following code for WCAG 2.1 {{level}} compliance:
+
+```{{language}}
+{{code}}
+```
+
+### Check For:
+
+**Perceivable (WCAG 1.x)**
+- [ ] Text alternatives for non-text content (1.1)
+- [ ] Captions and alternatives for multimedia (1.2)
+- [ ] Content adaptable to different presentations (1.3)
+- [ ] Distinguishable content (color, contrast) (1.4)
+
+**Operable (WCAG 2.x)**
+- [ ] Keyboard accessible (2.1)
+- [ ] Enough time to read and use content (2.2)
+- [ ] No content that causes seizures (2.3)
+- [ ] Navigable with clear wayfinding (2.4)
+- [ ] Input modalities beyond keyboard (2.5)
+
+**Understandable (WCAG 3.x)**
+- [ ] Readable text content (3.1)
+- [ ] Predictable operation (3.2)
+- [ ] Input assistance for forms (3.3)
+
+**Robust (WCAG 4.x)**
+- [ ] Compatible with assistive technologies (4.1)
+
+### Output Format:
+For each finding, provide:
+1. WCAG criterion violated (e.g., "1.1.1 Non-text Content")
+2. Level (A, AA, or AAA)
+3. Issue description
+4. Code location
+5. Remediation suggestion
+6. Code fix (if applicable)
+```
+
+---
+
+## Usage Examples
+
+### Check Component for AA Compliance
+
+```markdown
+/a11y wcag AA
+
+Check this button component for WCAG AA compliance:
+
+```tsx
+export const Button = ({ children, onClick }) => (
+  <div onClick={onClick} style={{ backgroundColor: '#777', color: '#999' }}>
+    {children}
+  </div>
+);
+```
+```
+
+### Expected Output
+
+```markdown
+## WCAG Compliance Report
+
+### Violations Found: 3
+
+#### 1. WCAG 1.4.3 Contrast (Minimum) - Level AA
+**Issue:** Insufficient color contrast between text (#999) and background (#777)
+**Ratio:** 1.63:1 (Required: 4.5:1 for normal text)
+**Location:** Button component styles
+**Fix:**
+```tsx
+style={{ backgroundColor: '#777', color: '#fff' }}
+// or
+style={{ backgroundColor: '#333', color: '#fff' }}
+```
+
+#### 2. WCAG 2.1.1 Keyboard - Level A
+**Issue:** `<div>` with onClick is not keyboard accessible
+**Location:** Button component
+**Fix:**
+```tsx
+<button onClick={onClick}>
+  {children}
+</button>
+```
+
+#### 3. WCAG 4.1.2 Name, Role, Value - Level A
+**Issue:** Using `<div>` instead of semantic `<button>` element
+**Location:** Button component
+**Fix:** Use native `<button>` element or add `role="button"` with keyboard handlers
+
+### Recommended Fixed Code
+
+```tsx
+export const Button = ({ children, onClick }) => (
+  <button
+    onClick={onClick}
+    style={{ backgroundColor: '#333', color: '#fff' }}
+  >
+    {children}
+  </button>
+);
+```
+```
+
+---
+
+## WCAG Quick Reference
+
+### Level A (Minimum)
+Must pass for basic accessibility:
+- 1.1.1 Non-text Content
+- 1.3.1 Info and Relationships
+- 1.4.1 Use of Color
+- 2.1.1 Keyboard
+- 2.4.1 Bypass Blocks
+- 4.1.1 Parsing
+- 4.1.2 Name, Role, Value
+
+### Level AA (Standard)
+Required for most compliance:
+- 1.4.3 Contrast (Minimum) - 4.5:1
+- 1.4.4 Resize Text
+- 2.4.6 Headings and Labels
+- 2.4.7 Focus Visible
+- 3.1.2 Language of Parts
+- 3.2.3 Consistent Navigation
+
+### Level AAA (Enhanced)
+Best practice:
+- 1.4.6 Contrast (Enhanced) - 7:1
+- 2.4.9 Link Purpose
+- 3.1.5 Reading Level
+- 3.2.5 Change on Request
+
+---
+
+## Automated Checks
+
+```typescript
+// These can be automated with tools
+const automatedChecks = [
+  'color-contrast',
+  'image-alt',
+  'label',
+  'link-name',
+  'list',
+  'listitem',
+  'meta-viewport',
+  'valid-lang'
+];
+
+// These require manual review
+const manualChecks = [
+  'meaningful-alt-text',
+  'logical-tab-order',
+  'consistent-navigation',
+  'error-prevention'
+];
+```
+
+---
+
+## Integration with Testing
+
+```typescript
+// vitest + @axe-core/react
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+it('should have no WCAG violations', async () => {
+  const { container } = render(<MyComponent />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```

package/proagents/prompts/debugging/README.md

@@ -0,0 +1,51 @@
+# Debugging Prompts
+
+AI-assisted debugging workflows.
+
+---
+
+## Available Prompts
+
+| Prompt | Use Case |
+|--------|----------|
+| [systematic.md](./systematic.md) | Systematic debugging approach |
+| [error-analysis.md](./error-analysis.md) | Analyze error messages |
+| [performance.md](./performance.md) | Debug performance issues |
+| [memory.md](./memory.md) | Debug memory leaks |
+
+---
+
+## Quick Commands
+
+```bash
+/debug analyze <error>     # Analyze error message
+/debug trace <issue>       # Trace issue through code
+/debug suggest <symptom>   # Get fix suggestions
+/debug test <hypothesis>   # Test a hypothesis
+```
+
+---
+
+## Debugging Workflow
+
+```
+1. Reproduce
+   - Consistent steps
+   - Minimal reproduction
+   - Environment details
+
+2. Isolate
+   - Narrow scope
+   - Binary search
+   - Remove variables
+
+3. Identify
+   - Root cause analysis
+   - Trace execution
+   - Check assumptions
+
+4. Fix
+   - Minimal change
+   - Test fix
+   - Prevent regression
+```