ai-developer-skill-os 9.1.2 → 9.3.1

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

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

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

@@ -98,7 +98,7 @@ steps:
 
   - id: verify
     name: "Verify implementation"
-    purpose: "Xác nhận feature hoạt động đúng theo acceptance criteria"
+    purpose: "Xác nhận feature hoạt động đúng theo acceptance criteria — quality gate bắt buộc"
     required: true
     skip_if: null
     inputs:
@@ -107,11 +107,15 @@ steps:
       - modified_files
     outputs:
       - verification_result
-      - unmet_criteria      # Any criteria not yet met
+      - unmet_criteria
+      - quality_gate_result   # PASS | PARTIAL | FAIL
     actions:
-      - "Đối chiếu từng acceptance criterion"
+      - "Đối chiếu từng acceptance criterion — list unmet nếu có"
       - "Re-read key implementation sections"
-      - "Run tests nếu có"
+      - "Run linter nếu có (npm run lint / ruff / eslint)"
+      - "Run tests nếu có (npm test / pytest / go test)"
+      - "Áp dụng shared quality gate → xem: .agents/workflows/shared/quality-gate.yml"
+      - "  Checklist: universal_checks + feature-delivery specific checks"
       - "Ghi log execution trace vào evals/traces/"
     exit_on_fail: PARTIAL
 

package/.agents/workflows/refactor.yml

@@ -77,8 +77,8 @@ steps:
       - "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"
+    name: "Verify behavior unchanged + quality gate"
+    purpose: "Xác nhận external behavior giống hệt trước refactor VÀ quality cải thiện"
     required: true
     skip_if: null
     inputs:
@@ -87,10 +87,13 @@ steps:
     outputs:
       - behavior_preserved    # true/false
       - test_results          # pass/fail/na
+      - quality_gate_result   # PASS | FAIL
     actions:
       - "Re-read modified sections"
-      - "So sánh với current_behavior_summary"
+      - "So sánh với current_behavior_summary — behavior PHẢI giống hệt"
       - "Chạy tests nếu có"
+      - "Áp dụng shared quality gate → xem: .agents/workflows/shared/quality-gate.yml"
+      - "  Checklist: universal_checks + refactor specific checks"
       - "Ghi log execution trace vào evals/traces/"
     exit_on_fail: FAILED
 

package/.agents/workflows/shared/quality-gate.yml

@@ -0,0 +1,94 @@
+name: quality-gate
+version: 9.2.0
+description: "Shared quality gate — embedded vào bước verify của feature-delivery, bug-resolution, refactor. Source of truth duy nhất cho R-C-10 checklist."
+type: shared-step
+
+# ─────────────────────────────────────────────────────────────
+# CÁCH DÙNG TRONG WORKFLOW:
+#   Trong step verify của workflow, thêm dòng sau vào actions:
+#   - "Áp dụng shared quality gate: xem .agents/workflows/shared/quality-gate.yml"
+#   Rồi liệt kê CHỈ những check đặc thù của workflow đó.
+#
+# KHÔNG copy toàn bộ checklist này vào workflow — trỏ về file này.
+# Khi cần update checklist: sửa file này, tất cả workflow tự được cập nhật.
+# ─────────────────────────────────────────────────────────────
+
+universal_checks:
+  description: "Áp dụng cho MỌI workflow có side_effects: edit_files (R-C-10 trong coding.md)"
+  items:
+    - id: fn-length
+      check: "Function length ≤ 40 lines"
+      action: "Extract sub-function nếu vi phạm"
+
+    - id: file-length
+      check: "File length ≤ 300 lines"
+      action: "Split module nếu vi phạm"
+
+    - id: nesting-depth
+      check: "Nesting depth ≤ 3 levels"
+      action: "Extract early return hoặc helper function"
+
+    - id: cyclomatic
+      check: "Cyclomatic complexity ≤ 10"
+      action: "Simplify conditions, extract logic"
+
+    - id: no-silent-errors
+      check: "Không có empty catch, không dùng `!` hoặc `as` để bypass type"
+      action: "Fix root cause — report BLOCKED nếu không rõ root cause"
+
+    - id: no-magic-numbers
+      check: "Không có magic numbers/strings trong logic"
+      action: "Extract thành named constant"
+
+    - id: dry
+      check: "Không có logic lặp ≥ 2 lần"
+      action: "Extract thành shared function/util"
+
+    - id: naming
+      check: "Naming conventions: camelCase fn, PascalCase class, UPPER_SNAKE constant"
+      action: "Rename theo convention"
+
+    - id: no-console-log
+      check: "Không có console.log/print/fmt.Println debug còn sót"
+      action: "Xóa hoặc thay bằng proper logger"
+
+    - id: root-cause-fix
+      check: "Fix là root cause, không phải symptom patch"
+      action: "Report BLOCKED nếu root cause chưa rõ"
+
+workflow_specific_checks:
+  feature-delivery:
+    description: "Thêm vào sau universal_checks khi verify feature mới"
+    items:
+      - id: acceptance-criteria
+        check: "Tất cả acceptance criteria đã được đáp ứng"
+        action: "List unmet criteria, report PARTIAL nếu còn thiếu"
+      - id: run-tests
+        check: "Chạy linter + test suite (npm run lint / ruff / eslint / pytest)"
+        action: "Fix lint errors trước khi report SUCCESS"
+
+  bug-resolution:
+    description: "Thêm vào sau universal_checks khi verify bug fix"
+    items:
+      - id: no-regression
+        check: "Callers/dependents không bị break"
+        action: "Đọc caller files, verify interface không thay đổi"
+      - id: security-boundary
+        check: "Tuân thủ R-SEC-04 (Security Boundary)"
+        action: "Flag nếu fix chạm auth/payment/permission code"
+
+  refactor:
+    description: "Thêm vào sau universal_checks khi verify refactor"
+    items:
+      - id: behavior-unchanged
+        check: "External behavior giống hệt trước refactor"
+        action: "So sánh với current_behavior_summary, report FAILED nếu có diff"
+      - id: run-tests
+        check: "Test suite pass — không có regression"
+        action: "Report FAILED + rollback nếu test fail sau refactor"
+
+exit_criteria:
+  SUCCESS:  "Tất cả universal_checks + workflow_specific_checks đều pass"
+  PARTIAL:  "Universal checks pass, nhưng có workflow-specific check chưa xong (VD: test chưa được viết)"
+  FAILED:   "Bất kỳ universal check nào fail, hoặc behavior changed sau refactor, hoặc test regression"
+  BLOCKED:  "Root cause chưa rõ, hoặc thiếu thông tin để verify"

package/.agents/workflows/skin-governance.yml

@@ -0,0 +1,115 @@
+name: skin-governance
+version: 9.2.0
+description: "Workflow tối ưu hóa, kiểm định và nâng cấp AI Skin — observe usage, measure success, improve, validate, promote."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: skill-evolution
+
+triggers:
+  - "improve this skill"
+  - "tối ưu skill"
+  - "why does this skill keep failing"
+  - "optimize this workflow"
+  - "phân tích usage skill"
+  - "nâng cấp skin"
+  - "skin governance"
+
+ide_binding:
+  slash_command: "/skin-tune"
+  aliases: ["/evolve-skill", "/skin-governance"]
+
+steps:
+  - id: observe_usage
+    name: "Observe Usage"
+    purpose: "Thống kê cách skill được gọi, token consumed, exit codes phân bổ"
+    required: true
+    inputs:
+      - skill_logs
+      - evals_traces
+    outputs:
+      - usage_metrics        # trigger_rate, avg_tokens, exit_distribution
+    actions:
+      - "Đọc evals/traces/ của skill target"
+      - "Thống kê trigger rate và token usage per exit code"
+      - "Phát hiện pattern gọi sai skill (routing error)"
+
+  - id: measure_success
+    name: "Measure Success Rate"
+    purpose: "Đánh giá chất lượng thực thi theo scorecard"
+    required: true
+    inputs:
+      - usage_metrics
+      - scorecard_yaml
+    outputs:
+      - success_rate         # % SUCCESS / total runs
+      - weak_areas           # Steps hay fail nhất
+    actions:
+      - "Tính SUCCESS / FAILED / PARTIAL / BLOCKED ratio"
+      - "Xác định bước nào trong workflow hay bị BLOCKED nhất"
+      - "So sánh với threshold trong scorecard.yaml"
+
+  - id: detect_failure
+    name: "Detect Failure Patterns"
+    purpose: "Tìm root cause của các lần fail — không đoán mò"
+    required: true
+    inputs:
+      - execution_results
+      - evals_traces
+    outputs:
+      - failure_patterns     # Categorized: ambiguous_input | hallucination | budget_overrun | wrong_routing
+    actions:
+      - "Phân loại lỗi: ambiguous_input / hallucination / budget_overrun / wrong_routing"
+      - "Tìm ví dụ cụ thể từ traces"
+      - "Ghi root cause evidence cho từng category"
+
+  - id: improve_skill
+    name: "Propose Improvement"
+    purpose: "Đề xuất thay đổi cụ thể — không thay đổi ngầm"
+    required: true
+    inputs:
+      - failure_patterns
+      - skill_body
+    outputs:
+      - improvement_proposal   # Diff: what to add/remove/change + reason
+    actions:
+      - "Giảm noise trong instruction (xóa rule không được enforce)"
+      - "Cập nhật examples với case thực tế từ traces"
+      - "Tinh chỉnh token_budget nếu hay bị overrun"
+      - "Cập nhật triggers nếu routing hay sai"
+      - "KHÔNG tự sửa — trả proposal để human review"
+    human_checkpoint:
+      condition: always
+      message: "Review improvement proposal trước khi apply vào SKILL.md"
+
+  - id: validate
+    name: "Validate Proposal"
+    purpose: "Đảm bảo bản cải tiến không vi phạm governance rules"
+    required: true
+    inputs:
+      - improvement_proposal
+    outputs:
+      - validation_result    # PASS | FAIL với lý do
+    actions:
+      - "Kiểm tra schema compliance (SPEC.md frontmatter)"
+      - "Đảm bảo không tạo scope overlap với skill khác"
+      - "Verify triggers không trùng skill khác trong routing table"
+
+  - id: promote
+    name: "Promote to Stable"
+    purpose: "Đưa bản cải tiến vào production sau khi đã validate"
+    required: true
+    inputs:
+      - validation_result
+    outputs:
+      - promoted_skill       # version bumped SKILL.md
+    actions:
+      - "Bump patch version (9.2.x → 9.2.x+1)"
+      - "Cập nhật registry: node tooling/generate-registry.js"
+      - "Ghi changelog entry"
+
+escalation:
+  max_retries: 1
+  on_failure: "Hủy bỏ bản cải tiến, giữ nguyên version hiện tại, ghi failure reason"

package/CHANGELOG.md

@@ -5,6 +5,44 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ---
 
+## [9.3.1] — 2026-09-14 — EDAOS v9.3: SSOT Trigger Discipline, Full-Body Execution & Complete Documentation
+
+### Added
+- **Complete v9.3 Documentation Sync**: Updated `README.md` and `CHANGELOG.md` with comprehensive architectural documentation, active skill breakdown, and governance notes.
+- **SSOT 2-Clause Trigger Standard**: Implemented Anthropic 2-clause standard across all 29 active skills (`qk-*`). Clause 1 defines primary responsibility; Clause 2 defines explicit trigger intents including colloquial Vietnamese triggers ("kể cả khi chỉ nói...").
+- **Closed-Loop 4-Tier Body Architecture**: Completed full execution body across all 29 active skills (Preconditions, In/Out-of-Scope boundaries, Step-by-step pipeline, Role-aware Prompt Templates & Command argument specs).
+- **Direct Terminal Visual Rendering**: Enforced Unicode/ASCII Box Drawing for architectural diagrams, sequence flows, and decision trees directly in terminal output (GEMINI.md).
+- **Vitest Isolation Engine**: Added isolated `vitest.config.js` ignoring external IDE worktrees (`.kilo/`) for fast (<1s) 10/10 test suite execution.
+
+### Changed
+- **Boundary Disambiguation**: Resolved trigger overlaps between paired skills:
+  - `qk-project-audit` (pre-code gap analysis & feasibility) vs `qk-project-health` (code smells & technical debt audit of running codebase).
+  - `qk-ui-audit` (visual consistency & 57-check anti-slop) vs `qk-web-quality-gate` (WCAG a11y, performance, lighthouse).
+  - `qk-access-policy` (RBAC/ABAC & auth middleware) vs `qk-security-audit` (OWASP scan & vulnerability detection).
+- **Skill Restructuring & Governance**:
+  - Archived `qk-frontend-architecture` and `qk-agent-observability` with deprecation paths.
+  - Relocated `qk-engineering-standard` to Behavior Policy Rule (`.agents/rules/coding.md`).
+  - Relocated `qk-validation-gate` to Eval Pipeline Engine (`evals/runner.js`).
+  - Preserved 3 legacy v9.1 skills (`qk-fe-api-integration`, `qk-help`, `qk-system-evolution`) for zero-breaking backward compatibility.
+
+---
+
+## [9.2.0] — 2026-09-11 — EDAOS v9.2: Role-Aware Execution & Semantic Naming
+
+### Added
+- **DEV_PROFILE.md**: Project-level role and stack context file automatically loaded at session start.
+- **Role Behavior Matrix**: Added 6 developer profiles (`fe`, `be`, `fullstack`, `data`, `ai-engineer`, `devops`) with focus, depth, and skip guidance.
+- **Role-Aware Prompt Templates**: Integrated role-specific templates in key skills.
+
+### Changed
+- Renamed `qk-fe-api-integration` → `qk-api-consumer`.
+- Renamed `qk-system-evolution` → `qk-upgrade`.
+- Renamed `qk-project-analyst` → `qk-project-audit`.
+- Renamed workflows: `skill-evolution.yml` → `skin-governance.yml`, `research.yml` → `context-discovery.yml`.
+- Deprecated and removed legacy `qk-help` in favor of `qk-orchestrator`.
+
+---
+
 ## [9.0.0] — 2026-08 — EDAOS v9.0: Universal Project Knowledge V1 & Dual-Mode Memory Architecture
 
 ### Added