# Agent Development Guidelines

This document defines the rules, responsibilities, and output formats that AI agents must follow when contributing to the TableTrack codebase.

---

## RESPONSIBILITIES

### 1. CODE GENERATION & ORGANIZATION
- Create files ONLY in correct directories per architecture (e.g., `/backend/src/api/` for controllers, `/frontend/src/components/` for UI, `/common/types/` for shared models)
- Maintain strict separation between frontend, backend, and shared code
- Use only technologies defined in the architecture
- Follow naming conventions: camelCase functions, PascalCase components, kebab-case files
- Every function must be fully typed — no implicit any

### 2. CONTEXT-AWARE DEVELOPMENT
- Before generating code, read and interpret the relevant architecture section
- Infer dependencies between layers (how frontend/services consume backend/api endpoints)
- When adding features, describe where they fit in architecture and why
- Cross-reference existing patterns before creating new ones
- If request conflicts with architecture, STOP and ask for clarification

### 3. DOCUMENTATION & SCALABILITY
- Update ARCHITECTURE when structural changes occur
- Auto-generate docstrings, type definitions, and comments following existing format
- Suggest improvements that enhance maintainability without breaking architecture
- Document technical debt directly in code comments

### 4. TESTING & QUALITY
- Generate matching test files in `/tests/` for every module
- Use appropriate frameworks (Jest, Vitest, Pytest) and quality tools (ESLint, Prettier)
- Maintain strict type coverage and linting standards
- Include unit tests and integration tests for critical paths

### 5. SECURITY & RELIABILITY
- Implement secure auth (JWT, OAuth2) and encryption (TLS, AES-256)
- Include robust error handling, input validation, and logging
- NEVER hardcode secrets — use environment variables
- Sanitize all user inputs, implement rate limiting

### 6. INFRASTRUCTURE & DEPLOYMENT
- Generate Dockerfiles, CI/CD configs per `/scripts/` and `/.github/` conventions
- Ensure reproducible, documented deployments
- Include health checks and monitoring hooks

### 7. ROADMAP INTEGRATION
- Annotate potential debt and optimizations for future developers
- Flag breaking changes before implementing

---

## RULES

### NEVER:
- Modify code outside the explicit request
- Install packages without explaining why
- Create duplicate code — find existing solutions first
- Skip types or error handling
- Generate code without stating target directory first
- Assume — ask if unclear

### ALWAYS:
- Read architecture before writing code
- State filepath and reasoning BEFORE creating files
- Show dependencies and consumers
- Include comprehensive types and comments
- Suggest relevant tests after implementation
- Prefer composition over inheritance
- Keep functions small and single-purpose

---

## OUTPUT FORMAT

### When creating files:

```
📁 [filepath]
Purpose: [one line]
Depends on: [imports]
Used by: [consumers]
```

```[language]
[fully typed, documented code]
```

```
Tests: [what to test]
```

### When architecture changes needed:

```
⚠️ ARCHITECTURE UPDATE
What: [change]
Why: [reason]
Impact: [consequences]
```

---

## WORKFLOW

1. Read the architecture documentation first
2. Understand existing patterns and conventions
3. Ask clarifying questions if anything is unclear
4. State the target directory and reasoning before coding
5. Generate fully typed, documented code
6. Suggest relevant tests
7. Flag any architectural impacts

---

*Now read the architecture and help me build. If anything is unclear, ask before coding.*