agent-directives 0.3.0 → 0.4.0

package/README.md

@@ -13,7 +13,7 @@ dependencies between files.
 | **Navigation** | 1 directive | SAFE pattern for exploring codebases before implementation |
 | **Memory** | 2 directives | Error memory and session decisions for persistent learning |
 | **Skills** | 13 skills | Code reviewer, test reviewer, spec reviewer, product requirements writer, implementation task planner, subagent-driven development, self-audit, systematic debugging, architecture boundary reviewer, codebase health reviewer, production readiness reviewer, harness hooks reviewer, and MCP integration reviewer |
-| **Rules** | 3 Angular rules | Lazy-loaded Angular project, component/template, and testing standards selected by stack or explicit category |
+| **Rules** | 6 Angular rules | Lazy-loaded Angular project structure, components/templates, coding style, application patterns, security, and testing standards — selected by stack or explicit category |
 | **Templates** | 4 templates | Drop-in instruction files for AGENTS.md, CLAUDE.md, Copilot, and decision logs |
 | **Tooling** | TypeScript scripts | Validate directive wiring, assemble eval scenarios, record loaded-file manifests, and generate eval health reports |
 

package/directives/adaptive-routing.md

@@ -1,7 +1,7 @@
 ---
 name: adaptive-routing
 description: Selects the lightest safe workflow path, relevant directives/skills, and handoff requirements based on task intent, risk, and touched surfaces.
-version: 1.4.0
+version: 1.6.0
 required: true
 category: workflow
 tools:
@@ -138,13 +138,27 @@ work but do not replace directives or skills.
 - Do not load unrelated framework rule packs. Project-local instructions override
   rule-pack guidance when they conflict.
 
-Initial rule pack:
-
-| Situation / evidence | Selected rules |
-| --- | --- |
-| Angular project structure, routing, source layout, or workspace config (`angular.json`, `@angular/core`, or Angular app files) | `rules/angular/project-structure.md` |
-| Angular component, template, component style, inputs/outputs, lifecycle, accessibility, or UI behavior | `rules/angular/components-and-templates.md` |
-| Angular tests, specs, services under test, or Angular behavior changes needing test evidence | `rules/angular/testing.md` |
+### Selecting rules by discovery
+
+Do not maintain a per-rule routing table in this directive. Rule packs grow, and
+this directive loads on every task; an inline catalog would put every rule pack's
+metadata in always-loaded context. Discover matching rules on demand instead:
+
+1. **Detect the stack** from project evidence. For example, `angular.json` or an
+   `@angular/core` dependency selects the `angular` pack.
+2. **Open the rule index.** Each rule entry in `manifest.json` carries `category`
+   (the pack), `description` (what it governs), and `applies_to` (the file globs
+   it scopes to). The `rules/<pack>/` directory holds the same entries on disk;
+   read a rule's frontmatter for the authoritative scope.
+3. **Match before loading.** Load a rule only when its `applies_to` globs match a
+   file you will touch *and* its `description` is relevant to what the task
+   actually changes. A glob match alone is not enough — editing a
+   `*.component.ts` file does not pull in the security rule unless the task
+   involves untrusted input, HTTP, secrets, or SSR.
+4. **Skip absent packs.** Do not load a pack whose evidence is missing, and do
+   not load a whole pack by default.
+
+The only pack today is `rules/angular/`.
 
 ---
 

package/dist/manifest.d.ts

@@ -8,6 +8,7 @@ export interface ManifestEntry {
     required: boolean;
     category: string;
     tools: string[];
+    applies_to?: string[];
 }
 export interface Manifest {
     version: string;

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAGD,eAAO,MAAM,WAAW,QAAwB,CAAC;AAEjD,wBAAgB,YAAY,IAAI,QAAQ,CAMvC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,EAAE,CAQ5F;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEzF"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAGD,eAAO,MAAM,WAAW,QAAwB,CAAC;AAEjD,wBAAgB,YAAY,IAAI,QAAQ,CAMvC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,EAAE,CAQ5F;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEzF"}

package/dist/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA2BzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAEjD,MAAM,UAAU,YAAY;IAC1B,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,8BAA8B,YAAY,0CAA0C,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAa,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAwB,EAAE,IAAmB;IACzE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9B,IAAI,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QACpE,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAClF,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAChE,IAAI,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAwB,EAAE,EAAU;IAC5D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA4BzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAEjD,MAAM,UAAU,YAAY;IAC1B,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,8BAA8B,YAAY,0CAA0C,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAa,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAwB,EAAE,IAAmB;IACzE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9B,IAAI,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QACpE,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAClF,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAChE,IAAI,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAwB,EAAE,EAAU;IAC5D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAClD,CAAC"}

package/manifest.json

@@ -6,7 +6,7 @@
       "type": "directive",
       "path": "directives/adaptive-routing.md",
       "description": "Selects the lightest safe workflow path, relevant directives/skills, and handoff requirements based on task intent, risk, and touched surfaces.",
-      "version": "1.4.0",
+      "version": "1.6.0",
       "required": true,
       "category": "workflow",
       "tools": [
@@ -383,11 +383,51 @@
         "cursor"
       ]
     },
+    {
+      "id": "angular-coding-style",
+      "type": "rule",
+      "path": "rules/angular/coding-style.md",
+      "description": "Concrete Angular coding-style patterns — signals, dependency injection with inject(), change detection, RxJS usage, and TypeScript strictness for Angular code.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "angular",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ],
+      "applies_to": [
+        "src/app/**/*.ts",
+        "src/**/*.ts"
+      ]
+    },
     {
       "id": "angular-components-and-templates",
       "type": "rule",
       "path": "rules/angular/components-and-templates.md",
-      "description": "Angular component and template rules for typed, maintainable Angular UI changes.",
+      "description": "Concrete patterns for building modern Angular components, signal-based inputs/outputs, OnPush change detection, and v17+ control-flow templates.",
+      "version": "1.1.0",
+      "required": false,
+      "category": "angular",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ],
+      "applies_to": [
+        "src/app/**/*.component.ts",
+        "src/app/**/*.component.html",
+        "src/app/**/*.component.css",
+        "src/app/**/*.component.scss"
+      ]
+    },
+    {
+      "id": "angular-patterns",
+      "type": "rule",
+      "path": "rules/angular/patterns.md",
+      "description": "Concrete Angular application patterns — smart/dumb component split, service-layer ownership, routing/guards/resolvers, HTTP interceptors, and reactive state with signals or RxJS.",
       "version": "1.0.0",
       "required": false,
       "category": "angular",
@@ -396,13 +436,45 @@
         "copilot",
         "codex",
         "cursor"
+      ],
+      "applies_to": [
+        "src/app/**/*.component.ts",
+        "src/app/**/*.component.html",
+        "src/app/**/*.service.ts",
+        "src/app/**/*.store.ts",
+        "src/app/**/*.routes.ts",
+        "src/app/**/*.guard.ts",
+        "src/app/**/*.resolver.ts",
+        "src/app/**/*.interceptor.ts"
       ]
     },
     {
       "id": "angular-project-structure",
       "type": "rule",
       "path": "rules/angular/project-structure.md",
-      "description": "Angular workspace and project-structure standards for agents working in Angular applications.",
+      "description": "Concrete Angular workspace, file-naming, feature-folder, and provider-bootstrapping standards for agents working in Angular applications.",
+      "version": "1.1.0",
+      "required": false,
+      "category": "angular",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ],
+      "applies_to": [
+        "angular.json",
+        "package.json",
+        "src/main.ts",
+        "src/app/**/*.ts",
+        "src/app/**/*.html"
+      ]
+    },
+    {
+      "id": "angular-security",
+      "type": "rule",
+      "path": "rules/angular/security.md",
+      "description": "Concrete Angular security rules — XSS prevention, HttpClient discipline, secret handling, route guards, and SSR safety.",
       "version": "1.0.0",
       "required": false,
       "category": "angular",
@@ -411,14 +483,25 @@
         "copilot",
         "codex",
         "cursor"
+      ],
+      "applies_to": [
+        "src/app/**/*.component.ts",
+        "src/app/**/*.component.html",
+        "src/app/**/*.service.ts",
+        "src/app/**/*.interceptor.ts",
+        "src/app/**/*.guard.ts",
+        "src/app/**/*.routes.ts",
+        "src/environments/**/*.ts",
+        "src/**/*.server.ts",
+        "server.ts"
       ]
     },
     {
       "id": "angular-testing",
       "type": "rule",
       "path": "rules/angular/testing.md",
-      "description": "Angular testing rules for component, service, and integration-style Angular changes.",
-      "version": "1.0.0",
+      "description": "Concrete Angular testing patterns — TestBed configuration, signal-input harnesses, router and HTTP testing utilities, and behavior-first test design.",
+      "version": "1.1.0",
       "required": false,
       "category": "angular",
       "tools": [
@@ -426,6 +509,11 @@
         "copilot",
         "codex",
         "cursor"
+      ],
+      "applies_to": [
+        "src/app/**/*.spec.ts",
+        "src/app/**/*.test.ts",
+        "src/**/*.spec.ts"
       ]
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-directives",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Reusable agent directives, skills, and CLI tooling for AI coding workflows",
   "license": "MIT",
   "author": "Rob Simpson <rsimpson2@me.com>",

package/rules/angular/coding-style.md

@@ -0,0 +1,164 @@
+---
+name: angular-coding-style
+description: Concrete Angular coding-style patterns — signals, dependency injection with inject(), change detection, RxJS usage, and TypeScript strictness for Angular code.
+version: 1.0.0
+required: false
+category: angular
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+source_urls:
+  - https://angular.dev/style-guide
+  - https://angular.dev/guide/signals
+  - https://angular.dev/guide/di
+  - https://angular.dev/guide/components/dependency-injection
+  - https://rxjs.dev/guide/operators
+applies_to:
+  - src/app/**/*.ts
+  - src/**/*.ts
+---
+
+# Angular Coding Style Rules
+
+**Load when:** Writing or reviewing Angular TypeScript — components, services, directives, pipes, guards, resolvers, interceptors, or any code that uses Angular's DI / signals / RxJS surface.
+
+## Version Awareness
+
+Many of the patterns below (`inject()`, signal primitives, `linkedSignal`, `resource`, functional guards/interceptors, `takeUntilDestroyed`) are version-gated. Check `package.json` / `ng version` and use the patterns the installed version supports — do not introduce a v18+ API into a v15 project.
+
+## Sources
+
+- Angular Style Guide — https://angular.dev/style-guide
+- Angular Signals Guide — https://angular.dev/guide/signals
+- Angular Dependency Injection Guide — https://angular.dev/guide/di
+- RxJS Operators — https://rxjs.dev/guide/operators
+
+## Rules
+
+### Dependency injection
+
+Use `inject()` over constructor injection in components, services, guards, resolvers, interceptors, and pipes. Keep constructors empty (or remove them) so DI calls live at field declarations next to their use.
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private http = inject(HttpClient);
+  private router = inject(Router);
+}
+```
+
+```typescript
+// Avoid on new code — verbose and harder to tree-shake/refactor
+constructor(private http: HttpClient, private router: Router) {}
+```
+
+Use `InjectionToken` for non-class dependencies (config, env, capability flags):
+
+```typescript
+export const API_URL = new InjectionToken<string>('API_URL');
+
+// In providers:
+{ provide: API_URL, useValue: 'https://api.example.com' }
+
+// At call site:
+private apiUrl = inject(API_URL);
+```
+
+- Prefer `providedIn: 'root'` for app-wide singletons. Scope a service to a component/route only when its lifecycle must follow that subtree.
+- `inject()` runs in an injection context. Calls outside a constructor/field initializer/factory need `runInInjectionContext` — do not stash `inject` calls inside arbitrary functions.
+
+### Signals
+
+Use signals for reactive state. Three primitives:
+
+```typescript
+count = signal(0);                                  // writable
+doubled = computed(() => this.count() * 2);         // derived, read-only
+selectedItem = linkedSignal(() => this.items()[0]); // writable derived: resets with source, also user-settable
+```
+
+- Never duplicate derived data in a separate writable signal updated through `effect()` — use `computed` (or `linkedSignal` if it must also be writable).
+- Bridge Observables to signals with `toSignal(stream$, { initialValue: ... })`. Do not assign Observable values into signals from manual `.subscribe()` callbacks.
+- For async fetching backed by signals, prefer `resource({ request, loader })` on v19+ projects:
+
+```typescript
+userResource = resource({
+  request: () => ({ id: this.userId() }),
+  loader: ({ request }) => fetch(`/api/users/${request.id}`).then(r => r.json()),
+});
+// Access: userResource.value(), userResource.isLoading(), userResource.error(), userResource.reload()
+```
+
+#### `effect()` usage
+
+Reserve `effect()` for genuine side effects that must react to signal changes — logging, third-party DOM libraries, telemetry. Never use `effect()` to keep two signals in sync; that is what `computed` / `linkedSignal` are for.
+
+```typescript
+// Correct — side effect that must react
+effect(() => analytics.track('user_changed', { id: this.user().id }));
+
+// Wrong — derived state, use computed
+effect(() => this.fullName.set(`${this.first()} ${this.last()}`));
+```
+
+For DOM work that must run after the view renders, use `afterRenderEffect` (or `afterNextRender` for one-shot work).
+
+### Change detection
+
+- Default to `ChangeDetectionStrategy.OnPush` on every new component.
+- Drive view updates via signals or the `async` pipe. Avoid `ChangeDetectorRef.markForCheck()` / `detectChanges()` unless you have a narrow, documented reason (e.g., third-party callback outside the zone).
+- Consider zoneless change detection (`provideExperimentalZonelessChangeDetection()` / `provideZonelessChangeDetection()` on supporting versions) only as a project-level decision, never as a side effect of a feature change.
+
+### RxJS
+
+When the project still uses RxJS for streams alongside (or instead of) signals:
+
+| Operator | Use for |
+| --- | --- |
+| `switchMap` | Search, navigation, latest-wins — cancels prior inner stream |
+| `mergeMap` | Independent parallel inner streams |
+| `exhaustMap` | Form submissions, idempotency — ignores new emissions until current completes |
+| `concatMap` | Ordered queueing |
+
+- Always handle errors with `catchError`. Never let a long-lived stream die silently and stop emitting.
+- Use `takeUntilDestroyed(this.destroyRef)` for manual subscriptions in components/directives. Do not roll a manual `ngOnDestroy` + `Subject<void>` + `takeUntil` on new code.
+- Prefer the `async` pipe in templates over manual subscribe + assign. If the data is needed in component logic too, expose it as a signal via `toSignal`.
+
+```typescript
+search$ = this.query$.pipe(
+  debounceTime(300),
+  distinctUntilChanged(),
+  switchMap(q => this.service.search(q).pipe(catchError(() => of([])))),
+);
+```
+
+### TypeScript strictness
+
+- Run with `strict: true` and `strictTemplates: true` (Angular compiler option). Do not weaken either to make a change compile.
+- Type every public surface: component inputs/outputs, service method signatures, route data, interceptor return types.
+- Treat external data as `unknown` at the boundary. Narrow it with a validator (Zod, io-ts, hand-rolled type guard) before binding it to typed signals or components.
+- Do not use `any`, `as any`, or non-null `!` to silence template type errors — fix the type or narrow the value.
+
+### File-level style
+
+- One artifact per file. Co-locate template (`.html`) and styles (`.scss`/`.css`) with the component class.
+- Imports ordered: Angular core/common, third-party, project absolute (`@/...`), project relative (`./...`). Match the project's existing convention if it differs.
+- Member order inside a class: signal fields → injected dependencies → inputs/outputs → other state → constructor (if any) → lifecycle hooks → public methods → private methods. Adjust to project style if it has a stronger local convention.
+
+## Anti-patterns to refuse
+
+- Constructor-injected dependencies on a project that has already adopted `inject()`.
+- `effect()` used to synchronize signals.
+- Manual `.subscribe()` in components without `takeUntilDestroyed`, or with a hand-rolled `destroy$` subject.
+- `any` introduced to make typed templates compile, or `as any` casts on `HttpClient` responses.
+- Calling `inject()` outside an injection context (e.g., inside an arbitrary helper function not invoked from a factory).
+
+## Evidence
+
+For style-aligned changes, run the project's lint and typecheck:
+
+- `ng lint` (or the project's lint script) on touched files
+- `tsc --noEmit` or `ng build` to verify typed templates and the public TypeScript surface
+- Targeted tests covering the changed behavior (see `rules/angular/testing.md`)

package/rules/angular/components-and-templates.md

@@ -1,7 +1,7 @@
 ---
 name: angular-components-and-templates
-description: Angular component and template rules for typed, maintainable Angular UI changes.
-version: 1.0.0
+description: Concrete patterns for building modern Angular components, signal-based inputs/outputs, OnPush change detection, and v17+ control-flow templates.
+version: 1.1.0
 required: false
 category: angular
 tools:
@@ -13,6 +13,9 @@ source_urls:
   - https://angular.dev/style-guide
   - https://angular.dev/guide/components
   - https://angular.dev/guide/templates
+  - https://angular.dev/guide/signals
+  - https://angular.dev/guide/components/inputs
+  - https://angular.dev/guide/components/outputs
 applies_to:
   - src/app/**/*.component.ts
   - src/app/**/*.component.html
@@ -22,31 +25,114 @@ applies_to:
 
 # Angular Components and Templates Rules
 
-**Load when:** Creating, changing, or reviewing Angular components, templates, component styles, inputs, outputs, lifecycle behavior, or view logic.
+**Load when:** Creating, changing, or reviewing Angular components, templates, component styles, inputs/outputs, lifecycle behavior, or view logic.
 
-## Sources
+## Version Awareness
+
+Check the project's Angular version before writing code — APIs differ significantly between versions. Use `ng version` or inspect `package.json`. Match the project's existing component style first; do not migrate component styles as part of an unrelated change.
 
-Track source material explicitly so future updates can verify whether the rule is stale:
+## Sources
 
 - Angular Style Guide — https://angular.dev/style-guide
 - Angular Components Guide — https://angular.dev/guide/components
 - Angular Templates Guide — https://angular.dev/guide/templates
+- Angular Signals Guide — https://angular.dev/guide/signals
 
 ## Rules
 
-- Match the project's existing Angular style first, then Angular's current guidance.
-- Prefer standalone components for new components unless the project is clearly NgModule-centered.
-- Keep components focused on presentation and UI coordination. Move reusable business logic to services, utilities, or state primitives already used by the project.
-- Keep templates declarative. Avoid hiding complex branching, transformations, or side effects inside template expressions.
-- Type component inputs, outputs, and public component methods explicitly when they form a contract with templates, parents, or tests.
-- Do not introduce `any` for template or component data. Narrow external data at the boundary before binding it.
-- Preserve existing accessibility patterns. New interactive elements need keyboard, label, and semantic HTML coverage appropriate to the component.
-- Avoid drive-by component rewrites, style-system changes, or broad file moves while making localized UI changes.
+### Component shape
+
+- Prefer standalone components (v17+ default). Add `standalone: true` and declare template dependencies in `imports`. Do not mix standalone and NgModule registration for the same component.
+- Default to `ChangeDetectionStrategy.OnPush` on all new components.
+- Keep components focused on presentation and UI coordination. Move data access, business rules, and cross-component state to services or state primitives the project already uses.
+- One artifact per file — `user-card.component.ts`, `user-card.component.html`, `user-card.component.scss`, `user-card.component.spec.ts`.
+
+```typescript
+@Component({
+  selector: 'app-user-card',
+  standalone: true,
+  imports: [RouterLink, DatePipe],
+  templateUrl: './user-card.component.html',
+  styleUrl: './user-card.component.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserCardComponent {
+  user = input.required<User>();
+  highlight = input(false, { transform: booleanAttribute });
+  select = output<string>();
+
+  onClick() {
+    this.select.emit(this.user().id);
+  }
+}
+```
+
+### Inputs and outputs
+
+- On v17.1+ projects, prefer signal-based `input()` / `input.required()` / `output()` over decorators. Stay on `@Input()`/`@Output()` only if the project is uniformly decorator-based and the file you are editing already uses them.
+- Type every input and output. Do not introduce `any` to make a binding compile — narrow the source data at the boundary instead.
+- Use `input.required<T>()` when a parent must supply the value. Provide defaults (`input(false)`) only when the absence has a meaningful, documented behavior.
+- Two-way binding uses `model()` (e.g., `value = model<string>('')`). Do not invent custom `xChange` outputs when `model()` covers the use case.
+
+### Templates (v17+ control flow)
+
+Use the built-in block syntax. Always provide `track` in `@for`.
+
+```html
+@if (isLoading()) {
+  <app-spinner />
+} @else if (error()) {
+  <app-error [message]="error()" />
+} @else {
+  @for (item of items(); track item.id) {
+    <app-item [item]="item" (select)="onSelect($event)" />
+  } @empty {
+    <p>No items found.</p>
+  }
+}
+
+@switch (status()) {
+  @case ('active')  { <app-active /> }
+  @case ('pending') { <app-pending /> }
+  @default          { <app-unknown /> }
+}
+```
+
+- Keep templates declarative. Move complex branching, transformations, or side effects into the component class, a `computed`, or a pure pipe.
+- Call signals as functions in the template (`items()`, not `items`). Do not access `.value` on a signal — that is not the public API.
+- Use the `async` pipe for Observables in templates rather than subscribing manually. Prefer converting to signals via `toSignal()` when possible.
+- Use `@defer` for non-critical UI blocks (below the fold, behind interaction). Pair with `@placeholder`, `@loading`, and `@error` blocks.
+
+### Lifecycle and DOM access
+
+- Use `inject()` over constructor injection. Keep constructors empty.
+- For DOM work that must run after the view renders, prefer `afterRenderEffect` / `afterNextRender`. Do not reach into the DOM from `ngOnInit`.
+- Use `viewChild()` / `viewChildren()` / `contentChild()` (signal queries) over the decorator forms on v17.2+ projects.
+- Avoid `ngOnChanges` when an `input()` signal plus a `computed` or `effect` expresses the dependency directly.
+
+### Styles
+
+- Keep `ViewEncapsulation.Emulated` (default). Use `ViewEncapsulation.None` only for design-system roots that intentionally bleed styles.
+- Scope styles to the component file. Use `:host`, `:host-context`, and CSS custom properties for themeable values rather than global selectors.
+- Preserve existing accessibility patterns. New interactive elements need keyboard support, programmatic labels, focus management, and semantic HTML appropriate to the component.
+
+### Change detection hygiene
+
+- Signals and the `async` pipe drive change detection on `OnPush` components automatically. Do not reach for `ChangeDetectorRef.markForCheck()` or `detectChanges()` unless you have a documented, narrow reason.
+- Do not mutate input objects in place when `OnPush` is in effect — produce new references.
+
+## Anti-patterns to refuse
+
+- `@Component({ standalone: false })` on new components without an NgModule that already owns it.
+- `ChangeDetectionStrategy.Default` on new components.
+- Using `*ngIf` / `*ngFor` / `*ngSwitch` on projects that have adopted block syntax.
+- Calling `.subscribe()` from a template, or storing computed/derived values in plain signals updated via `effect()`.
+- Typing inputs/outputs as `any`, or bypassing the type system with `!` to silence template errors.
 
 ## Evidence
 
 For component behavior changes, include one of:
 
 - updated component/unit tests,
-- existing tests that cover the changed behavior,
-- or a stated reason tests are unavailable plus a lower-confidence fallback such as build/typecheck evidence.
+- existing tests that already cover the changed behavior,
+- or a stated reason tests are unavailable plus a lower-confidence fallback such as build/typecheck output (`ng build`, `tsc --noEmit`).