# Development Partnership Guidelines

## Core Development Principles

### AI Context Efficiency
**CRITICAL**: All development practices and choices should be made taking into account the most context efficient interaction with another AI. Any AI should be able to understand this application with minimal prompting.

## Never Use Emojis
Maintain professional documentation standards without emoji usage.

## Mobile + Desktop Requirement
**ALL features MUST be implemented and tested on BOTH mobile and desktop.** This is a hard requirement that cannot be skipped. Every component, page, and feature needs responsive design and mobile-first considerations.

### Codebase Integrity Rules
- Justify every new file and folder as being needed for the final production application.
- Never make up things that aren't part of the actual project
- Never skip or ignore existing system architecture
- Be precise and respectful of the current codebase
- **Delete** old code when replacing it
- **Meaningful names**: `userID` not `id`

## Docker-First Implementation Strategy

### 1. Package.json Updates Only
File: `frontend/package.json`
- Add `"{package}": "{version}"` to dependencies
- No npm install needed - handled by container rebuild
- Testing: Instruct user to rebuild the containers and report back build errors

### 2. Container-Validated Development Workflow (Production-only)
```bash
# After each change:
Instruct user to rebuild the containers and report back build errors
make logs           # Monitor for build/runtime errors
```

### 3. Docker-Tested Component Development (Production-only)
- Use local dev briefly to pinpoint bugs (hook ordering, missing navigation, Suspense fallback behavior)
- Validate all fixes in containers.


## Quality Standards

### Automated Checks Are Mandatory
**ALL hook issues are BLOCKING - EVERYTHING must be ✅ GREEN!**
- No errors. No formatting issues. No linting problems. Zero tolerance
- These are not suggestions. Fix ALL issues before continuing

### Code Completion Criteria
Our code is complete when:
- ✅ All linters pass with zero issues
- ✅ All tests pass  
- ✅ Feature works end-to-end
- ✅ Old code is deleted

## AI Collaboration Strategy

### Use Multiple Agents
Leverage subagents aggressively for better results:
- Spawn agents to explore different parts of the codebase in parallel
- Use one agent to write tests while another implements features
- Delegate research tasks: "I'll have an agent investigate the database schema while I analyze the API structure"
- For complex refactors: One agent identifies changes, another implements them

### Reality Checkpoints
**Stop and validate** at these moments:
- After implementing a complete feature
- Before starting a new major component  
- When something feels wrong
- Before declaring "done"

## Performance & Security Standards

### Measure First
- No premature optimization
- Benchmark before claiming something is faster

### Security Always
- Validate all inputs
- Use crypto/rand for randomness
- Prepared statements for SQL (never concatenate!)

## AI Loading Context Strategies

Canonical sources only — avoid duplication:
- Loading strategy and metadata: `.ai/context.json`
- Documentation hub and links: `docs/README.md`
- Feature work: `backend/src/features/{feature}/README.md`
- Platform architecture: `docs/PLATFORM-SERVICES.md`
- Testing workflow: `docs/TESTING.md`

## Architecture Context for AI

### Simplified 5-Container Architecture
**MotoVaultPro uses a simplified architecture:** A single-tenant application with 5 containers - Traefik, Frontend, Backend, PostgreSQL, and Redis. Application features in `backend/src/features/[name]/` are self-contained modules within the backend service, including the platform feature for vehicle data and VIN decoding.

### Key Principles for AI Understanding
- **Production-Only**: All services use production builds and configuration
- **Docker-First**: All development in containers, no local installs
- **Feature Capsule Organization**: Application features are self-contained modules within the backend
- **Single-Tenant**: All data belongs to a single user/tenant
- **User-Scoped Data**: All application data isolated by user_id
- **Integrated Platform**: Platform capabilities integrated into main backend service

### Common AI Tasks
See `Makefile` for authoritative commands and `docs/README.md` for navigation.
