@jhm1909/ag-kit 0.1.0

package/.agent/skills/devops-engineer/references/observability-security.md

@@ -0,0 +1,45 @@
+# Observability & Security
+
+## Observability (The 3 Pillars)
+
+### 1. Logs
+
+- **Structured Logging**: JSON over plain text.
+  - Bad: `console.log("User login failed for " + user)`
+  - Good: `logger.error({ event: "login_failed", user_id: 123 })`
+- **Aggregation**: ELK Stack, Splunk, Datadog Logs.
+
+### 2. Metrics
+
+- **Golden Signals**:
+  - **Latency**: Time it takes to serve a request.
+  - **Traffic**: Demand placed on the system.
+  - **Errors**: Rate of requests failing.
+  - **Saturation**: How "full" the service is.
+- **Tools**: Prometheus (collection) + Grafana (visualization).
+
+### 3. Traces
+
+- **Distributed Tracing**: Tracking a request across microservices.
+- **Tools**: OpenTelemetry (Standard), Jaeger, Zipkin.
+
+## Security (DevSecOps)
+
+### Pipeline Integration
+
+1.  **SAST (Static Application Security Testing)**: Scan source code.
+    - _Tools_: SonarQube, CodeQL.
+2.  **SCA (Software Composition Analysis)**: Scan dependencies.
+    - _Tools_: `npm audit`, Snyk, Dependabot.
+3.  **Container Scanning**:
+    - _Tools_: Trivy, Clair.
+4.  **DAST (Dynamic Application Security Testing)**: Scan running app.
+    - _Tools_: OWASP ZAP.
+
+### Secret Management
+
+- **Vault Strategy**:
+  - **Local**: `.env` (gitignored).
+  - **CI/CD**: Repo Secrets.
+  - **Runtime**: AWS Secrets Manager, HashiCorp Vault.
+- **Scanning**: Use `git-secrets` or TruffleHog to prevent leaks.

package/.agent/skills/devops-engineer/references/vercel-supabase.md

@@ -0,0 +1,17 @@
+# Platform: Vercel & Supabase
+
+## CI/CD Pipeline (GitHub Actions)
+
+1.  **Pull Request**:
+    - `npm run lint`
+    - `npm run typecheck`
+    - `npm run test:unit`
+    - Vercel Preview Deployment (Automatic)
+
+2.  **Merge to Main**:
+    - Supabase Migration (`supabase migration up`)
+    - Vercel Production Deployment
+
+## Secrets
+
+- **Required**: `NEXT_PUBLIC_SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` (CI only), `DATABASE_URL`.

package/.agent/skills/devops-engineer/templates/release-notes.md

@@ -0,0 +1,8 @@
+# Release v1.0.1
+
+**Date**: YYYY-MM-DD
+**Features**:
+
+- 🚀 **New**: Dark Mode support.
+- 🐛 **Fix**: Login crash on Safari.
+- ✨ **Improvement**: Faster search results.

package/.agent/skills/frontend-developer/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: frontend-developer
+description: >
+  Foundation for all frontend development. Use when implementing UI code,
+  optimizing performance, or ensuring accessibility.
+  Includes Vercel React performance rules and composition patterns.
+license: MIT
+compatibility: Claude Code, Cursor, Gemini CLI, GitHub Copilot
+metadata:
+  author: jhm1909
+  version: "4.0.0"
+  domain: web
+  estimated_tokens: 5000
+  sources:
+    - vercel-labs/agent-skills (react-best-practices, composition-patterns)
+---
+
+# Frontend Developer
+
+Foundation skill for web frontend development. Framework-agnostic patterns for performance, accessibility, and code quality.
+
+## Knowledge Graph
+
+- **extends**: none (base skill)
+- **requires**: []
+- **suggests**: []
+- **conflicts**: []
+- **enhances**: [[designer]] (implementation of designs)
+- **moc**: [[web-development-moc]]
+
+## ?�� THE GOLDEN RULE: "Quote First"
+
+**You must NEVER write code without first citing your source.**
+
+Before implementing:
+1. **Locate** authoritative documentation
+2. **Quote** the specific section justifying your decision
+3. **Implement** strictly according to that quote
+
+_If no source found, PAUSE and `search_web` or ask._
+
+## ?�� Core Philosophy
+
+1. **Zero-Bundle Budget** ??Every kilobyte justifies existence
+2. **Hydration is Overhead** ??Static when possible
+3. **User Waits for Nothing** ??Optimistic UI, non-blocking main thread
+4. **Accessibility is NOT Optional** ??`<div onClick>` is a bug
+
+## Framework Specializations
+
+| Framework | Skill | Relationship |
+|-----------|-------|--------------|
+| React / Next.js | `react-nextjs/` | **extends** this skill |
+| Vue / Nuxt | [[vue-developer]] | **extends** this skill |
+| Angular | [[angular-developer]] | **extends** this skill |
+| Svelte / Solid / Qwik | [[modern-signals]] | **extends** this skill |
+
+## Capability Add-ons
+
+Add these to any frontend specialization:
+
+| Capability | Location | Use For |
+|------------|----------|---------|
+| 3D Graphics | `threejs/` | WebGL, 3D product showcases |
+| Video Generation | [[remotion-best-practices]] | Programmatic video |
+| Animations | [[framer-motion]] | Complex UI animations |
+| Styling | [[tailwind-setup]] | Utility-first CSS |
+
+## Dynamic Stack Loading
+
+Load framework-specific guides as needed:
+
+| When User Needs | Load This |
+|:----------------|:----------|
+| Next.js App Router patterns | `react-nextjs/README.md` |
+| 3D graphics, WebGL | `threejs/README.md` |
+| Tailwind CSS setup | `tailwind-setup/README.md` |
+
+### Example Workflows
+
+**Next.js Project:**
+```
+User: "Build a Next.js app with App Router"
+??Load frontend-developer/react-nextjs/README.md
+??Follow Server Components patterns
+??Implement loading.tsx, error.tsx
+```
+
+**3D Product Viewer:**
+```
+User: "Add a 3D model viewer to my React app"
+??Load frontend-developer/threejs/README.md
+??Set up React Three Fiber
+??Configure Canvas, lights, controls
+```
+
+## Quick Rules
+
+| Aspect | Rule |
+|--------|------|
+| Performance | Check Web Vitals after every change |
+| Accessibility | All images need `alt`, interactive elements need focus |
+| Bundles | Code-split by route, lazy load below fold |
+| Images | Use modern formats (WebP, AVIF), provide fallbacks |
+| React Perf | Eliminate waterfalls, no barrel imports (Vercel rules) |
+| Composition | Compound components over boolean props (Vercel patterns) |
+
+## References
+
+| Reference | Purpose |
+|:----------|:--------|
+| `react_performance_rules.md` | 65 Vercel React/Next.js perf rules (8 categories) |
+| `composition_patterns.md` | React composition patterns (Vercel) |
+
+## Related Skills
+
+- [[react-nextjs]] ??React & Next.js specific
+- [[vue-developer]] ??Vue & Nuxt specific
+- [[backend-developer]] ??When building fullstack
+- [[designer]] ??Design system implementation
+- [[qa-tester]] ??E2E testing
+
+---
+
+*Part of [[web-development-moc]] | Base skill for all frontend work*

package/.agent/skills/frontend-developer/react-nextjs/README.md

@@ -0,0 +1,90 @@
+# React & Next.js
+
+Next.js App Router and React Server Components best practices.
+
+## When to Use
+
+Use this guide when:
+- Building with Next.js App Router (app/ directory)
+- Deciding between Server vs Client Components
+- Implementing data fetching, caching, or mutations
+- Handling loading states and errors
+- Working with Server Actions
+
+## Core Philosophy
+
+1. **Server Components First** — Default to RSC, `'use client'` is the exception
+2. **Colocation** — Keep related code close (components, tests, styles)
+3. **Progressive Enhancement** — Core works without JS
+
+## Server vs Client Components
+
+| Use Server Component | Use Client Component |
+|:---------------------|:---------------------|
+| Data fetching | Event handlers (`onClick`) |
+| Backend resources (`fs`, DB) | Browser APIs |
+| Sensitive logic (tokens, keys) | `useState`, `useEffect` |
+| Large dependencies | Hooks requiring DOM |
+
+## Quick Rules
+
+| Context | Implementation |
+|:--------|:---------------|
+| Data fetching | Server Components + `fetch`, or Server Actions |
+| Forms | Server Actions + `useFormStatus` |
+| Images | Always `next/image` |
+| Fonts | Always `next/font` |
+| Routes | File-based in `app/` directory |
+| Metadata | Export `metadata` object |
+
+## Common Patterns
+
+### Loading States
+```tsx
+// app/posts/loading.tsx — Automatic loading UI
+export default function Loading() {
+  return <PostSkeleton />;
+}
+```
+
+### Error Boundaries
+```tsx
+// app/posts/error.tsx — Automatic error handling
+'use client';
+export default function Error({ error, reset }) {
+  return <ErrorUI error={error} retry={reset} />;
+}
+```
+
+### Server Actions
+```tsx
+// Server action in component or separate file
+async function createPost(formData: FormData) {
+  'use server';
+  // Mutate data, revalidate cache
+}
+```
+
+## Conflicting Patterns
+
+| ❌ Avoid | ✅ Use Instead |
+|:---------|:---------------|
+| `useEffect` + `fetch` | Server Component + `fetch` |
+| Manual `<head>` | `metadata` export |
+| `pages/_app.tsx` | `app/layout.tsx` |
+| `getServerSideProps` | Server Component |
+| `getStaticProps` | `fetch` with `cache: 'force-cache'` |
+
+## Extensions
+
+- **3D/Three.js** → Load `threejs` capability for 3D product viewers
+- **Video** → Load `remotion-best-practices` for programmatic video
+- **Auth** → Use `next-auth` or `clerk`
+- **Database** → Use `prisma` or `drizzle`
+
+## Triggers
+
+- `next/router|next/navigation|next/headers` pattern detected
+- `app/layout.tsx|app/page.tsx|app/loading.tsx` files present
+- `next.config.(js|ts|mjs)` file exists
+- `next` dependency in package.json

package/.agent/skills/frontend-developer/references/angular.md

@@ -0,0 +1,52 @@
+# Modern Angular Architecture
+
+**Status**: Definitive Guide
+**Stack**: Angular 17+
+
+## 🏗 Architecture: Standalone & Zone-less
+
+### 1. Standalone Components
+
+- **Ban**: `NgModule` (unless for legacy libs).
+- **Enforce**: `standalone: true` in all components, directives, and pipes.
+- **Why**: Tree-shaking, easier testing, simplified learning curve.
+
+### 2. Signals (State Management)
+
+- **Signals over Observables**: Use Signals for synchronous state. Use RxJS ONLY for complex asynchronous event streams (debounce, switchMap).
+- **Ban**: `Zone.js` (eventually). Prepare for zoneless by using `ChangeDetectionStrategy.OnPush` everywhere.
+
+```typescript
+// ✅ GOOD: Signal
+@Component({ ... changeDetection: ChangeDetectionStrategy.OnPush })
+export class Counter {
+  count = signal(0);
+  double = computed(() => this.count() * 2);
+
+  increment() {
+    this.count.update(c => c + 1);
+  }
+}
+```
+
+### 3. Control Flow Syntax
+
+- **Use**: `@if`, `@for`, `@switch`.
+- **Ban**: `*ngIf`, `*ngFor` (legacy structural directives).
+
+## ⚡ Performance Patterns
+
+### 1. Deferrable Views
+
+- Use `@defer` to lazy load components without routing.
+- Criteria: `@defer (on viewport)` for below-the-fold content.
+
+### 2. Hydration
+
+- Enable Client Hydration in `app.config.ts`.
+- Avoid direct DOM manipulation which breaks hydration.
+
+## 🧪 Testing
+
+- **Harnesses**: Use Component Harnesses for robust tests.
+- **Signals**: Test signals by verifying computed outputs.

package/.agent/skills/frontend-developer/references/composition_patterns.md

@@ -0,0 +1,60 @@
+# React Composition Patterns
+
+> Source: Vercel Engineering — composition-patterns skill
+
+Patterns for building flexible, maintainable React components at scale.
+
+## Core Principle
+**Composition over boolean proliferation.** If you're adding a boolean prop, stop — compose instead.
+
+## Architecture (HIGH Priority)
+
+### Avoid Boolean Props
+❌ `<Modal isFullscreen isDismissible hasOverlay />`
+✅ Compose: `<Modal.Fullscreen> <Modal.Dismissible> <Modal.Overlay>`
+
+### Compound Components
+Pattern: Share state via Context, expose sub-components.
+
+```jsx
+<Select>
+  <Select.Trigger />
+  <Select.Options>
+    <Select.Option value="a">Option A</Select.Option>
+  </Select.Options>
+</Select>
+```
+
+## State Management (MEDIUM)
+
+### Decouple Implementation
+Provider is the ONLY place that knows how state is managed:
+```jsx
+// Good: Context provides generic interface
+const CartContext = { items, addItem, removeItem, total }
+// Bad: Components import zustand/redux directly
+```
+
+### Context Interface Pattern
+Define generic interface with `state`, `actions`, `meta`:
+```jsx
+{ state: {}, actions: {}, meta: { isLoading, error } }
+```
+
+### Lift State
+Move state into Provider for sibling component access.
+
+## Implementation Patterns (MEDIUM)
+
+### Explicit Variants
+❌ `<Button isPrimary />` `<Button isDanger />`
+✅ `<PrimaryButton />` `<DangerButton />`
+
+### Children Over Render Props
+❌ `renderHeader={(...) => <Header />}`
+✅ `<Card><Card.Header>...</Card.Header></Card>`
+
+## React 19 (⚠️ React 19+ only)
+
+- Drop `forwardRef` — ref is now a regular prop
+- Use `use()` instead of `useContext()`

package/.agent/skills/frontend-developer/references/core-performance.md

@@ -0,0 +1,68 @@
+# Core Performance & Accessibility Standards
+
+**Status**: Mandaory
+**Applies To**: ALL Frameworks (React, Vue, Angular, Svelte, etc.)
+
+## 🚀 Performance: The "Zero-Overhead" Standard
+
+### 1. Core Web Vitals (The Holy Trinity)
+
+You must optimize for these metrics _before_ writing business logic.
+
+- **LCP (Largest Contentful Paint)**: < 2.5s
+  - **Strategy**: The LCP element (usually Hero Image or H1) must be in the initial HTML.
+  - **Ban**: Never lazy-load the LCP image. Never use client-side rendering for the LCP element.
+  - **Code**: `<img fetchpriority="high" decoding="sync" ... />`
+
+- **INP (Interaction to Next Paint)**: < 200ms
+  - **Strategy**: Break up long tasks.
+  - **Ban**: `useEffect` or watchers that run heavy computation on input. Yield to main thread (`scheduler.yield()` or `setTimeout(..., 0)`).
+
+- **CLS (Cumulative Layout Shift)**: < 0.1
+  - **Strategy**: Rigidly defined dimensions for all media and containers.
+  - **Ban**: Images without `width/height`. Ad containers without `min-height`.
+
+### 2. Bundle Analysis
+
+- **Budget**: Initial JS < 50KB (gzip).
+- **Tree-Shaking**: Import specific functions, not whole libraries.
+  - ✅ `import { map } from 'lodash-es'`
+  - ❌ `import _ from 'lodash'`
+- **Splitting**: Route-level splitting is mandatory. Component-level splitting for heavy interactions (modals, charts).
+
+### 3. Image Optimization
+
+- **Formats**: AVIF > WebP > JPG/PNG.
+- **Responsive**: Use `srcset` and `sizes`.
+- **Lazy**: `loading="lazy"` for everything below the fold.
+
+---
+
+## ♿ Accessibility: The "Keyboard First" Standard
+
+**Rule**: If you can't use it with `Tab` + `Enter`/`Space`, it is broken.
+
+### 1. Semantic HTML
+
+- **Buttons**: Use `<button>`, not `<div onClick>`.
+- **Links**: Use `<a>` with `href`, not `<button onClick="go()">`.
+- **Landmarks**: `<main>`, `<nav>`, `<aside>`, `<header>`, `<footer>`.
+
+### 2. Focus Management
+
+- **Visible Focus**: Never remove `outline` without replacing it with a custom high-contrast focus style.
+- **Trap Focus**: Modals must trap focus inside them.
+
+### 3. ARIA (Last Resort)
+
+- Use ARIA only when HTML is insufficient.
+- **No ARIA > Bad ARIA**.
+- **Images**: `alt=""` for decorative, descriptive text for informational.
+
+---
+
+## 🔒 Security Basics
+
+- **XSS**: Sanitize all `innerHTML`.
+- **Deps**: Audit `npm audit` regularly.
+- **HTTPS**: Enforce HSTS.

package/.agent/skills/frontend-developer/references/modern-signals.md

@@ -0,0 +1,43 @@
+# Modern Signals & Fine-Grained Reactivity
+
+**Stack**: Svelte 5 (Runes), SolidJS, Qwik
+
+## 🧠 The Philosophy: "No Virtual DOM"
+
+Unlike React/Vue, these frameworks target the DOM directly.
+
+- **Fine-Grained**: Only the text node that changes updates. No component re-renders.
+- **Mental Model**: Code runs _once_ (setup), then reactivity takes over.
+
+## 🧱 Framework specifics
+
+### Svelte 5 (Runes)
+
+- **State**: `let count = $state(0)`
+- **Derived**: `let double = $derived(count * 2)`
+- **Side Effects**: `$effect(() => ...)`
+- **Snippets**: Replace slots with `{#snippet}`.
+
+### SolidJS
+
+- **Read/Write Split**: `const [count, setCount] = createSignal(0)`
+- **DOM Access**: strictly in `onMount`.
+- **Control Flow**: Use `<Show>`, `<For>` (don't use map).
+
+### Qwik (Resumability)
+
+- **The Golden Rule**: Do not execute JS on the client unless checking an event.
+- **Serialized State**: All state must be serializable (JSON).
+- **$**: The optimizer barrier. `onClick$`, `useSignal$`.
+
+## ⚡ Performance Targets
+
+1.  **Hydration**:
+    - **Svelte/Solid**: Fast hydration.
+    - **Qwik**: No hydration (Resumability).
+2.  **Closures**: Avoid creating closures in render loops (except Qwik where `$` handles it).
+
+## 🧪 Testing
+
+- **E2E**: Playwright is the gold standard for all three.
+- **Unit**: Vitest.

package/.agent/skills/frontend-developer/references/react_performance_rules.md

@@ -0,0 +1,55 @@
+# React & Next.js Performance Rules
+
+> Source: Vercel Engineering — react-best-practices skill (65 rules, 8 categories)
+
+## Priority 1: Eliminating Waterfalls (CRITICAL)
+
+- **Move await late**: `async-defer-await` — Defer `await` until the branch that uses the result
+- **Parallel promises**: `async-parallel` — `Promise.all()` for independent async operations
+- **Partial deps**: `async-dependencies` — Use `better-all` when Promise B needs result of A but C doesn't
+- **API route promises**: `async-api-routes` — Start promises at function top, `await` at bottom
+- **Suspense streaming**: `async-suspense-boundaries` — Wrap slow components in `<Suspense>` to stream content
+
+## Priority 2: Bundle Size Optimization (CRITICAL)
+
+- **No barrel files**: `bundle-barrel-imports` — Import directly from source, never barrel `index.ts`
+- **Dynamic imports**: `bundle-dynamic-imports` — `next/dynamic` for heavy components (chart libs, editors)
+- **Defer third-party**: `bundle-defer-third-party` — Load analytics/logging AFTER hydration
+- **Conditional load**: `bundle-conditional` — Load modules only when feature flag is ON
+- **Preload on hover**: `bundle-preload` — Start loading route/chunk on hover/focus for perceived speed
+
+## Priority 3: Server-Side Performance (HIGH)
+
+- **Auth in actions**: `server-auth-actions` — ALWAYS authenticate server actions (they're public endpoints)
+- **React.cache()**: `server-cache-react` — Per-request deduplication for shared data
+- **LRU cache**: `server-cache-lru` — Cross-request caching for expensive computations
+- **Dedup props**: `server-dedup-props` — Don't pass same data to multiple Client Components
+- **Hoist I/O**: `server-hoist-static-io` — Module-level for fonts, logos, static assets
+- **Minimize serialization**: `server-serialization` — Only pass needed data to client components
+- **Parallel fetching**: `server-parallel-fetching` — Restructure components to parallelize
+- **after()**: `server-after-nonblocking` — Use `after()` for analytics, logging (non-blocking)
+
+## Priority 4: Client-Side Data Fetching (MEDIUM-HIGH)
+
+- **SWR dedup**: `client-swr-dedup` — Use SWR for automatic deduplication and caching
+- **Dedup listeners**: `client-event-listeners` — One global listener, not per-component
+- **Passive scroll**: `client-passive-event-listeners` — Always `{ passive: true }` for scroll
+- **localStorage**: `client-localstorage-schema` — Version and minimize stored data
+
+## Priority 5: Re-render Optimization (MEDIUM)
+
+Key rules:
+- **Defer reads**: Don't subscribe to state only used in callbacks
+- **Memoize**: Extract expensive children into `React.memo()` components
+- **Derived state**: Subscribe to derived booleans, not raw objects
+- **No inline components**: NEVER define components inside components
+- **Functional setState**: `setCount(prev => prev + 1)` for stable callbacks
+- **startTransition**: Use for non-urgent state updates
+
+## Priority 6-8: Rendering, JS, Advanced (MEDIUM-LOW)
+
+- **content-visibility**: `auto` for off-screen long lists
+- **Ternary over &&**: `{x ? <A/> : null}` not `{x && <A/>}`
+- **Set/Map lookups**: O(1) instead of array `.includes()`
+- **flatMap**: Replace `.filter().map()` with single `.flatMap()`
+- **requestIdleCallback**: Defer non-critical work to idle time

package/.agent/skills/frontend-developer/references/vue-nuxt.md

@@ -0,0 +1,55 @@
+# Vue & Nuxt 3 Architecture
+
+**Status**: Definitive Guide
+**Stack**: Vue 3 (Composition API), Nuxt 3
+
+## 🏗 Architecture: Composition & Modules
+
+### 1. Composition API Only
+
+- **Ban**: Options API (`data`, `methods`).
+- **Enforce**: `<script setup lang="ts">`.
+- **Why**: Better TypeScript support, logic reuse via composables.
+
+### 2. Nuxt Directory Structure
+
+```
+server/              # API routes (Nitro)
+components/          # Auto-imported components
+composables/         # Auto-imported logic
+pages/               # File-based routing
+layouts/             # Layouts
+stores/              # Pinia definitions
+```
+
+## ⚡ Performance Patterns
+
+### 1. Data Fetching
+
+- **SSR-Friendly**: Use `useFetch` or `useAsyncData`.
+- **Keying**: Always provide a unique key if parameters change.
+- **Lazy**: `lazy: true` to prevent blocking navigation.
+
+```ts
+// ✅ GOOD
+const { data, pending } = await useFetch("/api/posts", {
+  lazy: true,
+  server: false, // If client-only execution is needed
+});
+```
+
+### 2. State Management (Pinia)
+
+- **Setup Stores**: Use the function syntax (like `setup()`), not the object syntax.
+- **Dedupe**: Don't put everything in store. Use `useState` for simple shared state.
+
+### 3. Compute Stability
+
+- Use `computed()` for derived state.
+- Use `shallowRef()` for large objects that don't need deep reactivity.
+
+## 🧪 Testing
+
+- **Unit**: Vitest.
+- **Component**: Vue Test Utils.
+- **E2E**: Nuxt Test Utils (Playwright wrapper).

package/.agent/skills/frontend-developer/scripts/validate_compliance.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+import sys
+import re
+import os
+
+def check_file(filepath):
+    """
+    Simple heuristic checks for frontend compliance.
+    """
+    with open(filepath, 'r') as f:
+        content = f.read()
+
+    errors = []
+    
+    # Check 1: Image Accessibility
+    # Matches <img ...> without alt=
+    img_tags = re.findall(r'<img[^>]*>', content)
+    for tag in img_tags:
+        if 'alt=' not in tag:
+            errors.append(f"ACCESSIBILITY: Found <img> tag without 'alt' attribute: {tag}")
+
+    # Check 2: Next.js Image Optimization
+    if 'next/image' in content or '<Image' in content:
+        # Check for sizes prop if not fill
+        if '<Image' in content and 'sizes=' not in content and 'fill' not in content:
+             errors.append("PERFORMANCE: Found <Image> component (Next.js) without 'sizes' attribute. Use 'sizes' for responsive hydration.")
+
+    # Check 3: React Anti-Pattern (Effect Fetching)
+    if 'useEffect' in content and 'fetch(' in content:
+        errors.append("ARCHITECTURE: Found 'fetch' inside 'useEffect'. Use Server Components, React Query, or SWR instead.")
+
+    # Check 4: Angular Legacy
+    if '*ngIf' in content:
+         errors.append("MODERNIZATION: Found '*ngIf'. Use modern Angular control flow '@if'.")
+
+    return errors
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python validate_compliance.py <file_or_directory>")
+        sys.exit(1)
+
+    target = sys.argv[1]
+    all_errors = []
+
+    if os.path.isfile(target):
+        all_errors.extend(check_file(target))
+    elif os.path.isdir(target):
+        for root, _, files in os.walk(target):
+            for file in files:
+                if file.endswith(('.tsx', '.jsx', '.vue', '.ts', '.js')):
+                    path = os.path.join(root, file)
+                    all_errors.extend(check_file(path))
+
+    if all_errors:
+        print("❌ Compliance Errors Found:")
+        for err in all_errors:
+            print(f"- {err}")
+        sys.exit(1)
+    else:
+        print("✅ No obvious compliance errors found (Heuristic Check).")
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()