@tungvivas/angular-vibe-kit 0.1.0 → 0.2.0

package/README.md

@@ -18,7 +18,8 @@ and keeps the AI honest with version-correct Angular rules (v14 → v19).
 
 It also handles the real-world case: **the project isn't fully best-practice yet.**
 The kit adds correct rules for *new* code without forcing risky refactors on legacy
-modules (Strangler Fig).
+modules (Strangler Fig). And when the project wraps its UI library in `shared/components/`,
+the kit teaches the AI to always use the wrapper, not the raw library import.
 
 ---
 
@@ -104,6 +105,25 @@ Anything uncertain becomes a question — the kit never silently rewrites your r
 
 ---
 
+## Component Wrapping (generic UI convention)
+
+The kit enforces a generic priority rule for UI components:
+
+1. **Wrapper in `shared/components/`** (or `ui/`, `common/`, etc.) — used if it exists for the need
+2. **UI library direct** — used only if no wrapper exists; warning logged
+3. **Custom build** — only when the library has no equivalent
+
+When you run `/init`, it scans your codebase for wrapper components (sub-folders
+of `shared/components/` that import a known UI library) and writes a
+**Wrapped Components** table into `docs/DESIGN_SYSTEM.md`. From then on:
+- `/new-feature` consults that table when generating UI code
+- `/review-pr` flags a wrapper-bypass as 🔴 BLOCKER in new code
+- `/write-context` captures the WHY behind any library-direct decisions
+
+Works for any UI library — PrimeNG, Material, ng-zorro, ng-bootstrap, custom.
+
+---
+
 ## What gets created in your project
 
 ```

package/commands/init.md

@@ -25,7 +25,8 @@ The version-matched best-practice file is in `.claude/angular-practices/`
 
 ## Stage 0: Scan (read-only, no output yet)
 1. Read the BP file in `.claude/angular-practices/` (one file — the version's idioms).
-2. Read `package.json` → Angular version, UI library, test runner, state libs.
+2. Read `package.json` → Angular version, **UI library (auto-detect from dependencies)**, test runner, state libs.
+   - **UI library detection**: scan `dependencies` and `devDependencies` for known third-party UI packages. Examples include but are NOT limited to: `primeng`, `@angular/material`, `@angular/cdk`, `ng-zorro-antd`, `@ng-bootstrap/*`, `ngx-bootstrap`, `@clr/angular`, `@progress/kendo-angular-*`, `@ionic/angular`, `@nebular/*`, `element-angular`, `@spike-rabbit/element-angular`, `flowbite-angular`, or any package whose name suggests a UI/design system. **Record all matches** — the project may use more than one. **Do NOT hardcode a fixed list** — infer from what is actually installed.
 3. Scan `src/`:
    - Module system: standalone vs NgModule
    - State: NgRx / Signals / BehaviorSubject / plain service
@@ -33,6 +34,17 @@ The version-matched best-practice file is in `.claude/angular-practices/`
    - HTTP pattern: HttpClient in services vs components
    - Interceptors, guards, auth flow, token handling
    - Test setup, shared components, UI library usage
+   - **Wrapped components detection** (library-agnostic — works for any UI library the project actually uses):
+     - Use the UI library list detected from `package.json` in Step 2 (NOT a hardcoded list)
+     - Enumerate the project's shared component folder (e.g. `shared/components/`, `ui/`, `common/`, `components/` — record the actual folder name)
+     - For each sub-folder, look for:
+       - A `*.component.ts` file with a `@Component` decorator
+       - A TypeScript `import` statement that matches one of the detected UI library packages
+         (e.g. if `primeng` is in deps → look for `from 'primeng/...'`; if `@clr/angular` is in deps → look for `from '@clr/angular'`)
+       - A simple `value`/`valueChange` input-output pair suggesting it wraps a single primitive
+     - Exclude framework imports from the match list: `@angular/core`, `@angular/common`, `@angular/router`, `@angular/forms`, `@angular/animations`, `@angular/platform-browser*`, `rxjs`, `@ngrx/*`, `zone.js`, `tslib` (these are NOT UI library imports)
+   - Record each candidate as `wrapper {name} → library {detected_package}/{imported_module}` for Stage 2 table generation
+   - Pick one as "Wrapper Reference Example" (simplest API + most reused) and record the path for `project-rules.md` Reference Examples table
 4. **Find the best-example files** — the most complete, idiomatic feature to use as a
    reference template. Pick the best example for each of: a service, a smart/page
    component, a dumb component, a test spec. Verify each path exists.
@@ -43,6 +55,9 @@ The version-matched best-practice file is in `.claude/angular-practices/`
 1. Gather every `uncertain` item across ALL seven files into a single list
    (e.g. "both NgRx and Signals present — which is primary?", "response envelope shape?",
    "auth model?", "which forms approach?", "confirm this legacy do-not-touch list").
+   - **Wrapper auto-detection**: if wrappers were detected in Stage 0, confirm for each:
+     (a) which library component it wraps, (b) custom additions, (c) is it required (BLOCKER) or preferred (SUGGESTION).
+     Default if team does not answer: treat as SUGGESTION.
 2. Ask them as ONE grouped batch of multiple-choice questions.
 3. **WAIT** for the answers. Do not write any file until the batch is answered.
 4. If nothing is uncertain, say so and proceed directly to Stage 2.
@@ -56,7 +71,7 @@ placeholder with real content. Do NOT stop between files.
 3. **docs/ARCHITECTURE.md** — actual layer structure, routing/lazy-loading, state approach, HTTP/interceptor flow, auth strategy. Full detail here (not in CLAUDE.md).
 4. **.claude/rules/project-rules.md** — tech stack, naming, coding rules (actionable, not prose). Include the `## Precedence` section, the `## Reference Examples` section (best-example files from Stage 0 — paths that exist only), and the `## Coexistence Strategy` section (see below).
 5. **docs/PROJECT-STATUS.md** — snapshot: what exists, in progress, known issues, next tasks. Session counter = 1.
-6. **docs/DESIGN_SYSTEM.md** — UI library, design tokens (infer from styles/theme), shared/reusable components in whatever the project calls that folder (record the actual name).
+6. **docs/DESIGN_SYSTEM.md** — UI library, design tokens (infer from styles/theme), shared/reusable components in whatever the project calls that folder (record the actual name), AND the **Wrapped Components** table (filled from Stage 0 detection, confirmed in Stage 1). If no wrappers found, OMIT the Wrapped Components section and add: `> This project uses UI library components directly — no shared wrappers.`
 7. **docs/decisions/** — one ADR per real decision confirmed (e.g. `001-state-management.md`, `002-auth-token-storage.md`). Only for actual decisions.
 
 ### Coexistence Strategy (inside project-rules.md)
@@ -85,7 +100,7 @@ Print a summary so I can review everything at once:
 | docs/ARCHITECTURE.md | created/updated | ... |
 | .claude/rules/project-rules.md | created/updated | precedence + coexistence + reference examples |
 | docs/PROJECT-STATUS.md | created/updated | ... |
-| docs/DESIGN_SYSTEM.md | created/updated | ... |
+| docs/DESIGN_SYSTEM.md | created/updated | ... | + Wrapped Components table (N rows, or omitted if none) |
 | docs/decisions/00x-*.md | created | ... |
 
 **3. Questions I asked & your answers** — short list (for the record).

package/commands/new-feature.md

@@ -10,7 +10,7 @@ has no convention or is below standard (new code only); legacy modules are never
 - Read `.claude/rules/project-rules.md` → naming, structure, Coexistence rules, **Reference Examples**
 - Read `docs/ARCHITECTURE.md` → where this feature fits
 - Read `docs/API_CONTRACT.md` → which endpoints this feature calls
-- Read `docs/DESIGN_SYSTEM.md` → shared components to use
+- Read `docs/DESIGN_SYSTEM.md` → shared components to use, **AND the Wrapped Components table → which wrapper to use for each UI library primitive** (e.g. for a dropdown, use `<app-select>` not `p-dropdown`)
 - **Open the Reference Example files** listed in `project-rules.md` (best existing service / page / component / spec) and mirror their style — this is the strongest signal for matching the project's real conventions
 - Ask me if anything is unclear before writing code
 
@@ -56,6 +56,7 @@ has no convention or is below standard (new code only); legacy modules are never
 - No `any` — interfaces/types for every model and response
 - Use the project's forms approach from `project-rules.md` (Reactive Forms by default; Formly / template-driven if that's what the project uses)
 - No hardcoded backend URL — use `environment`
+- **Wrapper priority**: import from `@shared/components/<name>` (or the project's wrapper folder) if a wrapper exists; never import the library component directly. See `docs/DESIGN_SYSTEM.md` → Wrapped Components.
 
 ## Step 6: Update Documentation
 - `docs/API_CONTRACT.md` if you used/discovered endpoints

package/commands/review-pr.md

@@ -51,6 +51,14 @@ because it differs from the profile.
 - [ ] No dead code, no `console.log`
 - [ ] Naming follows `.claude/rules/project-rules.md`
 
+## Component Wrapping (follow `docs/DESIGN_SYSTEM.md` → Wrapped Components)
+- [ ] No feature imports a raw UI library component (`p-dropdown`, `mat-form-field`, `nz-input`, etc.) when a wrapper exists in `shared/components/`
+- [ ] All UI primitive imports go through the project's wrapper (check the import path matches the wrapper's location)
+- [ ] If a wrapper exists for the need but the PR uses the library directly → 🔴 BLOCKER
+- [ ] If no wrapper exists and the library is used directly → 🟡 SUGGESTION: "Consider creating a wrapper in `shared/components/` for consistency"
+- [ ] New components do NOT silently re-implement logic an existing wrapper already provides
+- [ ] If a brand-new wrapper is introduced → verify it follows the Wrapper Reference Example from `project-rules.md`
+
 ## Documentation
 - [ ] New feature: `CONTEXT.md` created inside feature folder
 - [ ] Logic changed: `CONTEXT.md` Refactor Log updated (append only)

package/commands/write-context.md

@@ -45,6 +45,12 @@ Note what is local component state vs shared state.
 - **{Decision}**: {reason}
 - **{Decision}**: {reason}
 
+## Component Wrapping Decisions
+- **Wrapped components used**: list the `<app-*>` components used by this feature (e.g. `<app-select>`, `<app-data-table>`)
+- **Library components used directly**: list any direct library imports and the reason (e.g. `p-tree` used directly because no wrapper exists yet, and creating one is out of scope for this feature)
+- **New wrappers introduced**: if this feature adds a new wrapper to `shared/components/`, list it here and link to the PR/ADR
+- **Wrappers NOT used (with reason)**: if a wrapper exists for the need but you chose not to use it, document why (e.g. "wrapper doesn't support X yet — track in #123")
+
 ## Considered and Rejected
 - **{Option}**: rejected because {reason}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tungvivas/angular-vibe-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Bootstrap a Vibe Coding workflow (CLAUDE.md, project docs, slash-commands) into any Angular project. Detects your Angular version and installs version-matched best-practice rules.",
   "keywords": [
     "angular",

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

package/templates/rules/project-rules.md

@@ -49,11 +49,19 @@ When guidance conflicts, follow this order top to bottom:
 ## Coding Rules
 > /init will generate concrete rules based on Angular version + what the project does.
 
+## Component Wrapper Priority
+- ALWAYS check `docs/DESIGN_SYSTEM.md` → **Wrapped Components** before importing a UI library
+- If a wrapper exists for the need → import the wrapper (e.g. `import { AppSelectComponent } from '@shared/components/select'`), NEVER the raw library (`p-dropdown`)
+- If no wrapper exists → use the library directly and log a warning to the user: `> ⚠️ No wrapper for <X> — using library directly. Consider creating one in shared/components/`
+- If unsure whether a wrapper exists → ASK the team before writing the import
+- This rule is enforced by `/review-pr` (🔴 BLOCKER if violated in new code)
+
 ## DO NOT
 - Do NOT use `any`
 - Do NOT call HttpClient from components
 - Do NOT store tokens in localStorage
 - Do NOT hardcode the backend URL
+- Do NOT import UI library components directly in features when a wrapper exists in `shared/components/`
 
 ## Reference Examples
 > /init fills this with the best existing files to copy patterns from.