@tungvivas/angular-vibe-kit 0.2.0 → 0.3.0

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/srs/README.md

@@ -0,0 +1,29 @@
+# SRS (source requirements)
+
+Drop your **already-split** SRS excerpts here — one file per module/feature, not the whole
+multi-module document. If your SRS is a Word doc converted via `pandoc` into one large Markdown
+file with an images folder, extract just the section you're about to build and save it here,
+keeping any image references relative and valid.
+
+## Convention
+
+```
+docs/srs/
+├── module-5-order-management.md
+├── module-6-invoicing.md
+└── images/                        # keep paths relative to match what pandoc generated
+```
+
+## Usage
+
+This folder is **not** auto-read — `/plan` doesn't scan it on its own. Point to the file
+explicitly when you start planning:
+
+```
+/plan
+
+Đọc yêu cầu từ docs/srs/module-5-order-management.md
+```
+
+Keep these files committed — they're the record of what was actually asked for each module,
+useful when a later module needs to know how an earlier one was scoped.

package/templates/rules/project-rules.md

@@ -63,6 +63,14 @@ When guidance conflicts, follow this order top to bottom:
 - Do NOT hardcode the backend URL
 - Do NOT import UI library components directly in features when a wrapper exists in `shared/components/`
 
+## Commit Convention
+> Read by the `git-commit` skill and the `angular-git-workflow` agent. /init fills this from `git log`.
+- **Prefix**: {{none}}  <!-- prepended before <type>, e.g. "VIVAS_"; default: none -->
+- **Language**: {{vi}}  <!-- subject/body language for commits AND /explain output; default: vi -->
+- **Format**: `<prefix><type>(<scope>): <subject>`
+- **Scope source**: top-level folder under {{src/app/features | src/app/modules | ...}} of the changed files; multiple modules → omit scope
+- **Types**: feat, fix, refactor, docs, style, test, chore, perf, ci, build, revert
+
 ## Reference Examples
 > /init fills this with the best existing files to copy patterns from.
 > `/new-feature` opens these and mirrors their style.