ai-developer-skill-os 7.0.2 → 7.5.0

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

@@ -0,0 +1,96 @@
+---
+name: qk-deployment
+description: >-
+  Cấu hình CI/CD pipelines, tạo Dockerfile và thiết lập môi trường để deploy lên Vercel, AWS hoặc VPS.
+version: 1.0.0
+category: backend
+tags: [deploy, ci-cd, docker, github-actions, devops, hosting]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Deployment & DevOps
+
+> **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 "how do I deploy this?", "create a Dockerfile", or "setup CI/CD"
+- Configuring GitHub Actions, GitLab CI, or Jenkins
+- Preparing a project for Vercel, Netlify, Render, or AWS
+- Setting up environment variables for production
+
+---
+
+## Scope
+
+- ✅ **Containerization:** Write `Dockerfile` and `docker-compose.yml`.
+- ✅ **CI/CD Pipelines:** Write GitHub Actions YAML for testing, building, and deploying.
+- ✅ **Environment Setup:** Create `.env.example` and document required production variables.
+- ✅ **Build Scripts:** Ensure `package.json` has correct build and start commands.
+
+---
+
+## Non-goals
+
+- ❌ Do NOT expose real production secrets. Always use placeholders or CI secrets.
+- ❌ Do NOT over-complicate (e.g., don't setup Kubernetes if a simple Docker container on a VPS is enough).
+
+---
+
+## Workflow
+
+### Phase 1 — Platform Selection
+
+Ask the user where they are deploying (if not specified):
+1. **PaaS (Vercel, Render, Heroku):** Very easy, mostly relies on `vercel.json` or standard build scripts. No Docker needed usually.
+2. **VPS/VM (DigitalOcean, AWS EC2):** Needs Docker and/or PM2 + Nginx reverse proxy.
+3. **Container Service (AWS ECS, Google Cloud Run):** Needs a highly optimized Dockerfile.
+
+### Phase 2 — Containerization (If required)
+
+Create a multi-stage Dockerfile for minimal image size:
+1. `deps` stage: Install dependencies.
+2. `builder` stage: Build the app.
+3. `runner` stage: Copy only the built assets and prod modules, start the app.
+
+### Phase 3 — CI/CD Pipeline
+
+Create `.github/workflows/deploy.yml`:
+- Trigger on `push` to `main`.
+- Job 1: Setup Node/Python/Go, install deps, run tests, run linter.
+- Job 2: Build image and push to registry, or deploy to PaaS.
+
+### Phase 4 — Environment Variables
+
+Audit the codebase for `process.env.XYZ` and create a `.env.example` file listing every required variable.
+
+---
+
+## Output Format
+
+```
+🚀 Deployment Plan
+─────────────────────────────────────────────────
+Target:     [Vercel / Docker VPS / AWS]
+Tooling:    [GitHub Actions, Docker]
+
+Files Created/Modified:
+  ✅ `Dockerfile` (Multi-stage build)
+  ✅ `.github/workflows/deploy.yml`
+  ✅ `.env.example`
+
+⚠️ Prerequisites:
+  Before deploying, you must set these secrets in GitHub Actions:
+  - `DOCKER_USERNAME`
+  - `DATABASE_URL`
+
+🔗 Next Steps:
+  Commit these files and push to `main` to trigger the pipeline.
+```
+

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

@@ -0,0 +1,137 @@
+---
+name: qk-design-system
+description: >-
+  Ép buộc sử dụng design system, component library và token hiện có, ngăn chặn việc viết HTML/CSS rác.
+version: 1.0.0
+category: frontend
+tags: [design-system, ui-components, styling, tailwind, material-ui, shadcn]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Design System Enforcer
+
+> **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:
+- About to build UI screens or components
+- Styling or layout work is required
+- User asks to "make it look good" or "match the design"
+- Integrating a third-party UI library (Tailwind, MUI, AntD, Shadcn)
+
+---
+
+## Scope
+
+- ✅ Identify the UI library or design system in use
+- ✅ Map standard HTML elements to project-specific components (e.g., `<button>` → `<Button>`)
+- ✅ Enforce usage of design tokens (colors, spacing, typography) instead of hardcoded values
+- ✅ Provide available component variants and props to downstream skills (`ui-builder`)
+- ✅ Prevent generation of raw CSS/inline styles if utility classes or styled-components are standard
+
+---
+
+## Non-goals
+
+- ❌ Do NOT create new base components if an equivalent already exists
+- ❌ Do NOT introduce a new styling method (e.g., don't add Tailwind if project uses CSS Modules)
+- ❌ Do NOT design full pages (delegate to `ui-builder`)
+
+---
+
+## Workflow
+
+### Phase 1 — Detect Design System
+
+Analyze dependencies and project files to identify:
+1. **Component Library:** Shadcn UI, MUI, Ant Design, Chakra, Bootstrap, custom internal library?
+2. **Styling Method:** Tailwind CSS, CSS Modules, Styled Components, Emotion, SCSS, Vanilla CSS?
+3. **Location of Shared Components:** Usually `src/components/ui/`, `src/shared/components/`, or from an npm package.
+4. **Design Tokens:** `tailwind.config.js`, `theme.ts`, `variables.scss`.
+
+---
+
+### Phase 2 — Component Mapping
+
+Before `ui-builder` generates code, create a mapping table for required elements:
+
+| Standard Element | Project Component | Source / Import Path |
+|------------------|-------------------|----------------------|
+| `<button>` | `<Button>` | `@/components/ui/button` |
+| `<input type="text">` | `<Input>` | `@/components/ui/input` |
+| `<div>` (Card) | `<Card>` | `@/components/ui/card` |
+| `<h1>` | `<Typography variant="h1">` | `@mui/material` |
+
+---
+
+### Phase 3 — Token Extraction
+
+Identify available tokens for spacing, colors, and typography to avoid hardcoding:
+- *Instead of:* `margin-top: 16px; color: #3b82f6;`
+- *Use:* `mt-4 text-blue-500` (Tailwind) or `theme.spacing(2)` (MUI) or `var(--primary-color)`.
+
+---
+
+### Phase 4 — Rule Enforcement
+
+Pass strict instructions to `ui-builder` or `component-generator`:
+- "You MUST use `<Button>` instead of `<button>`."
+- "You MUST use Tailwind classes for all styling. No inline `style={{}}` allowed."
+
+---
+
+## Decision Tree
+
+```
+Does the project use a component library (e.g., Shadcn, MUI)?
+  ├── Yes → Is the required component available?
+  │           ├── Yes → Require its use
+  │           └── No  → Instruct `component-generator` to create it following library style
+  └── No  → Check if custom shared components exist
+              ├── Yes → Map to custom shared components
+              └── No  → Use raw HTML but enforce project's styling method (e.g., Tailwind)
+
+Does the project use utility classes (Tailwind)?
+  ├── Yes → Forbid inline styles or custom CSS files
+  └── No  → Enforce existing CSS Modules / Styled Components patterns
+```
+
+---
+
+## Output Format
+
+```
+🎨 Design System Rules
+─────────────────────────────────────────────────
+Library:        [Shadcn / MUI / Tailwind / Custom / etc.]
+Styling Method: [Tailwind / CSS Modules / Styled Components]
+
+Component Mapping for this task:
+  ✅ Button  → `<Button>` from `@/components/ui/button`
+  ✅ Input   → `<Input>` from `@/components/ui/input`
+  ✅ Layout  → Flexbox with Tailwind (`flex flex-col gap-4`)
+
+Styling Rules Enforced:
+  • No raw HTML `<button>` allowed
+  • No inline styles allowed
+  • Use primary color token for CTAs
+
+🔗 Next Steps:
+  Passing these rules to `ui-builder` to generate the UI.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Design system and styling method correctly identified
+- [ ] Mappings created for all necessary UI elements
+- [ ] Design tokens (spacing/colors) prioritized over hardcoded values
+- [ ] Strict enforcement rules passed to next skill
+

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

@@ -0,0 +1,140 @@
+---
+name: qk-form-builder
+description: >-
+  Xây dựng Form chuẩn xác với quản lý trạng thái, validate dữ liệu (Zod, Yup) và xử lý hiển thị lỗi.
+version: 1.0.0
+category: frontend
+tags: [form, validation, react-hook-form, zod, yup, formik]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Form 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 says "create a login form", "add a settings page", "build a contact form"
+- User provides a data model and needs a UI to create/edit it
+- A form needs complex validation logic added
+- Refactoring a messy form into a structured library pattern (e.g., React Hook Form)
+
+---
+
+## Scope
+
+- ✅ Define the form data schema and validation rules
+- ✅ Manage form state efficiently (preventing unnecessary re-renders)
+- ✅ Map form fields to the project's design system components
+- ✅ Handle submission state (loading, success, error)
+- ✅ Handle validation errors and display them accessibly
+- ✅ Integrate with `api-integration` for submission
+
+---
+
+## Non-goals
+
+- ❌ Do NOT reinvent form state management if a library is present
+- ❌ Do NOT use raw HTML inputs if design system components exist
+- ❌ Do NOT skip validation (client-side validation is required)
+
+---
+
+## Workflow
+
+### Phase 1 — Schema Design
+
+Define the exact shape of the data the form collects.
+Determine validation rules for each field (required, min length, email format, etc.).
+
+If the project uses Zod, Yup, or Joi, define the schema first.
+*Example:*
+```typescript
+const userFormSchema = z.object({
+  email: z.string().email("Invalid email address"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+});
+```
+
+---
+
+### Phase 2 — State Management Selection
+
+Check project dependencies for form libraries:
+1. `react-hook-form` (Preferred for React)
+2. `formik`
+3. Custom Vue/Svelte bindings
+4. Standard controlled components (`useState`) if no library exists and form is simple.
+
+---
+
+### Phase 3 — Component Assembly
+
+1. Set up the form wrapper and submission handler.
+2. For each field in the schema, render the appropriate UI component (from `design-system`).
+3. Connect the UI component to the form state (register / Controller).
+4. Render error messages below fields if validation fails.
+
+---
+
+### Phase 4 — Submission & Integration
+
+- Add `isLoading` state to the submit button.
+- Disable submit button during submission.
+- On success: Show success message or redirect, and optionally reset form.
+- On error: Display backend error messages (toast or form-level alert).
+
+---
+
+## Decision Tree
+
+```
+Does the project use a validation library (Zod, Yup)?
+  ├── Yes → Use it to define schema and pass to form resolver
+  └── No  → Implement standard HTML5 validation or simple manual validation logic
+
+Is it a complex multi-step form (wizard)?
+  ├── Yes → Break into sub-components, use global or lifted state for form data
+  └── No  → Handle state locally within the single form component
+```
+
+---
+
+## Output Format
+
+```
+📝 Form Built
+─────────────────────────────────────────────────
+Name:     [FormName]
+Schema:   [Zod / Yup / Manual]
+Library:  [React Hook Form / Formik / Native]
+
+Fields Implemented:
+  ✅ email (string, required, email)
+  ✅ password (string, required, min: 8)
+
+Integration:
+  - Validation: Client-side wired up
+  - Submission: Wired to `[submitFunction]`
+  - Loading UI: Handled on submit button
+
+🔗 Next Steps:
+  Make sure the API endpoint is ready to accept this payload.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Form uses existing design system components (Inputs, Buttons)
+- [ ] Client-side validation is implemented
+- [ ] Error messages are displayed properly
+- [ ] Loading state disables the submit button
+- [ ] Accessibility: Inputs have associated labels and error ARIA attributes
+

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

@@ -0,0 +1,155 @@
+---
+name: qk-frontend-architecture
+description: >-
+  Phân tích cấu trúc thư mục frontend và quyết định vị trí đặt file chuẩn xác theo kiến trúc hiện tại.
+version: 1.0.0
+category: frontend
+tags: [architecture, folder-structure, conventions, file-placement]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Frontend Architecture
+
+> **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:
+- About to create new files or components
+- User asks "where should I put this file?" or "how should I organize this?"
+- Moving or refactoring code across different modules
+- Inheriting an unfamiliar frontend project
+
+---
+
+## Scope
+
+- ✅ Discover the existing frontend folder structure
+- ✅ Define where new components, hooks, services, and types should be placed
+- ✅ Enforce separation of concerns (e.g., UI vs. Business Logic vs. Data)
+- ✅ Identify architectural patterns in use (e.g., Feature-based, Layer-based)
+- ✅ Validate file placement before execution by other skills
+
+---
+
+## Non-goals
+
+- ❌ Do NOT rewrite the entire project architecture unless explicitly asked
+- ❌ Do NOT generate code (delegate to `component-generator` or `ui-builder`)
+- ❌ Do NOT enforce personal preferences over established project conventions
+
+---
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Architectural violation that breaks the build or creates circular dependencies |
+| P1 | File placed in completely wrong layer (e.g., API logic in UI component) |
+| P2 | Inconsistent folder or file naming |
+| P3 | Minor deviation from convention |
+
+---
+
+## Workflow
+
+### Phase 1 — Structure Discovery
+
+*(Relies on `context-manager` if already loaded)*
+
+Analyze the root source directory (e.g., `src/`, `app/`):
+1. **Layer-based:** `components/`, `hooks/`, `services/`, `utils/`, `types/`
+2. **Feature-based:** `features/auth/`, `features/products/`
+3. **Framework-specific:** `app/` (Next.js App Router), `pages/` (Next.js Pages Router, Nuxt)
+4. **Domain-driven:** `domains/user/`, `domains/payment/`
+5. **FSD (Feature Sliced Design):** `app/`, `processes/`, `pages/`, `widgets/`, `features/`, `entities/`, `shared/`
+
+---
+
+### Phase 2 — Rule Extraction
+
+Based on discovery, define the project's rules for:
+- **Components:** Are they flat? Grouped by feature? Atomic design?
+- **Hooks:** Shared in `src/hooks/` or collocated with components?
+- **State:** Global store vs. feature stores?
+- **API/Services:** Where are HTTP calls made?
+- **Types:** Centralized `types/` or collocated?
+- **Naming Conventions:** PascalCase, camelCase, kebab-case, `index.ts` usage?
+
+---
+
+### Phase 3 — File Placement Decision
+
+When a new feature/component is requested, map it to the structure:
+
+**Input:** "Create a User Profile card that fetches user data."
+**Decision:**
+- UI Component: `src/features/user/components/UserProfileCard.tsx`
+- API Hook: `src/features/user/api/useUser.ts`
+- Types: `src/features/user/types/index.ts`
+
+---
+
+### Phase 4 — Enforcement & Validation
+
+Before passing control to a generation skill (like `ui-builder`), ensure the plan adheres to the rules.
+
+- [ ] Does it mix concerns? (e.g., putting an API call directly in a shared UI button)
+- [ ] Does it violate import boundaries? (e.g., a shared component importing from a specific feature)
+- [ ] Is the naming consistent?
+
+---
+
+## Decision Tree
+
+```
+Is the project using a Feature-based structure?
+  ├── Yes → Place feature-specific code in `features/<feature-name>/`
+  └── No  → Use Layer-based structure (`components/`, `hooks/`, etc.)
+
+Is the code shared across multiple domains/features?
+  ├── Yes → Place in `shared/` or global `components/` / `hooks/`
+  └── No  → Collocate with the specific domain/feature
+
+Are there existing examples of this type of file?
+  ├── Yes → Copy their placement and naming pattern
+  └── No  → Propose a standard location and ask user to confirm
+```
+
+---
+
+## Output Format
+
+```
+🏗️ Frontend Architecture Plan
+─────────────────────────────────────────────────
+Structure Type: [Feature-based / Layer-based / FSD / etc.]
+Naming:         [PascalCase for components, camelCase for functions]
+
+File Placement:
+  📄 [path/to/new/file1.tsx] — [Why it goes here]
+  📄 [path/to/new/file2.ts]  — [Why it goes here]
+
+⚠️ Constraints enforced:
+  • [Constraint 1, e.g., "API calls must be in hooks, not components"]
+  • [Constraint 2, e.g., "Shared UI components cannot import from features/"]
+
+🔗 Next Steps:
+  Delegating to `[skill-name]` to generate the files.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Structure type identified correctly
+- [ ] File placement follows existing conventions
+- [ ] Naming matches project standards
+- [ ] Separation of concerns maintained
+- [ ] Plan ready to be executed by generation skills
+

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

@@ -0,0 +1,133 @@
+---
+name: qk-frontend-debug
+description: >-
+  Chẩn đoán và sửa các lỗi đặc thù frontend như Hydration error, infinite re-render, stale closure và vỡ CSS.
+version: 1.0.0
+category: frontend
+tags: [debug, react, hydration, rerender, css, state-bug]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Frontend Debugger
+
+> **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 reports a UI-specific bug ("screen is blank", "button doesn't work")
+- React throws a Hydration Error (`Text content did not match. Server: "A" Client: "B"`)
+- React throws an infinite loop error (`Too many re-renders`)
+- CSS styling is broken or overflowing unexpectedly
+- Form validation behaves incorrectly
+
+**Note:** For backend or general logic bugs, use `bug-fix`. For performance issues, use `frontend-performance`.
+
+---
+
+## Scope
+
+- ✅ Diagnose and fix React hydration mismatches (Next.js / SSR)
+- ✅ Fix infinite loops in `useEffect` and missing dependencies
+- ✅ Resolve state staleness (stale closures in async functions or hooks)
+- ✅ Fix CSS layout issues (Flexbox/Grid blowouts, z-index stacking context)
+- ✅ Provide a targeted, minimal fix that doesn't break other UI elements
+
+---
+
+## Non-goals
+
+- ❌ Do NOT rewrite the entire component to fix a small CSS bug
+- ❌ Do NOT disable hydration checks (`suppressHydrationWarning`) unless absolutely necessary and justified
+- ❌ Do NOT apply quick-fixes (like `// @ts-ignore` or wrapping everything in `setTimeout`) without understanding the root cause
+
+---
+
+## Workflow
+
+### Phase 1 — Reproduction & Isolation
+
+1. Identify the exact error message or visual symptom.
+2. Isolate the component causing the issue.
+3. Determine the environment (SSR, CSR, mobile, specific browser).
+
+---
+
+### Phase 2 — Common Issue Diagnosis
+
+**Hydration Errors (Next.js/SSR):**
+- Cause: Rendering `window`, `localStorage`, or random data (e.g., `Math.random()`, Dates) on the first pass.
+- Fix: Move client-only rendering inside a `useEffect` (isMounted pattern) or use dynamic imports with `ssr: false`.
+
+**Too many re-renders:**
+- Cause: Updating state directly in the render body, or inside a `useEffect` without proper dependencies.
+- Fix: Move state updates into event handlers, or fix `useEffect` dependencies.
+
+**Stale Closures:**
+- Cause: A `useEffect` or `useCallback` is using old state because it's missing from the dependency array.
+- Fix: Add dependencies, use refs (`useRef`) for mutable values, or use functional state updates (`setState(prev => prev + 1)`).
+
+**CSS Z-Index/Stacking Issues:**
+- Cause: Missing `position: relative/absolute` on parent, or a new stacking context was created.
+- Fix: Inspect parent elements, adjust `z-index`, or use Portals for modals.
+
+---
+
+### Phase 3 — Fix Application
+
+Apply the minimal fix required to resolve the issue while preserving surrounding logic and styles.
+
+---
+
+## Decision Tree
+
+```
+Is it a Hydration Error?
+  ├── Yes → Is it caused by client-side APIs (window/localStorage)?
+  │           ├── Yes → Use `useEffect` to delay rendering until mounted
+  │           └── No  → Check for mismatched HTML tags (e.g., <p> inside <p>)
+  └── No  → Proceed to next check
+
+Is it an infinite loop?
+  ├── Yes → Check `useEffect` dependencies. Are objects/arrays re-created every render?
+  │           ├── Yes → Memoize them (`useMemo`) or move outside component
+  │           └── No  → Ensure `setState` isn't called unconditionally in render
+  └── No  → Proceed
+```
+
+---
+
+## Output Format
+
+```
+🪲 Frontend Debug Report
+─────────────────────────────────────────────────
+Symptom:    [Description of the bug]
+Root Cause: [Explanation of why it failed, e.g., Stale Closure in useEffect]
+
+🔧 Fix Applied:
+  [Brief description of the code change]
+
+✅ Verification:
+  - Error no longer throws
+  - UI renders correctly
+
+⚠️ Notes:
+  [Any side effects or things to watch out for]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Root cause clearly identified (not just patched)
+- [ ] Fix is minimal and targeted
+- [ ] No Hydration warnings remain
+- [ ] Component doesn't infinitely loop
+- [ ] No regression on related UI
+