ai-developer-skill-os 8.2.1 → 8.3.0

package/.agents/skills/qk-frontend-architecture/SKILL.md

@@ -1,134 +1,258 @@
----
-# ── Identity ───────────────────────────────────────────────
-name: qk-frontend-architecture
-version: 8.1.0
-status: experimental
-description: "Công cụ quyết định kiến trúc Frontend (Chiến lược component, quản lý state, định tuyến)."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V8: Classification ─────────────────────────────────────
-type: capability
-
-intent:
-  - frontend-architecture
-  - component-strategy
-  - state-management
-
-complexity:
-  level: high
-  criteria:
-    files_affected: "5-10"
-    has_behavior_change: true
-    has_external_dependency: true
-    has_breaking_change: false
-
-triggers:
-  - "cấu trúc frontend"
-  - "thiết kế component"
-  - "quản lý state"
-  - "kiến trúc react"
-
-# ── V8: References ─────────────────────────────────────────
-workflow: feature-delivery
-
-rules:
-  - global
-  - coding
-
-tools:
-  - filesystem
-
-related_skills:
-  - qk-design-system-engineering
-  - qk-web-quality-gate
-
-knowledge_scope:
-  domain:
-    - react
-    - frontend-architecture
-    - state-management
-  concepts:
-    - component-hierarchy
-    - routing-strategy
-  references:
-    - architecture
-
-decision_boundary:
-  owns:
-    - architecture decisions
-    - state strategy
-  does_not_own:
-    - component implementation
-    - pixel styling
-  conflicts_with:
-    - qk-ui-builder
-  delegates_to:
-    - qk-ui-builder
-    - qk-ui-system-builder
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: feature
-
-lifecycle:
-  promotion_gate:
-    requirements:
-      tests:
-        minimum_pass_rate: 0.95
-      usage:
-        minimum_runs: 20
-      conflicts:
-        zero_boundary_violation: true
-      evidence:
-        required:
-          - evaluation_report
-          - usage_history
-          - boundary_audit
-  demotion_gate:
-    triggers:
-      - repeated_failure
-      - boundary_violation
-      - outdated_reference
-    action:
-      change_status: "stable -> experimental"
-
-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, architecture_plan]
-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-frontend-architecture — Frontend Architect
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-## Preconditions
-- [ ] Xác định framework (React/Next.js/Vue, v.v.).
-- [ ] Phạm vi hệ thống frontend cần phân tích rõ ràng.
-
-## Scope
-- Đánh giá kiến trúc hiện tại của dự án Frontend.
-- Đưa ra quyết định chia nhỏ (breakdown) components.
-- Lựa chọn mô hình quản lý state (Global vs Local, Client vs Server).
-- Thiết kế hệ thống routing.
-- KHÔNG thay thế việc viết UI code (`qk-ui-builder`). Chỉ giới hạn ở quyết định kiến trúc.
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-frontend-architecture
+version: 8.1.0
+status: experimental
+description: "Công cụ quyết định kiến trúc Frontend (Chiến lược component, quản lý state, định tuyến)."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V8: Classification ─────────────────────────────────────
+type: capability
+
+intent:
+  - frontend-architecture
+  - component-strategy
+  - state-management
+
+complexity:
+  level: high
+  criteria:
+    files_affected: "5-10"
+    has_behavior_change: true
+    has_external_dependency: true
+    has_breaking_change: false
+
+triggers:
+  - "cấu trúc frontend"
+  - "thiết kế component"
+  - "quản lý state"
+  - "kiến trúc react"
+
+# ── V8: References ─────────────────────────────────────────
+workflow: feature-delivery
+
+rules:
+  - global
+  - coding
+
+tools:
+  - filesystem
+
+related_skills:
+  - qk-design-system-engineering
+  - qk-web-quality-gate
+
+knowledge_scope:
+  domain:
+    - react
+    - frontend-architecture
+    - state-management
+  concepts:
+    - component-hierarchy
+    - routing-strategy
+  references:
+    - architecture
+    - coding
+    - anti-patterns
+
+decision_boundary:
+  owns:
+    - architecture decisions
+    - state strategy
+  does_not_own:
+    - component implementation
+    - pixel styling
+  conflicts_with:
+    - qk-ui-builder
+  delegates_to:
+    - qk-ui-builder
+    - qk-ui-system-builder
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: feature
+
+lifecycle:
+  promotion_gate:
+    requirements:
+      tests:
+        minimum_pass_rate: 0.95
+      usage:
+        minimum_runs: 20
+      conflicts:
+        zero_boundary_violation: true
+      evidence:
+        required:
+          - evaluation_report
+          - usage_history
+          - boundary_audit
+  demotion_gate:
+    triggers:
+      - repeated_failure
+      - boundary_violation
+      - outdated_reference
+    action:
+      change_status: "stable -> experimental"
+
+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, architecture_plan]
+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-frontend-architecture — Frontend Architect
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+## Preconditions
+- [ ] Xác định framework (React/Next.js/Vue, v.v.).
+- [ ] Phạm vi hệ thống frontend cần phân tích rõ ràng.
+
+## Scope
+- Đánh giá kiến trúc hiện tại của dự án Frontend.
+- Đưa ra quyết định chia nhỏ (breakdown) components.
+- Lựa chọn mô hình quản lý state (Global vs Local, Client vs Server). **BẮT BUỘC: Ưu tiên TanStack Query cho Server State; Zustand/Context cho Client State. Tránh Redux trừ khi legacy project bắt buộc.**
+- Thiết kế hệ thống routing. **BẮT BUỘC: Sử dụng Next.js App Router (nếu framework là Next.js) hoặc TanStack Router (cho SPA).**
+- KHÔNG thay thế việc viết UI code (`qk-ui-builder`). Chỉ giới hạn ở quyết định kiến trúc.
+- BẮT BUỘC tuân thủ `anti-patterns.md` (đặc biệt R-C-09) khi thiết kế luồng dữ liệu.
+
+## Non-Goals
+- ❌ Provide implementation outside of Frontend Macro Architecture scope
+- ❌ Override explicit user directives without explanation
+- ❌ Guess ambiguous requirements without asking
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | Core Frontend Macro Architecture 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 Frontend Macro Architecture.
+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 Frontend Macro Architecture 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 Frontend Macro Architecture 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 Frontend Macro Architecture
+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 | Frontend Macro Architecture 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-help/SKILL.md

@@ -77,169 +77,31 @@ token_budget:
 exit_codes: [SUCCESS]
 ---
 
-# qk-help — Skill Directory V7.5
+# 🆘 V8.3 Skill System Help
 
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+> Lệnh: `./qk-help`
 
-When triggered, display this reference and exit with SUCCESS.
+Hệ thống AI Developer Skin V8.3 (Zero-Trust & Anti-Slop Architecture) sử dụng kiến trúc **Governed Capabilities** thay vì Prompt Engineering truyền thống. Mỗi kỹ năng (skill) là một module độc lập, có Decision Boundary (giới hạn quyền hạn) và Token Budget (ngân sách thực thi) riêng.
 
----
-
-## Scope
-- ✅ Display available skills and their purposes
-- ✅ Show common pipelines and best practices
-- ✅ Provide quick reference for skill commands
-
-## Non-Goals
-- ❌ Execute any skill — only display information
-- ❌ Modify project files or configuration
-- ❌ Answer questions outside the skill system
-
----
-
-## Preconditions
-- [ ] User requests help or list of skills
-
-```
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "Vui lòng hỏi trợ giúp hoặc liệt kê skills."
-```
-
----
-
-## Scope
-- ✅ Display available skills and their purposes
-- ✅ Show common pipelines and best practices
-- ✅ Provide quick reference for skill commands
-
-## Non-Goals
-- ❌ Execute any skill — only display information
-- ❌ Modify project files or configuration
-- ❌ Answer questions outside the skill system
-
----
-
-## Priority Order
-
-| Priority | Task | Skip Threshold |
-|----------|------|----------------|
-| P1 | List all available skills | Never |
-| P2 | Show common pipelines | Never |
-| P3 | Provide usage examples | Never |
-
----
-
-## Workflow
-
-### Phase 1 — Display Skills
-
-**Steps:**
-1. Read `.agents/registry/skills-index.yml` to get active skill list
-2. Format as table: Command | Purpose | Cost
-3. Display common pipelines
-
-**Exit When:**
-- Help displayed → EXIT: SUCCESS
-
----
-
-## Confidence Model
-
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | .agents/registry/skills-index.yml readable | Display directly |
-| MEDIUM | .agents/registry/skills-index.yml partially readable | Display what's available |
-| LOW | Cannot access .agents/registry/skills-index.yml | EXIT: BLOCKED |
-
----
-
-## Severity
-
-| Level | Definition | Example |
-|-------|-----------|---------|
-| CRITICAL | N/A — this skill is read-only | — |
-| HIGH | N/A — this skill is read-only | — |
-| MEDIUM | N/A — this skill is read-only | — |
-| LOW | N/A — this skill is read-only | — |
-
----
-
-## Evidence Format
-
-```
-[INFO] qk-help
-Message: [help content displayed]
-Confidence: HIGH
-```
-
----
-
-## Retry Policy
-
-```
-Display fails
-  └─ Check if .agents/registry/skills-index.yml is accessible
-       ├─ Accessible → retry display
-       └─ Not accessible → EXIT: BLOCKED
-```
-
----
+## 🛠 Cách Kích Hoạt Kỹ Năng
+Gõ `./qk-[tên-skill] [yêu cầu của bạn]`
 
-## Escalation Rules
+**Ví dụ:**
+- `./qk-ui-builder tạo trang login với Tailwind`
+- `./qk-feature-delivery thêm tính năng quên mật khẩu`
+- `./qk-bug-resolution fix lỗi hydration mismatch ở trang chủ`
+- `./qk-project-health đánh giá codebase`
 
-```
-BLOCKED: Cannot access .agents/registry/skills-index.yml
-Missing:
-  - .agents/registry/skills-index.yml file
-Questions:
-  1. Bạn cần hỗ trợ gì? (liệt kê skills / hướng dẫn dùng)
-```
+## 🚦 V8.3 Quality Gates
+Hệ thống áp dụng các checkpoint nghiêm ngặt. Nếu không qua được, AI sẽ tự động Block:
+1. **Validation Gate:** `qk-validation-gate` chạy lint/test/type-check.
+2. **Release Gate:** `qk-production-release` kiểm tra 8 cổng trước khi deploy.
+3. **Web Quality Gate:** `qk-web-quality-gate` check A11y, SEO, Performance.
+4. **UI Audit Gate:** `qk-ui-audit` check Anti-Slop (R-C-09).
+5. **Security Gate:** Tất cả các luồng phải tuân thủ Zero-Trust (R-SEC-04).
 
----
-
-## Handoff Contract
-
-### Consumes
-```json
-{
-  "from": "user",
-  "required_fields": ["help_request"],
-  "optional_fields": ["specific_skill"]
-}
-```
-
-### Produces
-```json
-{
-  "to": "user",
-  "output_fields": ["skill_list", "pipelines", "usage_examples"],
-  "exit_code": "SUCCESS"
-}
-```
-
----
-
-## Output Format
-
-```
-📚 Help — Available Skills
-─────────────────────────────────────────────────
-[table of skills]
-
-Common Pipelines:
-[common workflows]
+## 📋 Xem Danh Sách Kỹ Năng
+Các kỹ năng được chia theo nhóm (Capabilities).
+Đọc file `.agents/skills/skills.json` hoặc thư mục `.agents/skills/` để xem toàn bộ danh sách.
 
-Exit Code: SUCCESS
-```
-
----
-
-## Exit Codes
-
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Help displayed successfully | Normal completion |
-| BLOCKED | Cannot access .agents/registry/skills-index.yml | Setup required |
-
----
+*Mẹo: Nếu không biết dùng skill nào, hãy nhờ `qk-orchestrator` phân tích yêu cầu của bạn.*