agent-directives 0.2.1 → 0.4.0

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.3.0",
+      "version": "1.6.0",
       "required": true,
       "category": "workflow",
       "tools": [
@@ -382,6 +382,139 @@
         "codex",
         "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": "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",
+      "tools": [
+        "claude",
+        "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": "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",
+      "tools": [
+        "claude",
+        "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": "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": [
+        "claude",
+        "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.2.1",
+  "version": "0.4.0",
   "description": "Reusable agent directives, skills, and CLI tooling for AI coding workflows",
   "license": "MIT",
   "author": "Rob Simpson <rsimpson2@me.com>",
@@ -15,6 +15,7 @@
     "dist/",
     "directives/",
     "skills/",
+    "rules/",
     "templates/",
     "manifest.json",
     "README.md"

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

@@ -0,0 +1,138 @@
+---
+name: angular-components-and-templates
+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
+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
+  - src/app/**/*.component.css
+  - src/app/**/*.component.scss
+---
+
+# Angular Components and Templates Rules
+
+**Load when:** Creating, changing, or reviewing Angular components, templates, component styles, inputs/outputs, lifecycle behavior, or view logic.
+
+## 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.
+
+## 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
+
+### 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 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`).