ai-developer-skill-os 8.2.1 → 8.3.1

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

@@ -0,0 +1,23 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-context-loader"
+version: "8.3.1"
+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

@@ -0,0 +1,28 @@
+name: qk-context-loader-eval
+description: Đánh giá khả năng phân tích kiến trúc và tải context
+version: 8.3.1
+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đ)

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

@@ -1,7 +1,7 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-data-lifecycle
-version: 8.0.0
+version: 8.3.1
 status: stable
 description: "Quản lý Schema, Migrations an toàn — schema freeze → backward-compat migration → cleanup."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
@@ -47,6 +47,8 @@ knowledge_scope:
     - migrations
   references:
     - architecture
+    - security
+    - anti-patterns
 
 # ── V8: Verification ───────────────────────────────────────
 verification:
@@ -80,7 +82,7 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 # qk-data-lifecycle — Database Schema & Repository Manager
 
-> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
 ---
 
@@ -134,6 +136,9 @@ drop_column:
 
 rename_table:
   strategy: create new table → migrate → drop old (never ALTER TABLE RENAME in prod)
+  
+pii_data:
+  strategy: Khi add column chứa PII (Personal Identifiable Information), BẮT BUỘC áp dụng cơ chế hashing/encryption tương ứng (tuân thủ R-SEC-04).
 ```
 
 ---

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

@@ -0,0 +1,23 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-data-lifecycle"
+version: "8.3.1"
+description: "Quản lý Schema, Migrations an toàn — schema freeze → backward-compat migration → cleanup."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "schema"
+    - "migrations"
+  references:
+    - "architecture"
+    - "security"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-data-lifecycle"
+  does_not_own: []
+  conflicts_with: []

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

@@ -0,0 +1,29 @@
+name: qk-data-lifecycle-eval
+description: Đánh giá chất lượng quản lý Schema và an toàn Migration
+version: 8.3.1
+threshold: 90 # Tiêu chuẩn rất cao vì rủi ro mất mát dữ liệu (Data loss) là CRITICAL
+
+metrics:
+  - id: backward_compatible_migration
+    name: Migration tương thích ngược và an toàn
+    description: Agent có tạo migration an toàn, tránh phá vỡ dữ liệu đang chạy không?
+    weight: 40
+    criteria:
+      - Không sử dụng các lệnh destructive (DROP COLUMN, RENAME TABLE) một cách trực tiếp mà không qua chiến lược 3-phase (20đ)
+      - Các cột mới (add column) phải nullable hoặc có default value (10đ)
+      - Luôn định nghĩa hàm rollback `down()` (10đ)
+
+  - id: pii_and_security
+    name: Bảo mật dữ liệu PII (R-SEC-04)
+    description: Dữ liệu nhạy cảm có được mã hóa theo yêu cầu không?
+    weight: 30
+    criteria:
+      - Tự động nhận diện và áp dụng cơ chế hashing/encryption cho các cột chứa dữ liệu PII (Personal Identifiable Information) (30đ)
+
+  - id: layer_separation
+    name: Tách biệt Logic và Schema
+    description: Schema và truy vấn có được tách biệt khỏi Business Logic không?
+    weight: 30
+    criteria:
+      - Khai báo Schema (Model/Entity) rõ ràng trước khi viết truy vấn (15đ)
+      - Repository chỉ chứa truy vấn Database, không chứa Business Logic phức tạp (15đ)

package/.agents/skills/qk-db-optimizer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-db-optimizer
-version: 8.0.0
+version: 8.3.1
 status: stable
 description: "Tối ưu Database dựa trên bằng chứng: EXPLAIN → phân tích → index/join — không đoán mò."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
@@ -47,6 +47,7 @@ knowledge_scope:
     - query-optimization
   references:
     - architecture
+    - anti-patterns
 
 # ── V8: Verification ───────────────────────────────────────
 verification:
@@ -80,7 +81,7 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 # qk-db-optimizer — Database Performance Tuner
 
-> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
 ---
 
@@ -112,7 +113,7 @@ On missing precondition:
 | P | Issue Type | Action | Skip Threshold |
 |---|-----------|--------|----------------|
 | P1 | Sequential scan on large table (> 10k rows) | Add composite index | Never |
-| P2 | N+1 query pattern | Eager load / DataLoader | Budget < 30% |
+| P2 | N+1 query pattern | Eager load / DataLoader (Ưu tiên theo chuẩn dự án, không tự chế query lồng) | Budget < 30% |
 | P3 | Missing JOIN (multiple queries for related data) | Rewrite with JOIN | Budget < 50% |
 | P4 | SELECT * (over-fetching) | Select specific columns | Budget < 60% |
 

package/.agents/skills/qk-db-optimizer/capability.yaml

@@ -0,0 +1,22 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-db-optimizer"
+version: "8.3.1"
+description: "Tối ưu Database dựa trên bằng chứng: EXPLAIN → phân tích → index/join — không đoán mò."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "database-performance"
+    - "query-optimization"
+  references:
+    - "architecture"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-db-optimizer"
+  does_not_own: []
+  conflicts_with: []

package/.agents/skills/qk-db-optimizer/evals/scorecard.yaml

@@ -0,0 +1,28 @@
+name: qk-db-optimizer-eval
+description: Đánh giá chất lượng tối ưu hóa Database
+version: 8.3.1
+threshold: 85 # Yêu cầu dựa trên bằng chứng, không đoán mò
+
+metrics:
+  - id: evidence_based_analysis
+    name: Phân tích dựa trên bằng chứng (EXPLAIN)
+    description: Agent có chạy EXPLAIN/Analyze trước khi thêm Index/Sửa query không?
+    weight: 40
+    criteria:
+      - Bắt buộc phải có thông tin Slow query log hoặc chạy EXPLAIN trước khi hành động (20đ)
+      - Phân tích đúng nguyên nhân từ Plan (vd: Seq Scan, Nested Loop, N+1) (20đ)
+
+  - id: optimal_solution
+    name: Đưa ra giải pháp tối ưu
+    description: Giải pháp đưa ra có giải quyết triệt để và an toàn không?
+    weight: 35
+    criteria:
+      - Không tạo các index dư thừa (overlapping) (15đ)
+      - Xử lý triệt để bài toán N+1 bằng JOIN hoặc DataLoader theo đúng chuẩn dự án (20đ)
+
+  - id: verification
+    name: Kiểm chứng cải thiện (Verification)
+    description: Agent có cố gắng đo lường lại sau khi sửa không?
+    weight: 25
+    criteria:
+      - Đối chiếu/ước lượng mức độ cải thiện sau khi áp dụng giải pháp (25đ)

package/.agents/skills/qk-design-system-engineering/SKILL.md

@@ -1,112 +1,235 @@
----
-# ── Identity ───────────────────────────────────────────────
-name: qk-design-system-engineering
-version: 8.1.0
-status: experimental
-description: "Quản trị hệ thống thiết kế (Định nghĩa quy tắc hệ thống, tokens, các biến thể component)."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V8: Classification ─────────────────────────────────────
-type: capability
-
-intent:
-  - design-system
-  - tokens
-  - component-library
-  - accessibility
-
-complexity:
-  level: medium
-  criteria:
-    files_affected: "1-5"
-    has_behavior_change: true
-    has_external_dependency: false
-    has_breaking_change: false
-
-triggers:
-  - "định nghĩa design system"
-  - "cấu trúc token"
-  - "quy chuẩn ui"
-  - "variants"
-
-# ── V8: References ─────────────────────────────────────────
-workflow: feature-delivery
-
-rules:
-  - global
-  - coding
-
-tools:
-  - filesystem
-
-related_skills:
-  - qk-frontend-architecture
-
-knowledge_scope:
-  domain:
-    - design-system
-    - tokens
-  concepts:
-    - visual-consistency
-    - components-rules
-  references:
-    - architecture
-
-decision_boundary:
-  owns:
-    - tokens
-    - components rules
-    - design governance
-  does_not_own:
-    - page implementation
-    - business logic
-  conflicts_with:
-    - qk-ui-system-builder
-
-knowledge_dependencies:
-  - design-intelligence
-  - accessibility-guidelines
-  - component-patterns
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: feature
-
-selection:
-  priority: medium
-  confidence_threshold: 0.80
-
-examples: []
-learnings: []
-
-# ── V7 Runtime ─────────────────────────────────────────────
-execution_mode: deterministic
-cost: medium
-latency: medium
-risk: low
-side_effects: read_only
-produces: [report, tokens_definition]
-consumes: [user-description]
-
-token_budget:
-  max_files_read: 5
-  max_lines_per_read: 150
-  max_shell_commands: 0
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-design-system-engineering — Design System Governance
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-## Preconditions
-- [ ] Brand guidelines hoặc UX heuristics cơ bản đã có.
-
-## Scope
-- Định nghĩa các quy tắc hệ thống cho tokens, khoảng cách (spacing), màu sắc, phông chữ (typography).
-- Xác định quy chuẩn xây dựng component (composition, variants).
-- Thiết lập quy tắc A11y (Accessibility) ở cấp độ token.
-- KHÔNG thay thế việc viết UI code (`qk-ui-system-builder`). Skill này là "governance", không phải "implementation".
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-design-system-engineering
+version: 8.3.1
+status: experimental
+description: "Quản trị hệ thống thiết kế (Định nghĩa quy tắc hệ thống, tokens, các biến thể component)."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V8: Classification ─────────────────────────────────────
+type: capability
+
+intent:
+  - design-system
+  - tokens
+  - component-library
+  - accessibility
+
+complexity:
+  level: medium
+  criteria:
+    files_affected: "1-5"
+    has_behavior_change: true
+    has_external_dependency: false
+    has_breaking_change: false
+
+triggers:
+  - "định nghĩa design system"
+  - "cấu trúc token"
+  - "quy chuẩn ui"
+  - "variants"
+
+# ── V8: References ─────────────────────────────────────────
+workflow: feature-delivery
+
+rules:
+  - global
+  - coding
+
+tools:
+  - filesystem
+
+related_skills:
+  - qk-frontend-architecture
+
+knowledge_scope:
+  domain:
+    - design-system
+    - tokens
+  concepts:
+    - visual-consistency
+    - components-rules
+  references:
+    - architecture
+    - anti-patterns
+
+decision_boundary:
+  owns:
+    - tokens
+    - components rules
+    - design governance
+  does_not_own:
+    - page implementation
+    - business logic
+  conflicts_with:
+    - qk-ui-system-builder
+
+knowledge_dependencies:
+  - design-intelligence
+  - accessibility-guidelines
+  - component-patterns
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: feature
+
+selection:
+  priority: medium
+  confidence_threshold: 0.80
+
+examples: []
+learnings: []
+
+# ── V7 Runtime ─────────────────────────────────────────────
+execution_mode: deterministic
+cost: medium
+latency: medium
+risk: low
+side_effects: read_only
+produces: [report, tokens_definition]
+consumes: [user-description]
+
+token_budget:
+  max_files_read: 5
+  max_lines_per_read: 150
+  max_shell_commands: 0
+  stop_early: true
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-design-system-engineering — Design System Governance
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+## Preconditions
+- [ ] Brand guidelines hoặc UX heuristics cơ bản đã có.
+
+## Scope
+- Định nghĩa các quy tắc hệ thống cho tokens, khoảng cách (spacing), màu sắc, phông chữ (typography).
+- Xác định quy chuẩn xây dựng component (composition, variants).
+- Thiết lập quy tắc A11y (Accessibility) ở cấp độ token.
+- **Ngăn chặn triệt để UI Slop từ cấp độ Token (Không cung cấp màu tương phản quá thấp, kích thước quá bé).**
+- KHÔNG thay thế việc viết UI code (`qk-ui-system-builder`). Skill này là "governance", không phải "implementation".
+
+## Non-Goals
+- ❌ Provide implementation outside of Design System Governance scope
+- ❌ Override explicit user directives without explanation
+- ❌ Guess ambiguous requirements without asking
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | Core Design System Governance analysis and decision making | Never |
+| P2 | Validation of existing patterns | Budget < 30% |
+| P3 | Detailed documentation generation | Budget < 50% |
+| P4 | Edge case exploration | Budget < 70% |
+
+## Workflow
+
+### Phase 1 — Context Loading
+**Steps:**
+1. Read existing configuration and requirements related to Design System Governance.
+2. Check for missing preconditions.
+
+**Decision:**
+```
+IF context is clear
+  → Confidence: HIGH → go to Phase 2
+ELSE
+  → EXIT: BLOCKED — ask user
+```
+
+### Phase 2 — Analysis & Strategy
+**Steps:**
+1. Analyze the current state against Design System Governance best practices.
+2. Formulate strategy or audit report based on findings.
+
+**Decision:**
+```
+IF strategy/audit is complete
+  → Confidence: HIGH → go to Phase 3
+ELSE IF minor gaps exist
+  → Confidence: MEDIUM → proceed with assumptions noted
+```
+
+### Phase 3 — Finalization
+**Steps:**
+1. Generate final report or configuration.
+2. Prepare handoff data for subsequent skills.
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | All preconditions met, context fully understood | Proceed directly |
+| MEDIUM | Some context missing but safe defaults exist | Proceed and note assumptions |
+| LOW | Core requirements missing | EXIT: BLOCKED |
+
+## Severity (for findings)
+
+| Level | Definition |
+|-------|-----------|
+| CRITICAL | Severe violation of Design System Governance principles |
+| HIGH | Significant risk or technical debt |
+| MEDIUM | Suboptimal pattern but functional |
+| LOW | Minor style or documentation issue |
+
+## Evidence Format
+
+```
+[SEVERITY] Context/File
+Issue:      [what was found]
+Confidence: HIGH
+Recommendation: [actionable advice]
+```
+
+## Retry Policy
+```
+Task fails due to missing context
+  └─ Ask user for clarification
+       ├─ Provided → Retry Phase 1
+       └─ Not provided → EXIT: BLOCKED
+```
+
+## Escalation Rules
+
+```
+BLOCKED: Missing critical context for Design System Governance
+Missing:
+  - [Specific requirement]
+Questions:
+  1. Bạn có thể cung cấp thêm thông tin về yêu cầu này không?
+  2. Mục tiêu chính của bạn là gì?
+Recommended Assumptions: none
+```
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user or qk-orchestrator",
+  "required_fields": ["context"],
+  "optional_fields": ["existing_config"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "user or downstream skill",
+  "output_fields": ["strategy_report", "exit_code"]
+}
+```
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Design System Governance task completed successfully | Strategy/audit generated |
+| PARTIAL | Task completed with assumptions | Medium confidence |
+| BLOCKED | Missing context | Cannot proceed |
+| FAILED | Critical conflict or error | Unresolvable constraint |

package/.agents/skills/qk-design-system-engineering/capability.yaml

@@ -0,0 +1,25 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-design-system-engineering"
+version: "8.3.1"
+description: "Quản trị hệ thống thiết kế (Định nghĩa quy tắc hệ thống, tokens, các biến thể component)."
+tools:
+  - "filesystem"
+knowledge:
+  owns:
+    - "qk-design-system-engineering"
+  references:
+    - "architecture"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "tokens"
+    - "components rules"
+    - "design governance"
+  does_not_own:
+    - "page implementation"
+    - "business logic"
+  conflicts_with:
+    - "qk-ui-system-builder"

package/.agents/skills/qk-design-system-engineering/evals/scorecard.yaml

@@ -0,0 +1,27 @@
+name: qk-design-system-engineering-eval
+description: Đánh giá chất lượng quản trị hệ thống thiết kế (Design System)
+version: 8.3.1
+threshold: 85 # Đảm bảo sự nhất quán và ngăn chặn UI Slop từ gốc
+
+metrics:
+  - id: token_and_rules_definition
+    name: Định nghĩa Token và Quy tắc
+    description: Agent có thiết lập hệ thống token rõ ràng và nhất quán không?
+    weight: 40
+    criteria:
+      - Định nghĩa đầy đủ các quy tắc cho spacing, colors, typography (20đ)
+      - Ngăn chặn triệt để UI Slop bằng cách không cung cấp các token sai chuẩn (vd: độ tương phản quá thấp, font quá bé) (20đ)
+
+  - id: a11y_compliance
+    name: Tuân thủ Accessibility (A11y)
+    description: Các quy chuẩn có tính đến khả năng truy cập không?
+    weight: 30
+    criteria:
+      - Thiết lập quy tắc A11y ngay từ cấp độ Token (30đ)
+
+  - id: boundary_respect
+    name: Tôn trọng ranh giới (Decision Boundary)
+    description: Agent có giữ đúng vai trò Governance mà không lấn sân sang Implementation không?
+    weight: 30
+    criteria:
+      - Chỉ tập trung định nghĩa (Governance), KHÔNG thay thế việc viết UI code trực tiếp (nhường lại cho qk-ui-system-builder) (30đ)