ai-developer-skill-os 9.3.1 → 10.2.0

package/.agents/workflows/context-discovery.yml

@@ -1,94 +1,128 @@
-name: context-discovery
-version: 9.2.0
-description: "Pipeline load context dự án và vẽ dependency graph trước khi thực hiện task — ngăn hallucination kiến trúc."
-
-owner:
-  type: engineering
-  maintained_by: qk-team
-
-verification_profile: review
-
-triggers:
-  - "load context"
-  - "tìm hiểu codebase"
-  - "explore architecture"
-  - "explain the codebase"
-  - "trace dependency"
-  - "hiểu project"
-  - "which skill should i use"
-  - "help me choose"
-
-ide_binding:
-  slash_command: "/discover"
-  aliases: ["/context", "/explore", "/research"]
-
-steps:
-  - id: define_scope
-    name: "Xác định phạm vi cần khám phá"
-    purpose: "Biết chính xác cần tìm hiểu gì để phục vụ task tiếp theo"
-    required: true
-    inputs:
-      - task_goal            # Task người dùng muốn làm sau context load
-    outputs:
-      - discovery_questions  # Các câu hỏi cụ thể cần trả lời
-      - entry_points         # Files/folders bắt đầu đọc
-    actions:
-      - "Đặt 3-5 câu hỏi cụ thể cần trả lời (không đọc mọi thứ)"
-      - "Ưu tiên: package.json / go.mod / pyproject.toml → biết stack"
-      - "Sau đó: src/ structure → biết architecture pattern"
-    exit_on_fail: BLOCKED
-
-  - id: detect_stack
-    name: "Phát hiện Stack & Architecture"
-    purpose: "Xác định tech stack, project type, và conventions đang dùng"
-    required: true
-    inputs:
-      - entry_points
-    outputs:
-      - detected_stack       # language, framework, DB, CSS, test runner...
-      - project_type         # web-app / api / data-pipeline / monorepo / ai-agent
-      - architecture_pattern # feature-based / domain / layered / atomic
-    actions:
-      - "Đọc package.json / requirements.txt / go.mod / Cargo.toml"
-      - "Đọc cấu trúc thư mục src/ (1 level sâu)"
-      - "Tìm config files: tsconfig, prisma/schema, docker-compose, .env.example"
-      - "Đọc tối đa 2-3 file entry point để xác nhận pattern"
-
-  - id: map_dependencies
-    name: "Vẽ Dependency Map"
-    purpose: "Hiểu component nào phụ thuộc vào component nào"
-    required: false
-    skip_if: "Task không cần hiểu cross-component dependencies"
-    inputs:
-      - detected_stack
-      - entry_points
-    outputs:
-      - dependency_map       # Key components + their relationships
-      - critical_paths       # Paths hay bị ảnh hưởng khi thay đổi
-    context_budget: 100
-    actions:
-      - "Dùng grep_search để trace imports, không đọc toàn bộ file"
-      - "Đọc targeted sections (≤ 100 lines per read)"
-      - "Ghi lại circular deps hay God File nếu phát hiện"
-
-  - id: synthesize
-    name: "Tổng hợp Context"
-    purpose: "Đóng gói kết quả sẵn sàng inject vào skill thực thi tiếp theo"
-    required: true
-    inputs:
-      - detected_stack
-      - dependency_map
-      - discovery_questions
-    outputs:
-      - context_summary      # Stack + Architecture + Key files
-      - skill_recommendation # Skill phù hợp nhất cho task hiện tại
-      - warnings             # Deprecated patterns, risks, anti-patterns phát hiện
-    actions:
-      - "Viết summary dạng bullet (không dài hơn 10 dòng)"
-      - "Đề xuất skill phù hợp nhất nếu chưa được chọn"
-      - "Flag pattern cũ hoặc vi phạm convention"
-      - "Ghi log execution trace vào evals/traces/ nếu có"
-
-escalation:
-  max_retries: 1
-  on_failure: "Report partial findings với confidence level, list files chưa đọc được"
+name: context-discovery
+version: 10.2.0
+platforms: [antigravity, claude, opencode]
+runtime_version: 1
+description: "Pipeline load context dự án và vẽ dependency graph trước khi thực hiện task — ngăn hallucination kiến trúc."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: review
+
+triggers:
+  - "load context"
+  - "tìm hiểu codebase"
+  - "explore architecture"
+  - "explain the codebase"
+  - "trace dependency"
+  - "hiểu project"
+  - "which skill should i use"
+  - "help me choose"
+
+ide_binding:
+  slash_command: "/discover"
+  aliases: ["/context", "/explore", "/research"]
+
+steps:
+  - id: define_scope
+    name: "Xác định phạm vi cần khám phá"
+    purpose: "Biết chính xác cần tìm hiểu gì để phục vụ task tiếp theo"
+    required: true
+    inputs:
+      - task_goal            # Task người dùng muốn làm sau context load
+    outputs:
+      - discovery_questions  # Các câu hỏi cụ thể cần trả lời
+      - entry_points         # Files/folders bắt đầu đọc
+    actions:
+      - "Đặt 3-5 câu hỏi cụ thể cần trả lời (không đọc mọi thứ)"
+      - "Ưu tiên: package.json / go.mod / pyproject.toml → biết stack"
+      - "Sau đó: src/ structure → biết architecture pattern"
+    exit_on_fail: BLOCKED
+
+  - id: detect_stack
+    name: "Phát hiện Stack & Architecture"
+    purpose: "Xác định tech stack, project type, và conventions đang dùng"
+    required: true
+    inputs:
+      - entry_points
+    outputs:
+      - detected_stack       # language, framework, DB, CSS, test runner...
+      - project_type         # web-app / api / data-pipeline / monorepo / ai-agent
+      - architecture_pattern # feature-based / domain / layered / atomic
+    actions:
+      - "Đọc package.json / requirements.txt / go.mod / Cargo.toml"
+      - "Đọc cấu trúc thư mục src/ (1 level sâu)"
+      - "Tìm config files: tsconfig, prisma/schema, docker-compose, .env.example"
+      - "Đọc tối đa 2-3 file entry point để xác nhận pattern"
+
+  - id: map_dependencies
+    name: "Vẽ Dependency Map"
+    purpose: "Hiểu component nào phụ thuộc vào component nào"
+    required: false
+    skip_if: "Task không cần hiểu cross-component dependencies"
+    inputs:
+      - detected_stack
+      - entry_points
+    outputs:
+      - dependency_map       # Key components + their relationships
+      - critical_paths       # Paths hay bị ảnh hưởng khi thay đổi
+    context_budget: 100
+    actions:
+      - "Dùng grep_search để trace imports, không đọc toàn bộ file"
+      - "Đọc targeted sections (≤ 100 lines per read)"
+      - "Ghi lại circular deps hay God File nếu phát hiện"
+
+  - id: synthesize
+    name: "Tổng hợp Context"
+    purpose: "Đóng gói kết quả sẵn sàng inject vào skill thực thi tiếp theo"
+    required: true
+    inputs:
+      - detected_stack
+      - dependency_map
+      - discovery_questions
+    outputs:
+      - context_summary      # Stack + Architecture + Key files
+      - skill_recommendation # Skill phù hợp nhất cho task hiện tại
+      - warnings             # Deprecated patterns, risks, anti-patterns phát hiện
+    actions:
+      - "Viết summary dạng bullet (không dài hơn 10 dòng)"
+      - "Đề xuất skill phù hợp nhất nếu chưa được chọn"
+      - "Flag pattern cũ hoặc vi phạm convention"
+      - "Ghi log execution trace vào evals/traces/ nếu có"
+
+escalation:
+  max_retries: 1
+  on_failure: "Report partial findings với confidence level, list files chưa đọc được"
+
+# ── V10.2 Additions ──────────────────────────────
+# Confidence Model
+# | Level  | Condition              | Action       |
+# |--------|------------------------|--------------|
+# | HIGH   | Step inputs provided   | Proceed      |
+# | MEDIUM | Some assumptions needed | Note assumptions |
+# | LOW    | Insufficient evidence  | EXIT: BLOCKED|
+#
+# Exit Codes
+# | Code    | Meaning                       | When                    |
+# |---------|-------------------------------|-------------------------|
+# | SUCCESS | Step completed and verified   | All criteria met        |
+# | PARTIAL | Step done with minor gaps    | Some checks skipped     |
+# | BLOCKED | Missing precondition         | Ask user                |
+# | FAILED  | Step failed after max retries | Report error            |
+#
+# Evidence Format:
+#   [SEVERITY] step_id: [step-name]
+#   Reason:     [why this matters]
+#   Confidence: [HIGH|MEDIUM|LOW]
+#   Fix:        [suggestion]
+#
+# Compliance:
+#   Runtime Standard: 11/11
+#   Frontmatter Complete: yes
+#   References Valid: yes
+#   Decision Trees: PASS
+#   Thresholds Defined: PASS
+#   schema_version: 10.2.0
+#   runtime_version: 1
+#   platforms: [antigravity, claude, opencode]

package/.agents/workflows/documentation.yml

@@ -1,90 +1,124 @@
-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."
+name: documentation
+version: 10.2.0
+platforms: [antigravity, claude, opencode]
+runtime_version: 1
+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."
+
+# ── V10.2 Additions ──────────────────────────────
+# Confidence Model
+# | Level  | Condition              | Action       |
+# |--------|------------------------|--------------|
+# | HIGH   | Step inputs provided   | Proceed      |
+# | MEDIUM | Some assumptions needed | Note assumptions |
+# | LOW    | Insufficient evidence  | EXIT: BLOCKED|
+#
+# Exit Codes
+# | Code    | Meaning                       | When                    |
+# |---------|-------------------------------|-------------------------|
+# | SUCCESS | Step completed and verified   | All criteria met        |
+# | PARTIAL | Step done with minor gaps    | Some checks skipped     |
+# | BLOCKED | Missing precondition         | Ask user                |
+# | FAILED  | Step failed after max retries | Report error            |
+#
+# Evidence Format:
+#   [SEVERITY] step_id: [step-name]
+#   Reason:     [why this matters]
+#   Confidence: [HIGH|MEDIUM|LOW]
+#   Fix:        [suggestion]
+#
+# Compliance:
+#   Runtime Standard: 11/11
+#   Frontmatter Complete: yes
+#   References Valid: yes
+#   Decision Trees: PASS
+#   Thresholds Defined: PASS
+#   schema_version: 10.2.0
+#   runtime_version: 1
+#   platforms: [antigravity, claude, opencode]