@tungvivas/angular-vibe-kit 0.1.0 → 0.3.0

package/skills/clarify-request/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: clarify-request
+description: >
+  Normalize a vague or underspecified request into a standard brief BEFORE acting on it.
+  Use when the user asks for work with missing context — e.g. "fix bug A" (no repro/error),
+  "thêm tính năng B" / "add feature B" (no scope), "sửa cho tôi", "thêm trường X vào component Y"
+  (no data type / validation / API info), "kiểm tra hiệu suất" / "check performance" (no target or
+  symptom), "làm cho tôi cái này" — any coding request where the target, expected behavior, scope,
+  or done-criteria are unclear. Do NOT use when the request is already specific, when it is a pure
+  question (use explain), or when already inside a /plan, /dev-cycle, or /new-feature flow (those
+  have their own clarify phases).
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+# Clarify Request (prompt normalizer)
+
+Terse requests like "fix bug A" or "add field X" waste a round-trip when acted on blindly: the
+wrong file gets changed, the wrong shape gets assumed, the fix misses the actual symptom. This
+skill turns such a request into a **standard brief** — filled from the project first, from the
+user only for what the project cannot answer — then routes it to the right workflow.
+
+## When NOT to trigger (check first)
+
+Skip this skill entirely when:
+- The request already names the exact target AND the expected outcome AND its constraints.
+- It is a pure question ("why...", "explain...", "how does...") → the **explain** skill owns that.
+- You are already inside `/plan`, `/dev-cycle`, `/new-feature`, or `/init` — their own phases
+  (Phase B, Phase 0, Step 1, Stage 1) do the clarifying; do not stack a second layer.
+- The user explicitly says to just do it ("cứ làm đi", "just do it", "no questions") — then fill
+  gaps from the project, state your assumptions in one line each, and proceed.
+
+## Step 1 — Classify the intent
+
+| Intent | Signals |
+|--------|---------|
+| **bug** | "fix", "lỗi", "bug", "không chạy", "sai", an error message pasted |
+| **feature** | "thêm tính năng", "add feature", an SRS/spec mentioned, a new screen/module |
+| **small-edit** | "thêm trường/cột", "đổi label", "ẩn nút", a single component/file named |
+| **review** | "kiểm tra", "review", "tối ưu chưa", "hiệu suất", "check" |
+
+## Step 2 — Fill from the project BEFORE asking anything
+
+Never ask what the project already answers. Look here first:
+
+| Missing info | Where to look |
+|--------------|---------------|
+| Which file/component is "X" | `Glob`/`Grep` for the name; feature folders; `docs/ARCHITECTURE.md` |
+| Does the API return that field | `docs/API_CONTRACT.md`, the feature's `services/*.ts` + `models/*.ts` |
+| Which wrapper to use for new UI | `docs/DESIGN_SYSTEM.md` → Wrapped Components table |
+| Project conventions / do-not-touch | `.claude/rules/project-rules.md` (Precedence, Coexistence) |
+| What was recently worked on (bug context) | `docs/PROJECT-STATUS.md`, `git log` if permitted, feature `CONTEXT.md` |
+| Version idioms for the change | `.claude/angular-practices/` |
+
+## Step 3 — Ask ONE batched set of what's still missing
+
+Ask only the unfilled fields, all in one message, multiple-choice where possible.
+Required fields by intent:
+
+**Common (all intents):** exact target (file/component/feature) · current vs. expected behavior ·
+scope + constraints (what must NOT be touched) · done-criteria (how we know it's right).
+
+| Intent | Additional required fields |
+|--------|---------------------------|
+| **bug** | repro steps · error message/log · since when (after which change?) · which screen/module |
+| **feature** | SRS or description · screens in scope · endpoints (already in API_CONTRACT?) · relation to existing features · permissions |
+| **small-edit** | data type of the new field · validation rules · where it shows (form / table / both) · does the API already return it |
+| **review** | which page/component · concrete symptom (slow on load? scroll? typing?) · expected measure |
+
+If an answer reveals a new ambiguity, ask that one follow-up — don't guess silently, don't drip
+every question one at a time.
+
+## Step 4 — Print the brief, then route
+
+Print the normalized brief so the user can correct it at a glance:
+
+```markdown
+📋 **Brief**
+- Type: <bug | feature | small-edit | review>
+- Target: <exact file/component/feature path>
+- Current → Expected: <one line>
+- Scope: <in> / NOT: <out>
+- Done when: <criteria>
+- Filled from project: <what you found and where>
+- From user: <their answers>
+```
+
+Then route — do not reinvent workflows this kit already has:
+
+| Type | Route |
+|------|-------|
+| **feature** (multi-screen / multi-endpoint) | Suggest `/plan` → `/dev-cycle`; small single-screen feature may go straight to `/new-feature` |
+| **bug** (non-trivial / runtime) | Dispatch the **angular-debugger** agent; trivial one-liners fix directly |
+| **small-edit** | Do it directly, following the brief + `.claude/angular-practices/` + wrapper priority |
+| **review** | Run `/review-pr` inline, or dispatch **angular-reviewer** for a large diff; performance-scoped review states the symptom + target from the brief |
+
+One confirmation, not two: if the brief is complete and the route is obvious, state both and
+proceed — don't ask "is the brief OK?" and then "should I start?" as separate gates.

package/skills/component-wrapper-priority/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: component-wrapper-priority
+description: Use before importing a raw UI-library component (p-dropdown, mat-select, nz-*, ng-bootstrap, etc.) when implementing or reviewing a feature — enforces using this project's shared wrapper components from docs/DESIGN_SYSTEM.md instead of bypassing them with a direct library import.
+---
+
+# Component Wrapper Priority
+
+Before you write a template or import that uses a UI-library component directly, check whether
+the project already has a **shared wrapper** for that need. Bypassing an existing wrapper with a
+raw library import is a defect, not a shortcut.
+
+## Decision tree
+
+1. **Open `docs/DESIGN_SYSTEM.md` → the Wrapped Components table.**
+2. **A wrapper exists for the need? → USE IT.** Never bypass:
+   - Select / dropdown → use the project wrapper (e.g. `<app-select>`), not raw `p-dropdown` / `mat-select` / `nz-select`.
+   - Date input → use the wrapper (e.g. `<app-date-picker>`), not raw `p-calendar` / `mat-datepicker`.
+   - Dialog / modal, table, form field, button — use the wrapper if one is listed, not the raw library component.
+   - Shared UI states (spinner, empty, error) → use the shared component, don't re-implement inline.
+3. **No wrapper exists? → use the library component directly AND log a warning:**
+   ```
+   > ⚠️ No shared wrapper for <X> — using the library directly. Consider adding one to shared/components/.
+   ```
+4. **Unsure whether one exists? → ASK** the team before writing the code
+   (search the project's wrapper folder — `shared/components/`, `ui/`, `common/` — first).
+
+## Priority order (must follow)
+
+1. **Wrapper in `shared/components/`** (or the folder recorded in DESIGN_SYSTEM.md) — ALWAYS use it when one exists.
+2. **Library component direct** — only when no wrapper exists; import the library type + log the warning above.
+3. **Custom build from scratch** — only when the library has no equivalent.
+
+## Enforcement
+
+This rule is enforced by `/review-pr` and the `angular-reviewer` agent: a raw library import when a
+wrapper exists, in **new code**, is a 🔴 BLOCKER. Legacy modules (see Coexistence Strategy in
+`.claude/rules/project-rules.md`) are exempt — do not refactor them just to satisfy this rule.
+Works for any UI library — PrimeNG, Angular Material, ng-zorro, ng-bootstrap, or custom.

package/skills/explain/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: explain
+description: >
+  Explain Angular/TypeScript code, architecture, data flows, or technical decisions for THIS project.
+  Use when the user says "explain", "giải thích", "how does this work", "what is", "tại sao", "why",
+  "làm thế nào", "hoạt động ra sao", or wants to understand a file, component, service, module, pattern,
+  routing, state management, HTTP flow, or an architectural decision.
+argument-hint: "[code|concept|flow|why] [target]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+# Explain Code — Angular
+
+Explain code, architecture, and technical decisions for the Angular project you are in. This skill is
+**project-agnostic**: it never assumes a version, UI library, state-management approach, or folder
+layout — it reads those from the project's own docs and source before explaining.
+
+> **Scope:** a specific file / concept / flow / decision, explained **in-thread**. To map a WHOLE
+> unfamiliar repo (structure inventory, entry points, traced execution paths), use the
+> `angular-onboarding` agent instead — it runs in an isolated context built for repo-wide mapping.
+
+## Language
+Explain in the project's configured language — read `language` from the `## Commit Convention` block in
+`.claude/rules/project-rules.md`. **Default: Vietnamese** (technical terms kept in English), e.g.
+"Component này dùng `@Input()` để nhận data từ parent".
+
+## Load context first (never assume)
+**Always read the project's docs before explaining** — they are the source of truth for how THIS
+codebase works:
+- `CLAUDE.md` — stack summary + entry points + links.
+- `.claude/rules/project-rules.md` — folder structure, naming, conventions, Precedence.
+- `docs/ARCHITECTURE.md` — layers, routing, state approach, HTTP/interceptor flow, auth.
+- `docs/DESIGN_SYSTEM.md` — UI library + shared/wrapped components.
+- `.claude/angular-practices/<version>.md` — the version-matched idioms.
+
+Do NOT assume Angular version, UI library (Material/PrimeNG/ng-zorro/…), state management (NgRx/Signals/
+BehaviorSubject/…), base-service patterns, routing strategy, or interceptors. Take them from the docs +
+the actual code.
+
+## Workflow
+
+### 1. Determine mode
+If the user didn't say, infer intent:
+- Asks about a specific file → `code`
+- Asks about a pattern/concept (lazy loading, a state pattern, a base service…) → `concept`
+- Asks "how", "luồng", "flow" → `flow`
+- Asks "why", "tại sao", "lý do" → `why`
+
+If still unclear, ask: "Bạn muốn giải thích: code (file cụ thể), concept (khái niệm), flow (luồng xử lý),
+hay why (lý do thiết kế)?"
+
+### 2. Read order by mode
+| Mode | Read in this order |
+|------|--------------------|
+| `code` | CLAUDE.md → project-rules (Folder Structure) → the target file → related files (service/model) |
+| `concept` | CLAUDE.md + ARCHITECTURE.md → a **real example** of the concept from this codebase |
+| `flow` | CLAUDE.md → ARCHITECTURE.md (HTTP/interceptor flow) → component → service → interceptor/state |
+| `why` | ARCHITECTURE.md + project-rules → the relevant file → `docs/decisions/` (ADRs) if present |
+
+### 3. Find the source file
+If given only a name (no path), use `Glob` (e.g. `**/*{name}*`) to locate it. Use the Folder Structure
+in `project-rules.md` / `docs/ARCHITECTURE.md` to navigate — do not rely on a memorized tree.
+
+### 4. Use the templates
+Read `./templates/vi.md` and pick the skeleton for the mode. The templates are structure-only —
+fill every placeholder with facts read from THIS project's code (its UI library, its HTTP/service
+pattern, its interceptors, its state approach), not assumptions.
+
+## Rules
+- **Read real files, never guess** — verify the code still exists and matches before explaining.
+- **Docs are the source of truth** — patterns/conventions come from `project-rules.md` + `docs/`.
+- **Detail level** — beginners: from basics with everyday analogies; intermediate (default): patterns +
+  best practices; advanced: trade-offs + architectural decisions. Adjust to the question.
+- **Structure**: (1) short summary (1–2 sentences) → (2) detailed explanation with real code → (3) key
+  takeaways → (4) links to related parts of the system.
+
+## Error handling
+| Situation | Handling |
+|-----------|----------|
+| Mode unclear | Infer from the question; if still unclear, ask |
+| File not found | `Glob` with `**/*{name}*` |
+| File too large | Read in parts (offset/limit), focus on the relevant section |
+| Need more context | CLAUDE.md → ARCHITECTURE.md → service → model → component, in order |
+| Concept unclear | Find a real example in the codebase to illustrate |
+
+## Examples
+```
+User: "Giải thích user-list.component.ts"
+→ Mode: code → read CLAUDE.md + project-rules → the component (+ its service/model) → explain structure, data flow
+
+User: "State management pattern ở đây là gì?"
+→ Mode: concept → read ARCHITECTURE.md (state approach) → a real store/service example → explain the pattern used HERE
+
+User: "Luồng đăng nhập chạy thế nào?"
+→ Mode: flow → ARCHITECTURE.md (HTTP/interceptor) → login component → auth service → interceptor → render
+
+User: "Tại sao module này lazy-load?"
+→ Mode: why → ARCHITECTURE.md (routing) + the route config → explain reasons + trade-offs
+```

package/skills/explain/templates/vi.md

@@ -0,0 +1,184 @@
+# Templates Tiếng Việt — Giải thích code Angular (project-agnostic)
+
+> Đây là **khung cấu trúc**, không gắn với dự án cụ thể. Điền mọi `{{...}}` bằng thông tin đọc được
+> từ code thật của dự án (version, UI library, state approach, HTTP/service pattern, interceptors...).
+> KHÔNG giả định PrimeNG/Material, NgRx/Signals, hay BaseService — lấy từ `docs/ARCHITECTURE.md`,
+> `docs/DESIGN_SYSTEM.md`, `.claude/rules/project-rules.md` và code.
+
+## Giải thích Code
+
+```markdown
+## 📁 File: {filename}
+
+### Mục đích
+[1-2 câu: component/service này dùng để làm gì trong hệ thống]
+
+### Phân tích
+
+**Decorator / Metadata**
+- `@Component`: selector, templateUrl, styleUrls, `changeDetection` (nếu có)
+  - Standalone hay khai báo trong NgModule? → theo đúng cách dự án dùng ({{standalone|NgModule}})
+- `@Injectable`: `providedIn: 'root'` hay scoped
+
+**Module / Feature Context** *(nếu có)*
+- Thuộc feature/module: [tên — theo Folder Structure trong project-rules.md]
+- Lazy-loaded: [có/không, qua route nào]
+- Route path: [nếu có]
+
+**Inputs / Outputs** *(nếu có)*
+- `@Input()` / `input()`: [ý nghĩa, kiểu, ai truyền vào]
+- `@Output()` / `output()`: [event gì, emit khi nào, payload]
+
+**Dependencies (DI)**
+- [Liệt kê service/token được inject — theo đúng pattern DI dự án dùng: `inject()` hay constructor]
+- [Nếu dự án có base-service/abstraction dùng chung → nêu tên thật đọc từ code, không giả định]
+
+**Properties chính**
+- `propertyX: Type`: [vai trò, khởi tạo]
+
+**Lifecycle Hooks**
+- `ngOnInit()` / `ngOnDestroy()` / khác: [làm gì; teardown subscription thế nào]
+
+**Methods quan trọng**
+- [Tên method → nhiệm vụ, luồng xử lý]
+
+**Form Handling** *(nếu có)*
+- [Reactive/Template-driven — theo dự án; validators; luồng submit]
+
+**UI Components** *(nếu có)*
+- [Component của {{UI library dự án đang dùng}} hoặc wrapper trong shared/ — đọc từ DESIGN_SYSTEM.md]
+
+**State Management** *(nếu có)*
+- [Cách quản lý state THẬT của dự án: {{Signals | NgRx | BehaviorSubject | service}} — không giả định]
+
+### 💡 Điểm cần nhớ
+- [Key point về business logic / technical / edge cases]
+
+### 🔗 Liên kết
+- **Gọi service**: [service + methods]
+- **Được dùng bởi**: [parent component / route]
+- **Related files**: [model, service, routing]
+```
+
+---
+
+## Giải thích Concept
+
+```markdown
+## 🎯 {Tên Concept}
+
+### Là gì?
+[2-3 câu giải thích đơn giản]
+
+### Ví dụ đời thường
+[So sánh với thứ quen thuộc để dễ hiểu]
+
+### Trong dự án này
+**Vị trí**: `[đường dẫn file thật]`
+```typescript
+// Ví dụ code THẬT trích từ dự án (không bịa)
+```
+**Cách dùng**:
+```typescript
+// Ví dụ sử dụng trong component/service của dự án
+```
+
+### Tại sao dùng?
+- **Lý do 1..n**: [giải thích]
+
+### Không dùng thì sao?
+- ❌ [Vấn đề sẽ gặp]
+
+### So sánh với cách khác
+| Cách này | Cách khác | Khi nào dùng |
+|----------|-----------|--------------|
+| … | … | … |
+
+### 📚 Tìm hiểu thêm
+- Angular docs / docs của {{UI library / state library dự án dùng}} / related concepts
+```
+
+---
+
+## Giải thích Flow
+
+```markdown
+## 🔄 Flow: {Tên tính năng}
+
+### Tổng quan
+[1-2 câu: flow từ đâu đến đâu]
+
+### Sơ đồ
+```
+[User thao tác]
+    │
+    ▼
+[Component] ──── bắt event, validate (nếu có), gọi service
+    │
+    ▼
+[Service / lớp gọi API của dự án] ── chuẩn bị payload, gọi HTTP
+    │
+    ▼
+[HTTP Interceptor chain của dự án] ── {{liệt kê interceptor THẬT: auth, error, loading...}}
+    │
+    ▼
+[Backend API]
+    │
+    ▼
+[Response] ──► [Service] ──► [Component] ── handle success/error
+    │
+    ▼
+[Template re-render]
+```
+
+### Chi tiết từng bước
+**Bước 1: User thao tác** — [event handler]
+**Bước 2: Component xử lý** — [validate, gọi service]
+```typescript
+// code thật/minh họa theo dự án
+```
+**Bước 3: Service gọi API** — [method, endpoint]
+**Bước 4: Interceptors** — [đọc từ ARCHITECTURE.md: những interceptor dự án thực sự có]
+**Bước 5: Nhận response** — [success/error handling]
+**Bước 6: UI update** — [change detection / component cập nhật]
+
+### 🔍 Mẹo debug
+- Network tab: URL/headers/payload/status đúng không?
+- Console: lỗi từ interceptor? token? validation?
+- Environment/config: đọc từ nơi dự án lưu config (theo ARCHITECTURE.md)
+
+### Common issues
+- ❌ [liệt kê theo pattern thật của dự án]
+```
+
+---
+
+## Giải thích Why
+
+```markdown
+## ❓ Tại sao: {Câu hỏi}
+
+### Trả lời ngắn
+[1-2 câu trả lời trực tiếp]
+
+### Giải thích chi tiết
+- **Lý do 1..n**: [giải thích + ví dụ code nếu cần]
+
+### Nếu không làm vậy?
+- ❌ [Vấn đề + impact + mức độ]
+
+### Đánh đổi (Trade-offs)
+| Ưu điểm ✅ | Nhược điểm ❌ |
+|-----------|--------------|
+| … | … |
+
+### Có cách khác không?
+- **Cách 1..n**: [mô tả, khi nào dùng]
+
+### Context trong dự án này
+- [Đọc `docs/decisions/` (ADR) nếu có; nếu không, nêu rõ là suy luận từ code]
+
+### 📌 Kết luận
+**TL;DR**: [2-3 câu]
+**Key takeaways**: 💡 [điểm quan trọng]
+```

package/skills/git-commit/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: git-commit
+description: >
+  Write conventional commit messages for this project.
+  Use when the user says "commit", "git commit", "save changes",
+  "tạo commit", "viết commit message", or finished a task and wants to commit.
+argument-hint: "[type] [message]"
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Commit Message Generator
+
+Generates conventional commit messages that follow **this project's** convention. It is
+project-agnostic: the prefix, language, and scope source are read at runtime from the project's
+config — nothing is hardcoded.
+
+## Read the project's convention first
+Read the `## Commit Convention` block in `.claude/rules/project-rules.md` (filled by `/init`). It
+defines:
+- **Prefix** — an optional string prepended before `<type>` (e.g. `VIVAS_`). **Default: none.**
+- **Language** — the language for subject/body. **Default: `vi` (Vietnamese).**
+- **Scope source** — the folder level scope is derived from (see below).
+
+If that block is missing, fall back to: no prefix, language `vi`, scope derived dynamically.
+Full rules and type/subject conventions: `.claude/skills/git-commit/references/conventions.md`.
+(The `angular-git-workflow` agent reads the same block — keep them consistent.)
+
+## Format
+```
+<prefix><type>(<scope>): <subject>
+```
+- `<prefix>` from project-rules (default empty → standard conventional commit).
+- `<type>`: feat, fix, refactor, docs, style, test, chore, perf, ci, build, revert.
+- `<scope>`: derived from changed paths (see Scope Detection); omit if changes span multiple modules.
+- `<subject>`: in the configured language, imperative, ≤50 chars, no trailing period.
+
+## Usage
+```
+/commit                     → Auto-detect type + scope from staged changes
+/commit feat add login      → Quick commit with type + message
+/commit --amend             → Amend last commit message
+```
+
+## Workflow
+1. **Stage** (if nothing staged): `git add .`
+2. **Inspect**: `git diff --staged --stat` then `git diff --staged`.
+3. **Read convention**: the `## Commit Convention` block (prefix/language/scope source) +
+   `references/conventions.md`.
+4. **Detect type** from changed files/content (see conventions.md table).
+5. **Derive scope** (see below).
+6. **Generate message** → show a preview:
+   ```
+   📝 COMMIT PREVIEW
+
+   <prefix><type>(<scope>): <subject in configured language>
+
+   - <body bullet 1>
+   - <body bullet 2>
+
+   Staged files (N):
+     M <path>
+     A <path>
+
+   Commit? (yes/no/edit)
+   ```
+7. **Execute after confirm**: `yes` → `git commit -m "..."`; `edit` → user tweaks then commit;
+   `no` → abort (keep staged).
+
+## Scope Detection (dynamic — no hardcoded table)
+Derive `<scope>` from the staged file paths + the project's **Folder Structure** in
+`.claude/rules/project-rules.md` / `docs/ARCHITECTURE.md`:
+- Scope = the top-level feature/module folder the changed files live in (e.g. under
+  `src/app/features/<scope>/…` or `src/app/modules/<scope>/…` — use the project's actual layout).
+- Shared/cross-cutting folders map to their own scope (e.g. `shared`, `core`, `layout`).
+- Changes spanning multiple modules → **omit the scope**.
+
+## Quick Commit
+Skip the preview for trivial changes:
+```
+/commit fix typo in readme
+    ↓
+git commit -m "<prefix>fix: typo in readme"
+```
+
+## Rules
+- **Follow the project's convention** — prefix, language, and scope come from project-rules; never
+  hardcode a company prefix or module list here.
+- **Language** — subject/body in the configured language (default Vietnamese; imperative: "thêm",
+  "sửa", "cập nhật", "xóa").
+- **Lowercase** type and scope. **No trailing period.** **50/72 rule** (subject ≤50, body wrap 72).
+- **No Co-Authored-By** trailer.
+
+## Amend Last Commit
+```bash
+git commit --amend -m "<prefix><type>(<scope>): new message"
+```
+
+## Error Handling
+| Issue | Action |
+|-------|--------|
+| No staged changes | Stage with `git add .` or ask the user what to stage |
+| No changes at all | Report "nothing to commit" |
+| User declines | Abort, keep staged |
+| Convention block missing | Fall back to: no prefix, language vi, dynamic scope |
+| Git error | Show error, suggest fix |

package/skills/git-commit/references/conventions.md

@@ -0,0 +1,100 @@
+# Commit Conventions
+
+> **This project's prefix, language, and scope source come from the `## Commit Convention` block in
+> `.claude/rules/project-rules.md`** (filled by `/init`). This file defines the generic rules; the
+> project block supplies the project-specific values. Defaults if the block is missing: no prefix,
+> language `vi`, scope derived dynamically from changed paths.
+
+## Format
+
+```
+<prefix><type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+- `<prefix>` — optional, from project-rules (e.g. `VIVAS_`). Default: empty.
+- `<subject>`/`<body>`/`<footer>` — in the configured `language` (default Vietnamese).
+
+## Types
+
+| Type | When to use | Example change |
+|------|-------------|----------------|
+| `feat` | New feature | New component, endpoint, capability |
+| `fix` | Bug fix | Crash, wrong logic, edge case |
+| `refactor` | Restructure (no behavior change) | Rename, extract, reorganize |
+| `docs` | Documentation | README, comments, CLAUDE.md |
+| `style` | Formatting (no code change) | Lint fixes, whitespace |
+| `test` | Add/update tests | `*.spec.ts` |
+| `chore` | Maintenance | Dependencies, configs, scripts, environments |
+| `perf` | Performance | Optimize query, reduce bundle size |
+| `ci` | CI/CD | GitHub Actions, Docker |
+| `build` | Build system | `angular.json`, `tsconfig`, webpack |
+| `revert` | Revert a commit | Undo a previous commit |
+
+## Auto-detect Type
+
+| Changed files / content | Detected type |
+|-------------------------|---------------|
+| `*.spec.ts` only | `test` |
+| `*.md` only | `docs` |
+| `package.json`, `tsconfig*.json`, `.eslintrc*` only | `chore` |
+| `src/environments/*.ts` only | `chore` |
+| `angular.json`, `webpack*.js` | `build` |
+| New files + new exports | `feat` |
+| Fixed logic / error handling in existing files | `fix` |
+| Renamed / moved files, no logic change | `refactor` |
+
+## Scope Detection (dynamic — derive, don't hardcode)
+
+Derive `<scope>` from the staged file paths + the project's **Folder Structure** in
+`.claude/rules/project-rules.md` / `docs/ARCHITECTURE.md`:
+
+- Scope = the top-level feature/module folder the changed files live in — e.g. under
+  `src/app/features/<scope>/…` or `src/app/modules/<scope>/…` (use the project's actual layout).
+- Shared / cross-cutting folders map to their own scope name (e.g. `shared`, `core`, `layout`).
+- Changes spanning multiple modules → **omit the scope**.
+
+## Subject Rules
+- Prepend the configured prefix (if any) before `<type>`.
+- Configured language, concise and clear.
+- No trailing period.
+- ≤ 50 characters.
+- Imperative mood (VI: "thêm", "sửa", "cập nhật", "xóa" / EN: "add", "fix", "update", "remove").
+
+## Body Rules
+- Separate from subject with a blank line.
+- Explain WHAT and WHY, not HOW.
+- Bullet points for multiple changes.
+- Wrap at 72 characters.
+
+## Examples
+
+> These show the *shape*. The prefix depends on the project's config — shown both ways.
+
+### No prefix (default conventional commit)
+```
+fix(users): sửa lỗi null khi load danh sách người dùng
+```
+
+### With a configured prefix (e.g. project sets Prefix: VIVAS_)
+```
+VIVAS_feat(reports): thêm chức năng xuất báo cáo PDF
+
+- Thêm report-export component
+- Hỗ trợ filter theo thời gian và khu vực
+```
+
+### Multiple modules → omit scope
+```
+fix: sửa giao diện và validate ở nhiều module
+```
+
+### Breaking change
+```
+feat(api)!: thay đổi cấu trúc response
+
+BREAKING CHANGE: Response được bọc trong { success, data, error }.
+```

package/templates/docs/DESIGN_SYSTEM.md

@@ -21,7 +21,28 @@
 | ErrorMessage | Error display |
 | ConfirmDialog | Confirmation modal |
 
+## Wrapped Components
+> If this section is present and non-empty, ALWAYS prefer the wrapper over the
+> raw library component. Add a row only when a shared wrapper exists.
+> `/init` auto-detects these; the team confirms in Stage 1.
+
+| Need (library component) | Use this wrapper | Custom additions | Location |
+|---------------------------|------------------|------------------|----------|
+| `{{p-dropdown}}` | `{{<app-select>}}` | {{Loading state, error display, label slot}} | `{{shared/components/select/}}` |
+| `{{p-calendar}}` | `{{<app-date-picker>}}` | {{Min/max date, locale, disabled dates}} | `{{shared/components/date-picker/}}` |
+
+### Priority Order (must follow)
+1. **Wrapper in `shared/components/`** (or `ui/`, `common/`, `components/` — record actual folder) — ALWAYS use it when one exists
+2. **Library component direct** — use only when no wrapper exists; import the library type
+3. **Custom build from scratch** — only when the library has no equivalent
+
+### When you cannot find a wrapper
+- Search the project's wrapper folder first (recorded above)
+- If still unsure, ASK the team: "Có wrapper nào tôi chưa biết không?"
+- NEVER silently import the library and bypass the wrapper
+
 ## Rules
 - Every page must handle loading / error / empty states
 - Use design tokens, not hardcoded values
 - New shared UI goes in `shared/` only if used by 2+ features
+- If a wrapped component exists for a UI need, you MUST use the wrapper — never the raw library component directly