ai-developer-skill-os 2.0.1 → 3.0.0

package/skills/qk-context-loader/SKILL.md

@@ -1,206 +1,47 @@
----
-name: qk-context-loader
-purpose: Load ngữ cảnh thực tại (file, folder, logic) liên quan trực tiếp đến task.
-mode_supported: [standard]
-input: [Workflow task]
-output: [Context summaries, loaded files]
-workflow: [1. Quét file bị ảnh hưởng -> 2. Gom nhóm ngữ cảnh -> 3. Handoff]
-allowed_tools: [grep_search, read_file, list_dir]
-handoff_to: [qk-policy-engine]
----
-
-# 🛠️ qk-context-loader - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Load ngữ cảnh thực tại (file, folder, logic) liên quan trực tiếp đến task.
-
-## 🎯 1. Mục Tiêu (Goal)
-- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
-- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
-
-## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
-*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
-1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
-2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
-3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
-4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
-
-## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
-- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
-- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
-
-## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
-- Đích đến: `qk-policy-engine`
-- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
-
-## 📚 5. Kiến Thức Chuyên Sâu (Deep Knowledge)
-
-*(Nền tảng kiến thức và quy tắc chi tiết kế thừa từ kỹ sư)*
-
----
-
-
-
-# Context Manager
-
-> **Language rule:**
-> Use **English** for: file paths, architecture terms, module names, technical labels.
-> Use **the user's language** for: explanations, summaries, and questions.
-
----
-
-## Trigger
-
-Activate this skill when:
-- Starting work on an unfamiliar or large codebase
-- About to read many files and need to prioritize
-- Context window is at risk of overflowing
-- User asks "where is X", "what does Y do", "how is this project structured"
-- Another skill (e.g. `project-audit`, `frontend-architecture`) needs project context first
-
----
-
-## Scope
-
-- ✅ Identify which files are relevant to the current task
-- ✅ Summarize project architecture in structured format
-- ✅ Map folder structure to responsibilities
-- ✅ Track what has been read and what still needs reading
-- ✅ Flag context window risks
-- ✅ Maintain a working memory summary for multi-turn sessions
-
----
-
-## Non-goals
-
-- ❌ Do NOT modify any files
-- ❌ Do NOT fix bugs
-- ❌ Do NOT make architectural decisions
-- ❌ Do NOT read every file blindly — be selective and efficient
-
----
-
-## Workflow
-
-### Phase 1 — Project Discovery
-
-Read only top-level signals first:
-1. `package.json` / `pyproject.toml` / `Cargo.toml` → detect framework, language, scripts
-2. Root config files → `.env.example`, `tsconfig.json`, `vite.config.ts`, `next.config.js`
-3. Folder structure (1-2 levels deep) → identify key directories
-4. Entry points → `src/index.ts`, `app/`, `pages/`, `main.py`
-
-Produce: **Project Profile** (framework, language, key directories, architecture style)
-
----
-
-### Phase 2 — Task-Scoped File Selection
-
-Given the current task, identify the minimum relevant set of files:
-
-```
-Task type → Files to read
-─────────────────────────────────────────────────────
-UI work         → components/, pages/, styles/, design system files
-API work        → services/, hooks/, api/, types/
-State work      → store/, context/, hooks/
-Bug fix         → files mentioned in error, related modules
-Architecture    → folder structure, key abstractions
-```
-
-Rules:
-- Read **entry points** before diving into details
-- Prefer **index files** as anchors
-- Skip `node_modules`, `dist`, `build`, `.git`
-- If uncertain which file → check imports, not the file itself
-
----
-
-### Phase 3 — Architecture Summary
-
-Produce a concise summary:
-
-```
-Project:    [Name / repo]
-Framework:  [React 18 / Next.js 14 / Vue 3 / etc.]
-Language:   [TypeScript / JavaScript / Python]
-Structure:  [Feature-based / Layer-based / Domain-based]
-
-Key directories:
-  src/components/  → Shared UI components
-  src/features/    → Feature modules (collocated)
-  src/services/    → API and data services
-  src/hooks/       → Custom React hooks
-  src/types/       → TypeScript interfaces
-
-State:       [Zustand / Redux / React Query / Pinia]
-HTTP client: [axios instance at src/lib/axios.ts]
-Auth:        [JWT stored in httpOnly cookie]
-```
-
----
-
-### Phase 4 — Working Memory Maintenance
-
-During multi-turn sessions:
-- Track which files have been read (avoid re-reading)
-- Track decisions made (e.g. "we decided to use feature-based structure")
-- Flag when context is approaching limits
-- Offer to summarize and compress if needed
-
----
-
-## Decision Tree
-
-```
-Is this a new project / first time seeing this codebase?
-  ├── Yes → Run full Phase 1 + Phase 2 + Phase 3
-  └── No  → Has something changed since last context load?
-              ├── Yes → Re-run Phase 2 for affected area
-              └── No  → Use cached architecture summary
-```
-
-```
-Is context window at risk?
-  ├── Yes → Summarize what's been read, drop low-relevance files
-  └── No  → Continue loading relevant files
-```
-
----
-
-## Output Format
-
-```
-🗂️  Project Context Loaded
-
-Framework:  [framework]
-Language:   [language]
-Structure:  [style]
-
-Relevant files for this task:
-  📄 [path/to/file.ts]     — [why it's relevant]
-  📄 [path/to/file.ts]     — [why it's relevant]
-
-Architecture summary:
-  [2-4 lines describing how this codebase is organized]
-
-⚠️  Context notes:
-  [Any risks, unknowns, or files that couldn't be read]
-
-✅ Ready. Proceeding with: [next skill or action]
-```
-
----
-
-## Validation Checklist
-
-- [ ] Framework and language correctly identified
-- [ ] Only task-relevant files selected (no noise)
-- [ ] Architecture summary is accurate and concise
-- [ ] Context window usage is reasonable
-- [ ] Working memory updated for this session
-
----
-
-## Examples
-
-See `examples/` folder.
+---
+name: qk-context-loader
+version: 3.0.0
+updated: 2026-07-02
+description: Load relevant files and map the dependency graph for a task.
+category: utilities
+priority: medium
+tags: [context, filesystem, dependencies, graph]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: AI needs to understand the surrounding files before modifying a core component.
+inputs: [Target File]
+outputs: [Loaded Context, Dependency Graph]
+allowed_tools: [grep_search, read_file, list_dir]
+pipeline: [analyze, implement, complete]
+---
+
+# 🛠️ qk-context-loader - Standard Operating Procedure
+
+> **Goal:** "Người thu thập tình báo". Đảm bảo AI hiểu rõ môi trường xung quanh một file code trước khi tiến hành sửa nó, tránh lỗi thiếu context.
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze (Target Identification):**
+   - Identify the main file that needs modification.
+2. **Implement (Graph Traversal):**
+   - **Load Parents:** Search for files that import the target file.
+   - **Load Children:** Read the target file to see what it imports.
+   - Gather the essential chunks of these related files.
+3. **Complete (Context Mapping):**
+   - Build a mental map of how the data flows.
+
+## 🛡️ 2. Constraints & Rules
+- **Token Optimization:** Do not load `node_modules` or massive minified build files. Extract only the exact logic needed.
+
+## 🌳 3. Decision Tree
+```text
+Is the target file a UI Component?
+  ├── YES → Load its CSS/Theme tokens and any nested Child components.
+  └── NO (API Service) → Load the corresponding Controller and Database Model.
+```
+
+## 🤝 4. Handoff Pipeline
+1. `complete`: Provide the context map to the Orchestrator or Target Skill.
+
+## 📝 5. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **Tóm tắt (Summary):** Đã nạp thành công ngữ cảnh.
+- **Chi tiết (Changes):** Các file có liên quan trực tiếp.

package/skills/qk-data-lifecycle/SKILL.md

@@ -1,135 +1,60 @@
----
-name: qk-data-lifecycle
-purpose: Quản lý Schema, Migration, Repository, Query Tuning.
-mode_supported: [enterprise]
-input: [Data requirement]
-output: [Schema, Migration files]
-workflow: [1. Schema -> 2. Migration -> 3. Repository -> 4. Index]
-allowed_tools: [write_to_file, run_command]
-handoff_to: [qk-validation-gate]
----
-
-# 🛠️ qk-data-lifecycle - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Quản lý Schema, Migration, Repository, Query Tuning.
-
-## 🎯 1. Mục Tiêu (Goal)
-- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
-- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
-
-## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
-*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
-1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
-2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
-3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
-4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
-
-## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
-- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
-- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
-
-## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
-- Đích đến: `qk-validation-gate`
-- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
-
-## 📚 5. Kiến Thức Chuyên Sâu (Deep Knowledge)
-
-*(Nền tảng kiến thức và quy tắc chi tiết kế thừa từ kỹ sư)*
-
----
-
-
-
-# Database Engineer
-
-> **Language rule:**
-> Use English for: code, identifiers, file names, architecture terms, technical decisions.
-> Use the user's language for: explanations, questions, summaries, and feedback.
-> The user may write in any language — detect and match it automatically.
-
----
-
-## Trigger
-
-Activate this skill when:
-- User says "create a new table", "add a column", "design the schema"
-- Writing complex data retrieval logic (joins, aggregations)
-- A query is running slowly and needs optimization (indexing)
-- Running or generating database migrations
-
----
-
-## Scope
-
-- ✅ **Schema Design:** Model tables, relations (1:1, 1:N, N:M), and constraints (Unique, FK).
-- ✅ **ORM Integration:** Generate code for Prisma, Drizzle, TypeORM, Sequelize, or Mongoose.
-- ✅ **Migrations:** Generate SQL or ORM migration files safely.
-- ✅ **Query Optimization:** Prevent N+1 queries, add indexes, use efficient aggregations.
-
----
-
-## Non-goals
-
-- ❌ Do NOT execute destructive migrations (DROP TABLE) on production environments without extreme warnings and approval.
-- ❌ Do NOT mix raw SQL into ORM logic unless necessary for performance.
-
----
-
-## Workflow
-
-### Phase 1 — Schema Design
-
-Understand the business entities and relations.
-- Identify primary keys (UUID vs Auto-increment ID).
-- Identify foreign keys and cascade rules (`ON DELETE CASCADE`).
-- Ensure proper normalization (usually 3NF) or denormalization (if NoSQL).
-
-### Phase 2 — ORM / Migration Generation
-
-Map the design to the project's tool:
-- **Prisma:** Update `schema.prisma`.
-- **Drizzle:** Update `schema.ts`.
-- **Raw SQL:** Write `V1__create_table.sql`.
-
-### Phase 3 — Query Implementation
-
-Write the data access methods (Repository pattern or direct ORM calls).
-- Avoid fetching `SELECT *` if only 2 columns are needed.
-- Batch queries or use joins to prevent N+1 issues.
-
----
-
-## Decision Tree
-
-```
-Is the project using an ORM?
-  ├── Prisma  → Modify `schema.prisma`, use `prisma.entity.findMany()`
-  ├── Drizzle → Modify schema TS files, use Drizzle query builder
-  └── No      → Write raw SQL or use query builder (Knex)
-
-Does the schema change drop data or alter existing columns?
-  ├── Yes → Flag as High Risk. Provide rollback strategy. Ask for approval.
-  └── No  → Standard migration (e.g., adding a nullable column).
-```
-
----
-
-## Output Format
-
-```
-🗄️ Database Engineering Report
-─────────────────────────────────────────────────
-Action:     [Schema Update / Query Optimization]
-Tooling:    [Prisma / Raw SQL / etc.]
-
-Changes:
-  ✅ Added model: `User` (1:N with `Post`)
-  ✅ Added index on `User.email`
-  ✅ Generated query: `getUserWithPosts`
-
-⚠️ Risk Assessment:
-  [Low / High — e.g., "Safe addition, no data loss"]
-
-🔗 Next Steps:
-  Run `npx prisma migrate dev` to apply these changes locally.
-```
+---
+name: qk-data-lifecycle
+version: 3.0.0
+updated: 2026-07-02
+description: Manage Database Schema, Migrations, and Repositories.
+category: database
+priority: medium
+tags: [database, sql, migration, schema, orm]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: User asks to create a new database table, modify schema, or write complex queries.
+inputs: [Data model requirements]
+outputs: [Migration scripts, Models, Repositories]
+allowed_tools: [run_command, read_file, write_to_file]
+pipeline: [analyze, design, implement, engineering-standard, validate, complete]
+---
+
+# 🛠️ qk-data-lifecycle - Standard Operating Procedure
+
+> **Goal:** Quản lý an toàn vòng đời dữ liệu, đảm bảo Schema chuẩn xác, Migration có thể Rollback và Query tối ưu.
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze (Requirements):**
+   - Understand the entities and their relationships (1:1, 1:N, N:N).
+   - Identify the ORM/Query Builder used in the project (e.g., Prisma, TypeORM, Drizzle).
+2. **Design (Schema & Normalization):**
+   - Design the schema. Ensure foreign keys and indices are applied to frequently queried columns.
+   - Always include audit columns (`created_at`, `updated_at`).
+3. **Implement (Migration & Models):**
+   - Write the Migration script. MUST include both `up` (apply) and `down` (rollback) logic.
+   - Write/Update the Model/Entity files.
+   - Create Repository layer functions if necessary.
+4. **Verify (Safety Check):**
+   - Review the migration script for destructive operations (e.g., `DROP TABLE`, `DROP COLUMN`).
+
+## 🛡️ 2. Constraints & Rules
+- **No Data Loss:** NEVER execute a migration that drops data on Production without explicit User approval and a backup plan.
+- **Decoupling:** Do not write SQL queries directly in Controllers. Always use the Repository or DAO pattern.
+- **Index Rule:** Any column used in a `WHERE`, `JOIN`, or `ORDER BY` clause should be evaluated for an index.
+
+## 🌳 3. Decision Tree
+```text
+Is this modifying an existing table in Production?
+  ├── YES → Does it drop a column or change a data type destructively?
+  │       ├── YES → STOP. Create a new column, migrate data, then drop the old one (Expand & Contract Pattern).
+  │       └── NO → Proceed with safe migration (e.g., ADD COLUMN).
+  └── NO (New Table) → Ensure Primary Key, Timestamps, and Foreign Keys are defined.
+```
+
+## 🤝 4. Handoff Pipeline
+1. `engineering-standard`: Verify naming conventions (e.g., snake_case for DB columns if required).
+2. `validate`: Run dry-run migrations or unit tests.
+3. `complete`: Generate the Database report.
+
+## 📝 5. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **Tóm tắt (Summary):** Bảng nào được tạo/sửa.
+- **Chi tiết (Changes):** File migration và Model đã sinh ra.
+- **Kiến trúc (Reasoning):** Lý do thiết kế quan hệ bảng và các Index.
+- **Rủi ro (Risks):** Đánh giá mức độ an toàn của Migration (Có làm mất data không?).
+- **Hành động tiếp (Next Action):** Hướng dẫn user chạy lệnh migrate.

package/skills/qk-design-to-code/SKILL.md

@@ -1,33 +1,46 @@
----
-name: qk-design-to-code
-purpose: Chuyển đổi Figma/Screenshot thành Code UI tuân thủ hệ thống.
-mode_supported: [standard]
-input: [Image/Figma]
-output: [UI Code]
-workflow: [1. Analyze Image -> 2. Map Components -> 3. Code -> 4. Responsive]
-allowed_tools: [write_to_file]
-handoff_to: [qk-ui-audit]
----
-
-# 🛠️ qk-design-to-code - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Chuyển đổi Figma/Screenshot thành Code UI tuân thủ hệ thống.
-
-## 🎯 1. Mục Tiêu (Goal)
-- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
-- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
-
-## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
-*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
-1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
-2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
-3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
-4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
-
-## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
-- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
-- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
-
-## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
-- Đích đến: `qk-ui-audit`
-- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
+---
+name: qk-design-to-code
+version: 3.0.0
+updated: 2026-07-02
+description: Convert Figma/Images to semantic, pixel-perfect code components.
+category: frontend
+priority: high
+tags: [ui, figma, frontend, styling, css]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: User uploads an image mockup or provides a design requirement for a UI component.
+inputs: [Image/Mockup, Framework choice]
+outputs: [Code component, CSS/Tailwind classes]
+allowed_tools: [write_to_file, read_file]
+pipeline: [analyze, implement, engineering-standard, validate, complete]
+---
+
+# 🛠️ qk-design-to-code - Standard Operating Procedure
+
+> **Goal:** Dịch thiết kế (Mockups/Images) thành mã nguồn (React, Vue, HTML/CSS) với độ chính xác Pixel-Perfect.
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze (Deconstruct Design):**
+   - Look at the provided mockup.
+   - Break it down from Outside-In (Container -> Rows -> Columns -> Elements).
+2. **Plan (Token Mapping):**
+   - Map colors, fonts, and spacings to existing Design System Tokens (e.g., Tailwind classes `text-primary-500`, `gap-4`).
+3. **Implement (Code Construction):**
+   - Write the semantic HTML (`<article>`, `<section>`, `<nav>`).
+   - Apply styling.
+4. **Validate (Responsive Check):**
+   - Ensure the component uses relative units where necessary and scales on mobile.
+
+## 🛡️ 2. Constraints & Rules
+- **No Magic Values:** Do not use random hex codes or pixel values if a Design System is available.
+- **Accessibility:** Always include `alt` for images and `aria-label` for icon-only buttons.
+
+## 🤝 3. Handoff Pipeline
+1. `engineering-standard`: Ensure the UI component has no business logic.
+2. `validate`: Trigger `qk-ui-audit` checks.
+3. `complete`: Generate the UI Component Report.
+
+## 📝 4. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **Tóm tắt (Summary):** Tên Component vừa tạo.
+- **Chi tiết (Changes):** File chứa component.
+- **Rủi ro (Risks):** Vấn đề responsive nếu có.