ai-developer-skill-os 8.2.1 → 8.3.1

package/.agents/skills/qk-engineering-standard/capability.yaml

@@ -0,0 +1,23 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-engineering-standard"
+version: "8.3.1"
+description: "Ép buộc SOLID, DRY, Clean Code với ngưỡng số liệu cụ thể — không có rule mơ hồ."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "coding-standards"
+    - "best-practices"
+  references:
+    - "architecture"
+    - "security"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-engineering-standard"
+  does_not_own: []
+  conflicts_with: []

package/.agents/skills/qk-engineering-standard/evals/scorecard.yaml

@@ -0,0 +1,28 @@
+name: qk-engineering-standard-eval
+description: Đánh giá việc áp dụng Tiêu chuẩn Kỹ thuật và Clean Code
+version: 8.3.1
+threshold: 80 # Đánh giá tính chính xác của việc tính điểm Health Score
+
+metrics:
+  - id: concrete_thresholds
+    name: Áp dụng Thresholds định lượng
+    description: Agent có áp dụng đúng các ngưỡng cứng (Concrete Thresholds) không?
+    weight: 40
+    criteria:
+      - Nhận diện đúng hàm > 30 dòng, độ phức tạp > 10, file > 300 dòng (20đ)
+      - Phát hiện mã trùng lặp (DRY violation) nếu lặp lại >= 3 lần (20đ)
+
+  - id: health_score_calculation
+    name: Chấm điểm Health Score
+    description: Báo cáo có tính toán điểm sức khỏe (Health Score) chuẩn xác không?
+    weight: 35
+    criteria:
+      - Trừ điểm đúng theo thang điểm (CRITICAL: -25, HIGH: -10, MEDIUM: -5, LOW: -2) (20đ)
+      - Trả về đúng mức Exit Code tương ứng (SUCCESS nếu >=80, FAILED nếu <60) (15đ)
+
+  - id: non_intrusive_reporting
+    name: Báo cáo không can thiệp (Read-only)
+    description: Agent có tuân thủ quy tắc chỉ report mà không tự ý sửa code không?
+    weight: 25
+    criteria:
+      - Giữ nguyên trạng thái read-only, chỉ cung cấp report và suggestion (không tự sửa file) (25đ)

package/.agents/skills/qk-engineering-standard/references/anti-patterns.md

@@ -0,0 +1,121 @@
+# 🚫 Anti-Patterns Blacklist — Engineering Standard
+
+> Đây là danh sách đỏ. AI Agent **KHÔNG ĐƯỢC PHÉP** tạo ra code vi phạm các mục dưới đây,
+> trừ khi người dùng yêu cầu tường minh và chấp nhận rủi ro (kèm comment giải thích lý do).
+> Mục tiêu: chống "code rác" (slop), giữ codebase dễ bảo trì, an toàn kiểu dữ liệu, và có thể mở rộng.
+
+---
+
+## 1. TypeScript
+
+| Cấm | Thay bằng |
+|---|---|
+| `any` tùy tiện | `unknown` + type guard, hoặc định nghĩa type/interface cụ thể |
+| `// @ts-ignore` không có lý do | `// @ts-expect-error: <lý do cụ thể>` chỉ khi thực sự cần thiết tạm thời |
+| Ép kiểu ép buộc (`as unknown as X`, `!` non-null assertion tràn lan) | Type guard, Zod/valibot schema validation ở boundary (API, form input) |
+| Kiểu `object`, `Function` mơ hồ | Định nghĩa interface/type rõ ràng, dùng generic khi cần tái sử dụng |
+| Enum số học không rõ nghĩa | `as const` object hoặc string union type |
+| Interface/type định nghĩa lặp lại nhiều nơi | Tách vào `types/` hoặc co-locate cạnh feature, export dùng chung |
+
+**Ví dụ SAI:**
+```ts
+function handleData(data: any) {
+  return data.value; // không có gì đảm bảo `value` tồn tại
+}
+```
+
+**Ví dụ ĐÚNG:**
+```ts
+interface ApiResponse {
+  value: string;
+}
+function handleData(data: ApiResponse) {
+  return data.value;
+}
+```
+
+---
+
+## 2. React / UI
+
+| Cấm | Thay bằng |
+|---|---|
+| Mutate state trực tiếp (`state.items.push(...)`, `state.x = y`) | Tạo object/array mới (`setState(prev => [...prev, item])`) hoặc dùng Immer |
+| Spaghetti component: logic nghiệp vụ + fetch + JSX trộn chung 1 hàm khổng lồ | Tách Custom Hook (logic) khỏi Component (JSX thuần) — xem `component-cookbook.md` |
+| Inline style (`style={{color: 'red'}}`) thay vì Design Token | Dùng class Tailwind ánh xạ token (`text-danger`), hoặc CSS variable đã định nghĩa |
+| `useEffect` dùng để đồng bộ state phái sinh (derived state) | Tính toán trực tiếp trong render, hoặc `useMemo` nếu tốn kém |
+| `useEffect` không có dependency array hoặc dependency sai (gây vòng lặp/render thừa) | Khai báo đầy đủ dependency, dùng ESLint `react-hooks/exhaustive-deps` |
+| Component nhận > 5-6 props rời rạc không liên quan | Gom nhóm thành object prop, hoặc tách nhỏ component |
+| Key trong list dùng `index` khi list có thể reorder/filter | Dùng ID ổn định (`item.id`) |
+| Hardcode text UI trực tiếp (không chuẩn bị cho i18n) khi dự án có đa ngôn ngữ | Đưa qua lớp i18n / constants |
+| Bỏ qua trạng thái loading / error / empty khi render dữ liệu async | Luôn xử lý đủ 3 trạng thái: loading, error, empty, success |
+| Bỏ ARIA attributes / semantic HTML (`<div onClick>` thay vì `<button>`) | Dùng đúng thẻ semantic, thêm `aria-*` khi cần |
+
+---
+
+## 3. Kiến trúc (Architecture)
+
+| Cấm | Thay bằng |
+|---|---|
+| Import chéo tạo circular dependency giữa các module | Tách shared logic ra module trung lập (`shared/`, `lib/`), kiểm tra bằng `madge` hoặc lint rule |
+| Gọi API trực tiếp trong UI Component (`fetch()` ngay trong JSX/handler của component trình bày) | Tách vào `services/` hoặc data-layer hook (`useXxxQuery`) — component chỉ gọi hook |
+| Business logic nằm trong Component thay vì layer riêng | Tách `hooks/`, `utils/`, `services/` — Component chỉ điều phối |
+| Global mutable state ngoài store chính thức (biến module-level bị mutate) | Dùng Context/Zustand store có kiểm soát |
+| Magic number/string rải rác trong code | Đưa vào `constants.ts` |
+| Folder structure lộn xộn (component, hook, style của cùng 1 feature nằm rải rác nhiều nơi) | Co-location theo feature: `features/xxx/{components,hooks,services,types}` |
+| Duplicate logic dán đè (copy-paste) ở nhiều nơi thay vì tái sử dụng | Trích xuất thành hàm/hook dùng chung |
+| Commit code có `console.log` debug, code chết (dead code), TODO không có ticket | Dọn dẹp trước khi merge, hoặc gắn issue tracking rõ ràng |
+
+---
+
+## 4. React Query / TanStack Query
+
+| Cấm | Thay bằng |
+|---|---|
+| Copy dữ liệu từ `useQuery` vào `useState` cục bộ (`const [x,setX]=useState(); useEffect(()=>setX(data),[data])`) | Dùng thẳng `data` trả về từ `useQuery` — nó đã là single source of truth |
+| Tự quản lý loading/error bằng `useState` song song với `useQuery` | Dùng `isPending`/`isError`/`isFetching` có sẵn |
+| `queryKey` viết tay rải rác nhiều nơi (`["user", id]` gõ lại ở 5 file khác nhau) | Tập trung vào 1 file `queryKeys.ts` theo factory pattern |
+| Gọi `queryFn` chứa logic biến đổi dữ liệu phức tạp (mapping, tính toán nặng) | `queryFn` chỉ fetch thô; biến đổi dữ liệu qua `select` option hoặc hook riêng |
+| Dùng `useQuery` cho dữ liệu thuần client (không đến từ server) | Đó là client state → dùng `useState`/Context/Zustand |
+| `staleTime: 0` mặc định cho mọi query, gây refetch liên tục không cần thiết | Đặt `staleTime` phù hợp với tần suất đổi của dữ liệu |
+| `invalidateQueries` tràn lan sau mọi mutation dù chỉ đổi 1 field nhỏ | Ưu tiên `setQueryData` cập nhật cache trực tiếp khi biết chính xác dữ liệu mới |
+| Gọi `useQuery`/`useMutation` bên trong service/utility function (không phải React component/hook) | Hooks của React Query chỉ được gọi trong component hoặc custom hook |
+| Nuốt lỗi mutation im lặng (không xử lý `onError`, không hiển thị gì cho user) | Luôn xử lý `onError` hoặc kiểm tra `error` để phản hồi UI |
+| Trộn React Query với Redux/Zustand để lưu cùng một loại server-state ở 2 nơi | Server-state chỉ sống trong React Query cache, không đồng bộ ngược vào store khác |
+
+---
+
+## 5. TanStack Router / Table / Form / Virtual / Store
+
+| Cấm | Thay bằng |
+|---|---|
+| Định nghĩa route bằng object thường, params/search không có type (dễ gõ sai tên param) | TanStack Router — dùng `createFileRoute`/`createRoute`, params & search suy kiểu tự động |
+| Fetch dữ liệu trang trong component sau khi route đã mount (waterfall: chờ route load → mới fetch) | Prefetch trong `loader` của route (`loader: ({context}) => context.queryClient.ensureQueryData(...)`) |
+| Đọc/ghi query string bằng `URLSearchParams` tay khi đã dùng TanStack Router | Dùng `useSearch`/`Route.useSearch()` có type-safe, validate qua schema (Zod) |
+| Tự viết sort/filter/pagination state rời rạc bằng nhiều `useState` cho bảng dữ liệu | TanStack Table — quản lý qua `state` + `onXxxChange`, tách rõ khỏi cách render |
+| Trộn logic tính toán dữ liệu bảng (sort/filter) vào trong JSX render row | Định nghĩa `columns` + xử lý qua Table instance (`table.getRowModel()`), JSX chỉ map render |
+| Render toàn bộ hàng trăm/nghìn row DOM node cùng lúc trong Table/List | Kết hợp TanStack Virtual (`useVirtualizer`) để chỉ render row trong viewport |
+| Tự quản lý field, error, touched bằng `useState` rời rạc cho form nhiều field | TanStack Form (`useForm`, `field.state`) — validate đồng bộ/bất đồng bộ tập trung, tránh re-render toàn form mỗi keystroke |
+| Validate form chỉ ở client, không đồng bộ schema với backend | Dùng chung 1 schema (Zod) cho cả TanStack Form validator và backend validation |
+| Đưa state UI đơn giản (theme, sidebar open/close) vào Redux/Context nặng nề | TanStack Store (hoặc `useState` cục bộ) cho state nhỏ gọn, framework-agnostic |
+| Gọi trực tiếp DOM API để đo scroll/kích thước item thay vì dùng API của Virtual | Dùng `measureElement`/`estimateSize` của TanStack Virtual, tránh đọc/ghi layout thủ công gây jank |
+
+---
+
+## 6. Nguyên tắc review nhanh (Checklist trước khi xuất code)
+
+- [ ] Không còn `any`/`ts-ignore` không giải thích
+- [ ] Component tách rõ Logic (hook) / UI (JSX thuần)
+- [ ] State được update immutable
+- [ ] Không gọi API trực tiếp trong component trình bày
+- [ ] Có xử lý loading/error/empty cho dữ liệu async
+- [ ] Dùng Design Token, không inline style tùy tiện
+- [ ] Không có circular dependency
+- [ ] Không có console.log / code chết còn sót lại
+- [ ] Server-state đi qua React Query, không bị copy lại vào `useState`/store khác
+- [ ] `queryKey` lấy từ factory tập trung, không viết tay rải rác
+- [ ] Bảng/list dữ liệu lớn dùng TanStack Table/Virtual thay vì tự viết + render toàn bộ DOM
+- [ ] Form nhiều field dùng TanStack Form (hoặc RHF nếu đã có sẵn), không rời rạc `useState`
+- [ ] Route params/search có type-safe qua TanStack Router, không parse tay
+
+> Ghi chú: Nếu dự án dùng Redux thay vì Context/Zustand, áp dụng thêm quy tắc "không dispatch action trực tiếp trong component con sâu — đi qua thunk/selector có kiểm soát". Redux (nếu có) chỉ nên giữ **client state**; server-state luôn thuộc về React Query.

package/.agents/skills/qk-engineering-standard/rules/frontend.md

@@ -4,7 +4,7 @@
 
 ---
 
-## 🔄 [Merged from qk-frontend-architecture]
+## Referenced by: qk-frontend-architecture (file-placement subset)
 
 # Frontend Architecture
 

package/.agents/skills/qk-fe-api-integration/SKILL.md

@@ -1,7 +1,7 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-fe-api-integration
-version: 8.0.0
+version: 8.3.1
 status: stable
 description: "Consume API Backend, quản lý State, bind vào UI — tuân thủ kiến trúc Base dự án"
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
@@ -140,7 +140,7 @@ On missing precondition:
 **Decision:**
 ```
 IF wrapper/client found (e.g., apiClient.ts, axiosInstance.ts)
-  → Use it. NEVER bypass with raw fetch/axios.
+  → Use it. Ưu tiên bọc (wrap) bằng TanStack Query (useQuery/useMutation) nếu có thể. NEVER bypass with raw fetch/axios in components.
   → Confidence: HIGH → go to Phase 2
 
 ELSE IF no wrapper found
@@ -157,20 +157,22 @@ ELSE IF conflicting patterns found (mix of fetch + axios + rtk)
 
 ---
 
-### Phase 2 — Generate Types
+### Phase 2 — Generate Types & Validation
 
 **Steps:**
-1. Parse provided JSON payload → extract all fields with types
-2. Generate TypeScript interface (Request + Response)
-3. Flag any field that could be `null` or optional
+1. Parse provided JSON payload → extract all fields
+2. Generate **Zod schema** (`z.object({...})`) for runtime validation
+3. Export TypeScript interface via inferred Zod type (`export type Response = z.infer<typeof schema>`)
+4. Flag any field that could be `null` or optional with `.nullable()` or `.optional()`
 
 **Decision:**
 ```
 IF all fields clearly typed from JSON
+  → Khởi tạo Zod schema chính xác.
   → Confidence: HIGH → go to Phase 3
 
 ELSE IF some fields ambiguous (null | undefined)
-  → Mark as optional (?:) + add comment "// verify with backend"
+  → Mark as optional in Zod (`.optional()`) + add comment "// verify with backend"
   → Confidence: MEDIUM → go to Phase 3
 
 ELSE IF nested objects contain mixed null/non-null patterns
@@ -182,10 +184,11 @@ ELSE IF nested objects contain mixed null/non-null patterns
 ### Phase 3 — Implement Service + UI Binding
 
 **Steps:**
-1. Create/update service file (API calls only — no UI logic)
-2. Bind to component: implement Loading state (skeleton/spinner)
-3. Bind Success state: render data using generated types
-4. Bind Error state: handle HTTP errors per table below
+1. Create/update service file: Viết API fetcher function.
+2. Viết Custom Hook bọc fetcher function bằng **TanStack Query** (`useQuery` hoặc `useMutation`).
+3. Bind to component: Dùng các states từ hook (`isLoading`, `isPending`, `isError`, `data`) thay vì tự tạo `useEffect`.
+4. Bind Error state: handle HTTP errors per table below.
+5. Kiểm duyệt ranh giới an toàn (R-SEC-04): Validate dữ liệu API trả về bằng Zod Schema ở (2) trước khi render.
 
 **HTTP Error Handling (mandatory for ALL integrations):**
 ```
@@ -356,25 +359,3 @@ Exit Code:   [SUCCESS | PARTIAL | BLOCKED | FAILED]
 
 ---
 
-Consume backend API safely in frontend: identify existing client, generate types, implement service layer, and bind to UI with proper states.
-Triggered when user needs to integrate a backend API endpoint into a frontend application. Requires JSON payload sample and knowledge of existing API client patterns.
-- JSON payload sample (request/response)
-- API endpoint specification
-- Existing API client path (if any)
-- Component to bind (if specified)
-- Context graph (for existing patterns)
-1. **Identify:** Find existing API client or confirm need for new one
-2. **Generate:** Create TypeScript interfaces from JSON payload
-3. **Implement:** Build service layer with proper HTTP methods
-4. **Bind:** Connect to UI with Loading/Success/Error states
-5. **Audit:** Verify no hardcoded URLs, no API in JSX, proper error handling
-- NEVER bypass existing wrapper with raw fetch/axios
-- MUST generate strict TypeScript interfaces (no `any`)
-- MUST handle all 3 UI states: Loading, Success, Error
-- MUST NOT exceed token_budget (max 3 files, 100 lines each, 1 shell command)
-- MUST stop early if confidence threshold reached
-- Zero-Trust: Use existing client pattern, never invent new one without approval
-- Type Safety: All API responses must have explicit TypeScript types
-- Error Handling: All HTTP errors must be handled per mandatory table
-- Separation: Service layer only — no API calls in presentational components
----

package/.agents/skills/qk-fe-api-integration/capability.yaml

@@ -0,0 +1,21 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-fe-api-integration"
+version: "8.3.1"
+description: "Consume API Backend, quản lý State, bind vào UI — tuân thủ kiến trúc Base dự án"
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "api-integration"
+    - "state-management"
+  references:
+    - "architecture"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-fe-api-integration"
+  does_not_own: []
+  conflicts_with: []

package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml

@@ -0,0 +1,29 @@
+name: qk-fe-api-integration-eval
+description: Đánh giá chất lượng tích hợp API vào giao diện Frontend
+version: 8.3.1
+threshold: 85 # Đảm bảo tính toàn vẹn của DTO, UI State và ranh giới bảo mật
+
+metrics:
+  - id: type_and_validation
+    name: Khởi tạo Types và Validation (Zod)
+    description: Agent có gen ra Types và Zod schema từ JSON payload mẫu không?
+    weight: 30
+    criteria:
+      - Khởi tạo chính xác Zod Schema và xuất TypeScript interfaces (15đ)
+      - Phân biệt rõ ràng các trường bắt buộc và tùy chọn (.optional(), .nullable()) (15đ)
+
+  - id: architecture_compliance
+    name: Tuân thủ Kiến trúc dự án (Base Architecture)
+    description: Agent có tái sử dụng API Client có sẵn không?
+    weight: 30
+    criteria:
+      - Ưu tiên dùng wrapper có sẵn (Axios/TanStack Query) thay vì viết raw fetch tràn lan (15đ)
+      - Tuyệt đối không hardcode Base URL vào trong component (15đ)
+
+  - id: ui_state_handling
+    name: Xử lý State giao diện toàn diện
+    description: Có bao phủ đủ 3 trạng thái Loading, Success, Error không?
+    weight: 40
+    criteria:
+      - Xử lý mượt mà trạng thái Loading và Success (20đ)
+      - Có cơ chế bắt lỗi HTTP bài bản (401, 404, 500, Network Error) và map với Error state của giao diện (20đ)