class-ai-agent 1.4.0 → 1.5.0

package/.agents/agents/ui-ux-designer.md

@@ -0,0 +1,210 @@
+---
+name: UI/UX Designer
+description: Expert designer who creates intuitive, beautiful, and accessible user experiences
+---
+
+# UI/UX Designer Agent
+
+## Role
+
+You are a **Senior UI/UX Designer**. You create user experiences that are beautiful, intuitive, and accessible. Your designs define what gets built.
+
+## Philosophy
+
+> "Design is not how it looks, but how it works."
+
+Every decision is justified by user benefit. Accessible and consistent design is non-negotiable.
+
+---
+
+## Core Principles
+
+| Principle | Implementation |
+|-----------|---------------|
+| **User First** | Decisions based on user benefit, not aesthetics |
+| **Accessible** | WCAG 2.1 AA minimum |
+| **Consistent** | Use design system, no one-offs |
+| **Mobile First** | Design 320px first, enhance upward |
+
+---
+
+## Design Process
+
+### 1. User Research
+
+```markdown
+## User Analysis
+**Persona**: [Name, age, tech level]
+**Job to be done**: "When I [situation], I want to [motivation], so I can [outcome]"
+**Pain points**: [Current problems]
+**Success metric**: [How we measure success]
+```
+
+### 2. Information Architecture
+
+```markdown
+## Structure
+- Content hierarchy (what's most important?)
+- Navigation structure
+- Content grouping
+- CTA priority (primary vs secondary)
+```
+
+### 3. Design Tokens
+
+```typescript
+// tailwind.config.ts
+theme: {
+  extend: {
+    colors: {
+      primary: { 500: '#3b82f6', 600: '#2563eb' },
+      success: '#22c55e',
+      warning: '#f59e0b',
+      error: '#ef4444',
+    },
+    fontSize: {
+      'xs': ['12px', '16px'],
+      'sm': ['14px', '20px'],
+      'base': ['16px', '24px'],
+      'lg': ['18px', '28px'],
+      'xl': ['20px', '28px'],
+    },
+    spacing: {
+      // 4px base grid
+      '1': '4px', '2': '8px', '4': '16px', '6': '24px', '8': '32px',
+    },
+    borderRadius: {
+      'sm': '4px', 'md': '8px', 'lg': '12px',
+    },
+  },
+}
+```
+
+---
+
+## UX Patterns
+
+### Navigation
+- Primary nav: max 7 items
+- Active state clearly visible
+- Mobile: bottom tabs or hamburger
+- Breadcrumbs for depth > 2
+
+### Forms
+- Labels above inputs (never placeholder-only)
+- Inline validation on blur
+- Specific error messages
+- Disabled submit until valid
+- Loading state on submit
+
+### States
+
+```markdown
+Every component needs:
+- Default
+- Hover
+- Focus (visible ring)
+- Active/Pressed
+- Disabled
+- Loading
+- Error
+- Empty
+```
+
+### Loading States
+
+```tsx
+// Skeleton for content
+<Skeleton className="h-4 w-48" />
+
+// Empty state with action
+<EmptyState
+  icon={<PackageIcon />}
+  title="No orders yet"
+  description="Place your first order to get started"
+  action={<Button>Browse products</Button>}
+/>
+
+// Error with retry
+<ErrorState message="Failed to load" onRetry={refetch} />
+```
+
+---
+
+## Accessibility Requirements
+
+### Color
+- Text contrast: >= 4.5:1
+- Large text: >= 3:1
+- Never color alone for info
+
+### Focus
+- Visible focus ring
+- Focus trap in modals
+- Restore focus on close
+
+### Typography
+- Body: minimum 16px
+- Line height: >= 1.5
+
+### ARIA
+- Form inputs: label or aria-label
+- Icons: aria-hidden + adjacent text
+- Modals: role="dialog" aria-modal
+
+---
+
+## Responsive Breakpoints
+
+```
+Mobile:   320px – 767px   (design first)
+Tablet:   768px – 1023px
+Desktop:  1024px – 1279px
+Wide:     1280px+
+```
+
+---
+
+## Design Handoff Checklist
+
+- [ ] All states designed
+- [ ] Dark mode (if applicable)
+- [ ] All breakpoints
+- [ ] Design tokens match Tailwind
+- [ ] Interaction notes (animations, transitions)
+- [ ] Accessibility annotations
+- [ ] Real copy (not Lorem ipsum)
+
+---
+
+## Red Flags
+
+Stop and reconsider if you're:
+
+- Designing without user research
+- Ignoring accessibility
+- Creating one-off styles
+- Not considering mobile
+- Missing loading/error states
+- Using placeholder copy
+
+---
+
+## Collaboration
+
+| Works With | Handoff |
+|------------|---------|
+| **Frontend Developer** | Provides specs, tokens |
+| **Copywriter/SEO** | Collaborates on copy |
+| **Project Manager** | Aligns on requirements |
+
+---
+
+## When to Invoke
+
+- User flow design
+- Wireframes and mockups
+- Design system definition
+- Component design
+- Accessibility review
+- UX evaluation

package/.agents/references/accessibility-checklist.md

@@ -0,0 +1,174 @@
+# Accessibility Checklist (WCAG 2.1 AA)
+
+> Ensure your application is usable by everyone.
+
+## Keyboard Navigation
+
+- [ ] All interactive elements focusable with Tab
+- [ ] Focus order is logical (follows visual order)
+- [ ] Focus indicator visible (never `outline: none`)
+- [ ] Skip link to main content
+- [ ] No keyboard traps
+- [ ] Custom components work with Enter/Space
+
+```jsx
+// ✅ Good: Custom button with keyboard support
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') handleClick();
+  }}
+>
+  Click me
+</div>
+
+// ✅ Better: Use native button
+<button onClick={handleClick}>Click me</button>
+```
+
+## Screen Readers
+
+### Semantic HTML
+- [ ] Use semantic elements (`<nav>`, `<main>`, `<article>`, etc.)
+- [ ] Headings in logical order (h1 → h2 → h3)
+- [ ] Lists use `<ul>`, `<ol>`, `<dl>`
+- [ ] Tables have `<th>` with scope
+
+### ARIA
+- [ ] Images have alt text (empty `alt=""` for decorative)
+- [ ] Form inputs have labels
+- [ ] Buttons have accessible names
+- [ ] Dynamic content announced (aria-live)
+- [ ] Modals trap focus and have aria-modal
+
+```jsx
+// ✅ Good: Accessible form
+<label htmlFor="email">Email</label>
+<input id="email" type="email" aria-describedby="email-hint" />
+<span id="email-hint">We'll never share your email</span>
+
+// ✅ Good: Accessible icon button
+<button aria-label="Close menu">
+  <CloseIcon aria-hidden="true" />
+</button>
+
+// ✅ Good: Live region for updates
+<div aria-live="polite" aria-atomic="true">
+  {notification}
+</div>
+```
+
+## Visual Design
+
+### Color
+- [ ] Color contrast ratio ≥ 4.5:1 (text)
+- [ ] Color contrast ratio ≥ 3:1 (large text, UI components)
+- [ ] Information not conveyed by color alone
+- [ ] Links distinguishable from text (underline or contrast)
+
+### Text
+- [ ] Text resizable to 200% without loss
+- [ ] Line height ≥ 1.5
+- [ ] No text in images (except logos)
+
+### Motion
+- [ ] Respect `prefers-reduced-motion`
+- [ ] No flashing content (> 3 flashes/second)
+- [ ] Animations can be paused
+
+```css
+/* Respect motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Forms
+
+- [ ] All inputs have visible labels
+- [ ] Required fields marked
+- [ ] Error messages associated with inputs
+- [ ] Autocomplete attributes used
+- [ ] Form validation accessible
+
+```jsx
+// ✅ Accessible error message
+<input
+  id="email"
+  aria-invalid={hasError}
+  aria-describedby={hasError ? 'email-error' : undefined}
+/>
+{hasError && (
+  <span id="email-error" role="alert">
+    Please enter a valid email address
+  </span>
+)}
+```
+
+## Interactive Components
+
+### Buttons & Links
+- [ ] Buttons for actions, links for navigation
+- [ ] Link text is descriptive (not "click here")
+- [ ] Disabled state communicated
+
+### Modals/Dialogs
+- [ ] Focus trapped inside modal
+- [ ] Close with Escape key
+- [ ] Focus returns on close
+- [ ] `role="dialog"` and `aria-modal="true"`
+
+### Menus & Dropdowns
+- [ ] Arrow key navigation
+- [ ] `role="menu"` and `role="menuitem"`
+- [ ] Current item indicated
+
+## Testing Tools
+
+```bash
+# Automated testing
+npx axe-cli https://example.com
+npx pa11y https://example.com
+
+# Browser extensions
+- axe DevTools (Chrome)
+- WAVE (Chrome/Firefox)
+- Accessibility Insights (Chrome)
+```
+
+### Manual Testing
+- [ ] Navigate with keyboard only
+- [ ] Test with screen reader (VoiceOver/NVDA)
+- [ ] Zoom to 200%
+- [ ] Use high contrast mode
+- [ ] Test with reduced motion
+
+## ARIA Roles Quick Reference
+
+| Role | Use For |
+|------|---------|
+| `button` | Clickable elements (prefer `<button>`) |
+| `link` | Navigation (prefer `<a>`) |
+| `dialog` | Modal windows |
+| `alert` | Important messages |
+| `status` | Status updates |
+| `navigation` | Nav sections (prefer `<nav>`) |
+| `main` | Main content (prefer `<main>`) |
+| `region` | Distinct sections with label |
+| `tablist`, `tab`, `tabpanel` | Tab interfaces |
+
+## Common Issues
+
+| Issue | Fix |
+|-------|-----|
+| Missing alt text | Add descriptive alt or `alt=""` |
+| Low contrast | Increase color contrast |
+| Missing form labels | Add `<label>` elements |
+| Focus not visible | Don't remove outline, style it |
+| Mouse-only interactions | Add keyboard handlers |
+| Auto-playing media | Add controls, respect preferences |

package/.agents/references/agent-continuity.md

@@ -0,0 +1,42 @@
+# Agent continuity — quick reference
+
+## Files
+
+| Path | Role |
+|------|------|
+| `.agent/SESSION.md` | Live handoff (commit to git) |
+| `.agent/SESSION.template.md` | Schema reference |
+| `.agent/README.md` | Human overview |
+| `tasks/todo.md` | Task checklist (workflow) |
+| `SPEC.md` | Feature spec (workflow) |
+
+## Commands
+
+| Command | When |
+|---------|------|
+| **`/resume`** | Start of session — read SESSION, summarize, continue |
+| **`/handoff`** | End of session — write SESSION, sync tasks |
+
+## Read order (resume)
+
+1. `.agent/SESSION.md`
+2. `tasks/todo.md`
+3. Linked spec from SESSION Pointers
+
+## Install
+
+```bash
+npx class-ai-agent
+```
+
+Creates `.agent/` and seeds `SESSION.md` from template.
+
+## Rules
+
+- **Cursor:** `.cursor/rules/agent-continuity.mdc` (`alwaysApply`)
+- **Claude:** `.claude/rules/agent-continuity.md`
+- **Kiro:** `.kiro/steering/agent-continuity.md` (`inclusion: always`)
+
+## Skill
+
+`.cursor/skills/agent-continuity/SKILL.md` — full handoff/resume checklists.

package/.agents/references/codegraph.md

@@ -0,0 +1,90 @@
+# CodeGraph reference
+
+[CodeGraph](https://github.com/colbymchenry/codegraph) is a local, tree-sitter–parsed knowledge graph exposed to agents via MCP. **class-ai-agent** installs Cursor and Kiro MCP wiring plus usage rules, and runs `codegraph init -i` after scaffolding.
+
+## Antigravity (included with class-ai-agent)
+
+| Item | Path |
+|------|------|
+| MCP config | `~/.gemini/antigravity/mcp_config.json` |
+| Usage rules | `.agent/rules/codegraph.md` |
+| Index (generated) | `.codegraph/` (gitignored) |
+
+1. Restart Antigravity after configuring MCP so MCP connects.
+2. Confirm **CodeGraph** appears under MCP in Antigravity (Agent panel → Manage MCP Servers).
+3. Use `codegraph_*` tools for structural questions; grep/read for literal text.
+
+**Manual index:** `npx @colbymchenry/codegraph init -i`
+
+**Skip auto-index on install:** `CODEGRAPH_SKIP_INIT=1 npx class-ai-agent`
+
+## Cursor
+
+| Item | Path |
+|------|------|
+| MCP config | `.cursor/mcp.json` |
+| Usage rules | `.cursor/rules/codegraph.mdc` |
+
+Reload Cursor after install. See `.cursor/references/codegraph.md`.
+
+## Kiro
+
+| Item | Path |
+|------|------|
+| MCP config | `.kiro/settings/mcp.json` |
+| Usage rules | `.kiro/steering/codegraph.md` |
+
+Restart Kiro after install. See `.kiro/references/codegraph.md`.
+
+## Claude Code
+
+Project scaffolding does **not** add Claude MCP config. Install CodeGraph globally:
+
+```bash
+npx @colbymchenry/codegraph
+codegraph install --target=claude --yes
+```
+
+## MCP setup for Antigravity
+
+See `.agents/references/mcp-antigravity.md` for `mcp_config.json` example (CodeGraph + Supabase).
+
+## Requirements
+
+- **Node 20+** recommended for CodeGraph (class-ai-agent CLI itself supports Node 16.7+).
+- First index can take a minute on large repos; progress prints during `npx class-ai-agent` install.
+
+## Tool parameters
+
+| Tool | Pass | Not |
+|------|------|-----|
+| `codegraph_search` | `query`, optional `limit` | — |
+| `codegraph_context` | **`task`** (natural-language area), optional **`maxNodes`** | `query`, `limit` |
+
+Example — wrong (search-style args on context):
+
+```json
+{ "query": "auth flow", "limit": 15 }
+```
+
+→ `Error: task must be a non-empty string`
+
+Example — correct:
+
+```json
+{ "task": "how authentication flow works", "maxNodes": 15 }
+```
+
+**Session handoff** (`/resume`, `.agent/SESSION.md`) is not a CodeGraph call — read those files with the editor Read tool.
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `task must be a non-empty string` | Use `task` (not `query`) on `codegraph_context`; use `maxNodes` (not `limit`). For `/resume`, read `.agent/SESSION.md` instead. |
+| MCP “not initialized” | Run `npx @colbymchenry/codegraph init -i` in project root |
+| MCP not connecting | Reload Cursor; verify `.cursor/mcp.json`; test `npx @colbymchenry/codegraph serve --mcp` |
+| Stale symbols after edit | Wait ~2s for watcher sync, or check staleness banner in tool output |
+| Init failed during install | Run `npx @colbymchenry/codegraph init -i` manually |
+
+Upstream: [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph)

package/.agents/references/mcp-antigravity.md

@@ -0,0 +1,71 @@
+# Antigravity MCP reference
+
+Antigravity reads MCP server configuration from a **user-level** file (not committed to the project):
+
+| Platform | Path |
+|----------|------|
+| macOS / Linux | `~/.gemini/antigravity/mcp_config.json` |
+| Windows | `C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json` |
+
+**Open in IDE:** Agent panel → **...** → **MCP Servers** → **Manage MCP Servers** → **View raw config**.
+
+After editing, save and restart Antigravity (or refresh MCP servers in the UI).
+
+## Important differences from Cursor
+
+| Cursor (`.cursor/mcp.json`) | Antigravity (`mcp_config.json`) |
+|-------------------------------|-----------------------------------|
+| Project-level file | User-level file |
+| HTTP servers use `url` | HTTP servers use `serverUrl` |
+| `${workspaceFolder}` in args | Use absolute project path or cwd-relative paths |
+
+## Example configuration
+
+Derived from class-ai-agent's bundled Cursor MCP. **Do not commit secrets** — use environment variables.
+
+```json
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@colbymchenry/codegraph",
+        "serve",
+        "--mcp",
+        "--path",
+        "/absolute/path/to/your/project"
+      ]
+    },
+    "supabase": {
+      "serverUrl": "https://mcp.supabase.com/mcp?features=docs"
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/your/project` with your workspace root so CodeGraph indexes the correct tree.
+
+**Supabase:** Complete OAuth in the browser the first time you use Supabase MCP tools.
+
+## CodeGraph without MCP
+
+Install globally for CLI use:
+
+```bash
+npx @colbymchenry/codegraph
+codegraph install --target=claude --yes
+```
+
+Per-project index: `npx @colbymchenry/codegraph init -i` (class-ai-agent runs this on install).
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| MCP tools missing | Restart Antigravity; verify JSON syntax |
+| HTTP server fails | Use `serverUrl` not `url` |
+| CodeGraph stale | Wait ~2s after edits; run `codegraph init -i` if index missing |
+| Too many tools | Antigravity recommends keeping enabled tools under ~50 |
+
+See also `.agents/references/codegraph.md`.