ai-developer-skill-os 8.2.1 → 8.3.1

package/.agents/skills/qk-help/evals/scorecard.yaml

@@ -0,0 +1,13 @@
+name: qk-help-eval
+description: Đánh giá khả năng cung cấp thông tin hướng dẫn
+version: 8.3.1
+threshold: 100 # Kỹ năng đơn giản, yêu cầu độ chính xác cao khi cung cấp thông tin
+
+metrics:
+  - id: provide_accurate_info
+    name: Cung cấp thông tin chính xác
+    description: Agent có in ra đúng các lệnh và kiến trúc V8.3 không?
+    weight: 100
+    criteria:
+      - Hướng dẫn cú pháp ./qk-[skill-name] rõ ràng (50đ)
+      - Liệt kê chính xác danh sách các Quality Gates của hệ thống (50đ)

package/.agents/skills/qk-orchestrator/SKILL.md

@@ -1,7 +1,7 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-orchestrator
-version: 8.0.0
+version: 8.3.1
 status: stable
 description: "Điều hướng yêu cầu của người dùng đến đúng skill với kỷ luật thép — kiểm tra preconditions và routing table."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
@@ -55,6 +55,7 @@ knowledge_scope:
     - precondition-validation
   references:
     - all-skills                    # References registry to make decisions
+    - architecture
 
 # ── V8: Verification ───────────────────────────────────────
 verification:
@@ -86,7 +87,6 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
-
 ## Preconditions
 - [ ] User request is provided (any language)
 
@@ -96,7 +96,6 @@ On missing precondition:
   Message: "Vui lòng mô tả yêu cầu của bạn."
 ```
 
-
 ## Scope
 - ✅ Analyze user intent and route to the correct skill
 - ✅ Verify preconditions of target skill BEFORE delegating
@@ -108,7 +107,6 @@ On missing precondition:
 - ❌ Allow UI work without `DESIGN.md` verified
 - ❌ Allow logic work without context graph from `qk-context-loader`
 
-
 ## Priority Order
 
 | Priority | Check | Skip Threshold |
@@ -118,7 +116,6 @@ On missing precondition:
 | P3 | Check pipeline dependencies (e.g., context-loader first) | Never for logic tasks |
 | P4 | Estimate cost/latency for user info | Budget < 70% |
 
-
 ## Workflow
 
 ### Phase 1 — Intent Classification
@@ -145,7 +142,6 @@ ELSE IF no match
 - Skill identified → go to Phase 2
 - No matching skill → EXIT: BLOCKED
 
-
 ### Phase 2 — Precondition Check
 
 **Steps:**
@@ -165,7 +161,6 @@ ELSE
   → EXIT: BLOCKED
 ```
 
-
 ### Phase 3 — Pipeline Enforcement
 
 **Steps:**
@@ -188,30 +183,8 @@ Release tasks:
   [qk-validation-gate] → [qk-production-release]
 ```
 
-
 ## Routing Table (Quick Reference)
-Full table: see `references/routing-table.md`
-
-| Intent Keywords | Primary Skill | Pipeline |
-|----------------|---------------|----------|
-| bug, lỗi, error, broken, crash, fix, sửa | `qk-bug-resolution` | direct |
-| tính năng, feature, thêm, mới, add, implement | `qk-feature-delivery` | context-loader first |
-| UI, giao diện, design, component, layout, màn hình | `qk-ui-builder` | DESIGN.md check |
-| slow, query, index, N+1, performance DB | `qk-db-optimizer` | context-loader first |
-| deploy, release, production, CI/CD, build | `qk-production-release` | validation-gate first |
-| schema, migration, database, table, model | `qk-data-lifecycle` | context-loader first |
-| refactor, clean, SOLID, DRY, code quality | `qk-engineering-standard` | direct |
-| test, lint, validate, check quality | `qk-validation-gate` | direct |
-| upgrade, update thư viện, migrate library | `qk-system-evolution` | direct |
-| docs, documentation, README, comment | `qk-docs` | direct |
-| API, endpoint, route, contract | `qk-api-lifecycle` | context-loader first |
-| access, role, permission, RBAC, auth | `qk-access-policy` | direct |
-| AI, prompt, RAG, LLM, embedding | `qk-ai-builder` | direct |
-| design system, token, CSS variable | `qk-ui-system-builder` | DESIGN.md check |
-| project audit, health, tech debt | `qk-project-health` | direct |
-| new project, bootstrap, init | `qk-project-bootstrap` | direct |
-| memory, context, recall, lưu | `qk-project-memory` | direct |
-
+Single source of truth: `references/routing-table.md` — do not duplicate here. Read that file before routing.
 
 ## Confidence Model
 
@@ -221,7 +194,6 @@ Full table: see `references/routing-table.md`
 | MEDIUM | Multiple possible skills | Route to most likely, note ambiguity |
 | LOW | Request is too vague | Ask clarifying question |
 
-
 ## Escalation Rules
 
 ```
@@ -234,7 +206,6 @@ Questions:
 Recommended Assumptions: none — routing requires clear intent
 ```
 
-
 ## Handoff Contract
 
 ### Consumes
@@ -254,7 +225,6 @@ Recommended Assumptions: none — routing requires clear intent
 }
 ```
 
-
 ## Output Format
 
 ```
@@ -272,7 +242,6 @@ Preconditions:
 Exit Code:   SUCCESS
 ```
 
-
 ## Exit Codes
 
 | Code | Meaning | When |
@@ -284,4 +253,3 @@ Exit Code:   SUCCESS
 
 ---
 
-

package/.agents/skills/qk-orchestrator/capability.yaml

@@ -0,0 +1,22 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-orchestrator"
+version: "8.3.1"
+description: "Điều hướng yêu cầu của người dùng đến đúng skill với kỷ luật thép — kiểm tra preconditions và routing table."
+tools:
+  - "filesystem"
+knowledge:
+  owns:
+    - "task-routing"
+    - "skill-selection"
+    - "precondition-validation"
+  references:
+    - "all-skills"
+    - "architecture"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-orchestrator"
+  does_not_own: []
+  conflicts_with: []

package/.agents/skills/qk-orchestrator/evals/scorecard.yaml

@@ -0,0 +1,27 @@
+name: qk-orchestrator-eval
+description: Đánh giá khả năng điều phối và định tuyến tác vụ (Task Routing)
+version: 8.3.1
+threshold: 85 # Đóng vai trò kiểm soát luồng, yêu cầu độ chính xác cao
+
+metrics:
+  - id: intent_classification
+    name: Phân loại Intent chính xác
+    description: Agent có hiểu đúng yêu cầu và route đến đúng skill tương ứng không?
+    weight: 35
+    criteria:
+      - Phân tích và map đúng ý định người dùng với Routing Table (20đ)
+      - Đặt câu hỏi làm rõ nếu yêu cầu quá mờ nhạt thay vì đoán mò (15đ)
+
+  - id: precondition_enforcement
+    name: Kỷ luật kiểm tra Tiền điều kiện (Preconditions)
+    description: Cố tình route tác vụ khi thiếu thông tin hay chặn lại để yêu cầu cung cấp thêm?
+    weight: 35
+    criteria:
+      - Bắt buộc kiểm tra Preconditions của skill đích TRƯỚC KHI thực sự gọi skill đó (35đ)
+
+  - id: pipeline_execution
+    name: Thực thi Pipeline tuần tự
+    description: Có đảm bảo tuân thủ chuỗi phụ thuộc (e.g., context-loader -> feature-delivery) không?
+    weight: 30
+    criteria:
+      - Bắt buộc gọi các kỹ năng bổ trợ (như qk-context-loader cho Logic) trước khi bắt đầu công việc chính (30đ)

package/.agents/skills/qk-orchestrator/references/routing-table.md

@@ -1,5 +1,6 @@
 # Routing Table — qk-orchestrator V7.5
 
+> This is the ONLY routing table in the system. qk-orchestrator/SKILL.md must not contain a duplicate table.
 > Full intent → skill mapping. Updated whenever a new skill is added.
 
 ---
@@ -24,11 +25,22 @@
 | design system, token, CSS variable, design tokens | `qk-ui-system-builder` | DESIGN.md check |
 | project audit, health, tech debt, kiểm toán dự án | `qk-project-health` | direct |
 | new project, bootstrap, init, khởi tạo dự án | `qk-project-bootstrap` | direct |
-| help, list skills, danh sách, trợ giúp | `qk-orchestrator` | direct |
-| memory, context, recall, lưu ngữ cảnh | `qk-project-memory` | direct |
-| security, policy, authorization, bảo mật | `qk-policy-engine` | → redirect to `qk-access-policy` |
 | consume API, tích hợp API backend, gọi API từ FE | `qk-fe-api-integration` | `qk-context-loader` first |
 | UI audit, kiểm tra giao diện, anti-slop check | `qk-ui-audit` | DESIGN.md check |
+| metrics, telemetry, trace, agent observability, mô hình lỗi | `qk-agent-observability` | direct |
+| review code, kiểm toán, code review, PR | `qk-code-review` | direct |
+| graph, dependency, context, đọc hiểu architecture | `qk-context-loader` | direct |
+| design system rules, tokens structure, governance | `qk-design-system-engineering` | direct |
+| CI/CD, devops, pipeline, infrastructure, deployment strategy | `qk-devops-platform` | direct |
+| frontend architecture, file placement, routing strategy | `qk-frontend-architecture` | direct |
+| help, list skills, danh sách, trợ giúp | `qk-help` | direct |
+| orchestrate, định tuyến, phân loại yêu cầu | `qk-orchestrator` | direct |
+| product spec, requirement, tiêu chí chấp nhận | `qk-product-specification` | direct |
+| security, vulnerability scan, secret, OWASP | `qk-security-audit` | direct |
+| test strategy, mock, coverage, e2e, unit test | `qk-test-engineering` | direct |
+| web performance, accessibility, SEO, lighthouse | `qk-web-quality-gate` | direct |
+| memory, context, recall, lưu ngữ cảnh | `qk-project-memory` | direct |
+| security, policy, authorization, bảo mật | `qk-access-policy` | direct |
 
 ---
 

package/.agents/skills/qk-product-specification/SKILL.md

@@ -1,130 +1,253 @@
----
-# ── Identity ───────────────────────────────────────────────
-name: qk-product-specification
-version: 8.1.0
-status: experimental
-description: "Product thinking (Idea → Requirement → Acceptance criteria → Technical spec)."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V8: Classification ─────────────────────────────────────
-type: capability
-
-intent:
-  - product-specification
-  - requirement-analysis
-  - acceptance-criteria
-  - technical-spec
-
-complexity:
-  level: medium
-  criteria:
-    files_affected: "1-3"
-    has_behavior_change: false
-    has_external_dependency: false
-    has_breaking_change: false
-
-triggers:
-  - "viết spec"
-  - "phân tích yêu cầu"
-  - "ý tưởng sản phẩm"
-  - "acceptance criteria"
-
-# ── V8: References ─────────────────────────────────────────
-workflow: spec-driven-development
-
-rules:
-  - global
-  - coding
-
-tools:
-  - filesystem
-
-related_skills:
-  - qk-feature-delivery
-
-knowledge_scope:
-  domain:
-    - product-requirements
-    - technical-specifications
-  concepts:
-    - user-story
-    - acceptance-criteria
-  references:
-    - architecture
-
-decision_boundary:
-  owns:
-    - technical-ready specification
-    - acceptance criteria
-  does_not_own:
-    - market research
-    - pricing
-    - roadmap
-  conflicts_with: []
-  delegates_to:
-    - qk-feature-delivery
-
-# ── 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, specification]
-consumes: [user-description]
-
-token_budget:
-  max_files_read: 3
-  max_lines_per_read: 150
-  max_shell_commands: 0
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-product-specification — Product Specifier
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-## Preconditions
-- [ ] Tuân thủ workflow `spec-driven-development`.
-
-## Scope
-- Tiếp nhận Idea ban đầu từ user, thực hiện phân tích yêu cầu (Requirement Analysis).
-- Xác định và làm rõ ranh giới của tính năng.
-- Lên danh sách Acceptance Criteria (Tiêu chí nghiệm thu).
-- Đóng gói thành Technical Spec (đặc tả kỹ thuật) để chuẩn bị cho quá trình code (Plan & Implementation).
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-product-specification
+version: 8.3.1
+status: experimental
+description: "Product thinking (Idea → Requirement → Acceptance criteria → Technical spec)."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V8: Classification ─────────────────────────────────────
+type: capability
+
+intent:
+  - product-specification
+  - requirement-analysis
+  - acceptance-criteria
+  - technical-spec
+
+complexity:
+  level: medium
+  criteria:
+    files_affected: "1-3"
+    has_behavior_change: false
+    has_external_dependency: false
+    has_breaking_change: false
+
+triggers:
+  - "viết spec"
+  - "phân tích yêu cầu"
+  - "ý tưởng sản phẩm"
+  - "acceptance criteria"
+
+# ── V8: References ─────────────────────────────────────────
+workflow: spec-driven-development
+
+rules:
+  - global
+  - coding
+
+tools:
+  - filesystem
+
+related_skills:
+  - qk-feature-delivery
+
+knowledge_scope:
+  domain:
+    - product-requirements
+    - technical-specifications
+  concepts:
+    - user-story
+    - acceptance-criteria
+  references:
+    - architecture
+    - security
+    - anti-patterns
+
+decision_boundary:
+  owns:
+    - technical-ready specification
+    - acceptance criteria
+  does_not_own:
+    - market research
+    - pricing
+    - roadmap
+  conflicts_with: []
+  delegates_to:
+    - qk-feature-delivery
+
+# ── 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, specification]
+consumes: [user-description]
+
+token_budget:
+  max_files_read: 3
+  max_lines_per_read: 150
+  max_shell_commands: 0
+  stop_early: true
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-product-specification — Product Specifier
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+## Preconditions
+- [ ] Tuân thủ workflow `spec-driven-development`.
+
+## Scope
+- Tiếp nhận Idea ban đầu từ user, thực hiện phân tích yêu cầu (Requirement Analysis).
+- Xác định và làm rõ ranh giới của tính năng.
+- Lên danh sách Acceptance Criteria (Tiêu chí nghiệm thu). **BẮT BUỘC có Security Acceptance Criteria để phòng ngừa rủi ro theo R-SEC-04 (Zero-Trust).**
+- Đóng gói thành Technical Spec (đặc tả kỹ thuật) để chuẩn bị cho quá trình code (Plan & Implementation).
+
+## Non-Goals
+- ❌ Provide implementation outside of Product Thinking & Requirements scope
+- ❌ Override explicit user directives without explanation
+- ❌ Guess ambiguous requirements without asking
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | Core Product Thinking & Requirements 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 Product Thinking & Requirements.
+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 Product Thinking & Requirements 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 Product Thinking & Requirements 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 Product Thinking & Requirements
+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 | Product Thinking & Requirements 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-product-specification/capability.yaml

@@ -0,0 +1,27 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-product-specification"
+version: "8.3.1"
+description: "Product thinking (Idea → Requirement → Acceptance criteria → Technical spec)."
+tools:
+  - "filesystem"
+knowledge:
+  owns:
+    - "qk-product-specification"
+  references:
+    - "architecture"
+    - "security"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "technical-ready specification"
+    - "acceptance criteria"
+  does_not_own:
+    - "market research"
+    - "pricing"
+    - "roadmap"
+  conflicts_with: []
+  delegates_to:
+    - "qk-feature-delivery"

package/.agents/skills/qk-product-specification/evals/scorecard.yaml

@@ -0,0 +1,27 @@
+name: qk-product-specification-eval
+description: Đánh giá Tư duy Sản phẩm và Phân tích Yêu cầu
+version: 8.3.1
+threshold: 85 # Đảm bảo Spec rõ ràng và chứa đầy đủ tiêu chí bảo mật
+
+metrics:
+  - id: requirement_clarification
+    name: Làm rõ Yêu cầu (Requirement Analysis)
+    description: Agent có phân tích sâu ý tưởng để xác định ranh giới tính năng không?
+    weight: 35
+    criteria:
+      - Từ một Idea mơ hồ, bóc tách thành các gạch đầu dòng rõ ràng về scope (những gì làm và KHÔNG làm) (35đ)
+
+  - id: acceptance_criteria_quality
+    name: Chất lượng Acceptance Criteria (AC)
+    description: Các tiêu chí nghiệm thu có định lượng và bao phủ các trường hợp không?
+    weight: 35
+    criteria:
+      - Liệt kê các AC mạch lạc, testable (kiểm thử được) (15đ)
+      - BẮT BUỘC phải có tiêu chí bảo mật (Security AC) theo chuẩn R-SEC-04 (Zero Trust) (20đ)
+
+  - id: technical_readiness
+    name: Mức độ sẵn sàng cho Kỹ thuật (Technical Spec)
+    description: Spec viết ra có đủ độ chi tiết để delegate cho qk-feature-delivery chưa?
+    weight: 30
+    criteria:
+      - Tài liệu đầu ra được cấu trúc chặt chẽ (Technical Ready) không để lập trình viên phải đoán mò (30đ)