ai-developer-skill-os 7.0.2 → 7.5.0

package/.qk-ai-skill-os/skills/_archive_old_skills/qk-refactor/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: qk-refactor
+description: >-
+  Tái cấu trúc và dọn dẹp mã nguồn để dễ bảo trì hơn mà không làm thay đổi logic hoạt động bên ngoài.
+version: 1.0.0
+category: engineering
+tags: [refactor, clean-code, restructure, technical-debt, maintainability]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Refactor — Safe Restructuring
+
+> **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.
+
+> ⚠️ **Core constraint: Refactoring must NOT change observable behavior.**
+> If behavior changes are needed → that is a feature, not a refactor.
+> Stop and clarify with the user before proceeding.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User says "clean up", "refactor", "it's too messy", "hard to maintain"
+- Code has grown beyond its original design (God component, fat service, spaghetti logic)
+- Duplicate patterns exist across multiple files
+- `project-audit` identified architecture issues (P2/P3) ready to be addressed
+- User asks to "improve code quality" without changing functionality
+
+**Not this skill** → Use `bug-fix` if behavior is wrong. Use `migration` if upgrading dependencies.
+
+---
+
+## Scope
+
+- ✅ Rename for clarity (variables, functions, files, components)
+- ✅ Extract reusable logic into functions, hooks, services, or utilities
+- ✅ Remove dead code, unused imports, and orphaned files
+- ✅ Split large components / functions into focused units
+- ✅ Apply consistent patterns across the codebase
+- ✅ Improve type coverage (replace `any`, add missing types)
+- ✅ Reduce complexity (flatten nested conditions, simplify logic)
+
+---
+
+## Non-goals
+
+- ❌ Do NOT change behavior — if you must, stop and discuss first
+- ❌ Do NOT change public APIs or exported interfaces without explicit approval
+- ❌ Do NOT rewrite everything — prefer incremental, targeted changes
+- ❌ Do NOT apply opinionated style changes (formatting belongs to linter/prettier)
+- ❌ Do NOT introduce new dependencies
+- ❌ Do NOT refactor code unrelated to the stated scope
+
+---
+
+## Severity Levels (for issues found during analysis)
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Refactor introduces breaking change — stop immediately |
+| P1 | High coupling or duplication blocking feature work |
+| P2 | Code smell reducing maintainability |
+| P3 | Minor naming or style inconsistency |
+
+---
+
+## Workflow
+
+### Phase 1 — Understand Current State
+
+Before changing anything:
+1. Read the target code thoroughly
+2. Identify what it does (behavior, inputs, outputs, side effects)
+3. Note all callers and dependents of the code being refactored
+4. Check for existing tests — these are the safety net
+
+If there are **no tests** for the code being refactored → recommend writing characterization tests first, or proceed with extra caution and document risks.
+
+---
+
+### Phase 2 — Identify Refactor Targets
+
+Common code smells to look for:
+
+| Smell | Description |
+|-------|-------------|
+| God Component/Function | Does too many things — split by responsibility |
+| Duplicate Logic | Same pattern repeated — extract to shared utility |
+| Long Parameter Lists | >4 params — use options object |
+| Deep Nesting | >3 levels of if/else — flatten with early returns |
+| Magic Numbers/Strings | Unnamed constants — extract to named constants |
+| Dead Code | Unused variables, functions, imports — remove |
+| Inconsistent Naming | Mixed conventions — standardize |
+| Missing Types | `any`, missing return types — add precise types |
+| Large Files | >300 lines — consider splitting by concern |
+
+---
+
+### Phase 3 — Plan the Refactor
+
+Create a step-by-step plan before touching code:
+
+1. List each specific change with its justification
+2. Order changes from lowest to highest risk
+3. Identify what tests must pass after each step
+4. Flag any changes that touch shared/exported code
+
+Present plan to user if scope is large or changes are risky.
+
+---
+
+### Phase 4 — Execute Incrementally
+
+Apply changes in small, verifiable steps:
+
+**Safe refactor order:**
+1. Rename (lowest risk — IDEs can do this safely)
+2. Extract (pull logic into new functions/hooks without changing callers)
+3. Inline (remove unnecessary abstraction)
+4. Move (relocate to correct file/folder)
+5. Simplify (reduce complexity in logic)
+6. Remove (delete dead code last — confirm nothing breaks)
+
+After **each step** → verify tests still pass before moving on.
+
+---
+
+### Phase 5 — Verify Behavior Preserved
+
+- [ ] All existing tests pass
+- [ ] Run lint and type-check — clean
+- [ ] Manual smoke test of affected functionality
+- [ ] No new `any` types introduced
+- [ ] No unused imports or dead code left
+- [ ] Public API unchanged (or explicitly approved to change)
+
+---
+
+### Phase 6 — Report
+
+Document what changed and why:
+
+```
+What changed:   [List of changes]
+Why:            [Specific smell or issue addressed]
+Risk level:     [Low / Medium / High]
+Tests status:   [All pass / N new tests added]
+Behavior:       [Unchanged — verified]
+```
+
+---
+
+## Decision Tree
+
+```
+Is there existing test coverage?
+  ├── Yes → Proceed — tests are the safety net
+  └── No  → Recommend characterization tests first
+              ├── User agrees → write tests then refactor
+              └── User wants to proceed anyway → proceed with caution, document risk
+
+Does the refactor change public APIs?
+  ├── Yes → Stop — confirm with user, this may be a breaking change
+  └── No  → Proceed
+
+Is the scope larger than expected?
+  ├── Yes → Present updated plan, get approval before continuing
+  └── No  → Continue
+```
+
+---
+
+## Output Format
+
+```
+🔧 Refactor Summary
+─────────────────────────────────────────────────
+Scope:        [What was refactored]
+Changes:      [N files modified, N extracted, N removed]
+
+Changes applied:
+  ✅ [Rename: oldName → newName in path/to/file.ts]
+  ✅ [Extract: logic → useCustomHook in path/to/hook.ts]
+  ✅ [Remove: dead code in path/to/old.ts]
+  ✅ [Split: LargeComponent → ComponentA + ComponentB]
+
+📊 Quality improvement:
+  Before: [brief description of the problem]
+  After:  [brief description of improvement]
+
+✅ Verification:
+  Tests:     PASS (N tests)
+  Lint:      Clean
+  Types:     No new `any`
+  Behavior:  Unchanged
+
+⚠️  Notes:
+  [Any assumptions, risks, or follow-up suggestions]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Behavior is unchanged — verified with tests or manual check
+- [ ] All tests pass
+- [ ] Lint and type-check clean
+- [ ] No dead code, unused imports, or console.logs left
+- [ ] Public APIs unchanged (or explicitly approved)
+- [ ] Changes are documented with justification
+- [ ] No new dependencies introduced
+
+---
+
+## Examples
+
+See `examples/` folder.
+

package/.qk-ai-skill-os/skills/_archive_old_skills/qk-state-management/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: qk-state-management
+description: >-
+  Xác định và triển khai chiến lược quản lý state phù hợp (Zustand, Redux, React Query, Local State).
+version: 1.0.0
+category: frontend
+tags: [state, redux, zustand, react-query, context, pinia, data-flow]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# State Management
+
+> **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 asks to "store this data", "share state between components", or "cache API results"
+- Prop drilling becomes excessive (>3 levels deep)
+- Integrating complex UI interactions that need memory (e.g., shopping cart, multi-step wizard)
+- Managing async server data and loading/error states
+
+---
+
+## Scope
+
+- ✅ Decide which state layer to use based on the data's lifecycle and scope
+- ✅ Implement local state (`useState`, `useReducer`, `ref`)
+- ✅ Implement global UI state (Zustand, Pinia, Context, Redux)
+- ✅ Implement server state (React Query, SWR, Apollo)
+- ✅ Ensure state is immutable and updates correctly
+- ✅ Prevent race conditions and stale state bugs
+
+---
+
+## Non-goals
+
+- ❌ Do NOT introduce a new state management library if the project already uses one
+- ❌ Do NOT put server data (API responses) in a global UI store (like Redux) if React Query is available
+- ❌ Do NOT use global state for something that should be local (e.g., a modal's `isOpen` state)
+
+---
+
+## Workflow
+
+### Phase 1 — State Classification
+
+Analyze the data the user wants to manage and classify it:
+
+1. **Local UI State:** Only needed by one component (e.g., toggle button, input value).
+2. **Shared UI State:** Needed by multiple components, but not saved to DB (e.g., dark mode, cart items, selected filters).
+3. **Server State:** Data fetched from an API. Needs caching, refetching, and loading states.
+4. **URL State:** Data that should be shareable or survive refresh (e.g., search query `?q=shoes`, current page).
+
+---
+
+### Phase 2 — Strategy Selection
+
+Based on the classification and project stack (`project-audit`), choose the tool:
+
+| State Type | Recommended Tool |
+|------------|------------------|
+| Local UI | `useState`, `useReducer` |
+| Shared UI | Zustand, Pinia, Redux, Context API |
+| Server | React Query, RTK Query, Apollo, SWR |
+| URL | React Router `useSearchParams`, Next.js `useRouter` |
+
+**Rule:** Always respect existing project conventions. If they use Redux for everything, use Redux.
+
+---
+
+### Phase 3 — Implementation
+
+Generate the required code.
+
+**Example for Server State (React Query):**
+- Create query key factory
+- Create custom hook (`useUserList`)
+- Handle `isLoading`, `isError`, and `data`
+
+**Example for Global UI State (Zustand):**
+- Create store file (`userStore.ts`)
+- Define state interface and initial values
+- Define update actions (mutations)
+
+---
+
+### Phase 4 — Validation
+
+- [ ] Does it update correctly without mutating state directly?
+- [ ] Are unnecessary re-renders avoided?
+- [ ] Is server state properly cached and invalidated after mutations?
+- [ ] Is it placed in the correct directory (e.g., `src/store/` or `src/hooks/`)?
+
+---
+
+## Decision Tree
+
+```
+Is the data fetched from a backend API?
+  ├── Yes → Use Server State (React Query / SWR / RTK Query)
+  └── No  → Is the data only needed in one component and its direct children?
+              ├── Yes → Use Local State (`useState`)
+              └── No  → Is the data used across many distinct branches of the app?
+                          ├── Yes → Use Global State (Zustand / Redux)
+                          └── No  → Use Context API or lift state up
+```
+
+---
+
+## Output Format
+
+```
+🧠 State Management Plan
+─────────────────────────────────────────────────
+State Type: [Server / Global UI / Local / URL]
+Tool Used:  [React Query / Zustand / useState / etc.]
+
+Implementation:
+  ✅ [File 1] — [Store / Hook definition]
+  ✅ [File 2] — [Component integration]
+
+⚠️ Considerations:
+  • [Note on caching, stale time, or performance]
+
+🔗 Next Steps:
+  State is ready. Use the hook in your component.
+```
+
+---
+
+## Examples
+
+See `examples/` folder.
+

package/.qk-ai-skill-os/skills/_archive_old_skills/qk-table-crud-generator/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: qk-table-crud-generator
+description: >-
+  Tạo các bảng dữ liệu admin với đầy đủ tính năng phân trang, sắp xếp, lọc và thao tác thêm/sửa/xóa (CRUD).
+version: 1.0.0
+category: frontend
+tags: [table, data-grid, crud, admin, pagination, sorting]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Table & CRUD Generator
+
+> **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 an admin table", "build a user list", "add data grid"
+- User needs a view to manage a list of entities with CRUD capabilities
+- A feature requires complex data presentation (sorting, filtering, pagination)
+
+---
+
+## Scope
+
+- ✅ Generate a data table using design system components or libraries (e.g., TanStack Table)
+- ✅ Implement client-side or server-side pagination, sorting, and filtering
+- ✅ Add UI actions for Create, Edit, and Delete (modals or routing)
+- ✅ Integrate with `api-integration` hooks for data fetching and mutations
+- ✅ Handle loading, error, and empty states gracefully
+
+---
+
+## Non-goals
+
+- ❌ Do NOT build the backend API for the CRUD operations (assume they exist or delegate)
+- ❌ Do NOT use raw `<table>` tags if a powerful data-grid library is already installed
+
+---
+
+## Workflow
+
+### Phase 1 — Data Model & Requirements
+
+1. Understand the entity (e.g., `User`, `Product`).
+2. Identify columns to display.
+3. Determine operations needed (e.g., just Read/Delete, or full CRUD).
+4. Decide on Pagination strategy: Server-side (URL params) or Client-side (in-memory).
+
+---
+
+### Phase 2 — Table Component Setup
+
+1. Check for table libraries (e.g., `@tanstack/react-table`, MUI DataGrid, AntD Table).
+2. Define column definitions (headers, accessor keys, cell formatters).
+3. Set up the table UI wrapper.
+
+---
+
+### Phase 3 — Data Integration
+
+Connect to the state/API layer (e.g., React Query).
+- `useQuery` for fetching the list. Pass pagination/sorting state.
+- Handle `isLoading` → show skeleton or spinner.
+- Handle empty data → show empty state component.
+
+---
+
+### Phase 4 — CRUD Actions
+
+Implement actions (usually in an "Actions" column or toolbar):
+- **Create:** Button opening a Modal (delegate to `form-builder`) or routing to `/new`.
+- **Edit:** Button opening an Edit Modal or routing to `/edit/:id`.
+- **Delete:** Button opening a confirmation dialog, calling delete mutation on confirm.
+
+---
+
+## Decision Tree
+
+```
+Is the dataset large (requires backend pagination)?
+  ├── Yes → Implement Server-side pagination (sync state with URL search params)
+  └── No  → Implement Client-side pagination (fetch all once, slice in UI)
+
+Does the project use TanStack Table (React Table)?
+  ├── Yes → Use `useReactTable` to manage table state and column definitions
+  └── No  → Use the project's specific UI library table component
+```
+
+---
+
+## Output Format
+
+```
+📊 Table & CRUD Generated
+─────────────────────────────────────────────────
+Entity:     [Entity Name]
+Features:   [Pagination (Server), Sorting, CRUD actions]
+
+Components Created:
+  ✅ [Entity]Table.tsx
+  ✅ [Entity]Columns.tsx
+  ✅ DeleteConfirmModal.tsx
+
+Integration:
+  - Fetching: Linked to `use[Entity]List` hook
+  - Mutations: Linked to Create/Update/Delete hooks
+
+🔗 Next Steps:
+  If Create/Edit forms are needed, delegate to `form-builder`.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Columns are defined correctly
+- [ ] Loading and empty states are handled
+- [ ] Pagination/sorting state is managed properly
+- [ ] CRUD actions trigger the correct mutations or navigations
+- [ ] Delete actions have a confirmation step
+

package/.qk-ai-skill-os/skills/_archive_old_skills/qk-ui-builder/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: qk-ui-builder
+description: >-
+  Xây dựng các màn hình và layout phức tạp từ yêu cầu, tái sử dụng component và đảm bảo responsive.
+version: 1.0.0
+category: frontend
+tags: [ui, layout, screens, pages, styling, responsive]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# UI Builder
+
+> **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 wants to create a new page, screen, or view
+- User provides a mockup, wireframe, or visual description
+- User asks to "build a layout", "create a dashboard", "make the profile page"
+- Refactoring a large, messy view into a structured layout
+
+---
+
+## Scope
+
+- ✅ Translate requirements into a component hierarchy
+- ✅ Build layouts using Grid, Flexbox, and project styling conventions
+- ✅ Ensure responsive design (mobile-first or desktop-first based on project)
+- ✅ Integrate existing shared components (Buttons, Cards, Inputs) via `design-system` rules
+- ✅ Define placeholders for data and logic (to be filled by `api-integration` or `state-management`)
+
+---
+
+## Non-goals
+
+- ❌ Do NOT build backend APIs
+- ❌ Do NOT implement complex global state (delegate to `state-management`)
+- ❌ Do NOT invent new core UI components if they already exist in the design system
+- ❌ Do NOT write raw HTML (`<button>`) if a shared component (`<Button>`) exists
+
+---
+
+## Workflow
+
+### Phase 1 — Requirement Analysis
+
+1. Understand the goal: What screen are we building?
+2. Identify major sections: Header, Sidebar, Main Content, Footer, Modals.
+3. Identify data requirements: What data will populate this view? (Use mock data initially).
+
+---
+
+### Phase 2 — Component Hierarchy Planning
+
+Break the screen down into smaller components.
+**Rule of thumb:** If a section has complex logic or is reusable, it should be a separate component.
+
+*Example:*
+```text
+UserProfilePage
+  ├── ProfileHeader
+  │     ├── Avatar
+  │     └── UserStats
+  ├── UserSettingsForm (delegate to form-builder)
+  └── UserActivityList
+```
+
+---
+
+### Phase 3 — Design System Integration
+
+*(Relies on output from `design-system` skill)*
+Identify which existing components will be used for each part of the hierarchy.
+
+- Buttons → `<Button>`
+- Layouts → `<Container>`, `<Grid>`
+- Typography → `<Typography variant="h2">` or Tailwind text classes
+
+---
+
+### Phase 4 — Implementation
+
+Write the code.
+1. Build the layout skeleton first (Flexbox/Grid).
+2. Add static/mock data to visualize the structure.
+3. Apply styling for layout, spacing, and typography.
+4. Ensure responsive behavior (e.g., stack columns on mobile).
+
+---
+
+### Phase 5 — Validation
+
+- [ ] Does it match the requirements?
+- [ ] Is it responsive?
+- [ ] Does it strictly use the design system?
+- [ ] Is the code clean and well-structured (not one giant file)?
+
+---
+
+## Decision Tree
+
+```
+Is a section of the UI highly complex or forms a distinct logical unit?
+  ├── Yes → Extract it into its own component file (e.g., `ProfileHeader.tsx`)
+  └── No  → Keep it inline in the main layout file for now
+
+Does a required base component (e.g., DatePicker) exist in the project?
+  ├── Yes → Import and use it
+  └── No  → Use a standard HTML fallback or instruct `component-generator` to build it later
+
+Is the UI data-heavy (like a complex form or table)?
+  ├── Yes → Delegate specific sections to `form-builder` or `table-crud-generator`
+  └── No  → Build it fully within `ui-builder`
+```
+
+---
+
+## Output Format
+
+```
+🎨 UI Builder Summary
+─────────────────────────────────────────────────
+Screen:     [Name of the screen/view built]
+
+Component Hierarchy:
+  [Tree showing parent and child components]
+
+📁 Files Created/Modified:
+  ✅ [path/to/Page.tsx]
+  ✅ [path/to/SubComponent.tsx]
+
+🛠️ Implementation Details:
+  - Responsive: [Yes - describe breakpoints used]
+  - Mock Data:  [Added placeholders for API integration]
+
+🔗 Next Steps:
+  → Need to wire up API? Route to `api-integration`.
+  → Need complex state? Route to `state-management`.
+```
+
+---
+
+## Examples
+
+See `examples/` folder.
+