ai-developer-skill-os 7.5.1 → 8.1.4

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"

package/.agents/workflows/skill-evolution.yml

@@ -0,0 +1,65 @@
+name: skill-evolution
+description: "Workflow vòng lặp tiến hóa và tối ưu hóa skill (Skill Evolution)."
+version: 1.0.0
+
+steps:
+  - id: observe_usage
+    name: "Observe Usage"
+    purpose: "Theo dõi cách skill được sử dụng"
+    required: true
+    inputs: [skill_logs]
+    outputs: [usage_metrics]
+    actions:
+      - "Thống kê trigger rate và token usage"
+
+  - id: measure_success
+    name: "Measure Success"
+    purpose: "Đánh giá tỷ lệ thành công"
+    required: true
+    inputs: [usage_metrics, execution_results]
+    outputs: [success_rate]
+    actions:
+      - "Xác định các lần exit SUCCESS vs FAILED/PARTIAL"
+
+  - id: detect_failure
+    name: "Detect Failure Patterns"
+    purpose: "Phát hiện lý do thất bại"
+    required: true
+    inputs: [execution_results]
+    outputs: [failure_patterns]
+    actions:
+      - "Phân tích log lỗi, hallucination, out of budget"
+
+  - id: improve_skill
+    name: "Improve Skill"
+    purpose: "Đề xuất tối ưu skill"
+    required: true
+    inputs: [failure_patterns, skill_body]
+    outputs: [improved_skill_proposal]
+    actions:
+      - "Giảm noise trong instruction"
+      - "Cập nhật examples và learnings"
+      - "Tinh chỉnh token budget"
+
+  - id: validate_improvement
+    name: "Validate Improvement"
+    purpose: "Xác thực bản nâng cấp"
+    required: true
+    inputs: [improved_skill_proposal]
+    outputs: [validation_result]
+    actions:
+      - "Chạy qua validate-skills.js"
+      - "Kiểm tra schema compliance"
+
+  - id: promote
+    name: "Promote Skill"
+    purpose: "Đưa bản cải tiến vào sử dụng"
+    required: true
+    inputs: [validation_result]
+    outputs: [stable_skill]
+    actions:
+      - "Chuyển status thành stable"
+
+escalation:
+  max_retries: 1
+  on_failure: "Hủy bỏ bản cải tiến nếu validation thất bại"

package/.agents/workflows/spec-driven-development.yml

@@ -0,0 +1,57 @@
+name: spec-driven-development
+description: "Workflow phát triển dựa trên đặc tả (Specification-Driven Development)."
+version: 1.0.0
+
+steps:
+  - id: clarify_requirement
+    name: "Clarify Requirements"
+    purpose: "Làm rõ yêu cầu từ ý tưởng ban đầu"
+    required: true
+    inputs: [user_idea]
+    outputs: [clarified_requirement]
+    actions:
+      - "Hỏi các câu hỏi làm rõ scope và constraints"
+      - "Xác định rõ outcome mong muốn"
+
+  - id: create_spec
+    name: "Create Specification"
+    purpose: "Viết tài liệu đặc tả kỹ thuật"
+    required: true
+    inputs: [clarified_requirement]
+    outputs: [technical_spec]
+    actions:
+      - "Thiết kế API contracts, data models"
+      - "Xác định UI/UX heuristics"
+      - "Xác định edge cases"
+
+  - id: create_plan
+    name: "Create Plan"
+    purpose: "Lên kế hoạch triển khai"
+    required: true
+    inputs: [technical_spec]
+    outputs: [implementation_plan]
+    actions:
+      - "Chia nhỏ spec thành các task cụ thể"
+      - "Đánh giá rủi ro và thứ tự ưu tiên"
+
+  - id: implement
+    name: "Implement"
+    purpose: "Triển khai mã nguồn"
+    required: true
+    inputs: [implementation_plan, technical_spec]
+    outputs: [source_code]
+    actions:
+      - "Code theo đúng spec"
+
+  - id: verify
+    name: "Verify Implementation"
+    purpose: "Kiểm tra mã nguồn với đặc tả"
+    required: true
+    inputs: [source_code, technical_spec]
+    outputs: [verification_result]
+    actions:
+      - "Đối chiếu kết quả code với acceptance criteria"
+
+escalation:
+  max_retries: 2
+  on_failure: "Báo cáo lệch spec và xin chỉ thị"

package/CHANGELOG.md

@@ -1,70 +1,91 @@
-# Changelog
-
-All notable changes to the **AI Developer Skill OS** project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [7.0.2] - 2026-07-15
-
-### Added
-- **Frontend Integration**: Added `qk-fe-api-integration` skill to strictly enforce zero-overhead base API consumption, DTO mapping, and resilient UI states.
-
-## [7.0.0] - 2026-07-15
-
-### Changed (The "Anti-Slop & Zero-Trust" Architecture Upgrade)
-- **Zero-Trust Logic**: Core logic skills (`qk-context-loader`, `qk-orchestrator`, `qk-feature-delivery`) now mandate a Topological Context Graph prior to any code generation.
-- **Strict Design Contract**: Frontend skills (`qk-ui-system-builder`, `qk-ui-builder`, `qk-ui-audit`) now explicitly reject generic styling (slop) and enforce strict token matching against a mandated `DESIGN.md`.
-- **Repair Loop Enforcement**: `qk-bug-resolution` updated to strictly prohibit jumping to fixes without explicitly establishing an `Observe -> Hypothesis -> Evidence` chain.
-- **Contract-First APIs**: `qk-api-lifecycle` now requires explicit OpenAPI/Swagger definitions prior to endpoint implementation.
-- **Upgraded Testing Framework**: Fixed regex and validation logic in `behavior-conformance.test.js` to rigorously support YAML array strings and precise V7 markdown constraints. All 22 skills bumped to `v7.0.0`.
-- **Project Bootstrapping**: `qk-project-bootstrap` now scaffolds `DESIGN.md` explicitly upon initialization.
-
-
-## [4.0.0] - 2026-07-02
-
-### Changed (Major Architecture Upgrade)
-- **Intent-Based Agent Architecture:** Replaced rule-based individual skill exceptions with global behavioral group classifications (Static Analysis, Development, Validation, Maintenance).
-- **OS Kernel Refactor:** Completely rewrote `AGENTS.md` (the "OS Kernel") into a strictly organized, lightweight structure under 100 lines.
-- **Progressive Evidence Collection:** Agents now enforce an 80% Confidence Threshold and incremental Context Budget (`1 file` → `3 files`) to prevent over-fetching and hallucination loops.
-- **Cost & Escalation Policies:** Introduced strict cost-optimization logic, Stopping Criteria, and Escalation protocols to prevent infinite `run_command` retries.
-- **Risk-based Verification:** Dynamic test execution based on the risk level of changes (Levels 0-3).
-
-### Added
-- **Registry Validation Suite:** Full Vitest test suite enforcing SKILL.md frontmatter compliance against `docs/SPEC.md`.
-- **GitHub Actions CI:** Automated validation on every PR and push to main.
-- **Idempotent Installer:** `bin/install.js` now detects and updates existing rule blocks instead of duplicating them.
-- **Kilo Code Native Support:** First-class support for `CLAUDE.md` + `kilo.json` config generation.
-- **Governance Docs:** `docs/GOVERNANCE.md`, ADRs, and skill classification policy for enterprise maintainability.
-- **Engineering Standards:** `qk-engineering-standard` and `qk-validation-gate` skills enforce SOLID, DRY, Clean Code, and mandatory quality gates.
-
-## [1.0.1] - 2026-07-01
-### Fixed
-- Standardized Language rule across all 23 SKILL.md files for consistency.
-- Updated registry version to match package.json.
-
-## [1.0.0] - 2026-07-01
-
-### Added
-- Released the complete AI Developer Skill OS with 23 targeted skills for coding agents.
-- **Engineering Core (8 skills):**
-  - `agent-orchestrator` for planning and delegating tasks.
-  - `context-manager` for project context and file selection.
-  - `project-audit` for 3-mode health checks.
-  - `bug-fix` with root cause analysis.
-  - `refactor` for safe, behavior-preserving code restructuring.
-  - `migration` for dependency updates and library swapping.
-  - `api-integration` for robust API connections.
-  - `git-engineer` for commit messages and PR documentation.
-- **Frontend Core (11 skills):**
-  - `frontend-architecture`, `design-system`, `ui-builder`, `component-generator`.
-  - `state-management`, `form-builder`, `table-crud-generator`.
-  - `frontend-debug`, `frontend-testing`, `accessibility-audit`, `frontend-performance`.
-- **Backend Core (4 skills):**
-  - `backend-architecture`, `database-engineer`, `auth-security`, `deployment`.
-- Added comprehensive `skills.json` registry with dependencies and trigger keywords.
-- Added bilingual `README.md` (English/Vietnamese).
-- Added detailed user documentation in `docs/HUONG_DAN_SU_DUNG.md` and `docs/CHI_TIET_SKILLS.md`.
-- Translated all skill frontmatter descriptions to Vietnamese for better UX in agent terminals.
-- Included generic English and Vietnamese usage examples in `_template/examples/`.
-
+# Changelog
+
+All notable changes to AI Developer Skill OS are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+
+---
+
+## [8.1.4] — 2026-07 — Design Intelligence Pack
+
+### Added
+- **Design Intelligence Layer**: `.agents/knowledge/design-intelligence/` (industries, themes, patterns, visual-language, components, templates)
+- **Knowledge Dependencies**: `qk-design-system-engineering` and `qk-ui-builder` now have strict dependency bounds tied to Design Intelligence without bloating the Capability Graph.
+- **Design Routing Test Cases**: `design-intel-01`, `02`, `03` for validating routing logic in design scenarios.
+- **Re-introduced CLI Installer**: Restored and refactored `bin/install.js` to correctly copy `.agents` across global/local directories for easy NPM setup.
+
+### Changed
+- Refined **Decision Boundaries**: `qk-ui-builder` explicitly forbidden from defining visual direction or brand identity (strict capability bounds).
+- **README.md** reflects 30 Master Skills and the "Agent Engineering OS" mindset.
+- **package.json**: Version bump `8.1.4` and whitelisted files for npm publish.
+
+---
+
+## [8.1.3] — 2026-07 — Architecture Freeze & Governance
+
+### Added
+- **Capability Graph & Routing**: `.agents/registry/capability-graph.yml` to define skill relations (`depends_on`, `delegates_to`).
+- **Priority Governance**: `.agents/rules/priorities.yml` enforcing safety layers (`P1: System Integrity`, `P2: Guardrails`).
+- **Audit Tools**: `tooling/run-aar.js` for architectural acceptance testing.
+- Test cases for routing and boundary attacks.
+
+### Changed
+- Name transition from "Self-Improving" to **Adaptive Agent OS** (Self Optimizing ≠ Self Modifying).
+- Enforced hard cap of **30 Skills** to prevent Skill Inflation.
+- Frozen Baseline achieved: `v8.1.3-agent-os-production`.
+
+---
+
+## [8.0.0] — 2026-07 — Agent Knowledge System
+
+### Philosophy shift
+- **V7:** Skill Repository — human selects skill, AI executes
+- **V8:** Agent Knowledge System — AI retrieves context, selects capability, executes workflow, verifies
+
+### Added
+- `rules/` — Agent behavior policies (global, coding, safety)
+- `workflows/` — Reusable execution pipelines (YAML, with inputs/outputs per step)
+- `examples/` — Few-shot knowledge (good/, bad/)
+- `learnings/` — Evidence-based learning lifecycle (draft/, validated/, deprecated/)
+- `registry/` — Generated AI retrieval index (skills-index.yml)
+- `docs/ARCHITECTURE.md` — Agent request flow diagram
+- `docs/VERSIONING.md` — Semantic versioning policy
+- `docs/schemas/` — Schema definitions for all knowledge objects
+- `docs/decisions/` — Architecture Decision Records (ADRs)
+- `.agentsignore` — AI boundary file (what agents should NOT load)
+- `tooling/` — Dev automation (generate-registry.js, validate-skills.js)
+- `tests/agent-evaluation/` — Agent behavior test harness
+
+### Changed
+- SKILL.md schema upgraded to V8: added `type`, `intent`, `triggers`, `complexity`, `workflow`, `verification`, `related_skills`
+- `skills.json` demoted to **generated compatibility manifest** (source of truth = SKILL.md)
+- Workflows extracted from individual skills → shared reusable templates
+
+### Removed
+- Embedded workflows inside SKILL.md body (moved to workflows/)
+- Old migration scripts (migrate-v*.js, patch*.py, add_lang.*, etc.)
+- Duplicate documentation (CLAUDE.md, old docs/)
+- Experimental packages (packages/edaos-sdk)
+- framework/, knowledge/, specs/, templates/ directories
+
+### Migration
+- V7.5.1 tagged at git: `v7.5.1`
+- V7 skills preserved in git history; migration is additive schema upgrade
+
+---
+
+## [7.5.1] — 2026-07 — Final V7 Release
+
+- Bumped all skill versions to 7.5.1
+- Added qk-fe-api-integration skill
+- Added qk-performance-tuner (global config)
+- Stabilized frontmatter schema across all 22 skills
+
+## [7.5.0] — 2026-07
+
+- Major skills refactor with EDAOS runtime adapter
+- Added MCP server integration
+- Added qk-bug-resolution workflow contracts
+
+## [7.0.0] — 2026
+
+- V7 release: 22 skills, YAML frontmatter, token budget system