@mrtrinhvn/ag-kit 1.0.5 → 1.0.7

package/.agent/skills/performance-profiling/scripts/lighthouse_audit.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+Skill: performance-profiling
+Script: lighthouse_audit.py
+Purpose: Run Lighthouse performance audit on a URL
+Usage: python lighthouse_audit.py https://example.com
+Output: JSON with performance scores
+Note: Requires lighthouse CLI (npm install -g lighthouse)
+"""
+import subprocess
+import json
+import sys
+import os
+import tempfile
+
+def run_lighthouse(url: str) -> dict:
+    """Run Lighthouse audit on URL."""
+    try:
+        with tempfile.NamedTemporaryFile(suffix='.json', delete=False) as f:
+            output_path = f.name
+        
+        result = subprocess.run(
+            [
+                "lighthouse",
+                url,
+                "--output=json",
+                f"--output-path={output_path}",
+                "--chrome-flags=--headless",
+                "--only-categories=performance,accessibility,best-practices,seo"
+            ],
+            capture_output=True,
+            text=True,
+            timeout=120
+        )
+        
+        if os.path.exists(output_path):
+            with open(output_path, 'r') as f:
+                report = json.load(f)
+            os.unlink(output_path)
+            
+            categories = report.get("categories", {})
+            return {
+                "url": url,
+                "scores": {
+                    "performance": int(categories.get("performance", {}).get("score", 0) * 100),
+                    "accessibility": int(categories.get("accessibility", {}).get("score", 0) * 100),
+                    "best_practices": int(categories.get("best-practices", {}).get("score", 0) * 100),
+                    "seo": int(categories.get("seo", {}).get("score", 0) * 100)
+                },
+                "summary": get_summary(categories)
+            }
+        else:
+            return {"error": "Lighthouse failed to generate report", "stderr": result.stderr[:500]}
+            
+    except subprocess.TimeoutExpired:
+        return {"error": "Lighthouse audit timed out"}
+    except FileNotFoundError:
+        return {"error": "Lighthouse CLI not found. Install with: npm install -g lighthouse"}
+
+def get_summary(categories: dict) -> str:
+    """Generate summary based on scores."""
+    perf = categories.get("performance", {}).get("score", 0) * 100
+    if perf >= 90:
+        return "[OK] Excellent performance"
+    elif perf >= 50:
+        return "[!] Needs improvement"
+    else:
+        return "[X] Poor performance"
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({"error": "Usage: python lighthouse_audit.py <url>"}))
+        sys.exit(1)
+    
+    result = run_lighthouse(sys.argv[1])
+    print(json.dumps(result, indent=2))

package/.agent/skills/plan-writing/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: plan-writing
+description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
+allowed-tools: Read, Glob, Grep
+---
+
+# Plan Writing
+
+> Source: obra/superpowers
+
+## Overview
+This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
+
+## Task Breakdown Principles
+
+### 1. Kỷ Luật Micro-Tasking (Hành động 5 phút)
+ - Each task should take 2-5 minutes MAXIMUM.
+ - Tên Task KHÔNG PHẢI LÀ "Làm tính năng X". Tên Task phải là **hành động cụ thể trên 1 file cụ thể**.
+ - VD Sai: `[ ] Thêm logic phân quyền`
+ - VD Đúng: `[ ] Taọ file auth.middleware.ts, đọc token từ header và trả về role.`
+ 
+ ### 2. Clear Verification & TDD (Nếu có thể)
+ - How do you know it's done?
+ - What exact command to run? (e.g. `npm run test auth.test.ts`)
+ - What's the expected output?
+
+### 3. Logical Ordering
+- Dependencies identified
+- Parallel work where possible
+- Critical path highlighted
+- **Phase X: Verification is always LAST**
+
+### 4. Dynamic Naming in Project Root
+- Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
+- Name derived from task (e.g., "add auth" → `auth-feature.md`)
+- **NEVER** inside `.claude/`, `docs/`, or temp folders
+
+## Planning Principles (NOT Templates!)
+
+> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
+
+### Principle 1: Keep It SHORT
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
+| Every micro-step listed | Only actionable items |
+| Verbose descriptions | One-line per task |
+
+> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
+
+---
+
+### Principle 2: Be STRICTLY SPECIFIC (File-Level)
+ 
+ | ❌ Wrong (Cấm Tuyệt Đối) | ✅ Right (Chuẩn Superpowers) |
+ |----------|----------|
+ | "Set up project" | "Run `npx create-next-app`" |
+ | "Add authentication" | "Tạo `api/auth.ts`, code hàm verify JWT và trả 401" |
+ | "Style the UI" | "Mở `Header.tsx`, đổi bg-white thành bg-slate-900" |
+ 
+ > **Rule:** Mỗi task là một phát súng bắn tỉa chính xác vào 1 file. Không viết task bắn tỉa mù.
+
+---
+
+### Principle 3: Dynamic Content Based on Project Type
+
+**For NEW PROJECT:**
+- What tech stack? (decide first)
+- What's the MVP? (minimal features)
+- What's the file structure?
+
+**For FEATURE ADDITION:**
+- Which files are affected?
+- What dependencies needed?
+- How to verify it works?
+
+**For BUG FIX:**
+- What's the root cause?
+- What file/line to change?
+- How to test the fix?
+
+---
+
+### Principle 4: Scripts Are Project-Specific
+
+> 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
+
+| Project Type | Relevant Scripts |
+|--------------|------------------|
+| Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
+| Backend/API | `api_validator.py`, `security_scan.py` |
+| Mobile | `mobile_audit.py` |
+| Database | `schema_validator.py` |
+| Full-stack | Mix of above based on what you touched |
+
+**Wrong:** Adding all scripts to every plan
+**Right:** Only scripts relevant to THIS task
+
+---
+
+### Principle 5: Verification is Simple
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
+| "Test the API" | "curl localhost:3000/api/users returns 200" |
+| "Check styles" | "Open browser, verify dark mode toggle works" |
+
+---
+
+## Plan Structure (Flexible, Not Fixed!)
+
+```markdown
+ # [Tên tính năng ngắn gọn]
+ 
+ > **MANDATORY STEP BEFORE PLAN:** Đã đọc `.agent/knowledge/architecture_decisions.md` (ADR) để không lập kế hoạch sai luồng công nghệ chưa?
+ 
+ ## Tasks 
+ - [ ] `path/to/file1.py`: [Chính xác hàm gì cần thêm/sửa, tốn bao nhiêu phút?]
+   -> Verify: Chạy `pytest file1`, output X.
+ - [ ] `path/to/file2.ts`: [Chỉnh sửa dòng nào thành dòng nào?]
+   -> Verify: Bật browser check console log.
+ 
+ ## Done When
+ - [ ] [Main success criteria]
+```
+
+> **That's it.** No phases, no sub-sections unless truly needed.
+> Keep it minimal. Add complexity only when required.
+
+## Notes
+[Any important considerations]
+```
+
+---
+
+## Best Practices (Quick Reference)
+
+1. **Start with goal** - What are we building/fixing?
+2. **Max 10 tasks** - If more, break into multiple plans
+3. **Each task verifiable** - Clear "done" criteria
+4. **Project-specific** - No copy-paste templates
+5. **Update as you go** - Mark `[x]` when complete
+
+---
+
+## When to Use
+
+- New project from scratch
+- Adding a feature
+- Fixing a bug (if complex)
+- Refactoring multiple files

package/.agent/skills/powershell-windows/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: powershell-windows
+description: PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# PowerShell Windows Patterns
+
+> Critical patterns and pitfalls for Windows PowerShell.
+
+---
+
+## 1. Operator Syntax Rules
+
+### CRITICAL: Parentheses Required
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `if (Test-Path "a" -or Test-Path "b")` | `if ((Test-Path "a") -or (Test-Path "b"))` |
+| `if (Get-Item $x -and $y -eq 5)` | `if ((Get-Item $x) -and ($y -eq 5))` |
+
+**Rule:** Each cmdlet call MUST be in parentheses when using logical operators.
+
+---
+
+## 2. Unicode/Emoji Restriction
+
+### CRITICAL: No Unicode in Scripts
+
+| Purpose | ❌ Don't Use | ✅ Use |
+|---------|-------------|--------|
+| Success | ✅ ✓ | [OK] [+] |
+| Error | ❌ ✗ 🔴 | [!] [X] |
+| Warning | ⚠️ 🟡 | [*] [WARN] |
+| Info | ℹ️ 🔵 | [i] [INFO] |
+| Progress | ⏳ | [...] |
+
+**Rule:** Use ASCII characters only in PowerShell scripts.
+
+---
+
+## 3. Null Check Patterns
+
+### Always Check Before Access
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `$array.Count -gt 0` | `$array -and $array.Count -gt 0` |
+| `$text.Length` | `if ($text) { $text.Length }` |
+
+---
+
+## 4. String Interpolation
+
+### Complex Expressions
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `"Value: $($obj.prop.sub)"` | Store in variable first |
+
+**Pattern:**
+```
+$value = $obj.prop.sub
+Write-Output "Value: $value"
+```
+
+---
+
+## 5. Error Handling
+
+### ErrorActionPreference
+
+| Value | Use |
+|-------|-----|
+| Stop | Development (fail fast) |
+| Continue | Production scripts |
+| SilentlyContinue | When errors expected |
+
+### Try/Catch Pattern
+
+- Don't return inside try block
+- Use finally for cleanup
+- Return after try/catch
+
+---
+
+## 6. File Paths
+
+### Windows Path Rules
+
+| Pattern | Use |
+|---------|-----|
+| Literal path | `C:\Users\User\file.txt` |
+| Variable path | `Join-Path $env:USERPROFILE "file.txt"` |
+| Relative | `Join-Path $ScriptDir "data"` |
+
+**Rule:** Use Join-Path for cross-platform safety.
+
+---
+
+## 7. Array Operations
+
+### Correct Patterns
+
+| Operation | Syntax |
+|-----------|--------|
+| Empty array | `$array = @()` |
+| Add item | `$array += $item` |
+| ArrayList add | `$list.Add($item) | Out-Null` |
+
+---
+
+## 8. JSON Operations
+
+### CRITICAL: Depth Parameter
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `ConvertTo-Json` | `ConvertTo-Json -Depth 10` |
+
+**Rule:** Always specify `-Depth` for nested objects.
+
+### File Operations
+
+| Operation | Pattern |
+|-----------|---------|
+| Read | `Get-Content "file.json" -Raw | ConvertFrom-Json` |
+| Write | `$data | ConvertTo-Json -Depth 10 | Out-File "file.json" -Encoding UTF8` |
+
+---
+
+## 9. Common Errors
+
+| Error Message | Cause | Fix |
+|---------------|-------|-----|
+| "parameter 'or'" | Missing parentheses | Wrap cmdlets in () |
+| "Unexpected token" | Unicode character | Use ASCII only |
+| "Cannot find property" | Null object | Check null first |
+| "Cannot convert" | Type mismatch | Use .ToString() |
+
+---
+
+## 10. Script Template
+
+```powershell
+# Strict mode
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Continue"
+
+# Paths
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# Main
+try {
+    # Logic here
+    Write-Output "[OK] Done"
+    exit 0
+}
+catch {
+    Write-Warning "Error: $_"
+    exit 1
+}
+```
+
+---
+
+> **Remember:** PowerShell has unique syntax rules. Parentheses, ASCII-only, and null checks are non-negotiable.

package/.agent/skills/product-management/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: product-management
+description: Skill nhập vai Product Manager. Viết PRD (Product Requirement Doc), lên Lộ trình (Roadmap) và theo dõi KPI.
+allowed-tools: Read, Write
+version: 1.0
+priority: HIGH
+---
+
+# Kỹ năng Quản Trị Sản Phẩm (Product Management)
+
+> **MỤC TIÊU:** Khi User muốn bổ sung "Tính năng mới", bạn KHÔNG PHẢI là Coder. Bạn là một Giám Đốc Sản Phẩm (PM).
+
+Hãy từ chối viết code ngay lập tức. Thay vào đó, hãy kích hoạt Kỹ năng PM:
+
+## 1. Viết PRD (Product Requirement Document)
+Bắt buộc trải qua quy trình Mổ xẻ tính năng:
+*   **Vấn đề cốt lõi:** User/Khách hàng đang gặp nỗi đau gì?
+*   **Giải pháp:** Tính năng này giải quyết nỗi đau đó như thế nào?
+*   **User Story:** "Là một [Vai trò], tôi muốn [Hành động] để [Nhận được giá trị gì]."
+*   **Out of Scope:** Tính năng này RÕ RÀNG KHÔNG LÀM điều gì?
+
+## 2. Đo Lường (Metrics & KPIs)
+*   Tính năng này sẽ được cho là "Thành công" khi chỉ số nào tăng/giảm? (Ví dụ: Số lượng Click vào nút Mua Hàng, Giảm độ trễ API xuống dưới 20ms).
+*   Công cụ Tracking dự kiến là gì? (Google Analytics, Sentry, Custom DB?)
+
+## 3. Lộ Trình (Roadmap Phân Nhỏ)
+Sử dụng tư duy của `plan-writing`: Chẻ nhỏ tính năng lớn thành nhiều viên gạch 5-phút. Viết rõ ràng từng viên gạch.
+
+> **QUY TẮC SẮT (PM RULE):**
+> Chỉ khi PRD và User Story được User "Gật đầu Approval", bạn mới được phép thoát vai PM và gọi `Task Boundary` chuyển sang vai Coder để Code.