@uocnv1998/agent-kit 1.0.0

package/templates/.agent/dev/frontend/skills/nextjs-react-expert/scripts/react_performance_checker.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+React Performance Checker
+Automated performance audit for React/Next.js projects
+Based on Vercel Engineering best practices
+"""
+
+import os
+import re
+import json
+from pathlib import Path
+from typing import List, Dict, Tuple
+
+class PerformanceChecker:
+    def __init__(self, project_path: str):
+        self.project_path = Path(project_path)
+        self.issues = []
+        self.warnings = []
+        self.passed = []
+
+    def check_waterfalls(self):
+        """Check for sequential await patterns (Section 1)"""
+        print("\n[*] Checking for waterfalls (sequential awaits)...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: multiple awaits in sequence without Promise.all
+                sequential_awaits = re.findall(r'await\s+\w+.*?\n\s*await\s+\w+', content)
+
+                if sequential_awaits:
+                    self.issues.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'CRITICAL',
+                        'issue': 'Sequential awaits detected (waterfall)',
+                        'fix': 'Use Promise.all() for parallel fetching',
+                        'section': '1-async-eliminating-waterfalls.md'
+                    })
+            except Exception as e:
+                continue
+
+    def check_barrel_imports(self):
+        """Check for barrel imports (Section 2)"""
+        print("[*] Checking for barrel imports...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: import from index files or barrel exports
+                barrel_imports = re.findall(r"import.*from\s+['\"](@/.*?)/index['\"]", content)
+                barrel_imports += re.findall(r"import.*from\s+['\"]\.\.?/.*?['\"](?!.*?\.tsx?)", content)
+
+                if barrel_imports:
+                    self.warnings.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'CRITICAL',
+                        'issue': 'Potential barrel imports detected',
+                        'fix': 'Import directly from specific files',
+                        'section': '2-bundle-bundle-size-optimization.md'
+                    })
+            except Exception as e:
+                continue
+
+    def check_dynamic_imports(self):
+        """Check if large components use dynamic imports (Section 2)"""
+        print("[*] Checking for missing dynamic imports...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check file size - if > 10KB, should probably use dynamic import
+                if len(content) > 10000:
+                    # Check if it's imported statically somewhere
+                    filename = filepath.stem
+
+                    # Search for static imports of this component
+                    for check_file in self.project_path.rglob('*.{ts,tsx}'):
+                        if check_file == filepath or 'node_modules' in str(check_file):
+                            continue
+
+                        check_content = check_file.read_text(encoding='utf-8')
+                        if f"import {filename}" in check_content or f"import {{ {filename}" in check_content:
+                            if 'dynamic(' not in check_content:
+                                self.warnings.append({
+                                    'file': str(check_file.relative_to(self.project_path)),
+                                    'type': 'CRITICAL',
+                                    'issue': f'Large component {filename} imported statically',
+                                    'fix': 'Use dynamic() for code splitting',
+                                    'section': '2-bundle-bundle-size-optimization.md'
+                                })
+                                break
+            except Exception as e:
+                continue
+
+    def check_useEffect_fetching(self):
+        """Check for data fetching in useEffect (Section 4)"""
+        print("[*] Checking for useEffect data fetching...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: fetch or axios in useEffect
+                if 'useEffect' in content:
+                    if re.search(r'useEffect.*?fetch\(', content, re.DOTALL):
+                        self.warnings.append({
+                            'file': str(filepath.relative_to(self.project_path)),
+                            'type': 'MEDIUM-HIGH',
+                            'issue': 'Data fetching in useEffect',
+                            'fix': 'Consider using SWR or React Query for deduplication',
+                            'section': '4-client-client-side-data-fetching.md'
+                        })
+            except Exception as e:
+                continue
+
+    def check_missing_memoization(self):
+        """Check for missing React.memo, useMemo, useCallback (Section 5)"""
+        print("[*] Checking for missing memoization...")
+
+        for filepath in self.project_path.rglob('*.{tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check for component definitions without memo
+                components = re.findall(r'(?:export\s+)?(?:const|function)\s+([A-Z]\w+)', content)
+
+                if components and 'React.memo' not in content and 'memo(' not in content:
+                    # Check if component receives props
+                    if 'props:' in content or 'Props>' in content:
+                        self.warnings.append({
+                            'file': str(filepath.relative_to(self.project_path)),
+                            'type': 'MEDIUM',
+                            'issue': 'Component with props not memoized',
+                            'fix': 'Consider using React.memo if props are stable',
+                            'section': '5-rerender-re-render-optimization.md'
+                        })
+            except Exception as e:
+                continue
+
+    def check_image_optimization(self):
+        """Check for unoptimized images (Section 6)"""
+        print("[*] Checking for image optimization...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check for <img> tags instead of next/image
+                if '<img' in content and 'next/image' not in content:
+                    self.warnings.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'MEDIUM',
+                        'issue': 'Using <img> instead of next/image',
+                        'fix': 'Use next/image for automatic optimization',
+                        'section': '6-rendering-rendering-performance.md'
+                    })
+            except Exception as e:
+                continue
+
+    def generate_report(self):
+        """Generate final report"""
+        print("\n" + "="*60)
+        print("REACT PERFORMANCE AUDIT REPORT")
+        print("="*60)
+
+        print(f"\n[CRITICAL ISSUES] ({len([i for i in self.issues if i['type'] == 'CRITICAL'])})")
+        for issue in self.issues:
+            if issue['type'] == 'CRITICAL':
+                print(f"  - {issue['file']}")
+                print(f"    Issue: {issue['issue']}")
+                print(f"    Fix: {issue['fix']}")
+                print(f"    Reference: {issue['section']}\n")
+
+        print(f"\n[WARNINGS] ({len(self.warnings)})")
+        for warning in self.warnings[:10]:  # Show first 10
+            print(f"  - {warning['file']}")
+            print(f"    Issue: {warning['issue']}")
+            print(f"    Fix: {warning['fix']}")
+            print(f"    Reference: {warning['section']}\n")
+
+        if len(self.warnings) > 10:
+            print(f"  ... and {len(self.warnings) - 10} more warnings")
+
+        print("\n" + "="*60)
+        print(f"SUMMARY:")
+        print(f"  Critical Issues: {len([i for i in self.issues if i['type'] == 'CRITICAL'])}")
+        print(f"  Warnings: {len(self.warnings)}")
+        print("="*60)
+
+        if len(self.issues) == 0 and len(self.warnings) == 0:
+            print("\n[SUCCESS] No major performance issues detected!")
+        else:
+            print("\n[ACTION REQUIRED] Review and fix issues above")
+            print("Priority: CRITICAL > HIGH > MEDIUM > LOW")
+
+    def run(self):
+        """Run all checks"""
+        print("="*60)
+        print("React Performance Checker (Vercel Engineering)")
+        print("="*60)
+        print(f"Scanning: {self.project_path}")
+
+        self.check_waterfalls()
+        self.check_barrel_imports()
+        self.check_dynamic_imports()
+        self.check_useEffect_fetching()
+        self.check_missing_memoization()
+        self.check_image_optimization()
+
+        self.generate_report()
+
+
+def main():
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: python react_performance_checker.py <project_path>")
+        sys.exit(1)
+
+    project_path = sys.argv[1]
+
+    if not os.path.exists(project_path):
+        print(f"[ERROR] Path not found: {project_path}")
+        sys.exit(1)
+
+    checker = PerformanceChecker(project_path)
+    checker.run()
+
+
+if __name__ == '__main__':
+    main()

package/templates/.agent/dev/frontend/skills/tailwind-patterns/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: tailwind-patterns
+description: Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Tailwind CSS Patterns (v4 - 2025)
+
+> Modern utility-first CSS with CSS-native configuration.
+
+---
+
+## 1. Tailwind v4 Architecture
+
+### What Changed from v3
+
+| v3 (Legacy) | v4 (Current) |
+|-------------|--------------|
+| `tailwind.config.js` | CSS-based `@theme` directive |
+| PostCSS plugin | Oxide engine (10x faster) |
+| JIT mode | Native, always-on |
+| Plugin system | CSS-native features |
+| `@apply` directive | Still works, discouraged |
+
+### v4 Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **CSS-first** | Configuration in CSS, not JavaScript |
+| **Oxide Engine** | Rust-based compiler, much faster |
+| **Native Nesting** | CSS nesting without PostCSS |
+| **CSS Variables** | All tokens exposed as `--*` vars |
+
+---
+
+## 2. CSS-Based Configuration
+
+### Theme Definition
+
+```
+@theme {
+  /* Colors - use semantic names */
+  --color-primary: oklch(0.7 0.15 250);
+  --color-surface: oklch(0.98 0 0);
+  --color-surface-dark: oklch(0.15 0 0);
+  
+  /* Spacing scale */
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 2rem;
+  
+  /* Typography */
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+}
+```
+
+### When to Extend vs Override
+
+| Action | Use When |
+|--------|----------|
+| **Extend** | Adding new values alongside defaults |
+| **Override** | Replacing default scale entirely |
+| **Semantic tokens** | Project-specific naming (primary, surface) |
+
+---
+
+## 3. Container Queries (v4 Native)
+
+### Breakpoint vs Container
+
+| Type | Responds To |
+|------|-------------|
+| **Breakpoint** (`md:`) | Viewport width |
+| **Container** (`@container`) | Parent element width |
+
+### Container Query Usage
+
+| Pattern | Classes |
+|---------|---------|
+| Define container | `@container` on parent |
+| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |
+| Named containers | `@container/card` for specificity |
+
+### When to Use
+
+| Scenario | Use |
+|----------|-----|
+| Page-level layouts | Viewport breakpoints |
+| Component-level responsive | Container queries |
+| Reusable components | Container queries (context-independent) |
+
+---
+
+## 4. Responsive Design
+
+### Breakpoint System
+
+| Prefix | Min Width | Target |
+|--------|-----------|--------|
+| (none) | 0px | Mobile-first base |
+| `sm:` | 640px | Large phone / small tablet |
+| `md:` | 768px | Tablet |
+| `lg:` | 1024px | Laptop |
+| `xl:` | 1280px | Desktop |
+| `2xl:` | 1536px | Large desktop |
+
+### Mobile-First Principle
+
+1. Write mobile styles first (no prefix)
+2. Add larger screen overrides with prefixes
+3. Example: `w-full md:w-1/2 lg:w-1/3`
+
+---
+
+## 5. Dark Mode
+
+### Configuration Strategies
+
+| Method | Behavior | Use When |
+|--------|----------|----------|
+| `class` | `.dark` class toggles | Manual theme switcher |
+| `media` | Follows system preference | No user control |
+| `selector` | Custom selector (v4) | Complex theming |
+
+### Dark Mode Pattern
+
+| Element | Light | Dark |
+|---------|-------|------|
+| Background | `bg-white` | `dark:bg-zinc-900` |
+| Text | `text-zinc-900` | `dark:text-zinc-100` |
+| Borders | `border-zinc-200` | `dark:border-zinc-700` |
+
+---
+
+## 6. Modern Layout Patterns
+
+### Flexbox Patterns
+
+| Pattern | Classes |
+|---------|---------|
+| Center (both axes) | `flex items-center justify-center` |
+| Vertical stack | `flex flex-col gap-4` |
+| Horizontal row | `flex gap-4` |
+| Space between | `flex justify-between items-center` |
+| Wrap grid | `flex flex-wrap gap-4` |
+
+### Grid Patterns
+
+| Pattern | Classes |
+|---------|---------|
+| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
+| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |
+| Sidebar layout | `grid grid-cols-[auto_1fr]` |
+
+> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.
+
+---
+
+## 7. Modern Color System
+
+### OKLCH vs RGB/HSL
+
+| Format | Advantage |
+|--------|-----------|
+| **OKLCH** | Perceptually uniform, better for design |
+| **HSL** | Intuitive hue/saturation |
+| **RGB** | Legacy compatibility |
+
+### Color Token Architecture
+
+| Layer | Example | Purpose |
+|-------|---------|---------|
+| **Primitive** | `--blue-500` | Raw color values |
+| **Semantic** | `--color-primary` | Purpose-based naming |
+| **Component** | `--button-bg` | Component-specific |
+
+---
+
+## 8. Typography System
+
+### Font Stack Pattern
+
+| Type | Recommended |
+|------|-------------|
+| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |
+| Mono | `'JetBrains Mono', 'Fira Code', monospace` |
+| Display | `'Outfit', 'Poppins', sans-serif` |
+
+### Type Scale
+
+| Class | Size | Use |
+|-------|------|-----|
+| `text-xs` | 0.75rem | Labels, captions |
+| `text-sm` | 0.875rem | Secondary text |
+| `text-base` | 1rem | Body text |
+| `text-lg` | 1.125rem | Lead text |
+| `text-xl`+ | 1.25rem+ | Headings |
+
+---
+
+## 9. Animation & Transitions
+
+### Built-in Animations
+
+| Class | Effect |
+|-------|--------|
+| `animate-spin` | Continuous rotation |
+| `animate-ping` | Attention pulse |
+| `animate-pulse` | Subtle opacity pulse |
+| `animate-bounce` | Bouncing effect |
+
+### Transition Patterns
+
+| Pattern | Classes |
+|---------|---------|
+| All properties | `transition-all duration-200` |
+| Specific | `transition-colors duration-150` |
+| With easing | `ease-out` or `ease-in-out` |
+| Hover effect | `hover:scale-105 transition-transform` |
+
+---
+
+## 10. Component Extraction
+
+### When to Extract
+
+| Signal | Action |
+|--------|--------|
+| Same class combo 3+ times | Extract component |
+| Complex state variants | Extract component |
+| Design system element | Extract + document |
+
+### Extraction Methods
+
+| Method | Use When |
+|--------|----------|
+| **React/Vue component** | Dynamic, JS needed |
+| **@apply in CSS** | Static, no JS needed |
+| **Design tokens** | Reusable values |
+
+---
+
+## 11. Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Arbitrary values everywhere | Use design system scale |
+| `!important` | Fix specificity properly |
+| Inline `style=` | Use utilities |
+| Duplicate long class lists | Extract component |
+| Mix v3 config with v4 | Migrate fully to CSS-first |
+| Use `@apply` heavily | Prefer components |
+
+---
+
+## 12. Performance Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| **Purge unused** | Automatic in v4 |
+| **Avoid dynamism** | No template string classes |
+| **Use Oxide** | Default in v4, 10x faster |
+| **Cache builds** | CI/CD caching |
+
+---
+
+> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.

package/templates/.agent/dev/frontend/skills/web-design-guidelines/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.
+
+---
+
+## Related Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| **[frontend-design](../frontend-design/SKILL.md)** | Before coding - Learn design principles (color, typography, UX psychology) |
+| **web-design-guidelines** (this) | After coding - Audit for accessibility, performance, and best practices |
+
+## Design Workflow
+
+```
+1. DESIGN   → Read frontend-design principles
+2. CODE     → Implement the design
+3. AUDIT    → Run web-design-guidelines review ← YOU ARE HERE
+4. FIX      → Address findings from audit
+```

package/templates/.agent/po_ba/ARCHITECTURE.md

@@ -0,0 +1,28 @@
+# PO / BA Architecture
+
+---
+
+## 🤖 Agents
+
+Specialist AI personas for product and requirements management.
+
+| Agent | Focus |
+| :--- | :--- |
+| `product-owner` | Requirements, Roadmap, Vision |
+| `product-manager` | Execution, Problem solving |
+| `documentation-writer` | PRD, Technical documentation |
+
+---
+
+## 🧩 Skills
+
+Modular knowledge domains for product management.
+
+- **Product**: `SKILL.md` (Product goals and metrics).
+- **Workflow**: `po_ba-workflow.md`.
+
+---
+
+## 🛠️ Rules
+
+- `GEMINI.md`: Guidelines for product requirements and documentation standards.