@djm204/agent-skills 1.0.0

package/templates/engineering/fullstack/.cursor/rules/api-contracts.mdc

@@ -0,0 +1,79 @@
+---
+description: API Contracts
+alwaysApply: false
+---
+
+# API Contracts
+
+Defining and maintaining contracts between frontend and backend.
+
+## Why Contracts Matter
+
+- **Type safety** — catch mismatches at compile time
+- **Single source of truth** — one schema drives both sides
+- **Parallel development** — frontend and backend work independently
+
+## Schema-Driven Development
+
+Define Zod schemas first, derive types:
+
+```ts
+import { z } from 'zod';
+export const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+});
+export const UserResponseSchema = z.object({
+  id: z.string(), email: z.string(), name: z.string(),
+  createdAt: z.string().datetime(),
+});
+export type CreateUserRequest = z.infer<typeof CreateUserSchema>;
+```
+
+### Backend — validate input
+
+```ts
+app.post('/users', async (req, res) => {
+  const parsed = CreateUserSchema.safeParse(req.body);
+  if (!parsed.success) return res.status(422).json({ error: parsed.error });
+  res.status(201).json({ data: await createUser(parsed.data) });
+});
+```
+
+### Frontend — validate before sending
+
+```ts
+async function createUser(data: CreateUserRequest) {
+  const res = await fetch('/api/users', {
+    method: 'POST', body: JSON.stringify(CreateUserSchema.parse(data)),
+    headers: { 'Content-Type': 'application/json' },
+  });
+  if (!res.ok) throw new ApiError(res);
+  return (await res.json()).data;
+}
+```
+
+## Type-Safe Clients
+
+Use **tRPC** for end-to-end type safety, or generate OpenAPI specs from Zod via `zod-to-openapi`.
+
+## Contract Testing
+
+```ts
+it('POST /users returns valid UserResponse', async () => {
+  const res = await request(app)
+    .post('/users').send({ email: 'test@example.com', name: 'Test' });
+  expect(res.status).toBe(201);
+  expect(UserResponseSchema.safeParse(res.body.data).success).toBe(true);
+});
+```
+
+## Versioning
+
+URL versioning (`/api/v1/users`) for breaking changes. Add new fields as optional for backwards compatibility.
+
+## Anti-Patterns
+
+- Defining request/response shapes independently on frontend and backend
+- Skipping server-side validation because the client validates
+- Evolving APIs without contract tests to catch breakage

package/templates/engineering/fullstack/.cursor/rules/architecture.mdc

@@ -0,0 +1,79 @@
+---
+description: Fullstack Architecture
+alwaysApply: false
+---
+
+# Fullstack Architecture
+
+Architectural patterns for full-stack applications.
+
+## Architectural Layers
+
+```
+Presentation → Application → Domain ← Infrastructure
+```
+
+- **Presentation**: Components, pages, state management, routing
+- **Application**: Route handlers, request validation, auth, response formatting
+- **Domain**: Business rules, models, use cases — pure functions, no external deps
+- **Infrastructure**: Database, external APIs, file storage, caching
+
+Dependencies point inward — domain has zero dependencies on outer layers.
+
+## Server vs Client Components
+
+```tsx
+// Server Component (default) — direct DB access, no interactivity
+export default async function UsersPage() {
+  const users = await db.user.findMany();
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+
+// Client Component — interactivity, hooks, browser APIs
+'use client';
+export function UserForm({ onSubmit }: Props) {
+  const [name, setName] = useState('');
+  return <form onSubmit={...}><input value={name} onChange={e => setName(e.target.value)} /></form>;
+}
+```
+
+**Composition**: Server component fetches data, passes to client component for interactivity.
+
+## Server Actions
+
+```tsx
+'use server';
+export async function createUser(formData: FormData) {
+  await db.user.create({ data: { name: formData.get('name') as string } });
+  revalidatePath('/users');
+}
+// Usage: <form action={createUser}>...</form>
+```
+
+## State Synchronization
+
+- **Optimistic updates**: `useOptimistic` to update UI before server confirms
+- **Cache invalidation**: `revalidatePath` / `revalidateTag` after mutations
+
+## Error Handling Across Stack
+
+```tsx
+// Server: structured errors with status codes
+if (!user) {
+  return NextResponse.json(
+    { error: { code: 'NOT_FOUND', message: 'User not found' } },
+    { status: 404 }
+  );
+}
+// Client: handle loading, error, and success states
+const { data, error, isLoading } = useQuery(['user', id], fetchUser);
+if (isLoading) return <Skeleton />;
+if (error) return <ErrorMessage error={error} />;
+return <UserCard user={data} />;
+```
+
+## Anti-Patterns
+
+- Putting business logic in route handlers instead of the domain layer
+- Using client components when server components suffice (unnecessary JS shipped)
+- Mutating server state without cache invalidation

package/templates/engineering/fullstack/.cursor/rules/overview.mdc

@@ -0,0 +1,61 @@
+---
+description: Fullstack Development
+alwaysApply: false
+---
+
+# Fullstack Development
+
+Guidelines for building cohesive full-stack web applications.
+
+## Scope
+
+- Monolithic full-stack apps and frameworks (Next.js, Nuxt, SvelteKit, Remix)
+- Separate frontend/backend codebases sharing types
+- JAMstack with serverless backends
+
+## Key Principles
+
+- **Unified Type System** — Share types between frontend and backend; catch errors at compile time
+- **Clear Boundaries** — Maintain separation between client and server concerns, even in unified frameworks
+- **API-First Thinking** — Design the API contract first, then implement both sides
+- **End-to-End Testing** — Test full user journeys, not just isolated components
+
+## Server vs Client Boundaries
+
+```ts
+// Server-only (never sent to client)
+import { PrismaClient } from '@prisma/client';
+export const db = new PrismaClient();
+
+// Client-only
+export const trackEvent = (event: string) => {
+  window.analytics?.track(event);
+};
+
+// Shared (works both sides) — validation schemas, types, constants
+export const UserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+});
+```
+
+## Data Flow
+
+```
+User Action → Component → API Request → Server Handler
+     ↓                                         ↓
+  UI Update ← State ← API Response ← Database
+```
+
+## Anti-Patterns
+
+- Duplicating validation logic instead of sharing schemas
+- Importing server-only code (DB clients, secrets) into client bundles
+- Skipping loading/error states on the frontend
+
+## Definition of Done
+
+- [ ] Types and validation shared between frontend and backend
+- [ ] Loading, error, and empty states handled
+- [ ] E2E tests cover critical paths
+- [ ] No TypeScript errors

package/templates/engineering/fullstack/.cursor/rules/shared-types.mdc

@@ -0,0 +1,77 @@
+---
+description: Shared Types
+alwaysApply: false
+---
+
+# Shared Types
+
+Strategies for sharing types between frontend and backend.
+
+## Why Share Types
+
+- **Single source of truth** — define once, use everywhere
+- **Compile-time safety** — catch mismatches before runtime
+- **Refactoring confidence** — changes propagate automatically
+
+## Shared Validation Schemas
+
+Derive types from Zod schemas so runtime validation and static types stay in sync:
+
+```ts
+import { z } from 'zod';
+export const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  role: z.enum(['user', 'admin']).default('user'),
+});
+export type CreateUserInput = z.infer<typeof CreateUserSchema>;
+```
+
+Both sides import the same schema:
+
+```ts
+// Backend
+const result = CreateUserSchema.safeParse(req.body);
+if (!result.success) return res.status(422).json({ error: result.error });
+// Frontend
+const form = useForm<CreateUserInput>({ resolver: zodResolver(CreateUserSchema) });
+```
+
+## API Response & Error Types
+
+```ts
+export interface ApiResponse<T> { data: T; }
+export interface PaginatedResponse<T> {
+  data: T[];
+  pagination: { page: number; limit: number; total: number };
+}
+export const ErrorCode = {
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  NOT_FOUND: 'NOT_FOUND',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+} as const;
+export type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
+export interface AppError { code: ErrorCode; message: string; details?: unknown; }
+```
+
+## Date Handling
+
+Dates serialize to strings in JSON — define internal and DTO types with transformers:
+
+```ts
+export interface User { id: string; name: string; createdAt: Date; }
+export interface UserDTO { id: string; name: string; createdAt: string; }
+export const toUserDTO = (u: User): UserDTO => ({ ...u, createdAt: u.createdAt.toISOString() });
+```
+
+## Best Practices
+
+- Keep the shared package minimal — no frontend or backend deps
+- Use `const` objects with `as const` for enum-like values
+- Export explicitly; enable `strict: true` in shared `tsconfig.json`
+
+## Anti-Patterns
+
+- Duplicating types across frontend and backend instead of sharing
+- Putting framework-specific code (React hooks, Express middleware) in shared
+- Using `any` to bridge type mismatches between client and server

package/templates/engineering/fullstack/.cursor/rules/testing.mdc

@@ -0,0 +1,72 @@
+---
+description: Fullstack Testing
+alwaysApply: false
+---
+
+# Fullstack Testing
+
+Testing strategies for full-stack applications.
+
+## Testing Pyramid
+
+- **E2E** — critical user journeys (fewest, slowest)
+- **Integration** — API + DB, components + API via MSW
+- **Unit** — pure functions, isolated logic (most, fastest)
+
+## E2E Tests
+
+```ts
+test('user can sign up', async ({ page }) => {
+  await page.goto('/signup');
+  await page.fill('[name="email"]', 'test@example.com');
+  await page.fill('[name="password"]', 'SecurePass123!');
+  await page.click('button[type="submit"]');
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+Seed state via the API, not the UI — keeps E2E tests fast.
+
+## Integration Tests
+
+```ts
+it('creates user and returns in list', async () => {
+  await request(app).post('/api/users')
+    .send({ email: 'new@example.com', name: 'New' }).expect(201);
+  const list = await request(app).get('/api/users');
+  expect(list.body.data).toContainEqual(
+    expect.objectContaining({ email: 'new@example.com' })
+  );
+});
+```
+
+### Component + API (MSW)
+
+Mock API responses with MSW's `setupServer` — call `server.listen()` in `beforeAll`, `server.close()` in `afterAll`. Assert rendered output after data loads with `waitFor`.
+
+## Contract Tests
+
+Validate responses against shared Zod schemas:
+
+```ts
+it('GET /users returns valid responses', async () => {
+  const res = await request(app).get('/api/users');
+  for (const user of res.body.data)
+    expect(UserResponseSchema.safeParse(user).success).toBe(true);
+});
+```
+
+## Test Data
+
+```ts
+import { faker } from '@faker-js/faker';
+export const userInput = (overrides?) => ({
+  email: faker.internet.email(), name: faker.person.fullName(), ...overrides,
+});
+```
+
+## Best Practices
+
+- Test at the right level — don't E2E-test what a unit test covers
+- Always test error scenarios (API failures, validation, empty states)
+- Isolate tests — clean DB state between integration tests

package/templates/engineering/fullstack/CLAUDE.md

@@ -0,0 +1,349 @@
+# Fullstack Development Guide
+
+Comprehensive guidelines for building cohesive full-stack web applications.
+
+---
+
+## Overview
+
+This guide applies to:
+- Monolithic full-stack applications
+- Full-stack frameworks (Next.js, Nuxt, SvelteKit, Remix)
+- Separate frontend/backend codebases sharing types
+- JAMstack with serverless backends
+
+### Key Principles
+
+1. **Unified Type System** - Share types between frontend and backend
+2. **Clear Boundaries** - Maintain separation between client and server
+3. **API-First Thinking** - Design the contract first
+4. **End-to-End Testing** - Test the full user journey
+
+### Project Structure
+
+**Monorepo:**
+```
+packages/
+├── shared/           # Shared types, validation, utilities
+├── web/              # Frontend application
+├── api/              # Backend API
+└── e2e/              # End-to-end tests
+```
+
+**Full-Stack Framework:**
+```
+src/
+├── app/              # Pages and routing
+├── components/       # React components
+├── lib/
+│   ├── client/       # Client-only code
+│   ├── server/       # Server-only code
+│   └── shared/       # Isomorphic code
+└── types/            # TypeScript definitions
+```
+
+---
+
+## Architecture
+
+### Architectural Layers
+
+```
+Presentation → Application → Domain ← Infrastructure
+```
+
+- **Presentation**: Components, pages, UI
+- **Application**: Route handlers, request validation
+- **Domain**: Business rules, pure functions
+- **Infrastructure**: Database, external APIs
+
+### Server vs Client Components
+
+**Server Components** (default):
+```tsx
+// Direct database access, no interactivity
+export default async function UsersPage() {
+  const users = await db.user.findMany();
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+**Client Components**:
+```tsx
+'use client';
+// Interactivity, hooks, browser APIs
+export function UserForm({ onSubmit }) {
+  const [name, setName] = useState('');
+  return <form onSubmit={...}>...</form>;
+}
+```
+
+### Data Flow
+
+```
+User Action → Component → API Request → Server Handler
+     ↓                                         ↓
+  UI Update ← State ← API Response ← Database
+```
+
+---
+
+## API Contracts
+
+### Schema-Driven Development
+
+```ts
+// shared/schemas/user.ts
+import { z } from 'zod';
+
+export const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+});
+
+export const UserResponseSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string(),
+  createdAt: z.string().datetime(),
+});
+
+export type CreateUserRequest = z.infer<typeof CreateUserSchema>;
+export type UserResponse = z.infer<typeof UserResponseSchema>;
+```
+
+### Use on Backend
+
+```ts
+app.post('/users', async (req, res) => {
+  const result = CreateUserSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(422).json({ error: result.error });
+  }
+  const user = await createUser(result.data);
+  res.status(201).json({ data: user });
+});
+```
+
+### Use on Frontend
+
+```ts
+export const usersApi = {
+  async create(data: CreateUserRequest): Promise<UserResponse> {
+    const validated = CreateUserSchema.parse(data);
+    const response = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify(validated),
+    });
+    return (await response.json()).data;
+  },
+};
+```
+
+---
+
+## Shared Types
+
+### Monorepo Setup
+
+```ts
+// packages/shared/src/types/user.ts
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: Date;
+}
+
+export type CreateUserInput = Omit<User, 'id' | 'createdAt'>;
+```
+
+### Using Shared Types
+
+```ts
+// In API
+import { User, CreateUserInput } from '@myapp/shared';
+
+// In Web
+import { User, CreateUserInput } from '@myapp/shared';
+```
+
+### Validation Schemas
+
+```ts
+// shared/validation/user.ts
+export const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+});
+
+export type CreateUserInput = z.infer<typeof CreateUserSchema>;
+```
+
+### Error Types
+
+```ts
+export const ErrorCode = {
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  NOT_FOUND: 'NOT_FOUND',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+} as const;
+
+export type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
+```
+
+---
+
+## State Synchronization
+
+### Optimistic Updates
+
+```tsx
+'use client';
+import { useOptimistic } from 'react';
+
+export function TodoList({ todos, addTodo }) {
+  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
+    todos,
+    (state, newTodo) => [...state, newTodo]
+  );
+
+  async function handleAdd(formData) {
+    addOptimisticTodo({ id: 'temp', title: formData.get('title') });
+    await addTodo(formData);
+  }
+}
+```
+
+### Cache Invalidation
+
+```ts
+import { revalidatePath, revalidateTag } from 'next/cache';
+
+export async function updateUser(id: string, data) {
+  await db.user.update({ where: { id }, data });
+  revalidatePath(`/users/${id}`);
+}
+```
+
+---
+
+## Testing
+
+### Testing Pyramid
+
+1. **E2E Tests**: Critical user flows
+2. **Integration Tests**: API + DB, components + API
+3. **Unit Tests**: Pure functions, isolated logic
+
+### E2E Tests
+
+```ts
+test('user can sign up and access dashboard', async ({ page }) => {
+  await page.goto('/signup');
+  await page.fill('[name="email"]', 'test@example.com');
+  await page.fill('[name="password"]', 'SecurePass123!');
+  await page.click('button[type="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.locator('text=Welcome')).toBeVisible();
+});
+```
+
+### Integration Tests
+
+```ts
+describe('User Management', () => {
+  it('creates user and returns in list', async () => {
+    const createRes = await request(app)
+      .post('/api/users')
+      .send({ email: 'new@example.com', name: 'New User' });
+
+    expect(createRes.status).toBe(201);
+
+    const listRes = await request(app).get('/api/users');
+    expect(listRes.body.data).toContainEqual(
+      expect.objectContaining({ email: 'new@example.com' })
+    );
+  });
+});
+```
+
+### Contract Tests
+
+```ts
+describe('User API Contract', () => {
+  it('returns valid UserResponse', async () => {
+    const response = await request(app).get('/api/users');
+
+    for (const user of response.body.data) {
+      const result = UserResponseSchema.safeParse(user);
+      expect(result.success).toBe(true);
+    }
+  });
+});
+```
+
+### Test Data Factories
+
+```ts
+import { faker } from '@faker-js/faker';
+
+export const createUserInput = (overrides?) => ({
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  ...overrides,
+});
+```
+
+---
+
+## Error Handling
+
+### Server-Side
+
+```ts
+export async function GET(request, { params }) {
+  const user = await db.user.findUnique({ where: { id: params.id } });
+
+  if (!user) {
+    return NextResponse.json(
+      { error: { code: 'NOT_FOUND', message: 'User not found' } },
+      { status: 404 }
+    );
+  }
+
+  return NextResponse.json({ data: user });
+}
+```
+
+### Client-Side
+
+```tsx
+export function UserProfile({ userId }) {
+  const { data, error, isLoading } = useQuery(['user', userId], () =>
+    fetch(`/api/users/${userId}`).then(res => res.json())
+  );
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+  return <UserCard user={data.data} />;
+}
+```
+
+---
+
+## Definition of Done
+
+A fullstack feature is complete when:
+
+- [ ] Types shared between frontend and backend
+- [ ] API contract documented
+- [ ] Frontend renders correctly
+- [ ] Backend handles all edge cases
+- [ ] Validation consistent on both sides
+- [ ] Loading and error states handled
+- [ ] E2E tests cover critical paths
+- [ ] No TypeScript errors
+- [ ] Performance acceptable
+- [ ] Code reviewed and approved