@tungvivas/angular-vibe-kit 0.1.0 → 0.3.0

package/commands/review-pr.md

@@ -1,63 +1,12 @@
-Review the code changes in this PR. Check every item — flag violations clearly.
-
-Read `.claude/angular-practices/` for version-correct idioms, and
-`.claude/rules/project-rules.md` for project-specific rules.
-
-**Precedence (see `project-rules.md` → Precedence):** a valid project convention wins over
-the BP profile; flag a BP deviation as a blocker only when it's an objective defect in NEW
-code. Do NOT flag legacy modules listed in the Coexistence Strategy — they are kept as-is.
-Do NOT flag a valid project choice (naming, structure, state lib, response shape) just
-because it differs from the profile.
-
-## Architecture
-- [ ] Smart / dumb separation: pages own data; presentational components only render + emit
-- [ ] HTTP calls ONLY in services — never in components
-- [ ] No business logic in templates
-- [ ] Feature routes are lazy-loaded
-
-## Type Safety
-- [ ] No `any` — interfaces/types for every model and API response
-- [ ] Responses typed with the project's response shape recorded in `project-rules.md` (e.g. an `ApiResponse<T>` envelope, a raw DTO, or a GraphQL type — whatever the backend actually returns)
-- [ ] No `@ts-ignore` / `@ts-expect-error`
-
-## Dependency Injection (follow `.claude/angular-practices/`)
-- [ ] DI matches the profile: `inject()` (v16+) or constructor injection (v12–15) — consistent across the project
-- [ ] Services `@Injectable({ providedIn: 'root' })`
-
-## Reactive / RxJS / Signals (follow `.claude/angular-practices/`)
-- [ ] Subscriptions torn down: `takeUntilDestroyed` (v16+) or `takeUntil(destroy$)` + `ngOnDestroy` (v12–15)
-- [ ] `async` pipe preferred over manual subscribe
-- [ ] No `toPromise()` — use `firstValueFrom()` if needed
-- [ ] Services return `Observable<T>` — do NOT subscribe internally
-- [ ] Signals used per profile: stable for state (v16+); derived state via `computed()`. `resource`/`httpResource` are experimental (v19+) — only if the team opted in
-
-## Error Handling
-- [ ] Loading / error / empty states handled in list/detail pages
-- [ ] HTTP errors surfaced to user (not swallowed)
-- [ ] Auth errors (e.g. 401) handled centrally by an interceptor — not per-feature
-
-## Security
-- [ ] Auth handled per the project's model in `project-rules.md` (token in memory / httpOnly cookie / session / OAuth) — and consistent with it. If tokens are used, they are NOT in localStorage
-- [ ] No hardcoded backend URL — uses `environment`
-- [ ] Routes needing auth are guarded
-- [ ] No unsanitized HTML (`innerHTML` / `bypassSecurityTrust*`) without a clear, reviewed reason
-
-## Performance
-- [ ] `ChangeDetectionStrategy.OnPush` on every component (or zoneless on v20+ if enabled)
-- [ ] List tracking present: `@for` with `track` (v17+) or `*ngFor` with `trackBy` (v12–16)
-
-## Code Quality
-- [ ] Component file < ~300 lines; method < ~50 lines
-- [ ] No dead code, no `console.log`
-- [ ] Naming follows `.claude/rules/project-rules.md`
-
-## Documentation
-- [ ] New feature: `CONTEXT.md` created inside feature folder
-- [ ] Logic changed: `CONTEXT.md` Refactor Log updated (append only)
-- [ ] Endpoint changed: `docs/API_CONTRACT.md` updated
-- [ ] `docs/PROJECT-STATUS.md` updated
-
-## Summary
-1. **Blockers** 🔴 — must fix before merge
-2. **Suggestions** 🟡 — improve but not blocking
-3. **Good parts** 🟢 — what was done well
+Review the current code changes against this project's Angular standards.
+
+1. Get the diff: run `git diff` (unstaged) and `git diff --staged`, or `git diff <base>...HEAD` if a
+   base branch is named. Review only the changed code.
+2. Apply the full checklist in `.claude/references/review-checklist.md` — it defines the review
+   dimensions, the Precedence rule (a valid project convention wins; don't flag legacy), and the
+   🔴/🟡/🟢 output format. That file is the single source of truth for what "correct" means here.
+3. Output the report **inline** in this conversation using the format from the checklist. If there are
+   no blockers, say so explicitly.
+
+> For a large diff, or to review in the background while you keep coding, dispatch the
+> `angular-reviewer` agent instead — it applies the same checklist in an isolated context.

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/commands/write-tests.md

@@ -1,110 +1,12 @@
-Write tests for the specified feature module. Read the source code first, then generate tests.
+Write tests for the specified feature module.
 
-Use the test runner the project already uses (Jest or Karma/Jasmine — check
-`package.json` / `angular.json`). Read `.claude/angular-practices/` for the
-version's testing idioms.
+Follow `.claude/references/test-spec.md` — it is the single source of truth for how this project writes
+tests: read-first, service unit tests (TestBed + `HttpTestingController`), component tests, E2E for
+critical flows only, and the verify step (coverage ≥ 80%, no real backend). It detects the project's
+runner (Jest or Karma/Jasmine) and version idioms from `.claude/angular-practices/`.
 
-## Step 1: Read Before Writing
-- Read the feature's source: model, service, page components, presentational components
-- Read the module's `CONTEXT.md` (if it exists) to understand trade-offs and edge cases
-- Read `docs/API_CONTRACT.md` for expected request/response shapes
-- Identify all code paths: happy path, error cases, empty states, validation
+Write the tests **inline** in this conversation, then run them and report the result (files created,
+what each covers, pass/fail + coverage).
 
-## Step 2: Unit Tests — `{feature}.service.spec.ts`
-
-Use `HttpClientTestingModule` + `HttpTestingController` (works on every version, v12+).
-On v15+ you may instead use the functional `provideHttpClient()` + `provideHttpClientTesting()`.
-Follow whichever style the project already uses (see `.claude/angular-practices/`).
-
-```typescript
-describe('{Feature}Service', () => {
-  let service: {Feature}Service;
-  let httpMock: HttpTestingController;
-
-  beforeEach(() => {
-    TestBed.configureTestingModule({
-      imports: [HttpClientTestingModule],
-      providers: [{Feature}Service],
-    });
-    service = TestBed.inject({Feature}Service);
-    httpMock = TestBed.inject(HttpTestingController);
-  });
-
-  afterEach(() => httpMock.verify());
-});
-```
-
-### Required Coverage Per Method
-**getAll:**
-- ✅ Success — returns list; assert request URL + method `GET`
-- ✅ Empty — returns empty array, not null
-- ✅ Server error — propagates error (500)
-
-**getById:**
-- ✅ Found — returns correct response; assert URL contains the id
-- ✅ Not found — 404 error propagated
-
-**create:**
-- ✅ Success — assert `POST` + request body matches payload
-- ✅ Validation error — 400
-- ✅ Conflict — 409
-
-**update:**
-- ✅ Success — assert `PUT`/`PATCH` + body
-- ✅ Not found — 404
-
-**delete:**
-- ✅ Success — assert `DELETE` + URL
-- ✅ Not found — 404
-
-### Unit Test Rules
-- Use `httpMock.expectOne(url)` to assert and flush each request
-- Test ONE behavior per test
-- Naming: `methodName_scenario_expectedResult`
-- Describe behavior in the test title, not the implementation
-- `httpMock.verify()` in `afterEach` — no unexpected requests
-- Never hit a real backend
-
-## Step 3: Component Tests — `{feature}-list.component.spec.ts`
-
-Mock the service with `jasmine.createSpyObj` (Karma) or `jest.fn()` (Jest).
-
-```typescript
-describe('{Feature}ListComponent', () => {
-  let fixture: ComponentFixture<{Feature}ListComponent>;
-  let serviceSpy: jasmine.SpyObj<{Feature}Service>;
-
-  beforeEach(() => {
-    serviceSpy = jasmine.createSpyObj('{Feature}Service', ['getAll', 'delete']);
-    TestBed.configureTestingModule({
-      imports: [{Feature}ListComponent],
-      providers: [{ provide: {Feature}Service, useValue: serviceSpy }],
-    });
-  });
-});
-```
-
-### Required Coverage
-- ✅ Render — list shows correct data after load
-- ✅ Loading — spinner visible while the request is pending
-- ✅ Error — error message visible when the service errors
-- ✅ Empty — empty-state message when no data
-- ✅ Interaction — clicking delete calls `service.delete` with the right id
-- ✅ Signals (v16+) — assert signal values update as expected
-
-### Component Test Rules
-- Mock the service — never the real HttpClient
-- Drive change detection with `fixture.detectChanges()`
-- Query the DOM via `fixture.nativeElement` / `DebugElement`
-- Each test is independent — no shared mutable state
-
-## Step 4: E2E (only for critical flows)
-For login and the main CRUD flow, add a Playwright spec under the project's e2e folder.
-Skip E2E for trivial pages — manual testing covers those.
-
-## Step 5: Verify
-- All tests pass: `ng test` / `jest`
-- No test depends on execution order
-- No unit test hits a real backend
-- Test names clearly describe WHAT is tested and the EXPECTED result
-- Coverage: every public service method has at least happy path + error case
+> For a large feature, or to write tests in the background while you keep coding, dispatch the
+> `angular-test-writer` agent instead — it follows the same spec in an isolated context.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tungvivas/angular-vibe-kit",
-  "version": "0.1.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.",
+  "version": "0.3.0",
+  "description": "Bootstrap a Vibe Coding workflow (CLAUDE.md, project docs, slash-commands, skills, agents) into any Angular project. Detects your Angular version and installs version-matched best-practice rules.",
   "keywords": [
     "angular",
     "claude",
@@ -9,7 +9,10 @@
     "ai",
     "scaffold",
     "vibe-coding",
-    "slash-commands"
+    "slash-commands",
+    "skills",
+    "agents",
+    "subagents"
   ],
   "license": "MIT",
   "type": "module",
@@ -17,9 +20,12 @@
     "angular-vibe-kit": "bin/cli.js"
   },
   "files": [
+    "agents/",
     "bin/",
     "commands/",
     "practices/",
+    "references/",
+    "skills/",
     "templates/",
     "README.md",
     "LICENSE"

package/references/feature-structure.md

@@ -0,0 +1,44 @@
+# Feature Structure & Coding Rules (shared source of truth)
+
+> Read by BOTH `/new-feature` (linear command) and `/dev-cycle` (gated orchestrator) when scaffolding
+> and implementing a new feature module. Keep the folder shape, build order, and coding rules HERE
+> only — the two commands differ in pacing (linear vs gated), not in what "correct" looks like.
+
+## Folder structure
+> **Use the project's actual layout and folder names from `.claude/rules/project-rules.md`.**
+> The tree below is only the DEFAULT shape — if the project calls things differently
+> (e.g. `containers/` instead of `pages/`, `ui/` or `common/` instead of `shared/`,
+> an Nx `libs/` layout, or NgModule-based folders), follow the project, not this tree.
+
+```
+{features-dir}/{feature-name}/        # e.g. features/, modules/, or an Nx lib
+├── {feature}.routes.ts
+├── models/
+│   └── {feature}.model.ts           # Interfaces mirroring the backend response shape
+├── services/
+│   └── {feature}.service.ts         # All data-access calls
+├── pages/                           # Smart (container) components — project may call these containers/
+│   ├── {feature}-list/
+│   │   ├── {feature}-list.component.ts
+│   │   ├── {feature}-list.component.html
+│   │   └── {feature}-list.component.scss
+│   └── {feature}-detail/
+└── components/                      # Dumb (presentational) components
+    └── {feature}-form/
+```
+
+## Implementation order
+1. **Model** — interfaces for entity, request/response, mirroring the backend's actual DTOs / response shape (per `project-rules.md` — envelope, raw DTO, or GraphQL type)
+2. **Service** — data-access methods returning `Observable<T>` typed with the project's response shape (HttpClient, or the project's client if it uses Apollo/another)
+3. **Routes** — lazy-loaded, guard-protected where needed
+4. **Page components (smart)** — data, loading/error/empty states
+5. **Presentational components (dumb)** — inputs/outputs only, no data access
+
+## Coding rules (from `.claude/rules/project-rules.md` + `.claude/angular-practices/`)
+- Data access ONLY in services — never in components
+- `ChangeDetectionStrategy.OnPush` on every component
+- Tear down subscriptions per profile: `takeUntilDestroyed` (v16+) or `takeUntil(destroy$)` + `ngOnDestroy` (v12–15)
+- 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.

package/references/plan-spec.md

@@ -0,0 +1,112 @@
+# Angular Plan Spec (shared source of truth)
+
+> Read by `/plan` (writes the plan) and by `/dev-cycle` + `/new-feature` (consume the plan).
+> Keep the plan format HERE only — the commands are thin wrappers around this file.
+> Adapted from [obra/superpowers](https://github.com/obra/superpowers) `writing-plans` (MIT).
+
+A plan is written for an engineer with **zero context for this codebase**: every task names exact
+files, exact types, and exact signatures. If a step changes code, the step shows the code.
+
+## Where plans live
+
+`docs/plans/YYYY-MM-DD-<feature-name>.md` — one plan per feature. Create `docs/plans/` if it
+doesn't exist yet.
+
+## Plan document header (required)
+
+```markdown
+# <Feature Name> — Implementation Plan
+
+**Goal:** <one sentence: what this builds and for whom>
+
+**Architecture:** <2-3 sentences: approach, where it sits in the app, key data flow>
+
+**Approach chosen:** <the approach the user approved in /plan Phase C, one line, with the
+main alternative that was rejected and why>
+
+## Global Constraints
+
+Do NOT restate project rules here — point at the sources every task implicitly obeys:
+
+- Precedence + naming + Coexistence: `.claude/rules/project-rules.md`
+- Version idioms (DI, control flow, Signals/RxJS): `.claude/angular-practices/<version>.md`
+- Folder shape, implementation order, coding rules: `.claude/references/feature-structure.md`
+- Wrapper priority: `docs/DESIGN_SYSTEM.md` → Wrapped Components table
+- Endpoints + payload shapes: `docs/API_CONTRACT.md`
+
+<Then list ONLY feature-specific constraints the user stated, one line each, verbatim —
+e.g. "must work offline", "max 1 request per keystroke", "reuse OrderService pagination".>
+```
+
+## File map (required, before any task)
+
+Lock decomposition in before writing tasks. Use the **project's actual layout** from
+`project-rules.md` (e.g. `containers/` not `pages/`, Nx `libs/`) — never the default tree blindly.
+
+```markdown
+## File Map
+
+| Action | Path | Responsibility |
+|--------|------|----------------|
+| Create | src/app/features/<feature>/models/<feature>.model.ts | DTOs mirroring API_CONTRACT |
+| Create | src/app/features/<feature>/services/<feature>.service.ts | Data access only |
+| Modify | src/app/app.routes.ts | Register lazy route |
+| Test   | src/app/features/<feature>/services/<feature>.service.spec.ts | Per test-spec.md |
+```
+
+One clear responsibility per file. Files that change together live together.
+
+## Task structure
+
+Order tasks by the Implementation Order in `feature-structure.md`:
+**Model → Service → Routes → Page components → Presentational components → Tests**
+(tests follow `.claude/references/test-spec.md`; this kit does not use red/green TDD ordering).
+
+Each task uses this shape:
+
+````markdown
+### Task N: <name>
+
+**Files:**
+- Create: `exact/path/file.ts`
+- Modify: `exact/path/existing.ts` (what changes)
+- Test: `exact/path/file.spec.ts`
+
+**Interfaces:**
+- Consumes: <what this task uses from earlier tasks — exact type names and signatures>
+- Produces: <what later tasks rely on — exact function names, parameter and return types.
+  A task's implementer may see only their own task; this block is how they learn the
+  names and types neighboring tasks use.>
+
+**Steps:**
+- [ ] Step 1: <one action, 2-10 minutes, with the actual code block if it changes code>
+- [ ] Step 2: <verify — exact command and expected output, e.g. `npx tsc --noEmit` → clean>
+````
+
+Task sizing: the smallest unit that is independently verifiable (compiles / tests pass on its
+own). Fold setup, config, and docs steps into the task whose deliverable needs them.
+
+## No placeholders (plan failures — never write these)
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases" (show the handling)
+- "Write tests for the above" without naming the cases (list them per test-spec.md coverage)
+- "Similar to Task N" — repeat the code; tasks may be read out of order
+- A step that describes what to do without showing how (code steps require code blocks)
+- References to types, functions, or methods not defined in any task and not existing in the codebase
+
+## Self-review (run after writing, fix inline — no re-review needed)
+
+1. **Requirement coverage** — for each requirement the user confirmed in `/plan`, point to the
+   task that implements it. A requirement with no task = add the task.
+2. **Placeholder scan** — search the plan for every pattern in the list above.
+3. **Type consistency** — types, signatures, and property names used in later tasks match what
+   earlier tasks define, AND match the shapes in `docs/API_CONTRACT.md`.
+4. **Wrapper check** — every UI element in the plan uses the wrapper from the Wrapped
+   Components table when one exists (a raw library import where a wrapper exists is a plan bug).
+5. **Layout check** — every path in the File Map matches the project's real folder layout from
+   `project-rules.md`.
+
+## Output
+
+Report the plan file path, the number of tasks, and the self-review result (what was fixed).

package/references/review-checklist.md

@@ -0,0 +1,88 @@
+# Angular Review Checklist (shared source of truth)
+
+> Read by BOTH `/review-pr` (command, runs inline) and the `angular-reviewer` agent (isolated context).
+> Keep review logic HERE only — the command and the agent are thin wrappers around this file.
+
+## Load the project's standards first
+- `.claude/angular-practices/*.md` — the version-matched idioms (DI, control flow, RxJS/Signals, tests).
+- `.claude/rules/project-rules.md` — naming, folder layout, Precedence, Coexistence.
+- `docs/DESIGN_SYSTEM.md` → Wrapped Components — the project's shared UI wrappers.
+
+## Precedence (do not over-flag)
+A valid project convention WINS over the best-practice profile. Flag a profile deviation as a blocker
+only when it's an **objective defect in NEW code**. Do NOT flag legacy modules listed in the Coexistence
+Strategy — they are kept as-is. Do NOT flag a valid project choice (naming, structure, state library,
+response shape) just because it differs from the profile. When unsure if something is a defect or a
+valid choice, say so rather than blocking.
+
+## Review dimensions
+
+### 1. Architecture
+- [ ] Smart / dumb separation: pages own data; presentational components only render + emit
+- [ ] HTTP calls ONLY in services — never in components
+- [ ] No business logic in templates
+- [ ] Feature routes are lazy-loaded
+
+### 2. Type Safety
+- [ ] No `any` — interfaces/types for every model and API response
+- [ ] Responses typed with the project's response shape recorded in `project-rules.md` (envelope, raw DTO, GraphQL type — whatever the backend returns)
+- [ ] No `@ts-ignore` / `@ts-expect-error`
+
+### 3. Dependency Injection (per `.claude/angular-practices/`)
+- [ ] DI matches the profile: `inject()` (v16+) or constructor injection (v12–15) — consistent across the project
+- [ ] Services `@Injectable({ providedIn: 'root' })` unless intentionally scoped
+
+### 4. Reactive / RxJS / Signals (per `.claude/angular-practices/`)
+- [ ] Subscriptions torn down: `takeUntilDestroyed` (v16+) or `takeUntil(destroy$)` + `ngOnDestroy` (v12–15)
+- [ ] `async` pipe preferred over manual subscribe
+- [ ] No `toPromise()` — use `firstValueFrom()` if needed
+- [ ] Services return `Observable<T>` — do NOT subscribe internally
+- [ ] Signals used per profile: stable for state (v16+); derived state via `computed()`. `resource`/`httpResource` are experimental (v19+) — only if the team opted in
+
+### 5. Error Handling
+- [ ] Loading / error / empty states handled in list & detail pages
+- [ ] HTTP errors surfaced to the user (not swallowed)
+- [ ] Auth errors (e.g. 401) handled centrally by an interceptor — not per-feature
+
+### 6. Security
+- [ ] Auth handled per the project's model in `project-rules.md` (token in memory / httpOnly cookie / session / OAuth) and consistent with it. If tokens are used, they are NOT in localStorage
+- [ ] No hardcoded backend URL — uses `environment`
+- [ ] Routes needing auth are guarded
+- [ ] No unsanitized HTML (`innerHTML` / `bypassSecurityTrust*`) without a clear, reviewed reason
+
+### 7. Performance
+- [ ] `ChangeDetectionStrategy.OnPush` on every component (or zoneless on v20+ if enabled)
+- [ ] List tracking present: `@for` with `track` (v17+) or `*ngFor` with `trackBy` (v12–16)
+
+### 8. Code Quality
+- [ ] Component file < ~300 lines; method < ~50 lines
+- [ ] No dead code, no `console.log`
+- [ ] Naming follows `.claude/rules/project-rules.md`
+
+### 9. Component Wrapping (per `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/`
+- [ ] UI-primitive imports go through the project's wrapper (import path matches the wrapper's location)
+- [ ] Wrapper exists but the PR uses the library directly → 🔴 BLOCKER
+- [ ] No wrapper exists and the library is used directly → 🟡 SUGGESTION: "Consider a wrapper in `shared/components/`"
+- [ ] New components do NOT silently re-implement logic an existing wrapper already provides
+- [ ] A brand-new wrapper follows the Wrapper Reference Example from `project-rules.md`
+
+### 10. Documentation
+- [ ] New feature: `CONTEXT.md` created inside the feature folder
+- [ ] Logic changed: `CONTEXT.md` Refactor Log updated (append only)
+- [ ] Endpoint changed: `docs/API_CONTRACT.md` updated
+- [ ] `docs/PROJECT-STATUS.md` updated
+
+## Output format
+```
+🔴 Blockers — must fix before merge
+  - <file:line> — <issue> → <fix>
+🟡 Suggestions — improve but not blocking
+  - <file:line> — <issue>
+💭 Nits — optional polish (naming, minor style not handled by the linter)
+  - <file:line> — <note>
+🟢 Good — clean patterns / clever solutions worth calling out
+  - <note>
+```
+If there are no blockers, say so explicitly. Cite `file:line`. Explain the "why" behind each finding
+and suggest rather than demand.

package/references/test-spec.md

@@ -0,0 +1,92 @@
+# Angular Test Spec (shared source of truth)
+
+> Read by BOTH `/write-tests` (command, runs inline) and the `angular-test-writer` agent (isolated).
+> Keep test logic HERE only — the command and the agent are thin wrappers around this file.
+
+## Load the project's standards first
+- `.claude/angular-practices/*.md` → the **Testing** section (version's `TestBed` idioms).
+- `.claude/rules/project-rules.md` + an existing spec (the Reference Example) — mirror its style.
+- Detect the runner from `package.json` / `angular.json` / `jest.config` / `karma.conf`
+  (Jest or Karma/Jasmine). Use what the project already uses — never introduce a new runner.
+
+## Step 1: Read before writing
+- Read the feature's source: model, service, page components, presentational components, guards, pipes, resolvers.
+- Read the feature's `CONTEXT.md` (if present) for trade-offs and edge cases.
+- Read `docs/API_CONTRACT.md` for expected request/response shapes.
+- Identify every code path: happy path, not-found, validation failure, loading/error/empty states, branches.
+
+## Step 2: Service unit tests — `{feature}.service.spec.ts`
+Use `HttpClientTestingModule` + `HttpTestingController` (works v12+). On v15+ you may use the functional
+`provideHttpClient()` + `provideHttpClientTesting()` — follow whichever style the project already uses.
+
+```typescript
+describe('{Feature}Service', () => {
+  let service: {Feature}Service;
+  let httpMock: HttpTestingController;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [HttpClientTestingModule],
+      providers: [{Feature}Service],
+    });
+    service = TestBed.inject({Feature}Service);
+    httpMock = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => httpMock.verify());
+});
+```
+
+### Required coverage per method
+- **getAll**: success (returns list; assert URL + `GET`) · empty (empty array, not null) · server error (500 propagates)
+- **getById**: found (assert URL contains id) · not found (404 propagates)
+- **create**: success (assert `POST` + body matches payload) · validation error (400) · conflict (409)
+- **update**: success (assert `PUT`/`PATCH` + body) · not found (404)
+- **delete**: success (assert `DELETE` + URL) · not found (404)
+
+### Service test rules
+- Use `httpMock.expectOne(url)` to assert and flush each request.
+- One behavior per test. Naming: `methodName_scenario_expectedResult`.
+- `httpMock.verify()` in `afterEach` — no unexpected requests. Never hit a real backend.
+
+## Step 3: Component tests — `{feature}-list.component.spec.ts`
+Mock the service with `jasmine.createSpyObj` (Karma) or `jest.fn()` (Jest).
+
+```typescript
+describe('{Feature}ListComponent', () => {
+  let fixture: ComponentFixture<{Feature}ListComponent>;
+  let serviceSpy: jasmine.SpyObj<{Feature}Service>;
+
+  beforeEach(() => {
+    serviceSpy = jasmine.createSpyObj('{Feature}Service', ['getAll', 'delete']);
+    TestBed.configureTestingModule({
+      imports: [{Feature}ListComponent],
+      providers: [{ provide: {Feature}Service, useValue: serviceSpy }],
+    });
+  });
+});
+```
+
+### Required coverage
+- Render (list shows correct data after load) · Loading (spinner while pending) · Error (message on service error)
+  · Empty (empty-state message) · Interaction (clicking delete calls `service.delete` with the right id)
+  · Signals (v16+): assert signal values update as expected.
+
+### Component test rules
+- Mock the service — never the real HttpClient.
+- Drive change detection with `fixture.detectChanges()`; query DOM via `fixture.nativeElement` / `DebugElement`.
+- Each test independent — no shared mutable state.
+
+## Step 4: E2E (only for critical flows)
+For login and the main CRUD flow, add a spec under the project's e2e folder using its configured E2E
+tool (e.g. Playwright). Skip E2E for trivial pages — manual testing covers those.
+
+## Step 5: Verify before reporting
+- All new tests pass (`ng test --watch=false` / `npm test` / `jest`, or target the new spec).
+- No test depends on execution order; no unit/component test hits a real backend.
+- Test names describe behavior and the expected result.
+- Coverage ≥ 80% for the feature (`ng test --code-coverage` / `jest --coverage` if configured);
+  every public service method has at least happy-path + error case.
+
+## Output
+List the spec files created, what each covers, and the final test-run result (pass/fail + coverage).

package/skills/angular-practices/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: angular-practices
+description: Use when writing, reviewing, or refactoring any Angular / TypeScript code in this project — components, dependency injection, templates, services, HTTP, routing, RxJS/Signals, forms, and testing. Provides the version-matched Angular {{NG_PROFILE_LABEL}} idioms for this codebase.
+---
+
+# Angular Practices (this project)
+
+When you write or review Angular code in this project, follow the version-matched
+best-practice profile that the installer selected for this codebase.
+
+**→ Read `.claude/angular-practices/{{PRACTICE_FILE}}` and apply it.**
+
+That file is the source of truth for HOW to write idiomatic Angular {{NG_PROFILE_LABEL}}:
+component style (standalone vs NgModule), DI (`inject()` vs constructor), template syntax
+(`@if/@for` vs `*ngIf/*ngFor`), thin components with a smart/dumb split, HTTP in services
+(not components), typed reactive forms, RxJS teardown (`takeUntilDestroyed`) or Signals for
+local state, `OnPush` change detection, and `TestBed` slice tests.
+
+## Precedence — which rule wins (read this first)
+
+The profile is **not** absolute. Follow this order (see `.claude/rules/project-rules.md` → Precedence):
+
+1. **This project's conventions** (the codebase + `.claude/rules/project-rules.md`) — HIGHEST.
+   If the project does something consistently and it works, match it — even if it differs
+   from the profile (folder layout, naming, state-management library, API/response shape, auth).
+2. **This profile** — applies only where the project has NO convention, or where existing
+   code is objectively below standard. In that case the standard applies to **NEW code only**.
+3. **Legacy modules** (Coexistence Strategy in project-rules.md) — never refactored.
+
+## Before importing a raw UI-library component
+
+Check whether a shared wrapper already exists for the need — see the
+**component-wrapper-priority** skill and `docs/DESIGN_SYSTEM.md` → Wrapped Components table.
+Never bypass an existing wrapper with a raw library import.