agentic-loop 1.0.0

package/templates/examples/CLAUDE-node.md

@@ -0,0 +1,246 @@
+# Project Instructions for AI Coding Agents
+
+## Naming Conventions
+- **Files**: `kebab-case.ts` — e.g., `user-service.ts`, `auth-middleware.ts`
+- **Functions/Variables**: `camelCase` — e.g., `getUserById`, `isValid`
+- **Classes/Interfaces/Types**: `PascalCase` — e.g., `UserService`, `CreateUserInput`
+- **Constants**: `SCREAMING_SNAKE` — e.g., `MAX_RETRIES`, `DEFAULT_PORT`
+- **Database tables**: `snake_case` — e.g., `user_sessions` (Prisma converts to camelCase)
+- **API endpoints**: `kebab-case` — e.g., `/api/user-profile`, `/api/auth/sign-in`
+
+## Tech Stack
+- **Runtime**: Node.js 20+
+- **Framework**: Express.js / Fastify
+- **Language**: TypeScript
+- **Database**: PostgreSQL with Prisma
+- **Testing**: Jest, Supertest
+
+## Code Quality Standards
+
+### TypeScript
+- Enable strict mode in tsconfig
+- Never use `any` - define proper types
+- Use `unknown` for truly dynamic data
+- Export types from dedicated files
+
+```typescript
+// types/user.ts
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: Date;
+}
+
+export interface CreateUserInput {
+  email: string;
+  name: string;
+  password: string;
+}
+```
+
+### API Endpoints
+- Use consistent response format
+- Return appropriate HTTP status codes
+- Validate all input with Zod or Joi
+- Handle errors with middleware
+
+```typescript
+// Consistent response format
+interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+// Controller
+export async function createUser(req: Request, res: Response) {
+  const input = createUserSchema.parse(req.body);
+
+  const user = await userService.create(input);
+
+  res.status(201).json({
+    success: true,
+    data: user,
+  });
+}
+```
+
+### Error Handling
+- Use custom error classes
+- Centralize error handling in middleware
+- Log errors with context
+- Never expose stack traces to clients
+
+```typescript
+// errors.ts
+export class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    public code: string,
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(404, 'NOT_FOUND', `${resource} not found`);
+  }
+}
+
+// middleware/errorHandler.ts
+export function errorHandler(
+  err: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  logger.error('Request error', { error: err, path: req.path });
+
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      success: false,
+      error: { code: err.code, message: err.message },
+    });
+  }
+
+  // Don't expose internal errors
+  res.status(500).json({
+    success: false,
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
+  });
+}
+```
+
+### Database (Prisma)
+- Use transactions for multi-step operations
+- Select only needed fields
+- Use pagination for list endpoints
+- Add indexes in schema
+
+```typescript
+// Good - select only needed fields
+const users = await prisma.user.findMany({
+  select: {
+    id: true,
+    email: true,
+    name: true,
+  },
+  take: 20,
+  skip: page * 20,
+});
+
+// Transaction
+await prisma.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+  await tx.inventory.decrement({ where: { productId }, data: { quantity } });
+  return order;
+});
+```
+
+### Async/Await
+- Always use try/catch or error middleware
+- Use Promise.all for parallel operations
+- Handle promise rejections
+- Avoid callback-style code
+
+```typescript
+// Parallel operations
+const [user, orders, notifications] = await Promise.all([
+  userService.getById(userId),
+  orderService.getByUser(userId),
+  notificationService.getUnread(userId),
+]);
+```
+
+### Security
+- Validate all input
+- Use parameterized queries (Prisma does this)
+- Set security headers (helmet)
+- Rate limit sensitive endpoints
+- Never log sensitive data
+
+### Logging
+- Use structured logging (pino, winston)
+- Include request ID for tracing
+- Log appropriate levels
+- Never log passwords or tokens
+
+```typescript
+logger.info('User created', {
+  userId: user.id,
+  email: user.email,
+  // Never log: password, token, etc.
+});
+```
+
+### Testing
+- Unit test business logic
+- Integration test API endpoints
+- Mock external services
+- Use test database
+
+```typescript
+describe('POST /api/users', () => {
+  it('creates a user with valid input', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'test@example.com', name: 'Test', password: 'secure123' });
+
+    expect(response.status).toBe(201);
+    expect(response.body.success).toBe(true);
+    expect(response.body.data.email).toBe('test@example.com');
+  });
+
+  it('returns 400 for invalid email', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'invalid', name: 'Test', password: 'secure123' });
+
+    expect(response.status).toBe(400);
+    expect(response.body.error.code).toBe('VALIDATION_ERROR');
+  });
+});
+```
+
+## File Structure
+```
+src/
+├── controllers/      # Route handlers
+├── services/         # Business logic
+├── repositories/     # Database access
+├── middleware/       # Express middleware
+├── types/            # TypeScript types
+├── utils/            # Helper functions
+├── routes/           # Route definitions
+└── index.ts          # App entry point
+```
+
+## Environment Variables
+```typescript
+// config.ts
+export const config = {
+  port: process.env.PORT || 3000,
+  databaseUrl: process.env.DATABASE_URL!,
+  jwtSecret: process.env.JWT_SECRET!,
+  nodeEnv: process.env.NODE_ENV || 'development',
+};
+```
+
+## Pre-commit Hooks
+This project uses agentic-loop hooks. Run `/vibe-check` before committing.
+
+## Common Commands
+```bash
+npm run dev          # Start dev server with hot reload
+npm run build        # Build TypeScript
+npm start            # Start production server
+npm test             # Run tests
+npm run lint         # Run linter
+npm run db:migrate   # Run Prisma migrations
+```

package/templates/examples/CLAUDE-react.md

@@ -0,0 +1,138 @@
+# Project Instructions for AI Coding Agents
+
+## Naming Conventions
+- **Files**: `PascalCase.tsx` for components, `camelCase.ts` for utilities — e.g., `UserProfile.tsx`, `useAuth.ts`
+- **Components**: `PascalCase` — e.g., `UserProfile`, `AuthProvider`
+- **Hooks**: `useCamelCase` — e.g., `useAuth`, `useUserData`
+- **Functions/Variables**: `camelCase` — e.g., `handleSubmit`, `isLoading`
+- **Types/Interfaces**: `PascalCase` — e.g., `UserProps`, `AuthState`
+- **Constants**: `SCREAMING_SNAKE` — e.g., `API_BASE_URL`, `MAX_RETRIES`
+- **CSS classes**: `kebab-case` (TailwindCSS utility classes are standard)
+
+## Tech Stack
+- **Frontend**: React 18, TypeScript, Vite
+- **Styling**: TailwindCSS
+- **State**: React Query for server state, Zustand for client state
+- **Testing**: Vitest, React Testing Library, Playwright
+
+## Code Quality Standards
+
+### TypeScript
+- **Never use `any`** - Create proper interfaces for all data
+- Use strict mode (`"strict": true` in tsconfig)
+- Prefer `interface` for object shapes, `type` for unions/intersections
+- Use `unknown` instead of `any` when type is truly unknown
+
+```typescript
+// Bad
+const data: any = await fetchUser();
+
+// Good
+interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+const data: User = await fetchUser();
+```
+
+### React Components
+- Use functional components with hooks
+- Keep components small and focused (< 100 lines)
+- Extract logic into custom hooks
+- Use proper TypeScript types for props
+
+```typescript
+// Good component structure
+interface UserCardProps {
+  user: User;
+  onEdit: (user: User) => void;
+}
+
+export function UserCard({ user, onEdit }: UserCardProps) {
+  return (/* ... */);
+}
+```
+
+### State Management
+- Use React Query for server state (caching, refetching)
+- Use Zustand for UI state only
+- Keep state as close to usage as possible
+- Don't duplicate server state in client state
+
+### Error Handling
+- Always handle loading, error, and empty states
+- Use Error Boundaries for unexpected errors
+- Show user-friendly error messages
+- Log errors with context for debugging
+
+```typescript
+// Always handle all states
+const { data, isLoading, error } = useQuery(['user'], fetchUser);
+
+if (isLoading) return <Skeleton />;
+if (error) return <ErrorMessage error={error} />;
+if (!data) return <EmptyState />;
+
+return <UserProfile user={data} />;
+```
+
+### Styling with TailwindCSS
+- Use Tailwind utility classes
+- Extract repeated patterns to components, not @apply
+- Use design system tokens (colors, spacing)
+- Keep className strings readable
+
+### Testing
+- Write tests for business logic and user interactions
+- Use React Testing Library (test behavior, not implementation)
+- Mock external dependencies
+- Use Playwright for critical user flows
+
+```typescript
+// Test user behavior, not implementation
+test('user can submit form', async () => {
+  render(<ContactForm />);
+
+  await userEvent.type(screen.getByLabelText(/email/i), 'test@example.com');
+  await userEvent.click(screen.getByRole('button', { name: /submit/i }));
+
+  expect(screen.getByText(/thanks/i)).toBeInTheDocument();
+});
+```
+
+## File Structure
+```
+src/
+├── components/     # Reusable UI components
+│   ├── ui/         # Design system primitives
+│   └── features/   # Feature-specific components
+├── hooks/          # Custom React hooks
+├── pages/          # Page components (routes)
+├── services/       # API calls and external services
+├── stores/         # Zustand stores
+├── types/          # TypeScript types/interfaces
+└── utils/          # Helper functions
+```
+
+## Environment Variables
+- Use `import.meta.env.VITE_*` for client-side env vars
+- Never commit real secrets
+- Provide defaults for local development
+
+```typescript
+const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:8000/api';
+```
+
+## Pre-commit Hooks
+This project uses agentic-loop hooks. Run `/vibe-check` before committing.
+
+## Common Commands
+```bash
+npm run dev          # Start dev server
+npm run build        # Build for production
+npm test             # Run unit tests
+npm run test:e2e     # Run E2E tests
+npm run lint         # Run linter
+npm run typecheck    # Check types
+```

package/templates/optional/cursorrules.template

@@ -0,0 +1,147 @@
+# Cursor Rules for Vibe Coding
+# Copy this file to your project root as `.cursorrules`
+
+You are an expert developer helping with this project. Follow these rules:
+
+## Code Quality
+
+### Never Use These Patterns
+- `any` type in TypeScript - create proper interfaces
+- Empty catch blocks - handle errors properly
+- `console.log` for error handling - use proper logging
+- Hardcoded URLs - use environment variables
+- Functions over 50 lines - break them up
+- Deep nesting (4+ levels) - refactor with early returns
+
+### Always Do This
+- Handle loading, error, and empty states
+- Use proper TypeScript types
+- Write descriptive variable names
+- Add error handling for async operations
+- Use environment variables for configuration
+
+## Response Format
+
+When writing code:
+1. Explain what you're doing briefly
+2. Write clean, typed code
+3. Include error handling
+4. Mention any edge cases to consider
+
+When I ask you to fix something:
+1. Explain what was wrong
+2. Show the fix
+3. Explain why it's better
+
+## TypeScript Rules
+
+```typescript
+// DON'T
+const data: any = await fetch('/api');
+function process(input: any): any { }
+
+// DO
+interface User { id: string; name: string; }
+const data: User = await fetchUser();
+function process(input: UserInput): ProcessedUser { }
+```
+
+## Error Handling
+
+```typescript
+// DON'T
+try { doThing(); } catch (e) { }
+
+// DO
+try {
+  await doThing();
+} catch (error) {
+  if (error instanceof NetworkError) {
+    logger.warn('Network error, retrying', { error });
+    return retry(doThing);
+  }
+  logger.error('Failed to do thing', { error });
+  throw error;
+}
+```
+
+## React Components
+
+```typescript
+// DON'T
+function UserProfile({ userId }) {
+  const [user, setUser] = useState();
+  // No loading/error handling
+  return <div>{user.name}</div>;
+}
+
+// DO
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading, error } = useUser(userId);
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+  if (!user) return <NotFound />;
+
+  return <div>{user.name}</div>;
+}
+```
+
+## Testing
+
+When I ask you to write tests:
+1. Use the SCENARIO/EXPECTED/FAILURE pattern
+2. Test behavior, not implementation
+3. Include happy path and error cases
+4. Keep tests independent
+
+```typescript
+test('user can submit form', async () => {
+  /**
+   * SCENARIO: User fills out valid form and submits
+   * EXPECTED: Success message shown, form cleared
+   * FAILURE: Error shown or form stuck
+   */
+});
+```
+
+## Security
+
+Never:
+- Put secrets in code
+- Use innerHTML with user content
+- Build SQL queries with string concatenation
+- Trust user input without validation
+
+Always:
+- Use parameterized queries
+- Sanitize HTML if you must render it
+- Validate input on both client and server
+- Use HTTPS for external requests
+
+## When Asked to Review Code
+
+Check for:
+1. Security vulnerabilities
+2. Missing error handling
+3. `any` types
+4. Code duplication
+5. Long functions
+6. Missing tests for critical paths
+
+## Project-Specific Notes
+
+<!-- Add your project-specific patterns here -->
+
+### Tech Stack
+- Frontend: [Your stack]
+- Backend: [Your stack]
+- Database: [Your database]
+
+### Patterns to Follow
+- [Pattern 1]
+- [Pattern 2]
+
+### Things to Avoid
+- [Anti-pattern 1]
+- [Anti-pattern 2]

package/templates/optional/eslint.config.js

@@ -0,0 +1,34 @@
+/**
+ * Example ESLint configuration using agentic-loop plugin
+ *
+ * Copy this file to your project root and customize as needed.
+ */
+
+import vibe from "agentic-loop/eslint-plugin";
+
+export default [
+  // Use the recommended config (balanced defaults)
+  vibe.configs.recommended,
+
+  // Or use strict config for stricter rules
+  // vibe.configs.strict,
+
+  // Custom configuration
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    rules: {
+      // Override specific rules if needed
+      // "vibe/no-any-type": "error",
+      // "vibe/max-function-length": ["warn", { max: 40 }],
+    },
+  },
+
+  // Disable rules for test files
+  {
+    files: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"],
+    rules: {
+      "vibe/no-magic-numbers": "off",
+      "vibe/max-function-length": "off",
+    },
+  },
+];

package/templates/optional/lint-staged.config.js

@@ -0,0 +1,34 @@
+/**
+ * Ready-to-use lint-staged configuration for agentic-loop
+ *
+ * Copy this file to your project root, or reference the config:
+ *
+ *   // package.json
+ *   {
+ *     "lint-staged": {
+ *       "*.{js,ts,jsx,tsx}": "vibe-check --fail-on error"
+ *     }
+ *   }
+ */
+
+export default {
+  // JavaScript/TypeScript files - full security and quality checks
+  '*.{js,jsx,ts,tsx,mjs,cjs}': [
+    'vibe-check --only secrets,urls,debug,unsafe-html,any-types,snake-case,empty-catch --fail-on error',
+  ],
+
+  // Python files
+  '*.py': [
+    'vibe-check --only secrets,urls,debug,empty-catch,magic-numbers --fail-on error',
+  ],
+
+  // Config files - secrets check only
+  '*.{json,yaml,yml,toml}': [
+    'vibe-check --only secrets --fail-on error',
+  ],
+
+  // Dockerfiles
+  'Dockerfile*': [
+    'vibe-check --only docker-platform --fail-on warning',
+  ],
+};