ai-developer-skill-os 3.1.5 → 6.0.0-rc1

package/skills/qk-project-health/SKILL.md

@@ -1,64 +1,36 @@
 ---
 name: qk-project-health
-version: 3.1.5
-updated: 2026-07-02
-description: Kiểm toán toàn diện về Code Smells, Tech Debt, và Architecture.
-category: architecture
-behavior: static-analysis
-intent: review-code
-priority: medium
-tags: [audit, architecture, tech-debt, code-smell]
-platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks for a project review, architecture audit, or health check.
-inputs: [Project directory]
-outputs: [Health Audit Score, Refactor roadmap]
-allowed_tools: [grep_search, run_command, read_file]
-pipeline: [analyze, review, validate, complete]
+category: maintenance
+version: 6.0.0
 ---
 
-# 🛠️ qk-project-health - Standard Operating Procedure
+# qk-project-health
 
-> **Goal:** "Khám sức khỏe" toàn diện cho Codebase. Tìm ra các Nợ Kỹ Thuật (Tech Debt), Mã Lỗi Thời (Code Smells), và các rủi ro cấu trúc dài hạn.
+## Scope
+- Comprehensive auditing of Code Smells, Tech Debt, and Architecture (Diagnose & Evaluate)
 
-## 🔄 1. Chain of Thought (SOP)
-
-1. **Analyze (Dependency Scan):**
-   - Read `package.json` to identify outdated libraries, bloated dependencies, or unused packages.
-2. **Review (Architecture Scan):**
-   - Use `list_dir` or tree commands to review the directory structure.
-   - Check if the project follows a scalable pattern (e.g., Feature-based vs flat `components` folder).
-3. **Validate (Smell Detection):**
-   - Scan for "God Components" (Files > 500 lines).
-   - Scan for heavy Prop Drilling (>3 levels deep).
-4. **Complete (Roadmap):**
-   - Generate a prioritized Refactor Roadmap (High, Medium, Low).
-
-## 🛡️ 3. Constraints & Rules
-
-- **Audit Only - No Touch:** Do not modify any code. You are diagnosing, not performing surgery.
-- **Evidence Based:** Provide concrete metrics (e.g., "Folder `components` has 45 files, making it hard to navigate").
-
-## 🌳 3. Decision Tree
-
-```text
-Is the `src/components` folder bloated (>30 files)?
-  ├── YES → Recommend migrating to a Feature-driven structure (e.g., `src/features/auth`).
-  └── NO → Pass.
-
-Are there components exceeding 500 lines?
-  ├── YES → Flag as "God Object" and recommend splitting.
-  └── NO → Pass.
+## Constraints
+```yaml
+must:
+  - Analyze dependency graphs and code complexity metrics
+  - Highlight architectural anti-patterns
+must_not:
+  - Rewrite major components without user consent
+  - Focus purely on stylistic lints (leave that to linter)
 ```
 
-## 🤝 4. Handoff Pipeline
-
-1. `complete`: Output the Health Audit Report.
-
-## 📝 5. Output Format
+## Policies
+```yaml
+prefer:
+  - Structural and performance improvements over minor refactors
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt.
+## Escalation
+```yaml
+stop:
+  - The project lacks basic structure making analysis impossible
+```
 
-- **Tóm tắt (Summary):** Đánh giá tổng quan Sức Khỏe Dự Án (Điểm: X/100).
-- **Chi tiết (Changes):** Phân tích Dependencies, Architecture, Code Smells.
-- **Xác thực (Verification):** Các bằng chứng thu thập được từ code (dòng nào, file nào phình to).
-- **Hành động tiếp (Next Action):** Lên Lộ trình Refactor (Refactor Roadmap) (Cao - Trung - Thấp).
+## Output
+- Health report and refactoring plan
+```

package/skills/qk-project-memory/SKILL.md

@@ -1,42 +1,35 @@
 ---
 name: qk-project-memory
-version: 3.1.5
-updated: 2026-07-02
-description: Lưu trữ và truy xuất ngữ cảnh dự án dài hạn qua các phiên làm việc.
-category: utilities
-behavior: static-analysis
-intent: maintain
-priority: low
-tags: [memory, context, storage]
-platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks to remember a specific configuration, rule, or architectural decision.
-inputs: [Context to remember]
-outputs: [Memory file updated]
-allowed_tools: [write_to_file, read_file]
-pipeline: [analyze, implement, complete]
+category: core
+version: 6.0.0
 ---
 
-# 🛠️ qk-project-memory - Standard Operating Procedure
-
-> **Goal:** "Bộ nhớ dài hạn". Giúp Agent nhớ lại các cấu hình, đường dẫn API hoặc luật lệ riêng của dự án mà không cần User nhắc lại.
-
-## 🔄 1. Chain of Thought (SOP)
-
-1. **Analyze (Fact Extraction):**
-   - Extract the core facts from the conversation (e.g., "The project uses pnpm, not npm").
-2. **Implement (Storage):**
-   - Append the fact to `.ai-memory.md` or a similar configuration file.
-
-## 🛡️ 2. Constraints & Rules
-
-- **Keep it small:** Do not write entire source files into memory. Only save abstract facts and rules.
-
-## 🤝 3. Handoff Pipeline
-
-1. `complete`: Output confirmation.
-
-## 📝 4. Output Format
-
-Vui lòng trả kết quả bằng Tiếng Việt.
-
-- **Tóm tắt (Summary):** Đã ghi nhớ thông tin gì.
+# qk-project-memory
+
+## Scope
+- Storing and retrieving long-term project context across sessions (Collect)
+
+## Constraints
+```yaml
+must:
+  - Organize context logically so it can be retrieved efficiently
+  - Update memory artifacts when major architectural decisions are made
+must_not:
+  - Store sensitive user data or secrets in project memory
+```
+
+## Policies
+```yaml
+prefer:
+  - Concise summaries over verbose logs for long-term memory
+```
+
+## Escalation
+```yaml
+ask:
+  - To clarify contradictory information found in the project memory
+```
+
+## Output
+- Updated memory artifacts
+```

package/skills/qk-system-evolution/SKILL.md

@@ -1,71 +1,35 @@
 ---
 name: qk-system-evolution
-version: 3.1.5
-updated: 2026-07-02
-description: Cập nhật an toàn các thư viện dependencies, di chuyển frameworks và quản lý quá trình rollback.
-category: operations
-behavior: maintenance
-intent: maintain
-priority: high
-tags: [upgrade, migration, devops, dependencies]
-platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User wants to update a library, upgrade a framework (e.g., Next.js 13 to 14), or perform a major refactor.
-inputs: [Target package, Target version]
-outputs: [Upgraded codebase, Rollback plan]
-allowed_tools: [run_command, grep_search, read_file]
-pipeline: [analyze, plan, implement, validate, complete]
+category: infrastructure
+version: 6.0.0
 ---
 
-# 🛠️ qk-system-evolution - Standard Operating Procedure
+# qk-system-evolution
 
-> **Goal:** Quản lý các thay đổi lớn cấp hệ thống (Major Updates) một cách an toàn, luôn có đường lui (Rollback) nếu xảy ra sự cố.
+## Scope
+- Safely updating dependencies, migrating frameworks, and managing rollbacks (Plan & Execute)
 
-## 🔄 1. Chain of Thought (SOP)
-
-1. **Analyze (Impact Analysis):**
-   - Read the Changelog or Migration Guide for the new version.
-   - Identify Breaking Changes and Deprecated APIs.
-   - Search the codebase to see how many files are affected.
-2. **Plan (Rollback Strategy):**
-   - Document the exact Git commands or NPM commands needed to revert the system if the upgrade fails completely.
-3. **Implement (Dry-Run & Upgrade):**
-   - **Mandatory Dry Run:** Create a temporary branch (e.g., `git checkout -b upgrade-dry-run`).
-   - Update dependencies and run Codemods on this branch.
-   - Fix Breaking Changes and pass the Validation Gate. Merge only if safe.
-4. **Verify (System Test):**
-   - Reinstall dependencies cleanly (`npm ci` or `yarn install`).
-   - Run the build process to ensure the system compiles.
-
-## 🛡️ 3. Constraints & Rules
-
-- **Safety First:** Never run `npm update` blindly across all packages. Update only what was requested.
-- **Lockfiles:** Do not delete `package-lock.json` or `yarn.lock` unless resolving extreme merge conflicts.
-- **Always Rollback:** If the system produces >50 compilation errors after an upgrade and you cannot fix them in 1 turn, immediately trigger the Rollback Plan.
-
-## 🌳 3. Decision Tree
-
-```text
-Are there Breaking Changes in the target version?
-  ├── YES → Create a migration checklist based on the official docs. Update code systematically.
-  └── NO (Minor/Patch) → Update version and run tests.
-
-Did the Build fail after the update?
-  ├── YES → Are there too many errors to fix easily?
-  │       ├── YES → Execute Rollback Plan (`git reset --hard HEAD`).
-  │       └── NO → Fix the specific API changes.
-  └── NO → Proceed to Validation.
+## Constraints
+```yaml
+must:
+  - Check compatibility matrices before upgrading dependencies
+  - Provide a rollback plan for major framework updates
+must_not:
+  - Perform destructive migrations without a backup strategy
 ```
 
-## 🤝 4. Handoff Pipeline
-
-1. `validate`: Run the full test suite and `npm run build` via `qk-validation-gate`.
-2. `complete`: Generate the Evolution report.
-
-## 📝 5. Output Format
+## Policies
+```yaml
+prefer:
+  - Incremental updates over 'big bang' migrations
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt.
+## Escalation
+```yaml
+stop:
+  - Critical dependencies are completely incompatible with the target framework version
+```
 
-- **Tóm tắt (Summary):** Đã nâng cấp package nào, từ vX lên vY.
-- **Chi tiết (Changes):** Số lượng file phải sửa do Breaking Changes.
-- **Kế hoạch lùi (Reasoning/Risks):** Ghi rõ lệnh Rollback để User copy-paste nếu cần.
-- **Xác thực (Verification):** Kết quả của Build/Test.
+## Output
+- Migration scripts, updated package files, and rollback plans
+```

package/skills/qk-ui-audit/SKILL.md

@@ -1,66 +1,35 @@
 ---
 name: qk-ui-audit
-version: 3.1.5
-updated: 2026-07-02
-description: Kiểm toán giao diện (UI) để đảm bảo tính nhất quán, khả năng truy cập (A11y), độ phản hồi (Responsive) và hiệu suất.
-category: validation
-behavior: static-analysis
-intent: review-code
-priority: medium
-tags: [ui, audit, frontend, a11y, responsive]
-platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks to check the UI, review styling, or run an audit on a component.
-inputs: [Target UI component, File path]
-outputs: [UI Audit Score, Fix recommendations]
-allowed_tools: [grep_search, read_file]
-pipeline: [analyze, review, validate, complete]
+category: qa
+version: 6.0.0
 ---
 
-# 🛠️ qk-ui-audit - Standard Operating Procedure
+# qk-ui-audit
 
-> **Goal:** Kiểm toán chất lượng Giao diện Người dùng (UI QA). Tìm ra các lỗi hiển thị, sự thiếu đồng nhất và vi phạm Accessibility (a11y).
+## Scope
+- UI consistency, accessibility (A11y), responsiveness, and performance auditing (Evaluate)
 
-## 🔄 1. Chain of Thought (SOP)
-
-1. **Analyze (Scan UI):**
-   - Read the UI component's source code.
-   - Look for inline styles (`style={{...}}`) and hardcoded magic numbers (e.g., `px`, `%` instead of standard tokens).
-2. **Review (Consistency & Responsive):**
-   - Check if standard Design System tokens (e.g., Tailwind classes like `p-4`, `text-lg`) are used.
-   - Check for mobile-first implementation (e.g., base classes for mobile, `md:` for desktop).
-3. **Validate (Accessibility - A11y):**
-   - Verify `<img>` tags have `alt` attributes.
-   - Verify `<button>` tags without text have `aria-label`.
-   - Verify interactive `<div>` elements have `role="button"` and `tabIndex`.
-4. **Complete (Report):**
-   - Calculate a rough score (0-100) based on violations.
-
-## 🛡️ 3. Constraints & Rules
-
-- **Audit Only:** Do not modify the code automatically unless the user explicitly requests you to apply the fixes.
-- **Evidence Based:** Point out the exact line number where the violation occurs.
-
-## 🌳 3. Decision Tree
-
-```text
-Does the component contain hardcoded `#hex` colors or `px` values?
-  ├── YES → Deduct Consistency score. Recommend using Design Tokens.
-  └── NO → Pass.
-
-Does the component have clickable `<div>` elements?
-  ├── YES → Deduct A11y score. Recommend using `<button>` or adding roles.
-  └── NO → Pass.
+## Constraints
+```yaml
+must:
+  - Check UI against established design tokens and guidelines
+  - Verify ARIA roles and contrast ratios
+must_not:
+  - Ignore mobile viewport constraints
 ```
 
-## 🤝 4. Handoff Pipeline
-
-1. `complete`: Generate the UI Audit Report.
-
-## 📝 5. Output Format
+## Policies
+```yaml
+prefer:
+  - Identifying systemic UI issues over isolated pixel tweaks
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt.
+## Escalation
+```yaml
+stop:
+  - UI components completely lack semantic structure
+```
 
-- **Tóm tắt (Summary):** Chấm điểm Giao diện (Score: X/100).
-- **Chi tiết (Changes):** Liệt kê các lỗi Consistency, A11y, Responsive (ghi rõ dòng).
-- **Nguyên nhân (Reasoning):** Tại sao lại đánh lỗi điểm đó.
-- **Hành động tiếp (Next Action):** Hỏi User có muốn tự động sửa các lỗi này không.
+## Output
+- UI audit report with actionable fixes
+```

package/skills/qk-ui-system-builder/SKILL.md

@@ -1,47 +1,35 @@
 ---
 name: qk-ui-system-builder
-version: 3.1.5
-updated: 2026-07-02
-description: Xây dựng và duy trì Design Systems, Token extraction, và các thư viện UI dùng chung.
 category: frontend
-behavior: development
-intent: implement-feature
-priority: medium
-tags: [design-system, tokens, shared-components, storybook]
-platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks to create a shared component (Button, Input) or extract a color palette.
-inputs: [UI Requirements]
-outputs: [Shared Components, Design Tokens]
-allowed_tools: [write_to_file, read_file]
-pipeline: [analyze, implement, engineering-standard, validate, complete]
+version: 6.0.0
 ---
 
-# 🛠️ qk-ui-system-builder - Standard Operating Procedure
-
-> **Goal:** Đảm bảo tính Nhất quán Giao diện (Consistency). Quản lý Design Tokens và xây dựng thư viện Shared Components.
-
-## 🔄 1. Chain of Thought (SOP)
-
-1. **Analyze (Token Extraction):**
-   - Extract raw colors and typography into CSS Variables or Tailwind config.
-2. **Implement (Component Factory):**
-   - Build foundational components (`<Button>`, `<TextInput>`) using generic polymorphic props if possible (e.g., `as="a"` or `as="button"`).
-3. **Validate (Story/Documentation):**
-   - Ensure every variation (primary, secondary, disabled) is accounted for.
-
-## 🛡️ 2. Constraints & Rules
-
-- **Stateless:** System UI components should NEVER have their own backend logic or hardcoded strings.
-- **Extendable:** Always allow users to pass `className` and `...props` to the base element.
-
-## 🤝 3. Handoff Pipeline
-
-1. `engineering-standard`: Verify naming conventions.
-2. `complete`: Output the Design System Report.
-
-## 📝 4. Output Format
-
-Vui lòng trả kết quả bằng Tiếng Việt.
-
-- **Tóm tắt (Summary):** Thư viện Component vừa cập nhật.
-- **Chi tiết (Changes):** Liệt kê các variant (màu sắc, kích cỡ).
+# qk-ui-system-builder
+
+## Scope
+- Building and maintaining Design Systems and shared UI tokens (Plan & Execute)
+
+## Constraints
+```yaml
+must:
+  - Extract reusable design tokens (colors, spacing, typography)
+  - Ensure components are accessible (A11y)
+must_not:
+  - Create duplicate tokens for the same visual value
+```
+
+## Policies
+```yaml
+prefer:
+  - Composable components over rigid layouts
+```
+
+## Escalation
+```yaml
+stop:
+  - Design tokens conflict with existing design guidelines
+```
+
+## Output
+- UI component library or Design System tokens
+```

package/skills/qk-validation-gate/SKILL.md

@@ -1,67 +1,36 @@
 ---
 name: qk-validation-gate
-version: 3.1.5
-updated: 2026-07-02
-description: Cổng kiểm tra chất lượng bắt buộc (Test, Lint, Security).
-category: validation
-behavior: validation
-intent: validate
-priority: critical
-tags: [ci, testing, linting, security, gatekeeper]
-platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: Triggered automatically as the final step in a pipeline, or manually when the user asks to "check the code".
-inputs: [Modified files]
-outputs: [Validation Report (Pass/Fail)]
-allowed_tools: [run_command, grep_search]
-pipeline: [analyze, validate, complete]
+category: qa
+version: 6.0.0
 ---
 
-# 🛠️ qk-validation-gate - Standard Operating Procedure
+# qk-validation-gate
 
-> **Goal:** Hoạt động như một "Người Gác Cổng" (Gatekeeper). Đảm bảo không có lỗi cú pháp, vi phạm bảo mật, hoặc code rác nào lọt qua trước khi báo cáo hoàn thành.
+## Scope
+- Mandatory quality checks (Test, Lint, Security) before merge/commit (Evaluate)
 
-## 🔄 1. Chain of Thought (SOP)
-
-1. **Analyze (Static Sweep):**
-   - Use `grep_search` to scan modified files for garbage code: `console.log(`, `debugger;`, `// TODO`, `@ts-ignore`.
-   - Scan for hardcoded secrets: `API_KEY=`, `Bearer ey...`.
-2. **Validate (Automated Checks):**
-   - Run the Linter: `npm run lint` or `eslint .`.
-   - Run the Type Checker: `tsc --noEmit`.
-   - Run the Tests: `npm run test` (if applicable).
-3. **Complete (Report & Auto-fix):**
-   - If minor lint errors exist, attempt an auto-fix (`npm run lint --fix`).
-   - If tests fail, report the exact failure to the user. Do NOT pretend it passed.
-
-## 🛡️ 3. Constraints & Rules
-
-- **Zero Tolerance:** A failed test or a TypeScript error means the Gate is FAILED. Do not ignore errors.
-- **No Force:** Never use `--force` or `--no-verify` flags.
-- **Real Execution:** You MUST run the actual CLI commands using `run_command` and wait for the output.
-
-## 🌳 3. Decision Tree
-
-```text
-Did `npm run lint` return errors?
-  ├── YES → Are they auto-fixable?
-  │       ├── YES → Run `npm run lint --fix`.
-  │       └── NO → Manually fix the file and re-run.
-  └── NO → Proceed to Type Checking.
-
-Did `tsc --noEmit` return errors?
-  ├── YES → Fix the TypeScript types. Do NOT use `any` as a shortcut.
-  └── NO → GATE PASSED.
+## Constraints
+```yaml
+must:
+  - Verify acceptance criteria and test coverage
+  - Fail early if critical errors or lint violations are found
+must_not:
+  - Approve incomplete work or failing tests
+  - Bypass security scans
 ```
 
-## 🤝 4. Handoff Pipeline
-
-1. `complete`: Once all checks pass, output the Validation Report.
-
-## 📝 5. Output Format
+## Policies
+```yaml
+prefer:
+  - Automated testing over manual verification
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt.
+## Escalation
+```yaml
+stop:
+  - Artifact is absent or tests are failing
+```
 
-- **Tóm tắt (Summary):** 🛡️ Đã chạy các cổng kiểm định (Lint, Test, Type).
-- **Chi tiết (Changes):** Liệt kê các lệnh đã chạy và kết quả.
-- **Xác thực (Verification):** Ghi rõ PASS (Xanh) hoặc FAIL (Đỏ).
-- **Rủi ro (Risks):** Có phát hiện code rác / comment tạm thời không.
+## Output
+- Pass/Fail decision and validation report
+```

package/specs/contracts/behavior-contract.yaml

@@ -0,0 +1,40 @@
+# Tập hợp tất cả các Behavior Contracts của hệ thống
+# Đây là "Source of Truth" để các bài test đối chiếu.
+
+bug-resolution:
+  must:
+    - ask_for_logs_when_missing
+    - avoid_large_refactor
+    - preserve_api
+  prefer:
+    - smallest_change
+    - deterministic_fix
+  never:
+    - invent_root_cause
+    - fabricate_test_result
+
+feature-delivery:
+  must:
+    - minimize_scope
+    - preserve_behavior
+    - verify_regression
+    - handle_ui_states
+  prefer:
+    - clean_code
+  never:
+    - redesign_architecture
+    - rewrite_core_module
+
+access-policy:
+  must:
+    - block_api
+    - enforce_rbac
+  never:
+    - ui_only_security
+
+engineering-standard:
+  must:
+    - maintain_readability
+    - pass_linter
+  never:
+    - change_business_logic

package/specs/expectations/qk-bug-resolution.yaml

@@ -0,0 +1,35 @@
+behavior: qk-bug-resolution
+
+must:
+  - gather_context_before_proposing
+  - require_stack_trace
+  - minimize_scope
+  - preserve_public_api
+  - evaluate_regression_risk
+  - communicate_user_intent
+  - ask_only_necessary_questions
+  - explain_decisions_in_user_language
+
+prefer:
+  - write_reproduction_steps
+  - identify_root_cause
+  - add_regression_test
+
+must_not:
+  - rewrite_module
+  - refactor_unrelated_code
+  - change_architecture
+  - guess_cause_without_evidence
+  - expose_internal_contract
+  - expose_internal_policy
+  - expose_internal_reasoning
+  - quote_yaml_sections
+
+evidence:
+  - stack_trace_or_log
+  - related_source_code
+
+completion:
+  - patch_provided
+  - risk_summary_provided
+  - verification_checklist_provided

package/specs/scenarios/fix-login-nullref.yaml

@@ -0,0 +1,3 @@
+scenario_id: fix-login-nullref
+description: "Một API production bị lỗi NullReferenceException sau khi merge."
+expected_behavior: qk-bug-resolution

package/taste-skill/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "taste-skill",
+  "description": "Taste skill library for Claude Code — frontend design, image-to-code, and aesthetic skills",
+  "owner": {
+    "name": "leonxlnx",
+    "email": ""
+  },
+  "plugins": [
+    {
+      "name": "taste-skill",
+      "description": "Frontend design taste skills including brutalist, minimalist, soft, redesign, stitch, and more",
+      "version": "1.0.0",
+      "source": "./",
+      "author": {
+        "name": "leonxlnx",
+        "email": ""
+      }
+    }
+  ]
+}

package/taste-skill/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "taste-skill",
+  "description": "Frontend design taste skills including brutalist, minimalist, soft, redesign, stitch, and more",
+  "version": "1.0.0",
+  "author": {
+    "name": "leonxlnx",
+    "email": ""
+  },
+  "homepage": "https://github.com/leonxlnx/taste-skill",
+  "repository": "https://github.com/leonxlnx/taste-skill",
+  "license": "MIT",
+  "keywords": [
+    "skills",
+    "frontend",
+    "design",
+    "taste",
+    "ui"
+  ]
+}

package/taste-skill/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: Leonxlnx