ai-developer-skill-os 7.5.0 → 8.1.4

package/.agents/workflows/_schema.yml

@@ -0,0 +1,109 @@
+# 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"

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

@@ -0,0 +1,101 @@
+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"

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

@@ -0,0 +1,77 @@
+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"

package/.agents/workflows/documentation.yml

@@ -0,0 +1,75 @@
+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."

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

@@ -0,0 +1,103 @@
+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"

package/.agents/workflows/refactor.yml

@@ -0,0 +1,81 @@
+name: refactor
+version: 8.0.0
+description: "Pipeline refactor an toàn: giữ nguyên behavior bên ngoài, cải thiện chất lượng bên trong."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: refactor
+
+steps:
+  - id: baseline
+    name: "Thiết lập baseline"
+    purpose: "Hiểu code hiện tại trước khi thay đổi"
+    required: true
+    skip_if: null
+    inputs:
+      - target_files
+      - refactor_goal    # e.g. "extract functions", "reduce complexity", "improve naming"
+    outputs:
+      - current_behavior_summary   # What the code does now
+      - pain_points                # Specific issues to address
+      - test_coverage_status       # Có tests không?
+    actions:
+      - "Đọc toàn bộ target section"
+      - "Mô tả behavior hiện tại"
+      - "Identify specific code smells"
+    exit_on_fail: BLOCKED
+
+  - id: plan
+    name: "Lên kế hoạch refactor"
+    purpose: "Quyết định approach để không thay đổi external behavior"
+    required: true
+    skip_if: null
+    inputs:
+      - pain_points
+      - current_behavior_summary
+    outputs:
+      - refactor_steps     # Ordered list of changes
+      - risk_assessment    # What could break
+      - rollback_point     # Git commit or checkpoint
+    min_confidence: HIGH
+    actions:
+      - "Outline từng bước thay đổi"
+      - "Xác định gì có thể break"
+
+  - id: execute
+    name: "Thực hiện refactor"
+    purpose: "Apply changes theo plan, step by step"
+    required: true
+    skip_if: null
+    inputs:
+      - refactor_steps
+    outputs:
+      - modified_files
+      - changes_summary
+    actions:
+      - "Làm từng bước nhỏ, verify sau mỗi bước"
+      - "Không refactor ngoài scope đã định"
+      - "Không add functionality mới trong khi refactor"
+
+  - id: verify
+    name: "Verify behavior unchanged"
+    purpose: "Xác nhận external behavior giống hệt trước refactor"
+    required: true
+    skip_if: null
+    inputs:
+      - current_behavior_summary
+      - modified_files
+    outputs:
+      - behavior_preserved    # true/false
+      - test_results          # pass/fail/na
+    actions:
+      - "Re-read modified sections"
+      - "So sánh với current_behavior_summary"
+      - "Chạy tests nếu có"
+    exit_on_fail: FAILED
+
+escalation:
+  max_retries: 1
+  on_failure: "Revert to rollback_point. Report what was completed and what remains."

package/.agents/workflows/research.yml

@@ -0,0 +1,60 @@
+name: research
+version: 8.0.0
+description: "Pipeline nghiên cứu codebase để hiểu context, dependency, và architecture trước khi thực hiện task lớn."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: review
+
+steps:
+  - id: define_scope
+    name: "Xác định phạm vi nghiên cứu"
+    purpose: "Biết chính xác cần tìm hiểu gì để phục vụ task"
+    required: true
+    skip_if: null
+    inputs:
+      - research_goal    # What decision does this research enable?
+    outputs:
+      - research_questions   # Specific questions to answer
+      - entry_points         # Files to start reading
+    exit_on_fail: BLOCKED
+
+  - id: explore
+    name: "Khám phá codebase"
+    purpose: "Thu thập thông tin đủ để trả lời research questions"
+    required: true
+    skip_if: null
+    inputs:
+      - entry_points
+      - research_questions
+    outputs:
+      - findings           # Answers to research questions
+      - dependency_map     # How components relate
+      - relevant_files     # Files most relevant to the task
+    actions:
+      - "Dùng grep_search để tìm patterns, không đọc toàn bộ repo"
+      - "Đọc targeted sections (≤ 100 lines per read)"
+      - "Build mental model của dependency relationship"
+
+  - id: synthesize
+    name: "Tổng hợp kết quả"
+    purpose: "Trả lời research questions + tạo context cho task tiếp theo"
+    required: true
+    skip_if: null
+    inputs:
+      - findings
+      - dependency_map
+    outputs:
+      - context_summary      # Ready-to-use context for next skill
+      - architecture_notes   # Key patterns và conventions
+      - warnings             # Gotchas, deprecated patterns, risks
+    actions:
+      - "Viết summary ngắn gọn (không cần exhaustive)"
+      - "Flag các pattern cũ/deprecated nếu thấy"
+      - "Liệt kê relevant files để task tiếp theo load"
+
+escalation:
+  max_retries: 1
+  on_failure: "Report partial findings với confidence level"

package/.agents/workflows/security-audit.yml

@@ -0,0 +1,72 @@
+name: security-audit
+description: "Workflow kiểm toán an toàn mã nguồn và chống xâm nhập (Security Audit)."
+version: 1.0.0
+
+steps:
+  - id: observe
+    name: "Observe System"
+    purpose: "Thu thập metadata về cấu trúc và các thành phần"
+    required: true
+    inputs: [source_code]
+    outputs: [system_context]
+    actions:
+      - "Xác định tech stack, boundaries và các third-party libs"
+
+  - id: dependency_scan
+    name: "Dependency Scan"
+    purpose: "Kiểm tra rủi ro từ package bên ngoài"
+    required: true
+    inputs: [system_context, package_files]
+    outputs: [dependency_vulnerabilities]
+    actions:
+      - "Kiểm tra version cũ, thư viện có CVE"
+
+  - id: secret_scan
+    name: "Secret Scan"
+    purpose: "Tìm kiếm thông tin nhạy cảm bị rò rỉ"
+    required: true
+    inputs: [source_code]
+    outputs: [leaked_secrets]
+    actions:
+      - "Quét hardcoded API keys, tokens, passwords trong code"
+
+  - id: permission_review
+    name: "Permission Review"
+    purpose: "Rà soát mô hình phân quyền và RBAC"
+    required: true
+    inputs: [system_context, access_control_code]
+    outputs: [permission_flaws]
+    actions:
+      - "Kiểm tra nguyên tắc least privilege"
+      - "Tìm lỗ hổng authentication/authorization bypass"
+
+  - id: risk_classification
+    name: "Risk Classification"
+    purpose: "Đánh giá mức độ nghiêm trọng"
+    required: true
+    inputs: [dependency_vulnerabilities, leaked_secrets, permission_flaws]
+    outputs: [classified_risks]
+    actions:
+      - "Phân loại LOW/MEDIUM/HIGH/CRITICAL"
+
+  - id: recommendation
+    name: "Recommendation"
+    purpose: "Đề xuất giải pháp khắc phục"
+    required: true
+    inputs: [classified_risks]
+    outputs: [security_report]
+    actions:
+      - "Tạo báo cáo chi tiết kèm actionable steps"
+
+  - id: verify
+    name: "Verify Fixes"
+    purpose: "Đảm bảo lỗ hổng đã được vá"
+    required: false
+    inputs: [source_code, security_report]
+    outputs: [final_audit_status]
+    actions:
+      - "Check lại các vị trí đã report"
+
+escalation:
+  max_retries: 0
+  on_failure: "Báo động đỏ (CRITICAL) nếu phát hiện secret leak"