agentic-loop 3.9.0 → 3.10.0

package/.claude/skills/review/SKILL.md

@@ -0,0 +1,167 @@
+---
+description: Review code for issues, improvements, and best practices.
+---
+
+# Code Review
+
+Review code for issues, improvements, and best practices.
+
+## Instructions
+
+When asked to review code, perform a thorough analysis looking for:
+
+### 1. Security Issues (Critical) - OWASP Top 10
+
+- [ ] **Injection**: SQL, command, LDAP injection via string concatenation
+- [ ] **XSS**: innerHTML, dangerouslySetInnerHTML, v-html with user data
+- [ ] **Broken Auth**: Hardcoded credentials, weak passwords, missing rate limiting
+- [ ] **Sensitive Data Exposure**: Secrets in code, sensitive data in logs/URLs
+- [ ] **Broken Access Control**: Missing auth checks, IDOR, privilege escalation
+- [ ] **Security Misconfiguration**: Debug mode, default credentials, verbose errors
+- [ ] **Insecure Deserialization**: pickle, eval() with user input
+- [ ] **Vulnerable Dependencies**: Outdated packages with known CVEs
+
+```typescript
+// VULNERABLE - SQL injection
+const query = `SELECT * FROM users WHERE name = '${userInput}'`;
+
+// SAFE - parameterized query
+const query = "SELECT * FROM users WHERE name = ?";
+db.execute(query, [userInput]);
+```
+
+```typescript
+// VULNERABLE - XSS
+element.innerHTML = userInput;
+
+// SAFE
+element.textContent = userInput;
+// or with sanitization
+element.innerHTML = DOMPurify.sanitize(userInput);
+```
+
+### 2. Error Handling (High)
+
+- [ ] Empty catch blocks
+- [ ] Missing error boundaries
+- [ ] Unhandled promise rejections
+- [ ] Missing null/undefined checks
+- [ ] Silent failures
+
+### 3. Type Safety (High for TypeScript)
+
+- [ ] Usage of `any` type
+- [ ] Missing type annotations
+- [ ] Type assertions that could fail
+- [ ] Inconsistent types
+
+### 4. Code Quality (Medium)
+
+- [ ] Functions over 50 lines
+- [ ] Deep nesting (4+ levels)
+- [ ] Code duplication
+- [ ] Magic numbers
+- [ ] Unclear variable names
+- [ ] Missing or outdated comments
+
+### 5. Performance (Medium)
+
+- [ ] N+1 query patterns
+- [ ] Missing memoization for expensive operations
+- [ ] Unnecessary re-renders (React)
+- [ ] Large bundle imports
+- [ ] Missing pagination
+
+### 6. Maintainability (Low)
+
+- [ ] Dead code
+- [ ] Commented-out code
+- [ ] TODOs that should be addressed
+- [ ] Inconsistent patterns
+- [ ] Missing tests
+
+## Output Format
+
+Structure your review like this:
+
+```markdown
+## Code Review: [filename or description]
+
+### Summary
+[1-2 sentence overview of the code quality]
+
+### Critical Issues
+These must be fixed before merging:
+
+1. **[Issue Title]** (Line X)
+   - Problem: [What's wrong]
+   - Risk: [What could happen]
+   - Fix: [How to fix it]
+   ```
+   [Code suggestion if applicable]
+   ```
+
+### Improvements
+These should be addressed:
+
+1. **[Issue Title]** (Line X)
+   - Current: [What it does now]
+   - Better: [What it should do]
+   - Why: [Benefit of changing]
+
+### Minor Suggestions
+Nice to have, low priority:
+
+1. **[Suggestion]** (Line X)
+   - [Brief explanation]
+
+### What's Good
+[Acknowledge good patterns and practices in the code]
+
+### Verdict
+[ ] Ready to merge
+[ ] Needs minor changes
+[ ] Needs significant changes
+[ ] Needs rewrite
+```
+
+## Severity Guide
+
+| Severity | Block Merge? | Examples |
+|----------|--------------|----------|
+| Critical | Yes | Security vulnerabilities, data loss risks |
+| High | Yes | Missing error handling, type safety issues |
+| Medium | Review | Performance issues, code quality |
+| Low | No | Style preferences, minor improvements |
+
+## Review Modes
+
+### Quick Review
+Focus only on critical and high-severity issues:
+> "Quick review of this code"
+
+### Full Review
+Check everything:
+> "Full review of src/api/users.ts"
+
+### Security Review (OWASP Top 10)
+Deep dive on security - injection, XSS, auth, access control, secrets:
+> "Security review of the authentication flow"
+> "Check for SQL injection vulnerabilities"
+> "Full security audit of the API endpoints"
+
+### Performance Review
+Focus on performance:
+> "Performance review of the dashboard page"
+
+### Dependency Audit
+Check for vulnerable dependencies:
+> "Check our dependencies for known vulnerabilities"
+
+## Be Constructive
+
+- Explain **why** something is an issue, not just that it is
+- Provide **specific** suggestions for fixes
+- Acknowledge what's **done well**
+- Be **respectful** - we all make mistakes
+- Focus on the **code**, not the coder

package/.claude/skills/sign/SKILL.md

@@ -0,0 +1,32 @@
+---
+description: Add a learned pattern (sign) that Ralph will remember for future stories.
+---
+
+# Add Sign
+
+The user wants to add a sign - a pattern or rule that Ralph should remember for all future work.
+
+**Get the pattern from the user.** Ask:
+1. What's the pattern or rule? (e.g., "Always use select_related for foreign keys")
+2. What category? (frontend, backend, general, testing)
+
+**Then run:**
+
+```bash
+npx ralph sign "THE PATTERN HERE" CATEGORY
+```
+
+**Examples:**
+```bash
+npx ralph sign "Never hardcode AI model names - use env vars" backend
+npx ralph sign "Always add data-testid for Playwright tests" frontend
+npx ralph sign "Use useCallback for event handlers passed to children" frontend
+npx ralph sign "Always paginate list endpoints" backend
+```
+
+**After adding, confirm:** "Added sign. Ralph will include this in every future story prompt."
+
+**To see all signs:**
+```bash
+npx ralph signs
+```

package/.claude/skills/styleguide/SKILL.md

@@ -0,0 +1,450 @@
+---
+description: Generate a complete HTML/React styleguide page for your project based on your design preferences.
+---
+
+# Styleguide Generator
+
+Generate a complete HTML/React styleguide page for your project based on your design preferences.
+
+## Instructions
+
+This skill creates a `/styleguide` route that displays all your UI components, making it easy for AI to understand and replicate your design system.
+
+### Phase 1: Discovery
+
+First, understand the project:
+
+**Check the tech stack:**
+- Look for `package.json` to identify the framework (React, Vue, Next.js, etc.)
+- Check for existing styling solution (Tailwind, CSS Modules, styled-components, etc.)
+- Find the components directory structure
+- Look for any existing design tokens or theme files
+
+**Check for existing components:**
+- Search for `components/` or `src/components/`
+- Look for existing Button, Input, Card components
+- Note any UI library usage (shadcn, MUI, Chakra, etc.)
+
+### Phase 2: Interview the User
+
+Ask these questions to understand their design vision. Present them as a friendly conversation:
+
+**1. "What's the vibe you're going for?"**
+
+Offer examples:
+- **Clean & Minimal** - Lots of whitespace, subtle shadows, muted colors
+- **Bold & Vibrant** - Saturated colors, strong contrasts, energetic
+- **Dark & Moody** - Dark backgrounds, neon accents, atmospheric
+- **Soft & Friendly** - Rounded corners, pastels, warm feeling
+- **Professional & Corporate** - Conservative, trustworthy, structured
+- **Playful & Fun** - Bright colors, animations, personality
+- **Neon Glass** - Glassmorphism, glows, futuristic
+- **Other** - Let them describe it
+
+**2. "What are your brand colors?"**
+
+Ask for:
+- **Primary color** - Main brand color (buttons, links, accents)
+- **Secondary color** - Supporting color
+- **Accent color** - For highlights and CTAs (optional)
+
+If they don't have colors, suggest palettes based on their vibe:
+- Clean: Blue (#3B82F6) + Gray
+- Bold: Orange (#F97316) + Purple (#8B5CF6)
+- Dark: Cyan (#06B6D4) + Purple (#A855F7)
+- Soft: Pink (#EC4899) + Lavender (#A78BFA)
+- Professional: Navy (#1E40AF) + Gold (#F59E0B)
+
+**3. "Light mode, dark mode, or both?"**
+
+- Light mode only
+- Dark mode only
+- Both (with toggle)
+
+**4. "What's your border radius preference?"**
+
+- **Sharp** - 0px (modern, editorial)
+- **Subtle** - 4px (clean, professional)
+- **Rounded** - 8px (friendly, approachable)
+- **Pill** - 9999px for buttons (playful)
+- **Mixed** - Rounded cards, pill buttons
+
+**5. "Any specific components you need?"**
+
+Common ones to include:
+- Buttons (primary, secondary, ghost, destructive)
+- Form inputs (text, select, checkbox, radio, toggle)
+- Cards
+- Modals/Dialogs
+- Alerts/Toasts
+- Navigation
+- Tables
+- Badges/Tags
+
+### Phase 3: Generate the Styleguide
+
+Create a styleguide page at `/styleguide` (or their preferred route).
+
+**File structure for React/Next.js:**
+```
+src/
+├── pages/styleguide.tsx (or app/styleguide/page.tsx for Next.js App Router)
+└── styles/
+    └── design-tokens.css (optional CSS variables)
+```
+
+**Include these sections:**
+
+#### 1. Design Tokens
+```tsx
+<section id="tokens">
+  <h2>Design Tokens</h2>
+
+  {/* Colors */}
+  <div className="grid grid-cols-5 gap-4">
+    <div className="h-20 rounded-lg bg-primary" title="Primary" />
+    <div className="h-20 rounded-lg bg-secondary" title="Secondary" />
+    <div className="h-20 rounded-lg bg-accent" title="Accent" />
+    <div className="h-20 rounded-lg bg-background" title="Background" />
+    <div className="h-20 rounded-lg bg-foreground" title="Foreground" />
+  </div>
+
+  {/* Typography Scale */}
+  <div className="space-y-2 mt-8">
+    <p className="text-xs">xs - 12px</p>
+    <p className="text-sm">sm - 14px</p>
+    <p className="text-base">base - 16px</p>
+    <p className="text-lg">lg - 18px</p>
+    <p className="text-xl">xl - 20px</p>
+    <p className="text-2xl">2xl - 24px</p>
+    <p className="text-3xl">3xl - 30px</p>
+    <p className="text-4xl">4xl - 36px</p>
+  </div>
+
+  {/* Spacing */}
+  <div className="flex items-end gap-2 mt-8">
+    <div className="w-1 h-1 bg-primary" title="1 - 4px" />
+    <div className="w-2 h-2 bg-primary" title="2 - 8px" />
+    <div className="w-3 h-3 bg-primary" title="3 - 12px" />
+    <div className="w-4 h-4 bg-primary" title="4 - 16px" />
+    <div className="w-6 h-6 bg-primary" title="6 - 24px" />
+    <div className="w-8 h-8 bg-primary" title="8 - 32px" />
+  </div>
+</section>
+```
+
+#### 2. Buttons
+```tsx
+<section id="buttons">
+  <h2>Buttons</h2>
+
+  {/* Variants */}
+  <div className="flex flex-wrap gap-4">
+    <Button variant="primary">Primary</Button>
+    <Button variant="secondary">Secondary</Button>
+    <Button variant="ghost">Ghost</Button>
+    <Button variant="destructive">Destructive</Button>
+    <Button variant="link">Link</Button>
+  </div>
+
+  {/* Sizes */}
+  <div className="flex items-center gap-4 mt-4">
+    <Button size="sm">Small</Button>
+    <Button size="md">Medium</Button>
+    <Button size="lg">Large</Button>
+  </div>
+
+  {/* States */}
+  <div className="flex flex-wrap gap-4 mt-4">
+    <Button>Default</Button>
+    <Button disabled>Disabled</Button>
+    <Button loading>Loading</Button>
+  </div>
+
+  {/* With Icons */}
+  <div className="flex gap-4 mt-4">
+    <Button><PlusIcon /> Add Item</Button>
+    <Button>Next <ArrowRightIcon /></Button>
+    <Button size="icon"><SearchIcon /></Button>
+  </div>
+</section>
+```
+
+#### 3. Form Inputs
+```tsx
+<section id="forms">
+  <h2>Form Inputs</h2>
+
+  {/* Text Inputs */}
+  <div className="space-y-4 max-w-md">
+    <Input label="Default" placeholder="Enter text..." />
+    <Input label="With value" value="Hello world" />
+    <Input label="Disabled" disabled value="Can't edit" />
+    <Input label="With error" error="This field is required" />
+    <Input label="With helper" helper="We'll never share your email" />
+  </div>
+
+  {/* Select */}
+  <Select label="Choose option">
+    <option>Option 1</option>
+    <option>Option 2</option>
+    <option>Option 3</option>
+  </Select>
+
+  {/* Checkbox & Radio */}
+  <div className="space-y-2 mt-4">
+    <Checkbox label="Accept terms" />
+    <Checkbox label="Checked" checked />
+    <Checkbox label="Disabled" disabled />
+  </div>
+
+  {/* Toggle */}
+  <div className="flex gap-4 mt-4">
+    <Toggle label="Off" />
+    <Toggle label="On" checked />
+  </div>
+</section>
+```
+
+#### 4. Cards
+```tsx
+<section id="cards">
+  <h2>Cards</h2>
+
+  <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+    {/* Basic Card */}
+    <Card>
+      <CardHeader>
+        <CardTitle>Card Title</CardTitle>
+        <CardDescription>Card description goes here</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>Card content with some text.</p>
+      </CardContent>
+    </Card>
+
+    {/* Card with Image */}
+    <Card>
+      <img src="/placeholder.jpg" className="w-full h-40 object-cover" />
+      <CardContent>
+        <h3>Image Card</h3>
+        <p>Card with image header</p>
+      </CardContent>
+    </Card>
+
+    {/* Interactive Card */}
+    <Card hover clickable>
+      <CardContent>
+        <h3>Interactive</h3>
+        <p>Hover and click states</p>
+      </CardContent>
+    </Card>
+  </div>
+</section>
+```
+
+#### 5. Feedback Components
+```tsx
+<section id="feedback">
+  <h2>Feedback</h2>
+
+  {/* Alerts */}
+  <div className="space-y-4">
+    <Alert variant="info">This is an info message</Alert>
+    <Alert variant="success">Success! Your changes were saved.</Alert>
+    <Alert variant="warning">Warning: This action cannot be undone.</Alert>
+    <Alert variant="error">Error: Something went wrong.</Alert>
+  </div>
+
+  {/* Badges */}
+  <div className="flex gap-2 mt-6">
+    <Badge>Default</Badge>
+    <Badge variant="success">Success</Badge>
+    <Badge variant="warning">Warning</Badge>
+    <Badge variant="error">Error</Badge>
+  </div>
+
+  {/* Loading States */}
+  <div className="flex gap-4 mt-6">
+    <Spinner size="sm" />
+    <Spinner size="md" />
+    <Spinner size="lg" />
+    <Skeleton className="h-4 w-32" />
+    <Skeleton className="h-10 w-full" />
+  </div>
+</section>
+```
+
+### Phase 4: Generate Component Files
+
+If components don't exist yet, create them based on the user's preferences.
+
+**Example Button component (Tailwind + React):**
+```tsx
+// src/components/ui/Button.tsx
+import { forwardRef } from 'react';
+import { cn } from '@/lib/utils';
+
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'ghost' | 'destructive' | 'link';
+  size?: 'sm' | 'md' | 'lg' | 'icon';
+  loading?: boolean;
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant = 'primary', size = 'md', loading, children, disabled, ...props }, ref) => {
+    return (
+      <button
+        ref={ref}
+        disabled={disabled || loading}
+        className={cn(
+          // Base styles
+          'inline-flex items-center justify-center font-medium transition-colors',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
+          'disabled:pointer-events-none disabled:opacity-50',
+
+          // Variants (customize based on user's vibe)
+          {
+            'bg-primary text-primary-foreground hover:bg-primary/90': variant === 'primary',
+            'bg-secondary text-secondary-foreground hover:bg-secondary/80': variant === 'secondary',
+            'hover:bg-accent hover:text-accent-foreground': variant === 'ghost',
+            'bg-destructive text-destructive-foreground hover:bg-destructive/90': variant === 'destructive',
+            'text-primary underline-offset-4 hover:underline': variant === 'link',
+          },
+
+          // Sizes
+          {
+            'h-8 px-3 text-sm rounded-md': size === 'sm',
+            'h-10 px-4 text-sm rounded-md': size === 'md',
+            'h-12 px-6 text-base rounded-lg': size === 'lg',
+            'h-10 w-10 rounded-md': size === 'icon',
+          },
+
+          className
+        )}
+        {...props}
+      >
+        {loading ? <Spinner className="mr-2" size="sm" /> : null}
+        {children}
+      </button>
+    );
+  }
+);
+```
+
+### Phase 5: Add CSS Variables
+
+Create design tokens as CSS variables for easy theming:
+
+```css
+/* src/styles/design-tokens.css */
+:root {
+  /* Colors - Light Mode */
+  --color-primary: 59 130 246;      /* blue-500 */
+  --color-secondary: 100 116 139;   /* slate-500 */
+  --color-accent: 168 85 247;       /* purple-500 */
+  --color-background: 255 255 255;  /* white */
+  --color-foreground: 15 23 42;     /* slate-900 */
+  --color-muted: 241 245 249;       /* slate-100 */
+  --color-border: 226 232 240;      /* slate-200 */
+
+  /* Feedback Colors */
+  --color-success: 34 197 94;       /* green-500 */
+  --color-warning: 234 179 8;       /* yellow-500 */
+  --color-error: 239 68 68;         /* red-500 */
+  --color-info: 59 130 246;         /* blue-500 */
+
+  /* Spacing */
+  --spacing-unit: 4px;
+
+  /* Border Radius */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px rgb(0 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px rgb(0 0 0 / 0.1);
+}
+
+/* Dark Mode */
+.dark {
+  --color-background: 15 23 42;     /* slate-900 */
+  --color-foreground: 248 250 252;  /* slate-50 */
+  --color-muted: 30 41 59;          /* slate-800 */
+  --color-border: 51 65 85;         /* slate-700 */
+}
+```
+
+### Phase 6: Update CLAUDE.md
+
+Add the styleguide reference to the project's CLAUDE.md:
+
+```markdown
+## Design System
+
+Reference `/styleguide` for all UI components and design tokens.
+
+### Quick Reference
+- Primary: [color]
+- Border Radius: [preference]
+- Mode: [light/dark/both]
+
+### Components
+Use components from `@/components/ui`:
+- Button, Input, Select, Checkbox, Toggle
+- Card, Alert, Badge, Modal
+- All variants shown in /styleguide
+```
+
+### Vibe-Specific Templates
+
+**Neon Glass:**
+```tsx
+// Dark background with glassmorphism
+<div className="bg-black min-h-screen">
+  <Card className="
+    bg-white/5 backdrop-blur-xl
+    border border-white/10
+    shadow-[0_0_30px_rgba(0,255,255,0.1)]
+  ">
+    <h2 className="text-transparent bg-clip-text bg-gradient-to-r from-cyan-400 to-purple-500">
+      Neon Glass
+    </h2>
+  </Card>
+</div>
+```
+
+**Clean & Minimal:**
+```tsx
+// Lots of whitespace, subtle shadows
+<div className="bg-gray-50 min-h-screen p-12">
+  <Card className="bg-white shadow-sm border border-gray-100 rounded-lg">
+    <h2 className="text-gray-900 font-light tracking-tight">
+      Clean & Minimal
+    </h2>
+  </Card>
+</div>
+```
+
+**Bold & Vibrant:**
+```tsx
+// Strong colors, high contrast
+<div className="bg-gradient-to-br from-orange-500 to-pink-600 min-h-screen">
+  <Card className="bg-white rounded-2xl shadow-2xl">
+    <h2 className="text-3xl font-black text-gray-900">
+      Bold & Vibrant
+    </h2>
+  </Card>
+</div>
+```
+
+## Notes
+
+- Always create components that match the user's chosen vibe
+- Include all states (hover, active, focus, disabled, loading)
+- Make the styleguide itself match the design system
+- Add code snippets so developers can copy usage examples
+- Test in both light and dark mode if applicable