ai-developer-skill-os 8.2.0 → 8.3.0

package/.agents/workflows/code-review.yml

@@ -1,77 +1,93 @@
-name: code-review
-version: 8.0.0
-description: "Pipeline kiểm tra chất lượng code theo SOLID, DRY, Clean Code và ngưỡng số liệu cụ thể."
-
-owner:
-  type: engineering
-  maintained_by: qk-team
-
-verification_profile: review
-
-steps:
-  - id: scope
-    name: "Xác định phạm vi review"
-    purpose: "Biết chính xác files/modules cần review"
-    required: true
-    skip_if: "Files đã được chỉ định rõ ràng"
-    inputs:
-      - target_files_or_module
-    outputs:
-      - file_list
-      - review_focus    # bug, quality, security, performance, all
-    exit_on_fail: BLOCKED
-
-  - id: static_analysis
-    name: "Phân tích tĩnh"
-    purpose: "Thu thập findings có bằng chứng rõ ràng"
-    required: true
-    skip_if: null
-    inputs:
-      - file_list
-      - review_focus
-    outputs:
-      - findings         # Each: severity + file + line + quote + reason + suggestion
-    min_confidence: HIGH
-    actions:
-      - "Đọc từng file theo budget (max 150 lines per read)"
-      - "Flag SOLID violations với ngưỡng cụ thể"
-      - "Flag DRY violations (≥ 2 duplications)"
-      - "Flag naming violations"
-      - "Flag error handling issues"
-
-  - id: severity_triage
-    name: "Phân loại mức độ"
-    purpose: "Xếp findings theo priority để human biết fix gì trước"
-    required: true
-    skip_if: null
-    inputs:
-      - findings
-    outputs:
-      - critical_findings    # Must fix: security, data loss risk
-      - high_findings        # Should fix: logic bugs, architecture violations
-      - medium_findings      # Consider: quality improvements
-      - low_findings         # Optional: style, minor naming
-    actions:
-      - "Áp dụng severity matrix: CRITICAL > HIGH > MEDIUM > LOW"
-      - "Không inflate severity để look impressive"
-
-  - id: report
-    name: "Tổng hợp báo cáo"
-    purpose: "Cung cấp báo cáo actionable cho developer"
-    required: true
-    skip_if: null
-    inputs:
-      - critical_findings
-      - high_findings
-      - medium_findings
-    outputs:
-      - review_report    # Structured markdown report
-      - health_score     # 0-100
-    actions:
-      - "Group findings theo file"
-      - "Mỗi finding: file:line + code quote + explanation + suggestion"
-      - "Tính health score: 100 - (critical×20 + high×10 + medium×3 + low×1)"
-
-escalation:
-  max_retries: 1
-  on_failure: "Report partial findings với số files đã review / tổng"
+name: code-review
+version: 8.0.0
+description: "Pipeline kiểm tra chất lượng code theo SOLID, DRY, Clean Code và ngưỡng số liệu cụ thể."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: review
+
+triggers:
+  - "review code"
+  - "review this"
+  - "đánh giá code"
+  - "kiểm tra chất lượng code"
+  - "check this PR"
+  - "pull request review"
+
+ide_binding:
+  slash_command: "/review"
+  aliases: ["/code-review", "/pr-review"]
+
+steps:
+  - id: scope
+    name: "Xác định phạm vi review"
+    purpose: "Biết chính xác files/modules cần review"
+    required: true
+    skip_if: "Files đã được chỉ định rõ ràng"
+    inputs:
+      - target_files_or_module
+    outputs:
+      - file_list
+      - review_focus    # bug, quality, security, performance, all
+    exit_on_fail: BLOCKED
+
+  - id: static_analysis
+    name: "Phân tích tĩnh"
+    purpose: "Thu thập findings có bằng chứng rõ ràng"
+    required: true
+    skip_if: null
+    inputs:
+      - file_list
+      - review_focus
+    outputs:
+      - findings         # Each: severity + file + line + quote + reason + suggestion
+    min_confidence: HIGH
+    context_budget: 150
+    actions:
+      - "Đọc từng file theo budget (max 150 lines per read)"
+      - "Flag SOLID violations với ngưỡng cụ thể"
+      - "Flag DRY violations (≥ 2 duplications)"
+      - "Flag naming violations"
+      - "Flag error handling issues"
+
+  - id: severity_triage
+    name: "Phân loại mức độ"
+    purpose: "Xếp findings theo priority để human biết fix gì trước"
+    required: true
+    skip_if: null
+    inputs:
+      - findings
+    outputs:
+      - critical_findings    # Must fix: security, data loss risk
+      - high_findings        # Should fix: logic bugs, architecture violations
+      - medium_findings      # Consider: quality improvements
+      - low_findings         # Optional: style, minor naming
+    actions:
+      - "Áp dụng severity matrix: CRITICAL > HIGH > MEDIUM > LOW"
+      - "Không inflate severity để look impressive"
+
+  - id: report
+    name: "Tổng hợp báo cáo"
+    purpose: "Cung cấp báo cáo actionable cho developer"
+    required: true
+    skip_if: null
+    inputs:
+      - critical_findings
+      - high_findings
+      - medium_findings
+    outputs:
+      - review_report    # Structured markdown report
+      - health_score     # 0-100
+    actions:
+      - "Group findings theo file"
+      - "Mỗi finding: file:line + code quote + explanation + suggestion"
+      - "Đánh giá mức độ tuân thủ R-C-09 (Zero-Slop)"
+      - "Đánh giá rủi ro R-SEC-04"
+      - "Ghi log execution trace vào evals/traces/"
+      - "Tính health score: 100 - (critical×20 + high×10 + medium×3 + low×1)"
+
+escalation:
+  max_retries: 1
+  on_failure: "Report partial findings với số files đã review / tổng"

package/.agents/workflows/documentation.yml

@@ -1,75 +1,90 @@
-name: documentation
-version: 8.0.0
-description: "Pipeline viết và cập nhật tài liệu chính xác — phải match code thực tế, cấm bịa đặt."
-
-owner:
-  type: engineering
-  maintained_by: qk-team
-
-verification_profile: documentation
-
-steps:
-  - id: audit_existing
-    name: "Kiểm tra tài liệu hiện tại"
-    purpose: "Xác định docs nào cần tạo mới, cập nhật, hay xóa"
-    required: true
-    skip_if: "Task là tạo doc mới hoàn toàn"
-    inputs:
-      - target_docs
-      - relevant_code
-    outputs:
-      - outdated_sections    # Sections that no longer match code
-      - missing_sections     # Things in code but not in docs
-      - accurate_sections    # Keep as-is
-
-  - id: read_source
-    name: "Đọc source code"
-    purpose: "Hiểu chính xác behavior của code trước khi viết về nó"
-    required: true
-    skip_if: null
-    inputs:
-      - relevant_code_files
-    outputs:
-      - verified_behavior    # What the code actually does
-      - api_signatures       # Function signatures, types, params
-      - examples_from_code   # Real usage examples found in codebase
-    min_confidence: HIGH
-    actions:
-      - "Đọc implementation, không chỉ interface"
-      - "Xác nhận examples từ test files nếu có"
-      - "Không assume behavior — phải verify từ code"
-
-  - id: write
-    name: "Viết tài liệu"
-    purpose: "Tạo tài liệu chính xác và hữu ích"
-    required: true
-    skip_if: null
-    inputs:
-      - verified_behavior
-      - api_signatures
-      - examples_from_code
-    outputs:
-      - draft_documentation
-    actions:
-      - "Chỉ viết những gì đã verify từ code"
-      - "Dùng examples thật từ codebase"
-      - "Structure: What → Why → How → Examples"
-
-  - id: verify_accuracy
-    name: "Xác minh độ chính xác"
-    purpose: "Đảm bảo doc không có thông tin sai hoặc lỗi thời"
-    required: true
-    skip_if: null
-    inputs:
-      - draft_documentation
-      - verified_behavior
-    outputs:
-      - accuracy_check    # PASS | FAIL with specific issues
-    actions:
-      - "So sánh từng claim trong doc với code thực tế"
-      - "Flag bất kỳ thứ gì không thể verify từ code"
-    exit_on_fail: FAILED
-
-escalation:
-  max_retries: 1
-  on_failure: "Report which sections could not be verified. Do not publish unverified content."
+name: documentation
+version: 8.0.0
+description: "Pipeline viết và cập nhật tài liệu chính xác — phải match code thực tế, cấm bịa đặt."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: documentation
+
+triggers:
+  - "write docs"
+  - "viết tài liệu"
+  - "update README"
+  - "cập nhật docs"
+  - "document this"
+  - "add documentation"
+
+ide_binding:
+  slash_command: "/docs"
+  aliases: ["/document", "/readme"]
+
+steps:
+  - id: audit_existing
+    name: "Kiểm tra tài liệu hiện tại"
+    purpose: "Xác định docs nào cần tạo mới, cập nhật, hay xóa"
+    required: true
+    skip_if: "Task là tạo doc mới hoàn toàn"
+    inputs:
+      - target_docs
+      - relevant_code
+    outputs:
+      - outdated_sections    # Sections that no longer match code
+      - missing_sections     # Things in code but not in docs
+      - accurate_sections    # Keep as-is
+
+  - id: read_source
+    name: "Đọc source code"
+    purpose: "Hiểu chính xác behavior của code trước khi viết về nó"
+    required: true
+    skip_if: null
+    inputs:
+      - relevant_code_files
+    outputs:
+      - verified_behavior    # What the code actually does
+      - api_signatures       # Function signatures, types, params
+      - examples_from_code   # Real usage examples found in codebase
+    min_confidence: HIGH
+    context_budget: 200
+    actions:
+      - "Đọc implementation, không chỉ interface"
+      - "Xác nhận examples từ test files nếu có"
+      - "Không assume behavior — phải verify từ code"
+
+  - id: write
+    name: "Viết tài liệu"
+    purpose: "Tạo tài liệu chính xác và hữu ích"
+    required: true
+    skip_if: null
+    inputs:
+      - verified_behavior
+      - api_signatures
+      - examples_from_code
+    outputs:
+      - draft_documentation
+    actions:
+      - "Chỉ viết những gì đã verify từ code"
+      - "Dùng examples thật từ codebase"
+      - "Đảm bảo docs tuân thủ R-C-09 (không có slop text)"
+      - "Structure: What → Why → How → Examples"
+
+  - id: verify_accuracy
+    name: "Xác minh độ chính xác"
+    purpose: "Đảm bảo doc không có thông tin sai hoặc lỗi thời"
+    required: true
+    skip_if: null
+    inputs:
+      - draft_documentation
+      - verified_behavior
+    outputs:
+      - accuracy_check    # PASS | FAIL with specific issues
+    actions:
+      - "So sánh từng claim trong doc với code thực tế"
+      - "Flag bất kỳ thứ gì không thể verify từ code"
+      - "Ghi log execution trace vào evals/traces/"
+    exit_on_fail: FAILED
+
+escalation:
+  max_retries: 1
+  on_failure: "Report which sections could not be verified. Do not publish unverified content."

package/.agents/workflows/feature-delivery.yml

@@ -1,103 +1,120 @@
-name: feature-delivery
-version: 8.0.0
-description: "Pipeline end-to-end để phát triển tính năng mới: từ requirement đến verified implementation."
-
-owner:
-  type: engineering
-  maintained_by: qk-team
-
-verification_profile: feature
-
-steps:
-  - id: requirement
-    name: "Phân tích yêu cầu"
-    purpose: "Xác định rõ feature cần làm gì, cho ai, thành công trông như thế nào"
-    required: true
-    skip_if: null
-    inputs:
-      - user_description
-      - existing_context
-    outputs:
-      - feature_scope        # What's in, what's out
-      - acceptance_criteria  # How to know it's done
-      - affected_areas       # Which parts of codebase are touched
-    min_confidence: HIGH
-    actions:
-      - "Viết lại requirement bằng ngôn ngữ kỹ thuật"
-      - "Xác định acceptance criteria rõ ràng"
-      - "Identify files/modules sẽ bị ảnh hưởng"
-    exit_on_fail: BLOCKED
-
-  - id: context
-    name: "Load context"
-    purpose: "Hiểu codebase hiện tại đủ để implement đúng cách"
-    required: true
-    skip_if: "Context graph đã có từ qk-context-loader"
-    inputs:
-      - affected_areas
-    outputs:
-      - existing_patterns    # How similar things are done in this codebase
-      - integration_points   # Where new code will connect
-      - constraints          # Tech stack, conventions to follow
-    actions:
-      - "Đọc các file liên quan (targeted, không đọc toàn bộ)"
-      - "Tìm pattern tương tự trong codebase"
-      - "Xác định integration points"
-
-  - id: design
-    name: "Thiết kế solution"
-    purpose: "Quyết định approach trước khi code"
-    required: true
-    skip_if: "Feature đơn giản, single file, no design decision needed"
-    inputs:
-      - feature_scope
-      - existing_patterns
-      - constraints
-    outputs:
-      - implementation_plan  # Files to create/modify + what changes
-      - data_structures      # New types, interfaces if needed
-      - api_contract         # If adding/changing API
-    min_confidence: HIGH
-    actions:
-      - "Outline: files to create, files to modify"
-      - "Define data structures và types"
-      - "Xác định API contract nếu cần"
-
-  - id: implement
-    name: "Implement"
-    purpose: "Viết code theo design đã approved"
-    required: true
-    skip_if: null
-    inputs:
-      - implementation_plan
-      - existing_patterns
-    outputs:
-      - created_files
-      - modified_files
-      - implementation_summary
-    actions:
-      - "Implement theo thứ tự: types → logic → UI → tests"
-      - "Follow existing patterns và conventions"
-      - "Không refactor ngoài scope"
-
-  - id: verify
-    name: "Verify implementation"
-    purpose: "Xác nhận feature hoạt động đúng theo acceptance criteria"
-    required: true
-    skip_if: null
-    inputs:
-      - acceptance_criteria
-      - created_files
-      - modified_files
-    outputs:
-      - verification_result
-      - unmet_criteria      # Any criteria not yet met
-    actions:
-      - "Đối chiếu từng acceptance criterion"
-      - "Re-read key implementation sections"
-      - "Run tests nếu có"
-    exit_on_fail: PARTIAL
-
-escalation:
-  max_retries: 1
-  on_failure: "Report implementation_plan + what was completed + what remains + blocker reason"
+name: feature-delivery
+version: 8.0.0
+description: "Pipeline end-to-end để phát triển tính năng mới: từ requirement đến verified implementation."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: feature
+
+triggers:
+  - "add feature"
+  - "thêm tính năng"
+  - "implement feature"
+  - "build a new"
+  - "new component"
+  - "làm tính năng mới"
+
+ide_binding:
+  slash_command: "/feature"
+  aliases: ["/build", "/implement"]
+
+steps:
+  - id: requirement
+    name: "Phân tích yêu cầu"
+    purpose: "Xác định rõ feature cần làm gì, cho ai, thành công trông như thế nào"
+    required: true
+    skip_if: null
+    inputs:
+      - user_description
+      - existing_context
+    outputs:
+      - feature_scope        # What's in, what's out
+      - acceptance_criteria  # How to know it's done
+      - affected_areas       # Which parts of codebase are touched
+    min_confidence: HIGH
+    actions:
+      - "Viết lại requirement bằng ngôn ngữ kỹ thuật"
+      - "Xác định acceptance criteria rõ ràng"
+      - "Identify files/modules sẽ bị ảnh hưởng"
+    exit_on_fail: BLOCKED
+
+  - id: context
+    name: "Load context"
+    purpose: "Hiểu codebase hiện tại đủ để implement đúng cách"
+    required: true
+    skip_if: "Context graph đã có từ qk-context-loader"
+    inputs:
+      - affected_areas
+    outputs:
+      - existing_patterns    # How similar things are done in this codebase
+      - integration_points   # Where new code will connect
+      - constraints          # Tech stack, conventions to follow
+    actions:
+      - "Đọc các file liên quan (targeted, không đọc toàn bộ)"
+      - "Tìm pattern tương tự trong codebase"
+      - "Xác định integration points"
+
+  - id: design
+    name: "Thiết kế solution"
+    purpose: "Quyết định approach trước khi code"
+    required: true
+    skip_if: "Feature đơn giản, single file, no design decision needed"
+    inputs:
+      - feature_scope
+      - existing_patterns
+      - constraints
+    outputs:
+      - implementation_plan  # Files to create/modify + what changes
+      - data_structures      # New types, interfaces if needed
+      - api_contract         # If adding/changing API
+    min_confidence: HIGH
+    actions:
+      - "Outline: files to create, files to modify"
+      - "Define data structures và types"
+      - "Xác định API contract nếu cần"
+    human_checkpoint:
+      condition: "affected_areas thuộc complexity level 'high' hoặc 'critical' (5+ files, có external dependency hoặc breaking change)"
+      message: "Feature này có độ phức tạp cao. Xác nhận implementation_plan trước khi bắt đầu code."
+  - id: implement
+    name: "Implement"
+    purpose: "Viết code theo design đã approved"
+    required: true
+    skip_if: null
+    inputs:
+      - implementation_plan
+      - existing_patterns
+    outputs:
+      - created_files
+      - modified_files
+      - implementation_summary
+    actions:
+      - "Implement theo thứ tự: types → logic → UI → tests"
+      - "Follow existing patterns và conventions"
+      - "Code phải tuân thủ nghiêm ngặt R-C-09 (Zero-Slop)"
+      - "Phải validate input/output theo R-SEC-04"
+      - "Không refactor ngoài scope"
+
+  - id: verify
+    name: "Verify implementation"
+    purpose: "Xác nhận feature hoạt động đúng theo acceptance criteria"
+    required: true
+    skip_if: null
+    inputs:
+      - acceptance_criteria
+      - created_files
+      - modified_files
+    outputs:
+      - verification_result
+      - unmet_criteria      # Any criteria not yet met
+    actions:
+      - "Đối chiếu từng acceptance criterion"
+      - "Re-read key implementation sections"
+      - "Run tests nếu có"
+      - "Ghi log execution trace vào evals/traces/"
+    exit_on_fail: PARTIAL
+
+escalation:
+  max_retries: 1
+  on_failure: "Report implementation_plan + what was completed + what remains + blocker reason"