AGENTS.md Guide

/init

# Autohand will:
# 1. Analyze your project structure
# 2. Detect frameworks and languages
# 3. Find build scripts and commands
# 4. Generate an appropriate AGENTS.md

# AGENTS.md

## Project overview
Brief description of what this project does and its primary purpose.

## Tech stack
- Framework: Next.js 14 with App Router
- Language: TypeScript (strict mode)
- Database: PostgreSQL with Prisma ORM
- Styling: Tailwind CSS

## Architecture
Explain the codebase structure and key patterns.

## Commands
```bash
bun install        # Install dependencies
bun run dev        # Start development server
bun run test       # Run tests
bun run build      # Production build
```

## Code style
- Prefer functional components
- Use early returns
- Name files in kebab-case
- Write tests for business logic

## Patterns to follow
Document established patterns in the codebase.

## Things to avoid
List antipatterns and common mistakes.

## Project overview
Autohand is an AI-powered CLI for software development. It helps developers
write, review, and refactor code through natural language conversations.

Key features:
- Multi-provider AI support (Claude, GPT, Gemini)
- Skills system for specialized tasks
- Git integration for code changes
- Session management for context persistence

## Tech stack
- Runtime: Node.js 20+
- Framework: Express 4.x
- Database: MongoDB 6.x with Mongoose
- Auth: Passport.js with JWT
- Testing: Jest + Supertest
- CI: GitHub Actions

## Architecture

```
src/
├── api/          # REST API routes
├── services/     # Business logic
├── models/       # Database schemas
├── utils/        # Shared utilities
└── middleware/   # Express middleware
```

### Key patterns
- Services handle all business logic
- Controllers are thin - just request/response handling
- All database access goes through models
- Middleware handles auth, logging, error handling

## Commands

```bash
# Development
npm run dev              # Start with hot reload
npm run dev:debug        # Start with debugger

# Testing
npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # With coverage report

# Building
npm run build            # Production build
npm run typecheck        # TypeScript check only

# Database
npm run db:migrate       # Run migrations
npm run db:seed          # Seed test data
npm run db:reset         # Reset and reseed
```

## Code style

### Naming
- Files: kebab-case (user-service.ts)
- Classes: PascalCase (UserService)
- Functions: camelCase (getUserById)
- Constants: SCREAMING_SNAKE_CASE (MAX_RETRIES)

### Functions
- Prefer arrow functions for callbacks
- Use named functions for top-level exports
- Max 30 lines per function
- Use early returns to reduce nesting

### Error handling
- Always use typed errors (AppError class)
- Log errors at the boundary, not inline
- Return Result types instead of throwing in services

## Patterns to follow

### API responses
Always use the standard response format:
```typescript
{
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
}
```

### Database queries
Use the repository pattern for complex queries:
```typescript
// Good
const users = await userRepository.findActiveWithProjects();

// Avoid
const users = await User.find({ active: true }).populate('projects');
```

### Feature flags
Check feature flags before new functionality:
```typescript
if (await features.isEnabled('new-checkout')) {
  // new implementation
}
```

## Things to avoid

### Don't
- Don't use `any` type - use `unknown` and narrow
- Don't mutate function parameters
- Don't use default exports (we use named exports)
- Don't commit .env files
- Don't use `console.log` - use the logger

### Known issues
- The legacy `/api/v1/users` endpoint has bugs - use `/api/v2/users`
- `OrderService.calculateTotal` has floating point issues on large orders
- MongoDB aggregations timeout after 10s - paginate large queries

### Security
- Never log user passwords or tokens
- Always sanitize user input before database queries
- Use parameterized queries, never string concatenation

# AGENTS.md

## Project overview
E-commerce platform built with Next.js 14 App Router.

## Tech stack
- Next.js 14 (App Router)
- TypeScript 5.x (strict)
- Prisma + PostgreSQL
- Tailwind CSS + shadcn/ui
- Stripe for payments

## Commands
```bash
bun install
bun run dev          # localhost:3000
bun run test
bun run build
```

## Architecture
```
app/
├── (auth)/          # Auth routes (login, register)
├── (shop)/          # Shop routes (products, cart)
├── api/             # API routes
└── layout.tsx       # Root layout
components/
├── ui/              # shadcn/ui components
└── features/        # Feature components
lib/
├── db.ts            # Prisma client
├── auth.ts          # Auth utilities
└── stripe.ts        # Stripe client
```

## Code style
- Use server components by default
- Add 'use client' only when needed
- Colocate components with routes
- Use Zod for form validation
- Prefer server actions over API routes

## Things to avoid
- Don't use `useEffect` for data fetching
- Don't put business logic in components
- Don't use `any` type

# AGENTS.md

## Project overview
Data pipeline CLI for ETL operations.

## Tech stack
- Python 3.11+
- Click for CLI
- SQLAlchemy 2.0
- Pandas for data processing
- Poetry for dependencies

## Commands
```bash
poetry install
poetry run pytest
poetry run mypy src/
poetry run cli --help
```

## Architecture
```
src/
├── cli/             # Click commands
├── extractors/      # Data source extractors
├── transformers/    # Data transformations
├── loaders/         # Destination loaders
└── models/          # SQLAlchemy models
```

## Code style
- Type hints on all functions
- Docstrings in Google style
- Max line length 88 (Black)
- Use dataclasses for config objects

## Patterns
- Extractors yield records, don't load all in memory
- Transformers are pure functions
- Use context managers for database connections

## Things to avoid
- Don't use mutable default arguments
- Don't catch bare exceptions
- Don't use print() - use logging

# Bad
Write clean, readable code.

# Good
Use early returns to reduce nesting:
```typescript
// Prefer this
function process(user: User | null) {
  if (!user) return null;
  if (!user.active) return null;
  return user.process();
}

// Not this
function process(user: User | null) {
  if (user) {
    if (user.active) {
      return user.process();
    }
  }
  return null;
}
```

# Good
We use server components by default because:
- Better performance (less JavaScript shipped)
- Direct database access without API layer
- Simplified data fetching with async components

Use 'use client' only for:
- Event handlers (onClick, onChange)
- Browser APIs (localStorage, geolocation)
- React hooks that need client state

# ~/.autohand/AGENTS.md

## My preferences

### Communication style
- Be concise, skip pleasantries
- Show code examples, not just explanations
- Ask clarifying questions before making assumptions

### Code style
- I prefer functional programming patterns
- Use TypeScript strict mode
- Prefer composition over inheritance

### Tools
- I use VS Code with Vim keybindings
- Terminal is iTerm2 with zsh
- Package manager preference: bun > pnpm > npm

### Commit messages
- Use conventional commits (feat:, fix:, docs:)
- Keep subject under 50 characters
- Include ticket number when available