ai-developer-skill-os 8.2.1 → 8.3.1

package/.agents/skills/qk-web-quality-gate/capability.yaml

@@ -0,0 +1,24 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-web-quality-gate"
+version: "8.3.1"
+description: "Kiểm toán tổng thể chất lượng Web: Accessibility (A11y), SEO, Web Performance, Security, UX Heuristics."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "qk-web-quality-gate"
+  references:
+    - "architecture"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "lighthouse audit"
+    - "accessibility review"
+    - "performance audit"
+    - "seo audit"
+  does_not_own:
+    - "ui component implementation"
+  conflicts_with: []

package/.agents/skills/qk-web-quality-gate/evals/scorecard.yaml

@@ -0,0 +1,26 @@
+name: qk-web-quality-gate-eval
+description: Đánh giá chất lượng tổng thể của Web (Performance, SEO, A11y, UX)
+version: 8.3.1
+threshold: 85 # Đảm bảo đo lường đầy đủ 4 trục chất lượng của ứng dụng Web
+
+metrics:
+  - id: core_web_vitals_focus
+    name: Phân tích Core Web Vitals
+    description: Có đánh giá đúng các chỉ số ảnh hưởng đến trải nghiệm (LCP, CLS, INP) không?
+    weight: 40
+    criteria:
+      - Báo cáo rõ ràng về kích thước Bundle, chiến lược Lazy loading và tối ưu hình ảnh (40đ)
+
+  - id: seo_and_accessibility
+    name: Kiểm tra SEO & A11y
+    description: Web có thân thiện với bot tìm kiếm và người khuyết tật không?
+    weight: 35
+    criteria:
+      - Quét Semantic HTML, Meta tags, và các rào cản truy cập ARIA (35đ)
+
+  - id: actionable_recommendations
+    name: Khuyến nghị thực tiễn (Actionable)
+    description: Các đề xuất tối ưu có khả thi để lập trình viên thực hiện ngay không?
+    weight: 25
+    criteria:
+      - Không chỉ ra lỗi chung chung mà chỉ định rõ cách fix (vd: "Thêm loading='lazy' vào thẻ img dòng 15") (25đ)

package/.agents/workflows/_schema.yml

@@ -1,109 +1,146 @@
-# Workflow Schema — V8 Standard
-# Every workflow YAML file MUST conform to this schema.
-# Version: 8.0.0
-
-schema_version: 8.0.0
-
-# ── Required top-level fields ──────────────────────────────
-required:
-  - name          # string: workflow identifier (kebab-case)
-  - version       # semver: 8.x.x
-  - description   # string: one sentence
-  - owner         # object: {type, maintained_by} — who owns this workflow
-  - steps         # array: minimum 2 steps
-  - escalation    # object: retry + on_failure
-
-# ── Owner field structure ───────────────────────────────────
-owner_fields:
-  type:           # string: engineering | security | ux | data | devops
-  maintained_by:  # string: team or person identifier
-
-# ── Required fields per step ────────────────────────────────
-step_required:
-  - id            # string: unique within workflow (snake_case)
-  - name          # string: human-readable step name
-  - purpose       # string: WHAT the step achieves (not HOW)
-  - inputs        # array: what this step needs to start
-  - outputs       # array: what this step produces when done
-  - required      # bool: true = cannot be skipped
-
-# ── Optional fields per step ────────────────────────────────
-step_optional:
-  - skip_if       # string: condition under which step can be skipped
-  - exit_on_fail  # enum: BLOCKED | PARTIAL | FAILED
-  - min_confidence # enum: HIGH | MEDIUM (default: HIGH)
-  - actions       # array: hints for HOW to achieve the purpose
-
-# ── Complexity definitions ──────────────────────────────────
-complexity_levels:
-  low:
-    files_affected: "1"
-    has_behavior_change: false
-    has_external_dependency: false
-    has_breaking_change: false
-    examples: ["fix typo", "rename variable", "add comment"]
-
-  medium:
-    files_affected: "2-5"
-    has_behavior_change: true
-    has_external_dependency: false
-    has_breaking_change: false
-    examples: ["fix bug", "add feature to existing module", "refactor function"]
-
-  high:
-    files_affected: "5+"
-    has_behavior_change: true
-    has_external_dependency: true
-    has_breaking_change: false
-    examples: ["add new API endpoint", "database migration", "new component with state"]
-
-  critical:
-    files_affected: "many"
-    has_behavior_change: true
-    has_external_dependency: true
-    has_breaking_change: true
-    examples: ["architecture change", "breaking API change", "auth system overhaul"]
-
-# ── Verification profiles ────────────────────────────────────
-verification_profiles:
-  bug-fix:
-    - regression_check    # Does the fix break anything else?
-    - root_cause_fixed    # Is the real cause addressed (not patched)?
-    - lint_clean          # No lint errors introduced
-    - test_if_available   # Run related tests if they exist
-
-  refactor:
-    - behavior_unchanged  # External behavior identical before/after
-    - test_pass           # All existing tests still pass
-    - lint_clean
-    - no_new_complexity   # Cyclomatic complexity not increased
-
-  feature:
-    - acceptance_criteria # Does it meet the stated requirements?
-    - test_coverage       # New logic has tests
-    - integration_check   # Works with existing system
-    - lint_clean
-
-  documentation:
-    - accuracy            # Content matches actual code behavior
-    - completeness        # All required sections present
-    - no_broken_links     # References are valid
-
-  review:
-    - findings_have_evidence   # Each finding has file+line+quote
-    - severity_justified       # Severity level is appropriate
-    - actionable_suggestions   # Each finding has a fix suggestion
-
-# ── Escalation schema ────────────────────────────────────────
-escalation_required: true
-escalation_fields:
-  required:
-    - max_retries    # int: max retry attempts (recommended: 2)
-    - on_failure     # string: what to do when all retries exhausted
-
-# ── Exit codes ───────────────────────────────────────────────
-exit_codes:
-  SUCCESS:  "Task completed and verified"
-  BLOCKED:  "Precondition not met — waiting for input"
-  FAILED:   "Execution failed after max_retries"
-  PARTIAL:  "Partially completed — output + reason provided"
+# Workflow Schema — V8 Standard
+# Every workflow YAML file MUST conform to this schema.
+# Version: 8.3.0
+
+schema_version: 8.3.0
+
+# ── Required top-level fields ──────────────────────────────
+required:
+  - name          # string: workflow identifier (kebab-case)
+  - version       # semver: 8.x.x
+  - description   # string: one sentence
+  - owner         # object: {type, maintained_by} — who owns this workflow
+  - steps         # array: minimum 2 steps
+  - escalation    # object: retry + on_failure
+
+# ── Optional top-level fields ───────────────────────────────
+optional:
+  - verification_profile   # string: key into verification_profiles table below
+  - triggers               # array: keywords to auto-select workflow
+  - ide_binding            # object: {slash_command, aliases} — maps workflow to an IDE command
+
+# ── IDE binding field structure ─────────────────────────────
+ide_binding_fields:
+  slash_command:  # string: e.g. "/fix-bug" — primary command to invoke this workflow
+  aliases:        # array: alternate strings that also trigger it
+
+# ── Owner field structure ───────────────────────────────────
+owner_fields:
+  type:           # string: engineering | security | ux | data | devops
+  maintained_by:  # string: team or person identifier
+
+# ── Required fields per step ────────────────────────────────
+step_required:
+  - id            # string: unique within workflow (snake_case)
+  - name          # string: human-readable step name
+  - purpose       # string: WHAT the step achieves (not HOW)
+  - inputs        # array: what this step needs to start
+  - outputs       # array: what this step produces when done
+  - required      # bool: true = cannot be skipped
+
+# ── Optional fields per step ────────────────────────────────
+step_optional:
+  - skip_if       # string: condition under which step can be skipped
+  - exit_on_fail  # enum: BLOCKED | PARTIAL | FAILED
+  - min_confidence # enum: HIGH | MEDIUM (default: HIGH)
+  - actions       # array: hints for HOW to achieve the purpose
+  - human_checkpoint  # object: {condition, message} — pause and wait for human approval before proceeding past this step
+  - context_budget    # int: max lines of code that should be read in this step (prevent token overflow)
+
+# ── Human checkpoint field structure ────────────────────────
+human_checkpoint_fields:
+  condition:  # string: when this checkpoint triggers, e.g. "any CRITICAL finding present"
+  message:    # string: what to show the human when asking for approval
+
+# ── Complexity definitions ──────────────────────────────────
+complexity_levels:
+  low:
+    files_affected: "1"
+    has_behavior_change: false
+    has_external_dependency: false
+    has_breaking_change: false
+    examples: ["fix typo", "rename variable", "add comment"]
+
+  medium:
+    files_affected: "2-5"
+    has_behavior_change: true
+    has_external_dependency: false
+    has_breaking_change: false
+    examples: ["fix bug", "add feature to existing module", "refactor function"]
+
+  high:
+    files_affected: "5+"
+    has_behavior_change: true
+    has_external_dependency: true
+    has_breaking_change: false
+    examples: ["add new API endpoint", "database migration", "new component with state"]
+
+  critical:
+    files_affected: "many"
+    has_behavior_change: true
+    has_external_dependency: true
+    has_breaking_change: true
+    examples: ["architecture change", "breaking API change", "auth system overhaul"]
+
+# ── Verification profiles ────────────────────────────────────
+verification_profiles:
+  bug-fix:
+    - regression_check    # Does the fix break anything else?
+    - root_cause_fixed    # Is the real cause addressed (not patched)?
+    - lint_clean          # No lint errors introduced
+    - test_if_available   # Run related tests if they exist
+    - security_boundary_check # Ensure R-SEC-04 is respected
+
+  refactor:
+    - behavior_unchanged  # External behavior identical before/after
+    - test_pass           # All existing tests still pass
+    - lint_clean
+    - no_new_complexity   # Cyclomatic complexity not increased
+    - anti_slop_compliance # Meets R-C-09 zero-slop standard
+
+  feature:
+    - acceptance_criteria # Does it meet the stated requirements?
+    - test_coverage       # New logic has tests
+    - integration_check   # Works with existing system
+    - lint_clean
+    - anti_slop_compliance # Meets R-C-09 zero-slop standard
+    - security_boundary_check # Enforces R-SEC-04
+
+  documentation:
+    - accuracy            # Content matches actual code behavior
+    - completeness        # All required sections present
+    - no_broken_links     # References are valid
+
+  review:
+    - findings_have_evidence   # Each finding has file+line+quote
+    - severity_justified       # Severity level is appropriate
+    - actionable_suggestions   # Each finding has a fix suggestion
+
+  security-audit:
+    - no_unverified_critical   # No CRITICAL risk left without a recommendation
+    - secret_scan_complete     # Secret scan actually ran, not skipped
+    - fix_confirmed            # Reported vulnerabilities re-checked after remediation
+
+  skill-evolution:
+    - improvement_schema_valid # Proposal passes validate-skills.js
+    - regression_free          # Success rate not lower than baseline
+    - change_justified         # Each change traces to a failure_pattern
+
+  spec-driven:
+    - spec_matches_code        # Implementation matches technical_spec
+    - edge_cases_covered       # Edge cases from spec are handled
+    - acceptance_criteria      # Verify step confirms criteria met
+
+# ── Escalation schema ────────────────────────────────────────
+escalation_required: true
+escalation_fields:
+  required:
+    - max_retries    # int: max retry attempts (recommended: 2)
+    - on_failure     # string: what to do when all retries exhausted
+
+# ── Exit codes ───────────────────────────────────────────────
+exit_codes:
+  SUCCESS:  "Task completed and verified"
+  BLOCKED:  "Precondition not met — waiting for input"
+  FAILED:   "Execution failed after max_retries"
+  PARTIAL:  "Partially completed — output + reason provided"

package/.agents/workflows/bug-resolution.yml

@@ -1,101 +1,121 @@
-name: bug-resolution
-version: 8.0.0
-description: "Pipeline chuẩn để diagnose và fix bugs theo chu trình: Observe → Hypothesize → Evidence → Patch → Verify."
-
-owner:
-  type: engineering
-  maintained_by: qk-team
-
-verification_profile: bug-fix
-
-steps:
-  - id: observe
-    name: "Thu thập triệu chứng"
-    purpose: "Xác định chính xác bug xảy ra ở đâu và biểu hiện thế nào"
-    required: true
-    skip_if: "Stack trace + affected file đã được cung cấp đầy đủ"
-    inputs:
-      - error_message
-      - stack_trace
-      - user_description
-    outputs:
-      - affected_file
-      - affected_line_range
-      - error_signature
-    actions:
-      - "Đọc error message và stack trace"
-      - "Xác định file và line range bị ảnh hưởng"
-      - "Mô tả triệu chứng bằng ngôn ngữ kỹ thuật"
-    exit_on_fail: BLOCKED
-
-  - id: hypothesize
-    name: "Đặt giả thuyết nguyên nhân"
-    purpose: "Xác định top 3 nguyên nhân có thể, xếp theo xác suất"
-    required: true
-    skip_if: null
-    inputs:
-      - error_signature
-      - affected_file
-    outputs:
-      - hypothesis_list      # Ordered list: [H1 (most likely), H2, H3]
-      - selected_hypothesis  # H1 unless evidence suggests otherwise
-    min_confidence: HIGH
-    actions:
-      - "List 3 nguyên nhân có thể gây ra triệu chứng này"
-      - "Xếp hạng theo xác suất dựa trên stack trace"
-      - "Chọn H1 để kiểm chứng trước"
-
-  - id: evidence
-    name: "Tìm bằng chứng xác nhận"
-    purpose: "Xác nhận hoặc loại bỏ hypothesis bằng code thực tế"
-    required: true
-    skip_if: null
-    inputs:
-      - selected_hypothesis
-      - affected_file
-    outputs:
-      - confirmed_root_cause   # File + line + quoted code
-      - evidence_quote         # Exact code causing the bug
-    min_confidence: HIGH
-    actions:
-      - "Dùng grep_search để tìm pattern liên quan"
-      - "Dùng view_file[StartLine:EndLine] để đọc section cụ thể"
-      - "Quote chính xác đoạn code gây bug"
-    exit_on_fail: PARTIAL
-
-  - id: patch
-    name: "Áp dụng fix"
-    purpose: "Sửa root cause, không chỉ patch triệu chứng"
-    required: true
-    skip_if: null
-    inputs:
-      - confirmed_root_cause
-      - evidence_quote
-    outputs:
-      - patched_files    # List of files modified
-      - diff_summary     # What changed and why
-    actions:
-      - "Edit source file trực tiếp với replace_file_content hoặc multi_replace_file_content"
-      - "Không tạo wrapper script"
-      - "Không dùng ?. hoặc ! để silence lỗi"
-      - "Fix root cause, không patch bề mặt"
-
-  - id: verify
-    name: "Xác minh fix"
-    purpose: "Xác nhận bug đã được fix và không có regression"
-    required: true
-    skip_if: null
-    inputs:
-      - patched_files
-    outputs:
-      - verification_result   # PASS | FAIL | PARTIAL
-      - evidence_of_fix       # Re-read patched section
-    actions:
-      - "Re-read patched code section"
-      - "Chạy test liên quan nếu có"
-      - "Kiểm tra caller/dependent nếu interface thay đổi"
-    exit_on_fail: FAILED
-
-escalation:
-  max_retries: 2
-  on_failure: "Report với full evidence chain (observe→hypothesis→evidence), escalate to human với gợi ý bước tiếp theo"
+name: bug-resolution
+version: 8.0.0
+description: "Pipeline chuẩn để diagnose và fix bugs theo chu trình: Observe → Hypothesize → Evidence → Patch → Verify."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: bug-fix
+
+triggers:
+  - "fix bug"
+  - "sửa lỗi"
+  - "error"
+  - "exception"
+  - "crash"
+  - "stack trace"
+  - "not working"
+  - "bị lỗi"
+
+ide_binding:
+  slash_command: "/fix-bug"
+  aliases: ["/bug", "/debug"]
+
+steps:
+  - id: observe
+    name: "Thu thập triệu chứng"
+    purpose: "Xác định chính xác bug xảy ra ở đâu và biểu hiện thế nào"
+    required: true
+    skip_if: "Stack trace + affected file đã được cung cấp đầy đủ"
+    inputs:
+      - error_message
+      - stack_trace
+      - user_description
+    outputs:
+      - affected_file
+      - affected_line_range
+      - error_signature
+    actions:
+      - "Đọc error message và stack trace"
+      - "Xác định file và line range bị ảnh hưởng"
+      - "Mô tả triệu chứng bằng ngôn ngữ kỹ thuật"
+    exit_on_fail: BLOCKED
+
+  - id: hypothesize
+    name: "Đặt giả thuyết nguyên nhân"
+    purpose: "Xác định top 3 nguyên nhân có thể, xếp theo xác suất"
+    required: true
+    skip_if: null
+    inputs:
+      - error_signature
+      - affected_file
+    outputs:
+      - hypothesis_list      # Ordered list: [H1 (most likely), H2, H3]
+      - selected_hypothesis  # H1 unless evidence suggests otherwise
+    min_confidence: HIGH
+    actions:
+      - "List 3 nguyên nhân có thể gây ra triệu chứng này"
+      - "Xếp hạng theo xác suất dựa trên stack trace"
+      - "Chọn H1 để kiểm chứng trước"
+
+  - id: evidence
+    name: "Tìm bằng chứng xác nhận"
+    purpose: "Xác nhận hoặc loại bỏ hypothesis bằng code thực tế"
+    required: true
+    skip_if: null
+    inputs:
+      - selected_hypothesis
+      - affected_file
+    outputs:
+      - confirmed_root_cause   # File + line + quoted code
+      - evidence_quote         # Exact code causing the bug
+    min_confidence: HIGH
+    context_budget: 150
+    actions:
+      - "Dùng grep_search để tìm pattern liên quan"
+      - "Dùng view_file[StartLine:EndLine] để đọc section cụ thể"
+      - "Quote chính xác đoạn code gây bug"
+    exit_on_fail: PARTIAL
+
+  - id: patch
+    name: "Áp dụng fix"
+    purpose: "Sửa root cause, không chỉ patch triệu chứng"
+    required: true
+    skip_if: null
+    inputs:
+      - confirmed_root_cause
+      - evidence_quote
+    outputs:
+      - patched_files    # List of files modified
+      - diff_summary     # What changed and why
+    actions:
+      - "Edit source file trực tiếp với replace_file_content hoặc multi_replace_file_content"
+      - "Không tạo wrapper script"
+      - "Không dùng ?. hoặc ! để silence lỗi"
+      - "Fix root cause, không patch bề mặt"
+    human_checkpoint:
+      condition: "file thuộc vùng auth/payment/permission/migration"
+      message: "Patch này chạm vào code nhạy cảm. Xác nhận an toàn trước khi thay đổi."
+  - id: verify
+    name: "Xác minh fix"
+    purpose: "Xác nhận bug đã được fix và không có regression"
+    required: true
+    skip_if: null
+    inputs:
+      - patched_files
+    outputs:
+      - verification_result   # PASS | FAIL | PARTIAL
+      - evidence_of_fix       # Re-read patched section
+    actions:
+      - "Re-read patched code section"
+      - "Chạy test liên quan nếu có"
+      - "Kiểm tra caller/dependent nếu interface thay đổi"
+      - "Đảm bảo tuân thủ R-SEC-04 (Security Boundary)"
+      - "Đảm bảo tuân thủ R-C-09 (Zero-Slop)"
+      - "Ghi log execution trace vào evals/traces/"
+    exit_on_fail: FAILED
+
+escalation:
+  max_retries: 2
+  on_failure: "Report với full evidence chain (observe→hypothesis→evidence), escalate to human với gợi ý bước tiếp theo"