@levironexe/architect 0.1.0

package/skills/stacks/nestjs.skill.yaml

@@ -0,0 +1,135 @@
+schema_version: "2.0.0"
+id: nestjs
+name: "NestJS"
+version: "1.1.0"
+description: "Enterprise-grade NestJS with module-per-feature structure, dependency injection, guards, and pipes."
+category: stack
+language: javascript
+frameworks:
+  - nestjs
+detection:
+  dependencies:
+    any:
+      - "@nestjs/core"
+    none:
+      - express
+      - fastify
+      - hono
+  source_indicators:
+    - "@Module("
+    - "@Controller("
+    - "@Injectable("
+    - "@nestjs/common"
+structure:
+  required_dirs:
+    - path: src/modules
+      purpose: "Feature modules — one directory per domain (users/, orders/, etc.) containing controller, service, and module file."
+    - path: src/common
+      purpose: "Cross-cutting NestJS primitives shared across all feature modules: guards (auth, roles), pipes (validation, transformation), interceptors (logging, caching), decorators, and exception filters. Nothing business-domain specific lives here."
+    - path: src/config
+      purpose: "Configuration module and environment validation."
+  recommended_dirs:
+    - path: src/database
+      purpose: "Database module, entity definitions, and repository setup. TypeORM entities, Prisma schema, or Drizzle table definitions live here — not in feature modules. Feature modules import the database module via DI."
+    - path: src/shared
+      purpose: "Shared DTOs, TypeScript interfaces, and pure utility functions used across feature modules. Unlike src/common (NestJS primitives), src/shared contains plain TypeScript — no NestJS decorators."
+separation:
+  rules:
+    - concern: module_structure
+      belongs_in: src/modules
+      rule_text: "Each feature module contains its own controller, service, and module file co-located in one directory. Do NOT put all controllers in one folder and all services in another — group by feature, not by type."
+      example: |
+        // src/modules/users/users.module.ts
+        @Module({ controllers: [UsersController], providers: [UsersService] })
+        export class UsersModule {}
+
+        // src/modules/users/users.controller.ts
+        @Controller('users')
+        export class UsersController {
+          constructor(private readonly usersService: UsersService) {}
+        }
+      indicators:
+        - "@Module("
+        - "src/modules"
+    - concern: dependency_injection
+      belongs_in: src/modules
+      rule_text: "Inject all dependencies via constructor — never instantiate services or repositories with `new`. This enables testing and module substitution."
+      example: |
+        // ✓ Injected via constructor
+        @Controller('users')
+        export class UsersController {
+          constructor(private readonly usersService: UsersService) {}
+          @Get() findAll() { return this.usersService.findAll(); }
+        }
+      anti_indicators:
+        - "new UsersService"
+        - "new Repository"
+    - concern: guards_and_pipes
+      belongs_in: src/common
+      rule_text: "Auth guards, validation pipes, and response interceptors live in src/common. Apply them globally via APP_GUARD/APP_PIPE in AppModule, or per-controller/route with decorators."
+      example: |
+        // src/common/guards/jwt-auth.guard.ts
+        @Injectable()
+        export class JwtAuthGuard extends AuthGuard('jwt') {}
+
+        // Apply globally in app.module.ts
+        providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }]
+      indicators:
+        - "@UseGuards"
+        - "@UsePipes"
+        - "APP_GUARD"
+        - "APP_PIPE"
+patterns:
+  data_flow:
+    direction: "Controller → Service → Repository/ORM"
+    rules:
+      - "Controllers receive HTTP input and delegate to services."
+      - "Services contain business logic and call repositories."
+      - "Repositories handle all database interactions."
+  error_handling:
+    recommended: "Use NestJS exception filters and built-in HttpException classes."
+  naming:
+    modules: "[resource].module.ts"
+    controllers: "[resource].controller.ts"
+    services: "[resource].service.ts"
+anti_patterns:
+  - id: direct_instantiation
+    severity: critical
+    description: "Creating service or repository instances manually with `new` instead of using NestJS dependency injection — untestable and bypasses the DI container."
+    bad_example: |
+      // ❌ Bypasses DI — untestable and breaks module scoping
+      @Controller('users')
+      export class UsersController {
+        private service = new UsersService();
+      }
+    good_example: |
+      // ✓ Injected via constructor — testable and scoped correctly
+      constructor(private readonly usersService: UsersService) {}
+  - id: flat_file_structure
+    severity: warning
+    description: "Organizing all controllers in one folder and all services in another instead of grouping by feature module."
+    bad_example: |
+      // ❌ Flat structure — breaks NestJS module boundaries
+      src/controllers/users.controller.ts
+      src/services/users.service.ts
+    good_example: |
+      // ✓ Feature module structure
+      src/modules/users/users.controller.ts
+      src/modules/users/users.service.ts
+      src/modules/users/users.module.ts
+  - id: business_logic_in_controller
+    severity: critical
+    description: "Placing business rules, validation logic, or DB queries directly in controllers instead of services."
+    bad_example: |
+      @Post()
+      async create(@Body() dto: CreateUserDto) {
+        const existing = await this.db.findOne({ email: dto.email });
+        if (existing) throw new ConflictException();
+        dto.password = await bcrypt.hash(dto.password, 10);
+        return this.db.save(dto);
+      }
+    good_example: |
+      @Post()
+      create(@Body() dto: CreateUserDto) {
+        return this.usersService.create(dto);
+      }

package/skills/stacks/nextjs-app-router.skill.yaml

@@ -0,0 +1,176 @@
+schema_version: "2.0.0"
+id: nextjs-app-router
+name: "Next.js App Router"
+version: "1.1.0"
+description: "Next.js App Router structure with app routes, layouts, server components, server actions, shared UI, and data-access helpers properly separated."
+category: stack
+language: javascript
+frameworks:
+  - next
+  - react
+detection:
+  dependencies:
+    any:
+      - next
+  files:
+    - next.config.js
+    - next.config.mjs
+    - next.config.ts
+    - app
+  source_indicators:
+    - "next/"
+    - "\"use client\""
+    - "'use client'"
+structure:
+  required_dirs:
+    - path: app
+      purpose: "App Router entry point. Contains only Next.js file-convention files: layout.tsx, page.tsx, loading.tsx, error.tsx, route.ts. No business logic or reusable components live here."
+    - path: components
+      purpose: "Reusable React components shared across multiple routes. Components here must not import from app/ — they receive data as props or use shared hooks."
+    - path: lib
+      purpose: "Server-side data access, third-party SDK wrappers, and shared utilities. All database queries and external API calls live here so they can be reused by server components, actions, and route handlers."
+  recommended_dirs:
+    - path: actions
+      purpose: "Server Actions for form mutations and data mutations. Each file begins with 'use server'. Actions call lib/ functions — they do not access the database directly."
+    - path: hooks
+      purpose: "Client-only React hooks that encapsulate stateful browser behaviour (useLocalStorage, useDebounce). Must not import server-only modules."
+separation:
+  rules:
+    - concern: routing
+      belongs_in: app
+      rule_text: "The app directory owns route structure using App Router file conventions (layout.tsx, page.tsx, loading.tsx, error.tsx, route.ts). Pages are thin: they call lib/ functions and pass data to components. No inline SQL, fetch wrappers, or reusable UI definitions inside page.tsx files."
+      example: |
+        // app/users/page.tsx — correct: thin page, delegates to lib and components
+        import { listUsers } from '@/lib/users';
+        import { UsersTable } from '@/components/users-table';
+
+        export default async function UsersPage() {
+          const users = await listUsers();
+          return <UsersTable users={users} />;
+        }
+      indicators:
+        - "app/"
+        - "layout.tsx"
+        - "page.tsx"
+        - "route.ts"
+    - concern: shared_ui
+      belongs_in: components
+      rule_text: "Reusable React components belong in components/ so route files stay focused on composition and data loading. A component should receive data as props and not perform its own data fetching unless it is an explicitly-marked client component using SWR/React Query."
+      example: |
+        // components/users-table.tsx — server-safe, pure presentational
+        import type { User } from '@/lib/users';
+
+        export function UsersTable({ users }: { users: User[] }) {
+          return (
+            <table>
+              <tbody>
+                {users.map((user) => (
+                  <tr key={user.id}><td>{user.name}</td></tr>
+                ))}
+              </tbody>
+            </table>
+          );
+        }
+      anti_indicators:
+        - "prisma"
+        - "sql`"
+        - "drizzle"
+    - concern: server_action
+      belongs_in: actions
+      rule_text: "Server Actions for mutations and form handling live in actions/ with an explicit 'use server' directive at the top of the file. Actions validate input, call lib/ functions, and revalidate cache — they do not contain SQL or SDK calls directly."
+      example: |
+        // actions/user-actions.ts
+        'use server';
+
+        import { revalidatePath } from 'next/cache';
+        import { createUser } from '@/lib/users';
+        import { z } from 'zod';
+
+        const schema = z.object({ name: z.string().min(1) });
+
+        export async function createUserAction(formData: FormData) {
+          const { name } = schema.parse({ name: formData.get('name') });
+          await createUser({ name });
+          revalidatePath('/users');
+        }
+      indicators:
+        - "\"use server\""
+        - "'use server'"
+patterns:
+  data_flow:
+    direction: "app/page.tsx -> lib/ -> database/external API; actions/ -> lib/ -> database"
+    rules:
+      - "Use React Server Components by default. Only add 'use client' when the component needs browser APIs, event handlers, or client-side state."
+      - "Push 'use client' as far down the component tree as possible to maximize server-rendered surface."
+      - "Use loading.tsx and error.tsx file conventions for every route segment that performs async data fetching."
+      - "Never access process.env directly in components or lib/ — import from a centralized config module."
+  naming:
+    routes: "Use App Router file conventions: page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx, route.ts. Use (group) folders for layout sharing without URL impact. Use _folder prefix for private non-routable helpers colocated with routes."
+    components: "Use PascalCase for component files (UsersTable.tsx) and function names. Use kebab-case for utility and hook files (use-debounce.ts)."
+anti_patterns:
+  - id: use_client_everywhere
+    severity: warning
+    description: "The 'use client' directive is placed at the top of layout, page, or large wrapper components rather than pushed down to only the leaf components that actually need browser interactivity. This unnecessarily turns large component subtrees into client bundles, increasing JavaScript shipped to the browser."
+    bad_example: |
+      // app/dashboard/layout.tsx — wrong: entire layout becomes a client bundle
+      'use client';
+
+      export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+        return <div className="dashboard">{children}</div>;
+      }
+    good_example: |
+      // app/dashboard/layout.tsx — server component, no directive needed
+      export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+        return <div className="dashboard">{children}</div>;
+      }
+
+      // components/dashboard-nav.tsx — only the interactive nav is a client component
+      'use client';
+      import { useState } from 'react';
+      export function DashboardNav() { /* toggle state, event handlers */ }
+  - id: client_data_fetching_by_default
+    severity: warning
+    description: "Data fetching is moved to client components using useEffect/useState without a user interaction requirement. This delays the first meaningful paint, exposes API endpoints unnecessarily, and forfeits React Server Component streaming and caching benefits."
+    bad_example: |
+      'use client';
+
+      export default function UsersPage() {
+        const [users, setUsers] = useState([]);
+        useEffect(() => {
+          fetch('/api/users').then((r) => r.json()).then(setUsers);
+        }, []);
+        return <UsersTable users={users} />;
+      }
+    good_example: |
+      // Server component — data fetches on the server before any HTML is sent
+      import { listUsers } from '@/lib/users';
+      import { UsersTable } from '@/components/users-table';
+
+      export default async function UsersPage() {
+        const users = await listUsers();
+        return <UsersTable users={users} />;
+      }
+  - id: direct_db_in_page
+    severity: critical
+    description: "Database queries or external API calls are made directly inside page.tsx or layout.tsx files instead of being encapsulated in lib/. This scatters data-access logic across the route tree, makes it impossible to reuse queries in Server Actions or Route Handlers, and prevents centralized error handling and logging."
+    bad_example: |
+      // app/users/page.tsx — wrong: database logic inside the page
+      import { prisma } from '@/lib/prisma';
+
+      export default async function UsersPage() {
+        const users = await prisma.user.findMany({ where: { active: true } });
+        return <UserList users={users} />;
+      }
+    good_example: |
+      // lib/users.ts — all user queries live here
+      import { prisma } from './prisma';
+      export async function listActiveUsers() {
+        return prisma.user.findMany({ where: { active: true } });
+      }
+
+      // app/users/page.tsx — page calls lib, never touches prisma directly
+      import { listActiveUsers } from '@/lib/users';
+      export default async function UsersPage() {
+        const users = await listActiveUsers();
+        return <UserList users={users} />;
+      }

package/skills/stacks/react-spa.skill.yaml

@@ -0,0 +1,153 @@
+schema_version: "2.0.0"
+id: react-spa
+name: "React Single Page Application"
+version: "1.1.0"
+description: "React SPA structure with UI components, hooks, pages, services, and utilities separated. Enforces one-way data flow and keeps network logic out of render cycles."
+category: stack
+language: javascript
+frameworks:
+  - react
+detection:
+  dependencies:
+    any:
+      - react
+    none:
+      - next
+  source_indicators:
+    - "from 'react'"
+    - "from \"react\""
+    - "useState("
+    - "useEffect("
+structure:
+  required_dirs:
+    - path: src/components
+      purpose: "Reusable presentational React components shared across multiple pages. Components here receive all data via props and must not call services or perform fetch requests directly."
+    - path: src/hooks
+      purpose: "Custom React hooks that encapsulate stateful behaviour, data fetching, and side effects. Hooks here are reused by multiple pages or components — one-off hooks live colocated with their component."
+    - path: src/services
+      purpose: "Functions that perform HTTP calls and interact with external APIs. Every network request in the app originates here, making it the single place to add auth headers, error normalization, and request retries."
+  recommended_dirs:
+    - path: src/pages
+      purpose: "Top-level route components that correspond to URL paths. Pages orchestrate data loading via hooks and pass results down to components — they are not reused across routes."
+    - path: src/utils
+      purpose: "Pure helper functions with no React dependency (date formatting, string manipulation, array transforms). Functions here must be synchronous and have no side effects."
+separation:
+  rules:
+    - concern: ui_component
+      belongs_in: src/components
+      rule_text: "Components render UI from props and delegated hooks instead of embedding network or business logic. A component that calls fetch() or a service directly cannot be rendered in isolation during testing."
+      example: |
+        // src/components/user-card.tsx — receives data, never fetches it
+        import type { User } from '@/types';
+
+        export function UserCard({ user }: { user: User }) {
+          return (
+            <article>
+              <h2>{user.name}</h2>
+              <p>{user.email}</p>
+            </article>
+          );
+        }
+      indicators:
+        - "return <"
+        - "React.FC"
+    - concern: state_logic
+      belongs_in: src/hooks
+      rule_text: "Reusable stateful behaviour belongs in hooks so pages and components stay declarative. A hook name must start with 'use'. If the same useState/useEffect block appears in two components, extract it into a shared hook."
+      example: |
+        // src/hooks/use-users.ts — all user-list state in one place
+        import { useState, useEffect } from 'react';
+        import { listUsers } from '@/services/users';
+        import type { User } from '@/types';
+
+        export function useUsers() {
+          const [users, setUsers] = useState<User[]>([]);
+          const [loading, setLoading] = useState(true);
+
+          useEffect(() => {
+            void listUsers().then((data) => {
+              setUsers(data);
+              setLoading(false);
+            });
+          }, []);
+
+          return { users, loading };
+        }
+      indicators:
+        - "useState"
+        - "useEffect"
+    - concern: api_access
+      belongs_in: src/services
+      rule_text: "HTTP calls and third-party integrations belong in services that hooks and components consume. Services are plain async functions — they do not call useState or useEffect. This makes them independently testable with mocked fetch."
+      example: |
+        // src/services/users.ts — network logic isolated from React
+        import type { User } from '@/types';
+
+        export async function listUsers(): Promise<User[]> {
+          const response = await fetch('/api/users', {
+            headers: { Authorization: `Bearer ${getToken()}` },
+          });
+          if (!response.ok) throw new Error(`HTTP ${response.status}`);
+          return response.json() as Promise<User[]>;
+        }
+      indicators:
+        - "fetch("
+        - "axios."
+patterns:
+  data_flow:
+    direction: "src/pages -> src/hooks -> src/services -> external API"
+    rules:
+      - "Components do not perform inline API calls during render. All data fetching happens in hooks."
+      - "Shared behaviour moves into custom hooks. If the same useState/useEffect pair appears in two components, it must be extracted."
+      - "Lift state to the lowest common ancestor that needs it. Do not put local UI state (modal open, form field value) into global state management."
+      - "Derive values from state — do not create a second useState to hold a value that is computable from existing state."
+  naming:
+    components: "Use PascalCase for component files and function names (UserCard.tsx, ProductList.tsx). Use kebab-case for non-component utility and hook files (use-users.ts, format-date.ts)."
+    hooks: "All hook function names must start with 'use' (useUsers, useAuth). The file name matches the hook name in kebab-case (use-users.ts)."
+anti_patterns:
+  - id: business_logic_in_components
+    severity: warning
+    description: "Business logic (validation, data transformation, API calls) is embedded directly in UI components. This makes the component impossible to render in isolation during testing and ties UI to network behaviour."
+    bad_example: |
+      export function SignupForm() {
+        const handleSubmit = async (event: React.FormEvent) => {
+          event.preventDefault();
+          const payload = validateSignup(new FormData(event.currentTarget));
+          await fetch('/api/signup', { method: 'POST', body: JSON.stringify(payload) });
+        };
+        return <form onSubmit={handleSubmit}>...</form>;
+      }
+    good_example: |
+      // Component delegates to a hook; hook delegates to a service
+      export function SignupForm() {
+        const { submit, error } = useSignupForm();
+        return <form onSubmit={submit}>{error && <p>{error}</p>}</form>;
+      }
+  - id: inline_api_calls_in_render
+    severity: critical
+    description: "API calls occur directly during render (outside of useEffect or an async event handler). Each re-render triggers another network request, leading to request storms and race conditions."
+    bad_example: |
+      export function UsersPage() {
+        // called on every render — network storm
+        fetch('/api/users').then(() => undefined);
+        return <div>Loading...</div>;
+      }
+    good_example: |
+      export function UsersPage() {
+        const { users, loading } = useUsers();
+        if (loading) return <div>Loading...</div>;
+        return <UsersList users={users} />;
+      }
+  - id: array_index_as_key
+    severity: warning
+    description: "Using the array index as the React 'key' prop on list items causes silent reconciliation bugs when the list is reordered, filtered, or items are inserted or deleted. React uses the key to match elements between renders — an index-based key can swap component state to the wrong item."
+    bad_example: |
+      // key={index} breaks when items are reordered or deleted
+      {users.map((user, index) => (
+        <UserCard key={index} user={user} />
+      ))}
+    good_example: |
+      // Stable unique id from the data model — safe for any list mutation
+      {users.map((user) => (
+        <UserCard key={user.id} user={user} />
+      ))}

package/skills/stacks/vue-nuxt.skill.yaml

@@ -0,0 +1,115 @@
+schema_version: "2.0.0"
+id: vue-nuxt
+name: "Nuxt 3"
+version: "1.1.0"
+description: "Full-stack Nuxt 3 with auto-imports, composables, Nitro server routes, and Pinia state management."
+category: stack
+language: javascript
+frameworks:
+  - nuxt
+  - vue
+detection:
+  dependencies:
+    any:
+      - nuxt
+    none:
+      - next
+  source_indicators:
+    - "defineNuxtConfig"
+    - "nuxt.config"
+    - "useNuxtApp"
+structure:
+  required_dirs:
+    - path: pages
+      purpose: "File-based route components — each .vue file maps directly to a URL path. Pages are thin: they call composables for data and delegate rendering to components. No business logic or direct API calls in page components."
+    - path: components
+      purpose: "Reusable Vue components auto-imported by Nuxt — no import statement needed. Components receive data via props and emit events; they must not call useFetch or useAsyncData directly."
+    - path: composables
+      purpose: "Reusable stateful logic using Vue Composition API — auto-imported. Composables own local or feature-scoped reactive state. For state that must survive navigation or be shared between distant components, use a Pinia store instead."
+    - path: server/api
+      purpose: "Server-side Nitro API route handlers auto-discovered by filename ([resource].[method].ts). Handlers call server/utils/ functions — they must not embed business logic or SQL directly."
+  recommended_dirs:
+    - path: server/middleware
+      purpose: "Nitro server-side middleware that runs on every request: auth token validation, rate limiting, CORS headers. Executes before server/api/ route handlers."
+    - path: stores
+      purpose: "Pinia stores for global state that must persist across route navigations or be shared between unrelated components (auth session, shopping cart, notifications). Local UI state that belongs to one component or page stays as composable state — not in a store."
+    - path: utils
+      purpose: "Auto-imported pure utility functions with no Vue or Nuxt dependency (formatDate, slugify, truncate). Must be synchronous and side-effect-free."
+    - path: server/utils
+      purpose: "Server-side utility functions and service layer shared across server/api/ route handlers. Database queries, third-party API wrappers, and business logic live here — never inline in event handlers."
+separation:
+  rules:
+    - concern: data_fetching
+      belongs_in: composables
+      rule_text: "Use useFetch() or useAsyncData() inside composables, not directly in page components. This enables reuse, keeps pages declarative, and supports SSR hydration without duplication."
+      example: |
+        // composables/useUsers.ts
+        export function useUsers() {
+          return useFetch('/api/users');
+        }
+        // pages/users.vue
+        const { data: users } = useUsers();
+      indicators:
+        - "useFetch"
+        - "useAsyncData"
+    - concern: server_routes
+      belongs_in: server/api
+      rule_text: "Server routes in server/api/ use defineEventHandler(). They call services or utilities for business logic — no DB queries directly in event handlers."
+      example: |
+        // server/api/users.get.ts
+        export default defineEventHandler(async (event) => {
+          return getUsersService();
+        });
+    - concern: auto_imports
+      belongs_in: components
+      rule_text: "Nuxt auto-imports components, composables, and utils. Do NOT add explicit import statements for these — let Nuxt's auto-import system handle it."
+      example: |
+        // ✓ Just use it — Nuxt handles the import
+        const { data } = useUsers();
+      anti_indicators:
+        - "import { use"
+        - "from '~/composables"
+        - "from '~/components"
+patterns:
+  data_flow:
+    direction: "Page → Composable → useFetch/useAsyncData → Server Route → Service"
+    rules:
+      - "Pages use composables for data fetching — not useFetch directly."
+      - "Server API routes handle business logic via server utilities."
+      - "Pinia stores manage global client-side state."
+  error_handling:
+    recommended: "Use createError() in server routes and useError() in pages for unified error handling."
+  naming:
+    composables: "use[Resource].ts"
+    stores: "[resource].store.ts"
+    server_routes: "[resource].[method].ts"
+anti_patterns:
+  - id: explicit_auto_imports
+    severity: warning
+    description: "Writing explicit import statements for components, composables, or utils that Nuxt auto-imports adds noise and can cause confusion."
+    bad_example: |
+      // ❌ Nuxt auto-imports this — explicit import is redundant
+      import { useUsers } from '~/composables/useUsers';
+    good_example: |
+      // ✓ Just use it — Nuxt handles the import automatically
+      const { data } = useUsers();
+  - id: db_in_page_component
+    severity: critical
+    description: "Querying databases directly in page or layout components instead of going through server routes."
+    bad_example: |
+      // ❌ DB access in a page component — only works server-side, breaks hydration
+      const users = await prisma.user.findMany();
+    good_example: |
+      // ✓ Page → composable → server route → service
+      const { data: users } = useUsers();
+  - id: fetch_in_component
+    severity: warning
+    description: "Using useFetch() or useAsyncData() directly in page components instead of wrapping them in composables — prevents reuse and makes pages harder to test."
+    bad_example: |
+      // pages/users.vue — useFetch directly in page
+      const { data: users } = useFetch('/api/users');
+    good_example: |
+      // composables/useUsers.ts
+      export function useUsers() { return useFetch('/api/users'); }
+      // pages/users.vue
+      const { data: users } = useUsers();