thachvd-kit 1.0.29 → 1.0.30

package/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md

@@ -1,150 +0,0 @@
-# 8. Advanced Patterns
-
-> **Impact:** VARIABLE
-> **Focus:** Advanced patterns for specific cases that require careful implementation.
-
----
-
-## Overview
-
-This section contains **3 rules** focused on advanced patterns.
-
----
-
-## Rule 8.1: Initialize App Once, Not Per Mount
-
-**Impact:** LOW-MEDIUM  
-**Tags:** initialization, useEffect, app-startup, side-effects  
-
-## Initialize App Once, Not Per Mount
-
-Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
-
-**Incorrect (runs twice in dev, re-runs on remount):**
-
-```tsx
-function Comp() {
-  useEffect(() => {
-    loadFromStorage()
-    checkAuthToken()
-  }, [])
-
-  // ...
-}
-```
-
-**Correct (once per app load):**
-
-```tsx
-let didInit = false
-
-function Comp() {
-  useEffect(() => {
-    if (didInit) return
-    didInit = true
-    loadFromStorage()
-    checkAuthToken()
-  }, [])
-
-  // ...
-}
-```
-
-Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
-
----
-
-## Rule 8.2: Store Event Handlers in Refs
-
-**Impact:** LOW  
-**Tags:** advanced, hooks, refs, event-handlers, optimization  
-
-## Store Event Handlers in Refs
-
-Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
-
-**Incorrect (re-subscribes on every render):**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
-  useEffect(() => {
-    window.addEventListener(event, handler)
-    return () => window.removeEventListener(event, handler)
-  }, [event, handler])
-}
-```
-
-**Correct (stable subscription):**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
-  const handlerRef = useRef(handler)
-  useEffect(() => {
-    handlerRef.current = handler
-  }, [handler])
-
-  useEffect(() => {
-    const listener = (e) => handlerRef.current(e)
-    window.addEventListener(event, listener)
-    return () => window.removeEventListener(event, listener)
-  }, [event])
-}
-```
-
-**Alternative: use `useEffectEvent` if you're on latest React:**
-
-```tsx
-import { useEffectEvent } from 'react'
-
-function useWindowEvent(event: string, handler: (e) => void) {
-  const onEvent = useEffectEvent(handler)
-
-  useEffect(() => {
-    window.addEventListener(event, onEvent)
-    return () => window.removeEventListener(event, onEvent)
-  }, [event])
-}
-```
-
-`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
-
----
-
-## Rule 8.3: useEffectEvent for Stable Callback Refs
-
-**Impact:** LOW  
-**Tags:** advanced, hooks, useEffectEvent, refs, optimization  
-
-## useEffectEvent for Stable Callback Refs
-
-Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
-
-**Incorrect (effect re-runs on every callback change):**
-
-```tsx
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
-  const [query, setQuery] = useState('')
-
-  useEffect(() => {
-    const timeout = setTimeout(() => onSearch(query), 300)
-    return () => clearTimeout(timeout)
-  }, [query, onSearch])
-}
-```
-
-**Correct (using React's useEffectEvent):**
-
-```tsx
-import { useEffectEvent } from 'react';
-
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
-  const [query, setQuery] = useState('')
-  const onSearchEvent = useEffectEvent(onSearch)
-
-  useEffect(() => {
-    const timeout = setTimeout(() => onSearchEvent(query), 300)
-    return () => clearTimeout(timeout)
-  }, [query])
-}
-```
-

package/.agent/skills/nextjs-react-expert/SKILL.md

@@ -1,286 +0,0 @@
----
-name: react-best-practices
-description: React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
----
-
-# Next.js & React Performance Expert
-
-> **From Vercel Engineering** - 57 optimization rules prioritized by impact
-> **Philosophy:** Eliminate waterfalls first, optimize bundles second, then micro-optimize.
-
----
-
-## 🎯 Selective Reading Rule (MANDATORY)
-
-**Read ONLY sections relevant to your task!** Check the content map below and load what you need.
-
-> 🔴 **For performance reviews: Start with CRITICAL sections (1-2), then move to HIGH/MEDIUM.**
-
----
-
-## 📑 Content Map
-
-| File                                    | Impact             | Rules    | When to Read                                                    |
-| --------------------------------------- | ------------------ | -------- | --------------------------------------------------------------- |
-| `1-async-eliminating-waterfalls.md`     | 🔴 **CRITICAL**    | 5 rules  | Slow page loads, sequential API calls, data fetching waterfalls |
-| `2-bundle-bundle-size-optimization.md`  | 🔴 **CRITICAL**    | 5 rules  | Large bundle size, slow Time to Interactive, First Load issues  |
-| `3-server-server-side-performance.md`   | 🟠 **HIGH**        | 7 rules  | Slow SSR, API route optimization, server-side waterfalls        |
-| `4-client-client-side-data-fetching.md` | 🟡 **MEDIUM-HIGH** | 4 rules  | Client data management, SWR patterns, deduplication             |
-| `5-rerender-re-render-optimization.md`  | 🟡 **MEDIUM**      | 12 rules | Excessive re-renders, React performance, memoization            |
-| `6-rendering-rendering-performance.md`  | 🟡 **MEDIUM**      | 9 rules  | Rendering bottlenecks, virtualization, image optimization       |
-| `7-js-javascript-performance.md`        | ⚪ **LOW-MEDIUM**  | 12 rules | Micro-optimizations, caching, loop performance                  |
-| `8-advanced-advanced-patterns.md`       | 🔵 **VARIABLE**    | 3 rules  | Advanced React patterns, useLatest, init-once                   |
-
-**Total: 57 rules across 8 categories**
-
----
-
-## 🚀 Quick Decision Tree
-
-**What's your performance issue?**
-
-```
-🐌 Slow page loads / Long Time to Interactive
-  → Read Section 1: Eliminating Waterfalls
-  → Read Section 2: Bundle Size Optimization
-
-📦 Large bundle size (> 200KB)
-  → Read Section 2: Bundle Size Optimization
-  → Check: Dynamic imports, barrel imports, tree-shaking
-
-🖥️ Slow Server-Side Rendering
-  → Read Section 3: Server-Side Performance
-  → Check: Parallel data fetching, streaming
-
-🔄 Too many re-renders / UI lag
-  → Read Section 5: Re-render Optimization
-  → Check: React.memo, useMemo, useCallback
-
-🎨 Rendering performance issues
-  → Read Section 6: Rendering Performance
-  → Check: Virtualization, layout thrashing
-
-🌐 Client-side data fetching problems
-  → Read Section 4: Client-Side Data Fetching
-  → Check: SWR deduplication, localStorage
-
-✨ Need advanced patterns
-  → Read Section 8: Advanced Patterns
-```
-
----
-
-## 📊 Impact Priority Guide
-
-**Use this order when doing comprehensive optimization:**
-
-```
-1️⃣ CRITICAL (Biggest Gains - Do First):
-   ├─ Section 1: Eliminating Waterfalls
-   │  └─ Each waterfall adds full network latency (100-500ms+)
-   └─ Section 2: Bundle Size Optimization
-      └─ Affects Time to Interactive and Largest Contentful Paint
-
-2️⃣ HIGH (Significant Impact - Do Second):
-   └─ Section 3: Server-Side Performance
-      └─ Eliminates server-side waterfalls, faster response times
-
-3️⃣ MEDIUM (Moderate Gains - Do Third):
-   ├─ Section 4: Client-Side Data Fetching
-   ├─ Section 5: Re-render Optimization
-   └─ Section 6: Rendering Performance
-
-4️⃣ LOW (Polish - Do Last):
-   ├─ Section 7: JavaScript Performance
-   └─ Section 8: Advanced Patterns
-```
-
----
-
-## 🔗 Related Skills
-
-| Need                    | Skill                             |
-| ----------------------- | --------------------------------- |
-| API design patterns     | `@[skills/api-patterns]`          |
-| Database optimization   | `@[skills/database-design]`       |
-| Testing strategies      | `@[skills/testing-patterns]`      |
-| UI/UX design principles | `@[skills/frontend-design]`       |
-| TypeScript patterns     | `@[skills/typescript-expert]`     |
-| Deployment & DevOps     | `@[skills/deployment-procedures]` |
-
----
-
-## ✅ Performance Review Checklist
-
-Before shipping to production:
-
-**Critical (Must Fix):**
-
-- [ ] No sequential data fetching (waterfalls eliminated)
-- [ ] Bundle size < 200KB for main bundle
-- [ ] No barrel imports in app code
-- [ ] Dynamic imports used for large components
-- [ ] Parallel data fetching where possible
-
-**High Priority:**
-
-- [ ] Server components used where appropriate
-- [ ] API routes optimized (no N+1 queries)
-- [ ] Suspense boundaries for data fetching
-- [ ] Static generation used where possible
-
-**Medium Priority:**
-
-- [ ] Expensive computations memoized
-- [ ] List rendering virtualized (if > 100 items)
-- [ ] Images optimized with next/image
-- [ ] No unnecessary re-renders
-
-**Low Priority (Polish):**
-
-- [ ] Hot path loops optimized
-- [ ] RegExp patterns hoisted
-- [ ] Property access cached in loops
-
----
-
-## ❌ Anti-Patterns (Common Mistakes)
-
-**DON'T:**
-
-- ❌ Use sequential `await` for independent operations
-- ❌ Import entire libraries when you need one function
-- ❌ Use barrel exports (`index.ts` re-exports) in app code
-- ❌ Skip dynamic imports for large components/libraries
-- ❌ Fetch data in useEffect without deduplication
-- ❌ Forget to memoize expensive computations
-- ❌ Use client components when server components work
-
-**DO:**
-
-- ✅ Fetch data in parallel with `Promise.all()`
-- ✅ Use dynamic imports: `const Comp = dynamic(() => import('./Heavy'))`
-- ✅ Import directly: `import { specific } from 'library/specific'`
-- ✅ Use Suspense boundaries for better UX
-- ✅ Leverage React Server Components
-- ✅ Measure performance before optimizing
-- ✅ Use Next.js built-in optimizations (next/image, next/font)
-
----
-
-## 🎯 How to Use This Skill
-
-### For New Features:
-
-1. Check **Section 1 & 2** while building (prevent waterfalls, keep bundle small)
-2. Use server components by default (Section 3)
-3. Apply memoization for expensive operations (Section 5)
-
-### For Performance Reviews:
-
-1. Start with **Section 1** (waterfalls = biggest impact)
-2. Then **Section 2** (bundle size)
-3. Then **Section 3** (server-side)
-4. Finally other sections as needed
-
-### For Debugging Slow Performance:
-
-1. Identify the symptom (slow load, lag, etc.)
-2. Use Quick Decision Tree above
-3. Read relevant section
-4. Apply fixes in priority order
-
----
-
-## 📚 Learning Path
-
-**Beginner (Focus on Critical):**
-→ Section 1: Eliminating Waterfalls
-→ Section 2: Bundle Size Optimization
-
-**Intermediate (Add High Priority):**
-→ Section 3: Server-Side Performance
-→ Section 5: Re-render Optimization
-
-**Advanced (Full Optimization):**
-→ All sections + Section 8: Advanced Patterns
-
----
-
-## 🔍 Validation Script
-
-| Script                                 | Purpose                     | Command                                                      |
-| -------------------------------------- | --------------------------- | ------------------------------------------------------------ |
-| `scripts/react_performance_checker.py` | Automated performance audit | `python scripts/react_performance_checker.py <project_path>` |
-
----
-
-## 📖 Section Details
-
-### Section 1: Eliminating Waterfalls (CRITICAL)
-
-**Impact:** Each waterfall adds 100-500ms+ latency
-**Key Concepts:** Parallel fetching, Promise.all(), Suspense boundaries, preloading
-
-### Section 2: Bundle Size Optimization (CRITICAL)
-
-**Impact:** Directly affects Time to Interactive, Largest Contentful Paint
-**Key Concepts:** Dynamic imports, tree-shaking, barrel import avoidance
-
-### Section 3: Server-Side Performance (HIGH)
-
-**Impact:** Faster server responses, better SEO
-**Key Concepts:** Parallel server fetching, streaming, API route optimization
-
-### Section 4: Client-Side Data Fetching (MEDIUM-HIGH)
-
-**Impact:** Reduces redundant requests, better UX
-**Key Concepts:** SWR deduplication, localStorage caching, event listeners
-
-### Section 5: Re-render Optimization (MEDIUM)
-
-**Impact:** Smoother UI, less wasted computation
-**Key Concepts:** React.memo, useMemo, useCallback, component structure
-
-### Section 6: Rendering Performance (MEDIUM)
-
-**Impact:** Better rendering efficiency
-**Key Concepts:** Virtualization, image optimization, layout thrashing
-
-### Section 7: JavaScript Performance (LOW-MEDIUM)
-
-**Impact:** Incremental improvements in hot paths
-**Key Concepts:** Loop optimization, caching, RegExp hoisting
-
-### Section 8: Advanced Patterns (VARIABLE)
-
-**Impact:** Specific use cases
-**Key Concepts:** useLatest hook, init-once patterns, event handler refs
-
----
-
-## 🎓 Best Practices Summary
-
-**Golden Rules:**
-
-1. **Measure first** - Use React DevTools Profiler, Chrome DevTools
-2. **Biggest impact first** - Waterfalls → Bundle → Server → Micro
-3. **Don't over-optimize** - Focus on real bottlenecks
-4. **Use platform features** - Next.js has optimizations built-in
-5. **Think about users** - Real-world conditions matter
-
-**Performance Mindset:**
-
-- Every `await` in sequence = potential waterfall
-- Every `import` = potential bundle bloat
-- Every re-render = wasted computation (if unnecessary)
-- Server components = less JavaScript to ship
-- Measure, don't guess
-
----
-
-**Source:** Vercel Engineering
-**Date:** January 2026
-**Version:** 1.0.0
-**Total Rules:** 57 across 8 categories

package/.agent/skills/nextjs-react-expert/scripts/convert_rules.py

@@ -1,222 +0,0 @@
-#!/usr/bin/env python3
-"""
-Conversion Script: React Best Practices → .agent Format
-Merges 59 individual rules into 8 grouped section files
-"""
-
-import os
-import re
-from pathlib import Path
-from typing import Dict, List, Tuple
-
-# Section metadata from _sections.md
-SECTIONS = {
-    'async': {
-        'number': 1,
-        'title': 'Eliminating Waterfalls',
-        'impact': 'CRITICAL',
-        'description': 'Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.'
-    },
-    'bundle': {
-        'number': 2,
-        'title': 'Bundle Size Optimization',
-        'impact': 'CRITICAL',
-        'description': 'Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.'
-    },
-    'server': {
-        'number': 3,
-        'title': 'Server-Side Performance',
-        'impact': 'HIGH',
-        'description': 'Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.'
-    },
-    'client': {
-        'number': 4,
-        'title': 'Client-Side Data Fetching',
-        'impact': 'MEDIUM-HIGH',
-        'description': 'Automatic deduplication and efficient data fetching patterns reduce redundant network requests.'
-    },
-    'rerender': {
-        'number': 5,
-        'title': 'Re-render Optimization',
-        'impact': 'MEDIUM',
-        'description': 'Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.'
-    },
-    'rendering': {
-        'number': 6,
-        'title': 'Rendering Performance',
-        'impact': 'MEDIUM',
-        'description': 'Optimizing the rendering process reduces the work the browser needs to do.'
-    },
-    'js': {
-        'number': 7,
-        'title': 'JavaScript Performance',
-        'impact': 'LOW-MEDIUM',
-        'description': 'Micro-optimizations for hot paths can add up to meaningful improvements.'
-    },
-    'advanced': {
-        'number': 8,
-        'title': 'Advanced Patterns',
-        'impact': 'VARIABLE',
-        'description': 'Advanced patterns for specific cases that require careful implementation.'
-    }
-}
-
-
-def parse_frontmatter(content: str) -> Tuple[Dict, str]:
-    """Parse markdown frontmatter and body"""
-    if not content.startswith('---'):
-        return {}, content
-
-    parts = content.split('---', 2)
-    if len(parts) < 3:
-        return {}, content
-
-    # Parse YAML frontmatter manually (simple key: value)
-    frontmatter = {}
-    for line in parts[1].strip().split('\n'):
-        if ':' in line:
-            key, value = line.split(':', 1)
-            frontmatter[key.strip()] = value.strip()
-
-    body = parts[2].strip()
-    return frontmatter, body
-
-
-def parse_rule_file(filepath: Path) -> Dict:
-    """Parse a single rule file"""
-    with open(filepath, 'r', encoding='utf-8') as f:
-        content = f.read()
-
-    frontmatter, body = parse_frontmatter(content)
-
-    # Extract prefix from filename
-    filename = filepath.stem
-    prefix = filename.split('-')[0]
-
-    return {
-        'filename': filepath.name,
-        'prefix': prefix,
-        'title': frontmatter.get('title', filename),
-        'impact': frontmatter.get('impact', ''),
-        'impactDescription': frontmatter.get('impactDescription', ''),
-        'tags': frontmatter.get('tags', ''),
-        'body': body,
-        'frontmatter': frontmatter
-    }
-
-
-def group_rules_by_section(rules_dir: Path) -> Dict[str, List[Dict]]:
-    """Group all rules by their section prefix"""
-    grouped = {prefix: [] for prefix in SECTIONS.keys()}
-
-    for rule_file in sorted(rules_dir.glob('*.md')):
-        # Skip special files
-        if rule_file.name.startswith('_'):
-            continue
-
-        rule = parse_rule_file(rule_file)
-        prefix = rule['prefix']
-
-        if prefix in grouped:
-            grouped[prefix].append(rule)
-        else:
-            print(f"[WARNING] Unknown prefix '{prefix}' in file: {rule_file.name}")
-
-    return grouped
-
-
-def generate_section_file(section_prefix: str, rules: List[Dict], output_dir: Path):
-    """Generate a merged section file"""
-    if not rules:
-        print(f"[WARNING] No rules found for section: {section_prefix}")
-        return
-
-    section_meta = SECTIONS[section_prefix]
-    section_num = section_meta['number']
-    section_title = section_meta['title']
-    impact = section_meta['impact']
-    description = section_meta['description']
-
-    # Sort rules by title
-    rules.sort(key=lambda r: r['title'])
-
-    # Build content
-    content = f"""# {section_num}. {section_title}
-
-> **Impact:** {impact}
-> **Focus:** {description}
-
----
-
-## Overview
-
-This section contains **{len(rules)} rules** focused on {section_title.lower()}.
-
-"""
-
-    # Add each rule
-    for i, rule in enumerate(rules, 1):
-        rule_id = f"{section_num}.{i}"
-        title = rule['title']
-        rule_impact = rule['impact']
-        tags = rule['tags']
-        body = rule['body']
-
-        content += f"""---
-
-## Rule {rule_id}: {title}
-
-"""
-
-        if rule_impact:
-            content += f"**Impact:** {rule_impact}  \n"
-
-        if tags:
-            content += f"**Tags:** {tags}  \n"
-
-        content += f"\n{body}\n\n"
-
-    # Write file
-    output_file = output_dir / f"{section_num}-{section_prefix}-{section_title.lower().replace(' ', '-')}.md"
-    output_file.write_text(content, encoding='utf-8')
-    print(f"[OK] Generated: {output_file.name} ({len(rules)} rules)")
-
-
-def main():
-    """Main conversion function"""
-    # Paths
-    base_dir = Path(__file__).parent.parent.parent.parent.parent
-    rules_dir = base_dir / "others/agent-skills/skills/react-best-practices/rules"
-    output_dir = base_dir / ".agent/skills/react-best-practices"
-
-    print(f"[*] Reading rules from: {rules_dir}")
-    print(f"[*] Output to: {output_dir}")
-    print()
-
-    # Check if rules directory exists
-    if not rules_dir.exists():
-        print(f"[ERROR] Rules directory not found: {rules_dir}")
-        return
-
-    # Group rules
-    print("[*] Grouping rules by section...")
-    grouped_rules = group_rules_by_section(rules_dir)
-
-    # Stats
-    total_rules = sum(len(rules) for rules in grouped_rules.values())
-    print(f"[*] Found {total_rules} total rules")
-    print()
-
-    # Generate section files
-    print("[*] Generating section files...")
-    for section_prefix in SECTIONS.keys():
-        rules = grouped_rules[section_prefix]
-        generate_section_file(section_prefix, rules, output_dir)
-
-    print()
-    print("[SUCCESS] Conversion complete!")
-    print(f"[*] Generated 8 section files from {total_rules} rules")
-
-
-if __name__ == '__main__':
-    main()