ai-developer-skill-os 2.0.1 → 3.0.0

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

@@ -1,444 +1,40 @@
----
-name: qk-ui-system-builder
-purpose: Quản lý Design System, Component Library, Consistency.
-mode_supported: [standard, enterprise]
-input: [UI constraints]
-output: [Reusable UI components/Tokens]
-workflow: [1. Check Token -> 2. Check Pattern -> 3. Generate Component]
-allowed_tools: [write_to_file, read_file]
-handoff_to: [none]
----
-
-# 🛠️ qk-ui-system-builder - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Quản lý Design System, Component Library, Consistency.
-
-## 🎯 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: `none`
-- 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ư)*
-
----
-
-
-
-# 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
-
----
-
-
-
-# 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.
-
----
-
-
-
-# Component 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 a Card component", "make a reusable Button", "extract this into a component"
-- A larger skill (`ui-builder`, `form-builder`) requires a new isolated UI piece to be built
-- Refactoring a large component by splitting it into smaller, reusable parts
-
----
-
-## Scope
-
-- ✅ Generate a single, focused component (e.g., `UserCard`, `StatBadge`, `Dropdown`)
-- ✅ Define strict, explicit types/interfaces for all props
-- ✅ Implement component variants (e.g., `size`, `color`, `variant`) if needed
-- ✅ Follow project styling rules (Tailwind, CSS Modules, Styled Components)
-- ✅ Ensure accessibility (ARIA attributes, semantic HTML) where applicable
-
----
-
-## Non-goals
-
-- ❌ Do NOT build full pages or complex screens (delegate to `ui-builder`)
-- ❌ Do NOT handle complex business logic or data fetching inside a dumb/presentational component
-- ❌ Do NOT overwrite existing components without explicit instruction
-
----
-
-## Workflow
-
-### Phase 1 — Component Design
-
-Determine:
-1. **Name:** PascalCase (e.g., `ProductCard`).
-2. **Responsibility:** What exactly does this component do? Keep it single-responsibility.
-3. **Props:** What data does it need from its parent? What events does it emit?
-
----
-
-### Phase 2 — API (Props) Definition
-
-Draft the interface first.
-- Make required props explicit.
-- Use optional props (`?`) for variants or non-essential data.
-- Avoid `any`.
-
-*Example:*
-```typescript
-interface ProductCardProps {
-  id: string;
-  title: string;
-  price: number;
-  imageUrl?: string;
-  isAvailable?: boolean;
-  onAddToCart: (id: string) => void;
-}
-```
-
----
-
-### Phase 3 — Implementation
-
-Write the component code.
-1. Use destructuring for props.
-2. Apply styling based on `design-system` rules.
-3. Handle empty/null states (e.g., if `imageUrl` is missing, show a placeholder).
-4. Add basic interactivity (e.g., calling `onAddToCart` when clicked).
-
----
-
-### Phase 4 — Validation
-
-- [ ] Are all props typed correctly?
-- [ ] Is it truly reusable (no hardcoded data)?
-- [ ] Does it use project design tokens?
-- [ ] Is it exported correctly according to project conventions (default vs. named export)?
-
----
-
-## Decision Tree
-
-```
-Does the component need to manage its own state (e.g., an accordion opening/closing)?
-  ├── Yes → Add local state (`useState`). Keep it minimal.
-  └── No  → Make it a pure "dumb" component receiving props.
-
-Are there multiple visual styles requested (e.g., primary, secondary, outline)?
-  ├── Yes → Add a `variant` prop and map it to style classes.
-  └── No  → Implement the single required style.
-```
-
----
-
-## Output Format
-
-```
-🧩 Component Generated
-─────────────────────────────────────────────────
-Name:     [ComponentName]
-Path:     [path/to/Component.tsx]
-
-Props Interface:
-  [List key props here briefly]
-
-Features:
-  • [Feature 1, e.g., "Supports primary/secondary variants"]
-  • [Feature 2, e.g., "Fully typed with TypeScript"]
-
-🔗 Next Steps:
-  Component is ready to be imported into your layout.
-```
-
----
-
-## Examples
-
-See `examples/` folder.
+---
+name: qk-ui-system-builder
+version: 3.0.0
+updated: 2026-07-02
+description: Build and maintain Design Systems, Token extraction, and shared UI libraries.
+category: frontend
+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]
+---
+
+# 🛠️ 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ỡ).

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

@@ -1,33 +1,59 @@
----
-name: qk-validation-gate
-purpose: Cổng kiểm định chất lượng bắt buộc (Test, Lint, Security) trước khi hoàn tất.
-mode_supported: [standard]
-input: [Completed code]
-output: [Validation pass/fail]
-workflow: [1. Run Tests -> 2. Linting -> 3. Security Scan -> 4. Handoff if PASS]
-allowed_tools: [run_command]
-handoff_to: [qk-docs]
----
-
-# 🛠️ qk-validation-gate - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Cổng kiểm định chất lượng bắt buộc (Test, Lint, Security) trước khi hoàn tất.
-
-## 🎯 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-docs`
-- 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-validation-gate
+version: 3.0.0
+updated: 2026-07-02
+description: Mandatory Quality Gate (Test, Lint, Security).
+category: validation
+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]
+---
+
+# 🛠️ qk-validation-gate - Standard Operating Procedure
+
+> **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.
+
+## 🔄 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.
+
+## 🛡️ 2. 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.
+```
+
+## 🤝 4. Handoff Pipeline
+1. `complete`: Once all checks pass, output the Validation Report.
+
+## 📝 5. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **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.

package/templates/bug-report.md

@@ -0,0 +1,21 @@
+### 🐛 Báo Cáo Xử Lý Lỗi (Bug Report)
+
+**1. Tóm tắt (Summary)**
+- [Tóm tắt ngắn gọn lỗi là gì và đã sửa như thế nào]
+
+**2. Chi tiết thay đổi (Changes)**
+- Cập nhật file: `[Tên file]`
+- Xóa/Thêm: [Logic cụ thể đã sửa]
+
+**3. Nguyên nhân gốc rễ (Reason / Root Cause)**
+- Tại sao lỗi này xảy ra? (Giải thích kỹ thuật ngắn gọn)
+- Tại sao cách sửa này lại hiệu quả?
+
+**4. Xác thực (Verification)**
+- Làm sao để biết lỗi đã được sửa? (Test script hoặc các bước tái hiện)
+
+**5. Rủi ro (Risks / Side Effects)**
+- Việc sửa lỗi này có ảnh hưởng đến component nào khác không? (Nếu không, ghi "An toàn").
+
+**6. Hành động tiếp theo (Next Action)**
+- [Đề xuất bước tiếp theo: chạy test, deploy, hoặc bàn giao]

package/templates/design-report.md

@@ -0,0 +1,21 @@
+### 🎨 Báo Cáo Triển Khai Giao Diện (Design / UI Report)
+
+**1. Tóm tắt (Summary)**
+- [Tên Component/Trang vừa được code từ Design]
+
+**2. Chi tiết thay đổi (Changes)**
+- [Các CSS/Tailwind classes đã sử dụng]
+- [Cấu trúc Semantic HTML]
+
+**3. Quyết định UI/UX (Reason / Design Tokens)**
+- [Map màu sắc/font với Design System]
+
+**4. Xác thực (Verification)**
+- Responsive: [Đã test trên Mobile/Tablet chưa]
+- Accessibility (a11y): [Đã kiểm tra alt text, aria-label chưa]
+
+**5. Rủi ro (Risks / Side Effects)**
+- [Có dùng magic numbers (px cứng) thay vì token không?]
+
+**6. Hành động tiếp theo (Next Action)**
+- [Đề xuất: Gửi cho Designer review]

package/templates/feature-report.md

@@ -0,0 +1,20 @@
+### 🚀 Báo Cáo Triển Khai Tính Năng (Feature Report)
+
+**1. Tóm tắt (Summary)**
+- [Mô tả ngắn gọn tính năng vừa được phát triển]
+
+**2. Chi tiết thay đổi (Changes)**
+- Frontend: [Các component/UI đã thêm]
+- Backend/API: [Các endpoint/schema đã cập nhật]
+
+**3. Kiến trúc thiết kế (Reason / Design Reasoning)**
+- [Giải thích lựa chọn state management, hooks, hoặc cấu trúc DB]
+
+**4. Xác thực (Verification)**
+- [Cách chạy thử hoặc test case đã pass]
+
+**5. Rủi ro (Risks / Side Effects)**
+- [Có ảnh hưởng đến hiệu năng không? Bundle size?]
+
+**6. Hành động tiếp theo (Next Action)**
+- [Đề xuất: Chạy E2E test, Handoff sang QA]

package/templates/review-report.md

@@ -0,0 +1,21 @@
+### 📐 Báo Cáo Rà Soát Mã Nguồn (Code Review Report)
+
+**1. Tóm tắt (Summary)**
+- [Scope code đã được review]
+
+**2. Vấn đề phát hiện (Changes / Smells Detected)**
+- Lỗi Naming: [Chi tiết]
+- Vấn đề Clean Code: [Chi tiết]
+- Vi phạm SOLID/DRY: [Chi tiết]
+
+**3. Đề xuất & Giải pháp (Reasoning / Fixes Applied)**
+- [Tại sao phải sửa và code đã được refactor như thế nào]
+
+**4. Xác thực (Verification)**
+- [Kết quả chạy linter và type-checker sau khi sửa]
+
+**5. Rủi ro (Risks / Side Effects)**
+- [Có thể gây break API cũ không?]
+
+**6. Hành động tiếp theo (Next Action)**
+- [Đề xuất: Merge nhánh, Handoff sang Validation Gate]