ai-developer-skill-os 9.3.1 → 10.1.0

package/.agents/skills/qk-api-lifecycle/SKILL.md

@@ -1,251 +0,0 @@
----
-# ── Identity ───────────────────────────────────────────────
-name: qk-api-lifecycle
-version: 9.2.0
-status: stable
-description: "Thiết kế và implement API endpoint mới với Zero-Trust — contract trước, code sau. Dùng skill này khi user nhắc đến: viết api, tạo endpoint, thiết kế api, build api, rest, graphql, trpc, route handler, controller, request/response schema — kể cả khi chỉ hỏi \"API này nên nhận input gì, trả output gì\"."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V9: Classification ─────────────────────────────────────
-type: capability
-
-intent:
-  - api-design
-  - backend-development
-
-complexity:
-  level: medium
-  criteria:
-    files_affected: "1-5"
-    has_behavior_change: true
-    has_external_dependency: true
-    has_breaking_change: false
-
-triggers:
-  - "viết api"
-  - "tạo endpoint"
-  - "thiết kế api"
-  - "build api"
-  - "rest"
-  - "graphql"
-  - "trpc"
-  - "route handler"
-  - "controller"
-  - "request/response schema"
-
-
-# ── V8: References ─────────────────────────────────────────
-workflow: feature-delivery
-
-rules:
-  - global
-  - coding
-
-tools:
-  - filesystem
-  - terminal
-
-related_skills:
-  - qk-data-lifecycle
-
-knowledge_scope:
-  owns:
-    - api-contracts
-    - endpoints
-  references:
-    - architecture
-    - security
-    - anti-patterns
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: api-change
-
-selection:
-  priority: high
-  confidence_threshold: 0.85
-
-examples: []
-learnings: []
-
-# ── V7 Runtime ─────────────────────────────────────────────
-execution_mode: deterministic
-cost: medium
-latency: medium
-risk: medium
-side_effects: edit_files
-produces: [code, report]
-consumes: [context-graph, user-description]
-
-token_budget:
-  max_files_read: 3
-  max_lines_per_read: 150
-  max_shell_commands: 1
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-api-lifecycle — API Design & Implementation
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-Chịu trách nhiệm thiết kế và triển khai API endpoints mới hoặc nâng cấp endpoint hiện hữu theo triết lý **Zero-Trust: Contract First (Schema & Validation) → Route/Controller → Service/Business Logic → Error Handling & Documentation**.
-
----
-
-## Preconditions
-
-Trước khi viết code API mới, AI BẮT BUỘC kiểm tra:
-
-- [ ] Xác định backend framework và routing pattern từ `.agents/DEV_PROFILE.md` (Express, Next.js API Routes, FastAPI, NestJS, Go Fiber, v.v.).
-- [ ] Xác định cơ chế Authentication & Authorization cần thiết (Public, JWT, Session, API Key, RBAC).
-- [ ] Định nghĩa rõ ràng Request schema (headers, params, body) và Response schema (success + error cases).
-- [ ] Nếu vi phạm quy ước REST/HTTP status codes hoặc thiếu validation schema:
-  → **EXIT: BLOCKED**
-  → Báo cáo user đề xuất chuẩn hóa contract trước khi implement.
-
----
-
-## Scope
-
-✅ Skill này làm:
-- Thiết kế Request/Response DTO và validation schema (Zod, Joi, Pydantic, Class-validator).
-- Cài đặt Route handlers, Controllers, Middlewares xử lý request.
-- Tích hợp Service layer và xử lý logic nghiệp vụ an toàn.
-- Chuẩn hóa HTTP status codes (200, 201, 400, 401, 403, 404, 422, 500) và error response envelope.
-- Đảm bảo sanitized inputs chống SQL Injection, XSS, mass assignment.
-
-❌ Skill này KHÔNG làm:
-- Thay đổi cấu trúc bảng database hoặc migration (→ `qk-data-lifecycle`).
-- Viết giao diện Frontend để gọi API này (→ `qk-api-consumer`).
-- Tối ưu câu query SQL bên dưới (→ `qk-db-optimizer`).
-
----
-
-## Execution Steps
-
-### Step 1 — Contract & Schema Definition
-```
-Inputs:  Yêu cầu endpoint từ user, DEV_PROFILE.md
-Actions:
-  - Khai báo Schema cho Request (Path params, Query params, Request body).
-  - Khai báo Schema cho Response (Success payload, Error payload).
-  - Áp dụng các rules kiểm tra tính hợp lệ dữ liệu đầu vào.
-Output: Type-safe Schema definitions
-```
-
-### Step 2 — Route & Middleware Setup
-```
-Inputs:  Schema definitions
-Actions:
-  - Khai báo route path và HTTP method tương ứng.
-  - Gắn các middlewares bảo vệ: Auth, Rate-limiting, Input validation.
-Output: Secure Route registration
-```
-
-### Step 3 — Controller & Service Implementation
-```
-Inputs:  Validated input data
-Actions:
-  - Gọi Service/Repository để xử lý nghiệp vụ.
-  - Bọc trong khối try/catch hoặc error boundary trung tâm của framework.
-  - Tuyệt đối không để lộ sensitive data (passwords, tokens, internal stack traces) ra client.
-Output: Completed API endpoint
-```
-
-### Step 4 — Verification & Contract Testing
-```
-Inputs:  Endpoint implementation
-Actions:
-  - Kiểm tra status codes trả về ứng với từng kịch bản (success, missing field, unauthorized).
-  - Chạy linter và typecheck.
-Exit: SUCCESS nếu endpoint tuân thủ 100% schema contract và coding standards.
-```
-
----
-
-## Prompt Template
-
-AI đọc `DEV_PROFILE.md` để biết backend stack + auth pattern. Mô tả API contract — AI lo phần còn lại.
-
-```
-Endpoint:    [Method + Path — vd: POST /api/orders]
-Mục đích:    [API này làm gì trong business context]
-Auth:        [Public / user JWT / admin only / service-to-service]
-Input:       [Request body / query params / path params]
-Output:      [Response shape khi success + khi lỗi]
-Rules:       [Business rules, validation, side effects quan trọng]
-```
-
----
-
-### Theo Role — AI thiết kế theo chiều sâu khác nhau:
-
-**role: be**
-```
-Endpoint:    POST /api/orders
-Mục đích:    Tạo đơn hàng mới, trừ stock, gửi email xác nhận
-Auth:        User JWT (phải login)
-Input:       { items: [{ productId, quantity }], shippingAddressId, paymentMethod }
-Output:      201 { orderId, totalAmount, estimatedDelivery }
-             400 nếu product hết hàng, 404 nếu product không tồn tại
-Rules:       Transaction: trừ stock + tạo order phải atomic. Stock < 0 thì rollback.
-             Email gửi async (không block response). Idempotency key từ client.
-```
-→ AI thiết kế: DB transaction scope, optimistic vs pessimistic locking cho stock,
-  idempotency key pattern, async job queue cho email, error taxonomy (4xx vs 5xx),
-  OpenAPI spec trước khi code.
-
-**role: fullstack**
-```
-Endpoint:    GET /api/dashboard/stats
-Mục đích:    Trả thống kê cho dashboard — revenue, orders, users hôm nay
-Auth:        Admin JWT
-Input:       ?from=2024-01-01&to=2024-01-31&timezone=Asia/Ho_Chi_Minh
-Output:      { revenue: number, orders: number, newUsers: number, topProducts: [] }
-Rules:       Cache 5 phút. Timezone-aware aggregation. Chỉ admin mới gọi được.
-```
-→ AI thiết kế: query aggregation strategy, DB index cho date range,
-  timezone handling (store UTC, convert at query time), cache layer (Redis vs in-memory),
-  type-safe response contract cho FE (zod schema hoặc OpenAPI codegen).
-
-**role: fe** *(khi FE cần hiểu API để tích hợp đúng)*
-```
-Endpoint:    GET /api/products (đã có — cần hiểu contract để tích hợp)
-Mục đích:    Lấy danh sách sản phẩm với filter + pagination
-Input:       ?page=1&limit=20&category=shoes&minPrice=100&sort=price_asc
-Output:      { data: Product[], total: number, page: number, hasNextPage: boolean }
-Rules:       Cần biết: khi nào trả 404 vs data rỗng? Error shape là gì?
-```
-→ AI phân tích: type generation từ API response, error boundary design,
-  loading state granularity, stale-while-revalidate strategy, mock data cho dev.
-
-**role: data** *(API nhận dữ liệu từ pipeline)*
-```
-Endpoint:    POST /api/ingest/events (webhook từ data pipeline)
-Mục đích:    Nhận batch events từ Kafka consumer, validate và lưu vào DB
-Auth:        Service-to-service API key
-Input:       { events: [{ type, payload, timestamp, source }], batchId }
-Output:      202 { accepted: N, rejected: M, errors: [] }
-Rules:       Idempotent theo batchId. Reject invalid schema nhưng không fail toàn batch.
-             Rate limit: 1000 events/request, 100 req/min.
-```
-→ AI thiết kế: bulk insert strategy, partial failure handling,
-  schema validation per-row vs batch-level, idempotency key indexing,
-  backpressure mechanism khi DB chậm.
-
-**role: devops** *(API health + observability endpoints)*
-```
-Endpoint:    GET /health, GET /metrics, GET /ready
-Mục đích:    Kubernetes liveness/readiness probe + Prometheus scraping
-Auth:        Internal only (không expose ra public)
-Output:      /health: { status: "ok", uptime, version }
-             /metrics: Prometheus format
-             /ready: 200 nếu DB connected, 503 nếu không
-Rules:       /health không check DB (liveness). /ready check DB (readiness).
-             /metrics không cần auth nhưng chỉ bind localhost.
-```
-→ AI thiết kế: liveness vs readiness semantics, graceful shutdown handling,
-  metric naming convention (RED method), scrape security, k8s probe config.

package/.agents/skills/qk-api-lifecycle/capability.yaml

@@ -1,23 +0,0 @@
-# Auto-generated from SKILL.md frontmatter
-schema_version: 1
-id: "qk-api-lifecycle"
-version: "9.1.0"
-description: "Thiết kế, triển khai API endpoints với Zero-Trust — contract trước, code sau."
-tools:
-  - "filesystem"
-  - "terminal"
-knowledge:
-  owns:
-    - "api-contracts"
-    - "endpoints"
-  references:
-    - "architecture"
-    - "security"
-    - "anti-patterns"
-eval:
-  scorecard: "evals/scorecard.yaml"
-decision_boundary:
-  owns:
-    - "qk-api-lifecycle"
-  does_not_own: []
-  conflicts_with: []

package/.agents/skills/qk-api-lifecycle/evals/scorecard.yaml

@@ -1,29 +0,0 @@
-name: qk-api-lifecycle-eval
-description: Đánh giá chất lượng thiết kế và triển khai API
-version: 9.1.0
-threshold: 90 # Tiêu chuẩn cao vì liên quan đến hợp đồng dữ liệu và bảo mật cổng vào
-
-metrics:
-  - id: contract_first_design
-    name: Thiết kế theo hợp đồng (Contract-first)
-    description: Agent có định nghĩa Types/Interfaces rõ ràng trước khi code logic không?
-    weight: 30
-    criteria:
-      - Định nghĩa rõ ràng Request & Response structure bằng TypeScript interface / DTO (15đ)
-      - Khai báo đầy đủ HTTP method, route path và các HTTP status codes có thể trả về (15đ)
-
-  - id: zero_trust_validation
-    name: Tuân thủ Zero-Trust (R-SEC-04)
-    description: Mọi API Endpoint có được bảo vệ và validate dữ liệu ở cổng vào không?
-    weight: 40
-    criteria:
-      - Áp dụng thư viện validation (zod/yup/class-validator) cho toàn bộ input payload (20đ)
-      - Không rò rỉ dữ liệu nhạy cảm ở response cổng ra (sanitize/mask data) (20đ)
-
-  - id: error_handling_and_compat
-    name: Xử lý lỗi và Tương thích ngược
-    description: API có xử lý mượt mà các tình huống lỗi và giữ tính backward compatibility không?
-    weight: 30
-    criteria:
-      - Trả về đúng HTTP status code (400, 401, 403, 404, 422, 500) thay vì trả 500 cho mọi lỗi (15đ)
-      - Không làm hỏng (breaking changes) các trường dữ liệu của contract cũ mà không tăng version (15đ)

package/.agents/skills/qk-bug-resolution/capability.yaml

@@ -1,25 +0,0 @@
-# Auto-generated from SKILL.md frontmatter
-schema_version: 1
-id: "qk-bug-resolution"
-version: "9.1.0"
-description: "Sửa lỗi (bugs) bằng chu trình khép kín: Quan sát → Giả thuyết → Bằng chứng → Sửa."
-tools:
-  - "filesystem"
-  - "terminal"
-knowledge:
-  owns:
-    - "bug-diagnosis"
-    - "fix-strategies"
-    - "root-cause-analysis"
-  references:
-    - "testing"
-    - "language-specific-features"
-    - "security"
-    - "anti-patterns"
-eval:
-  scorecard: "evals/scorecard.yaml"
-decision_boundary:
-  owns:
-    - "qk-bug-resolution"
-  does_not_own: []
-  conflicts_with: []

package/.agents/skills/qk-code-review/capability.yaml

@@ -1,23 +0,0 @@
-# Auto-generated from SKILL.md frontmatter
-schema_version: 1
-id: "qk-code-review"
-version: "9.1.0"
-description: "Elite AI/Code Review System: Kiểm toán, Review code và cấu hình AI với tư duy Architect, áp dụng 4-Phase Review."
-tools:
-  - "filesystem"
-knowledge:
-  owns:
-    - "code-review-standards"
-    - "ai-configuration-review"
-    - "feedback-delivery"
-  references:
-    - "architecture"
-    - "security"
-    - "anti-patterns"
-eval:
-  scorecard: "evals/scorecard.yaml"
-decision_boundary:
-  owns:
-    - "qk-code-review"
-  does_not_own: []
-  conflicts_with: []

package/.agents/skills/qk-context-loader/SKILL.md

@@ -1,198 +0,0 @@
----
-# ── Identity ───────────────────────────────────────────────
-name: qk-context-loader
-version: 9.2.0
-status: stable
-description: "Khảo sát kiến trúc codebase, phân tích import graph, lập bản đồ phụ thuộc và tải context chính xác trước khi code — ngăn hallucination kiến trúc. Dùng skill này khi user nhắc đến: load context, understand project, vẽ dependency graph, analyze architecture, giải thích kiến trúc dự án, tìm hiểu codebase — kể cả khi chỉ hỏi 'dự án này tổ chức thế nào'."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V9: Classification ─────────────────────────────────────
-type: utility
-
-intent:
-  - context-loading
-  - project-understanding
-  - repository-analysis
-
-complexity:
-  level: low
-  criteria:
-    files_affected: "1-5"
-    has_behavior_change: false
-    has_external_dependency: false
-    has_breaking_change: false
-
-triggers:
-  - "load context"
-  - "understand project"
-  - "vẽ dependency graph"
-  - "analyze architecture"
-  - "giải thích kiến trúc dự án"
-  - "tìm hiểu codebase"
-
-
-selection:
-  priority: high
-  confidence_threshold: 0.75
-
-# ── V8: References ─────────────────────────────────────────
-workflow: context-discovery
-
-rules:
-  - global
-
-tools:
-  - filesystem
-  - terminal
-
-related_skills:
-  - qk-feature-delivery
-  - qk-orchestrator
-  - qk-project-memory
-
-knowledge_scope:
-  owns:
-    - project-context
-    - architecture-discovery
-    - dependency-mapping
-  references:
-    - coding
-    - repository-structure
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: review
-
-examples: []
-learnings: []
-
-# ── V7 Runtime ─────────────────────────────────────────────
-execution_mode: deterministic
-cost: low
-latency: fast
-risk: low
-side_effects: read_only
-produces: [context-graph]
-consumes: [source-code]
-
-token_budget:
-  max_files_read: 10
-  max_lines_per_read: 150
-  max_shell_commands: 2
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-context-loader — Dependency Graph & Architecture Discovery
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-Chịu trách nhiệm thấu hiểu cấu trúc dự án và thiết lập bản đồ phụ thuộc (Dependency Graph) chuẩn xác trước khi viết bất kỳ dòng code nào. **Mục tiêu tối thượng: Ngăn chặn triệt để AI hallucination về kiến trúc, conventions và vị trí đặt file**.
-
----
-
-## Preconditions
-
-Trước khi chạy khảo sát, AI BẮT BUỘC kiểm tra:
-
-- [ ] Workspace chứa mã nguồn thực tế (tồn tại ít nhất 1 file manifest: `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `pom.xml`, v.v.).
-- [ ] Xác định rõ phạm vi cần load: Toàn bộ repo (Full system) hay Module / Feature cụ thể.
-- [ ] Đọc `.ai-local/knowledge/index.yaml` (nếu có) để tái sử dụng kiến thức đã lưu thay vì quét lại từ đầu.
-
-*Nếu thư mục dự án hoàn toàn trống:*
-→ **EXIT: BLOCKED**
-→ Gợi ý: "Dự án chưa có mã nguồn. Vui lòng chạy `./qk-project-bootstrap` để khởi tạo framework và scaffolding ban đầu."
-
----
-
-## Scope
-
-✅ Skill này làm:
-- Đọc các tệp manifest và xác định chính xác Tech Stack, Runtime, State library, CSS framework, ORM.
-- Khảo sát cây thư mục theo độ sâu hợp lý (Max depth = 3) để nhận diện mô hình tổ chức (Modular, Layered, Feature-sliced, Domain-driven, Monorepo).
-- Phân tích Entry Point (`main`, `index`, `server`, `App`, router configuration).
-- Lập sơ đồ phụ thuộc (Dependency Flow / Architecture Diagram bằng Mermaid) từ Controller/Route → Service/UseCase → Repository/Model.
-- Trích xuất Conventions: đặt tên file, patterns xử lý lỗi, cơ chế Dependency Injection.
-- Cập nhật thông tin vào bộ nhớ phiên làm việc của AI.
-
-❌ Skill này KHÔNG làm:
-- Sửa đổi bất kỳ file nào trong dự án (`side_effects: read_only`).
-- Dump toàn bộ code files vào context làm cạn kiệt token budget.
-- Đánh giá chất lượng chi tiết code smells (thuộc `qk-project-health`).
-
----
-
-## Execution Steps
-
-### Step 1 — Nhận diện Tech Stack & Manifest
-```
-Inputs:  Thư mục gốc của project
-Actions:
-  - Đọc file manifest chính (package.json, pyproject.toml, go.mod...).
-  - Trích xuất: ngôn ngữ chính, runtime version, framework, ORM, state library, test runner.
-  - Đối chiếu với DEV_PROFILE.md nếu có.
-Outputs: Stack Profile tóm tắt
-```
-
-### Step 2 — Khảo sát Cấu trúc Thư mục & Entry Points
-```
-Actions:
-  - Chạy `list_dir` hoặc `find_by_name` với MaxDepth=2 trên src/ hoặc app/.
-  - Xác định vị trí các tầng:
-    - Routes / Controllers / API Handlers
-    - Business Logic / Services / Use Cases
-    - Data Access / Repositories / Entities / Models
-    - Shared / Utils / Components / Middleware
-  - Đọc entry point file chính (max 80 dòng đầu).
-Outputs: Sơ đồ phân tầng kiến trúc (Architectural Layers)
-```
-
-### Step 3 — Phân tích Luồng phụ thuộc (Dependency Tracing)
-```
-Actions:
-  - Chọn 1 feature tiêu biểu, trace import statements từ UI/Controller xuống DB.
-  - Xác định:
-    - Có dùng Dependency Injection không?
-    - Shared types/DTOs nằm ở đâu?
-    - Data fetching pattern: Client-side hook, Server Component, hay REST client?
-Outputs: Dependency Graph (Mermaid flowchart)
-```
-
-### Step 4 — Tổng hợp Context Report
-```
-Actions:
-  - Xuất báo cáo ngắn gọn, súc tích (dưới 40 dòng) gồm:
-    1. Kiến trúc tổng quan (Pattern & Style).
-    2. Quy ước đặt file & Naming conventions.
-    3. Đường đi của luồng dữ liệu (Data Flow).
-    4. Sơ đồ Mermaid trực quan.
-```
-
----
-
-## Prompt Template
-
-```
-Phạm vi:      [Toàn bộ dự án / Module X / Tính năng Y]
-Mục tiêu:     [Tìm hiểu kiến trúc trước khi thêm feature / refactor / debug]
-Câu hỏi cần:  [Data flow đi như thế nào? / Types đặt ở đâu? / Service kết nối DB ra sao?]
-```
-
-### Ví dụ theo Role:
-
-**role: fullstack (Khảo sát Next.js 14 Monorepo)**
-```
-Phạm vi:      apps/web và packages/api
-Mục tiêu:     Nắm rõ cách web gọi API và chia sẻ types giữa FE và BE.
-```
-→ AI trace: `packages/api/src/routers` → xuất `tRPC router` → `apps/web/src/utils/trpc.ts` → import types trong `apps/web/src/app/page.tsx`.
-→ AI vẽ sơ đồ Mermaid luồng type-safe RPC từ client tới DB query.
-
-**role: be (Khảo sát Clean Architecture NestJS)**
-```
-Phạm vi:      src/modules/orders
-Mục tiêu:     Hiểu luồng xử lý Order: DTO -> Controller -> UseCase -> Prisma Repository.
-```
-→ AI liệt kê cấu trúc layers, quy ước DTO validation, và cách inject repository vào service.

package/.agents/skills/qk-context-loader/capability.yaml

@@ -1,23 +0,0 @@
-# Auto-generated from SKILL.md frontmatter
-schema_version: 1
-id: "qk-context-loader"
-version: "9.1.0"
-description: "Tải context và vẽ dependency graph chính xác trước khi code — ngăn hallucination kiến trúc."
-tools:
-  - "filesystem"
-  - "terminal"
-knowledge:
-  owns:
-    - "project-context"
-    - "architecture-discovery"
-  references:
-    - "coding"
-    - "repository-structure"
-    - "anti-patterns"
-eval:
-  scorecard: "evals/scorecard.yaml"
-decision_boundary:
-  owns:
-    - "qk-context-loader"
-  does_not_own: []
-  conflicts_with: []

package/.agents/skills/qk-context-loader/evals/scorecard.yaml

@@ -1,28 +0,0 @@
-name: qk-context-loader-eval
-description: Đánh giá khả năng phân tích kiến trúc và tải context
-version: 9.1.0
-threshold: 85 # Tính chính xác của context là cốt lõi để tránh hallucination
-
-metrics:
-  - id: accurate_graph_traversal
-    name: Phân tích Graph chính xác và giới hạn
-    description: Agent có tuân thủ giới hạn chiều sâu và không quét thừa file không?
-    weight: 35
-    criteria:
-      - Quét đúng dependency graph từ entry point (15đ)
-      - Tuân thủ giới hạn max depth 3 và max_files_read, không bị tràn (infinite loop) (20đ)
-
-  - id: risk_assessment
-    name: Đánh giá mức độ rủi ro (Risk Assessment)
-    description: Agent có nhận diện đúng các module dùng chung (shared) hoặc vi phạm ranh giới không?
-    weight: 35
-    criteria:
-      - Đánh dấu chính xác các file được import nhiều lần là HIGH/CRITICAL risk (20đ)
-      - Phát hiện được các file vi phạm cấu trúc (vd: trộn lẫn Server Logic và Client UI) (15đ)
-
-  - id: strict_json_output
-    name: Định dạng Output JSON chuẩn mực
-    description: Agent có xuất ra được JSON Schema như yêu cầu để các agent khác đọc không?
-    weight: 30
-    criteria:
-      - Định dạng JSON trả về chứa đầy đủ nodes, imports, exports và risks theo đúng schema (30đ)