@mrtrinhvn/ag-kit 1.0.4 → 1.0.6

package/.agent/workflows/ui-ux-pro-max.md

@@ -0,0 +1,296 @@
+---
+description: Plan and implement UI
+---
+
+---
+description: AI-powered design intelligence with 50+ styles, 95+ color palettes, and automated design system generation
+---
+
+# ui-ux-pro-max
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Workflow
+
+When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
+- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
+- **Industry**: healthcare, fintech, gaming, education, etc.
+- **Stack**: React, Vue, Next.js, or default to `html-tailwind`
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for hierarchical retrieval across sessions, add `--persist`:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+
+### Step 4: Stack Guidelines (Default: html-tailwind)
+
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
+```
+
+Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
+, `jetpack-compose`
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) |
+| `react` | State, hooks, performance, patterns |
+| `nextjs` | SSR, routing, images, API routes |
+| `vue` | Composition API, Pinia, Vue Router |
+| `svelte` | Runes, stores, SvelteKit |
+| `swiftui` | Views, State, Navigation, Animation |
+| `react-native` | Components, Navigation, Lists |
+| `flutter` | Widgets, State, Layout, Theming |
+| `shadcn` | shadcn/ui components, theming, forms, patterns |
+| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition |
+
+---
+
+## Example Workflow
+
+**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"
+
+### Step 1: Analyze Requirements
+- Product type: Beauty/Spa service
+- Style keywords: elegant, professional, soft
+- Industry: Beauty/Wellness
+- Stack: html-tailwind (default)
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get UX guidelines for animation and accessibility
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux
+
+# Get alternative typography options if needed
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app"
+2. **Search multiple times** - Different keywords reveal different insights
+3. **Combine domains** - Style + Typography + Color = Complete design system
+4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues
+5. **Use stack flag** - Get implementation-specific best practices
+6. **Iterate** - If first search doesn't match, try different keywords
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+
+### Icons & Visual Elements
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |
+| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
+| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
+
+### Interaction & Cursor
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements |
+| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive |
+| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) |
+| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text |
+| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter |
+| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` |
+| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements |
+| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] Brand logos are correct (verified from Simple Icons)
+- [ ] Hover states don't cause layout shift
+- [ ] Use theme colors directly (bg-primary) not var() wrapper
+
+### Interaction
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback
+- [ ] Transitions are smooth (150-300ms)
+- [ ] Focus states visible for keyboard navigation
+
+### Light/Dark Mode
+- [ ] Light mode text has sufficient contrast (4.5:1 minimum)
+- [ ] Glass/transparent elements visible in light mode
+- [ ] Borders visible in both modes
+- [ ] Test both modes before delivery
+
+### Layout
+- [ ] Floating elements have proper spacing from edges
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] No horizontal scroll on mobile
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Color is not the only indicator
+- [ ] `prefers-reduced-motion` respected

package/bin/cli.js

@@ -24,6 +24,41 @@ function copyRecursiveSync(src, dest) {
   }
 }
 
+
+function migrateLegacyMemories() {
+  const legacyDir = path.join(process.cwd(), 'data', 'memories');
+  if (!fs.existsSync(legacyDir)) return;
+  
+  let migratedCount = 0;
+  try {
+    const files = fs.readdirSync(legacyDir).filter(f => f.endsWith('.jsonl'));
+    for (const file of files) {
+      const filePath = path.join(legacyDir, file);
+      const lines = fs.readFileSync(filePath, 'utf-8').split('\n');
+      let changed = false;
+      const newLines = lines.map(line => {
+        if (!line.trim()) return line;
+        try {
+          const item = JSON.parse(line);
+          if (item.content && !item.content.includes('[Node:')) {
+            item.content = `[Node:Legacy_Knowledge] => ${item.content}`;
+            changed = true;
+            return JSON.stringify(item);
+          }
+        } catch(e) {}
+        return line;
+      });
+      if (changed) {
+        fs.writeFileSync(filePath, newLines.join('\n'));
+        migratedCount++;
+      }
+    }
+    if (migratedCount > 0) {
+      console.log(`\x1b[35m🧠 TỰ ĐỘNG: Đã băm ${migratedCount} tệp Ký ức cũ thành Tiền-Đồ-Thị (Pseudo-Graph) để tương thích chuẩn mới!\x1b[0m`);
+    }
+  } catch(e) { /* ignore errors during migration */ }
+}
+
 const pkg = require('../package.json');
 program
   .name('ag-kit')
@@ -66,6 +101,7 @@ program.command('update')
         }
     });
 
+    migrateLegacyMemories();
     console.log('\x1b[32m✅ Cập nhật thành công 100% Cấu trúc kỹ năng siêu cấp!\x1b[0m');
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {

package/template/.agent/skills/memory-architecture/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: memory-architecture
+description: >
+  Hệ thống Bộ nhớ Đồ thị Đa Tầng (Multi-layered Graph Memory) cho Agent.
+  Hợp nhất giữa Progressive Disclosure (L1, L2, L3) và Temporal Knowledge Graph (Node-Edge).
+---
+
+# Multi-layered Graph Memory Architecture
+
+> 🔴 **CRITICAL RULE**: Trí nhớ của Agent không còn là Text phẳng. Nó là một **Đồ thị Tri thức Đa tầng (Graph)** cho phép "Zoom-out" nhìn toàn cảnh và "Zoom-in" đọc chi tiết lõi.
+
+---
+
+## 1. Nguyên tắc cốt lõi: 3 Tầng Ký ức (L1/L2/L3)
+
+```text
+L1 (Zoom Out) → session_summary & Core_Nodes  — "Toàn cảnh dự án, các khái niệm lõi"
+L2 (Mid)      → category-indexed & Edges      — "Mạng lưới quan hệ, mạch sự kiện"
+L3 (Zoom In)  → detail_record & Solutions     — "Chi tiết lỗi, code snippet gốc"
+```
+
+---
+
+## 2. Hình thái Dữ liệu cấp thấp (Node-Edge Graph)
+
+Mọi dữ liệu trong tầng L1/L2/L3 đều được lưu dưới dạng Đồ thị (Graph):
+
+### A. NODES (Hạt nhân Kiến thức)
+Các khái niệm định danh tĩnh. Vd: `[Node:DB_PORT] => 5432 (Energy: 100)`
+
+### B. EDGES / EPISODES (Mạch Câu chuyện)
+Luồng sự kiện liên kết. Vd: `[Node:USER] --(muốn mở port)--> [Node:DB_PORT]`
+
+### Progressive Disclosure (Tiết kiệm Token):
+Thay vì load toàn bộ Memory, hệ thống truy vấn tự động theo dạng Phóng to/Thu nhỏ:
+1. **Search (Zoom Out):** Chỉ lấy mỏ neo 1-2 Node lõi + Quan hệ (L1/L2) (Tốn rất ít token).
+2. **Details (Zoom In):** Nếu AI cần phân tích sâu 1 đoạn code phức tạp, gọi L3 (Token cao hơn nhưng cực kỳ chính xác).
+
+---
+
+## 3. Vòng đời Trí nhớ (Biocybernetic Lifecycle)
+
+1. **Temporal Decay (Phai mờ):** Mỗi Node và Edge có `Energy`. Bị hao hụt tự động mỗi 24h. L1 siêu bền, L3 hao nhanh.
+2. **Reinforcement (Củng cố):** Mỗi lần "bò" (traversal) qua Node, Energy phục hồi.
+3. **Consolidation (Ngủ):** Cứ đêm đến, AI gộp các mạch nhớ L3/L2 rườm rà thành 1 Node L1 khái quát siêu bền.
+4. **Forgetting (Quên lãng):** Node có `Energy < 0` HOẶC mồ côi (không ai gọi tới) sẽ BỊ XOÁ (Quét rác sinh học).
+
+---
+
+## 4. Bảng Phân loại Khối Lượng Ký ức
+
+| Target / Kiểu Node | Tầng | Giải thích | Energy Khởi tạo | Mức độ Tự Phân Hủy (Decay) |
+|---|---|---|---|---|
+| `session_summary` | L1 | Toàn cảnh phiên làm việc | 100 | Lâu dài (Gần như không) |
+| `Core_Fact` | L1 | Cấu hình, IP, Convention cốt lõi | 100 | Gần như không |
+| `User_Pref` | L2 | Thói quen user | 80 | Cực chậm |
+| `project_context` | L2 | Ngữ cảnh dự án hiện tại | 80 | Trung hạn (Cập nhật đổi version) |
+| `Episode_Edge` | L2 | "Hôm qua đã làm gì" | 30 | Nhanh (Rất mau phai mờ) |
+| `error_solution` | L3 | Bug log + Code fix cụ thể | 50 | Trung bình (Công nghệ đổi -> Xóa) |
+
+---
+
+## 5. Workflow Tương tác Trí Nhớ (Mô phỏng GraphRAG)
+
+### KHI BẮT ĐẦU task mới (Retrieve):
+```text
+1. Bắn 1 tia Vector Search thả mỏ neo vào Đồ thị (Tìm L1/L2).
+2. Khôi phục lại Mạch Câu Chuyện bằng cách "Bò" dọc theo Edges lân cận (BFS).
+3. Nếu cần code chính xác của 1 Bug, gọi lệnh lấy Detail (L3).
+```
+
+### KHI KẾT THÚC task (Commit):
+❌ **Sai:** Lưu text rác `memory_save("Fix xong bug X")` vào trong hư không.
+✅ **Đúng:** 
+```text
+1. Khởi tạo Node mới: Node[Fix_CORS] = "Thiếu accept headers"
+2. Nối Mạch: Node[Env_Prod] --(gặp lỗi)=> Node[Fix_CORS]
+3. (Tùy chọn) Gắn thêm Detail record vào L3 nếu fix cực phức tạp cần giữ code snippet.
+```
+
+---
+
+## 6. Anti-Patterns Kịch Độc
+
+```text
+❌ Gọi L3 load toàn bộ chi tiết khi không cần thiết (Tràn token).
+❌ Cố gắng chèn 200 dòng code vào Tên của Node (Node chỉ giữ Context lõi, Code đẩy xuống L3).
+❌ Tạo Node rác không gán Edge quan hệ. (Garbage Collector sẽ chém thẳng tay).
+```
+
+---
+
+## 7. Giao thức Tự động Dịch chuyển Ký ức (Self-Migration Protocol)
+
+> **Dành cho các AI Agent hoạt động trong dự án cũ (Legacy Projects) vừa được cập nhật `ag-kit` thông qua `npx`.**
+
+Khi bạn (AI) nhận thức được mình đang ở trong một dự án đã có sẵn dữ liệu ký ức cũ (chứa trong các file `.jsonl` hoặc `memory.db` phẳng), bạn **CÓ TRÁCH NHIỆM TỰ ĐỘNG** thực hiện quá trình "Memory Migration" (Dịch chuyển Ký ức) mà không cần User yêu cầu, theo các bước sau:
+
+1. **Phát hiện:** Dùng lệnh đọc file hoặc MCP để quét nội dung các ký ức cũ trong thư mục `data/memories/` (nếu có).
+2. **Băm nhỏ (Chunking & Entity Extraction):** Phân tích các đoạn log cũ xem chúng nói về chủ đề gì (vd: Lịch sử fix bug, Convention code cũ, Sở thích User).
+3. **Tái cấu trúc (Graph Construction):**
+   - Từ các đoạn text đó, rút trích ra các `Nodes` cốt lõi mang tính sự thật (Core Facts).
+   - Thiết lập các `Edges` (Mạch kết nối) mô tả luồng logic giữa các Nodes đó.
+4. **Lưu trữ (Commit):** Lưu bộ Graph vừa tạo vào cơ sở dữ liệu mới (thông qua `GraphMemoryTool` nếu dự án đã hỗ trợ, hoặc lưu ngược lại bằng `memory_save` dưới cấu trúc **Pseudo-Graph** cực đoan: `[Node:A] --[rel]--> [Node:B]` nếu nền tảng chưa được nâng cấp DB SQLite).
+
+Bằng giao thức này, kiến thức của dự án sẽ KHÔNG BAO GIỜ bị đứt gãy sau khi cập nhật kiến trúc. Mọi ký ức quá khứ sẽ tự động "tiến hóa" thành dạng Đồ thị tương lai!
+