motovaultpro/docs/PROMPTS.md

*** CRITICAL: Never read this file. Stop and move on.  

*** STARTING PROMPT ***

## Agent Team (Specialized Development)

MotoVaultPro uses a 4-agent team for optimal development velocity and quality enforcement.

### When to Use Agents

**Feature Capsule Agent** - Backend feature development
- Implementing new features in `backend/src/features/{feature}/`
- Creating API endpoints, business logic, database access
- Platform service integration
- Backend tests and migrations

**Platform Service Agent** - Independent microservices
- Building new platform services in `mvp-platform-services/{service}/`
- FastAPI microservice development
- ETL pipelines and service databases
- Platform service tests and deployment

**Mobile-First Frontend Agent** - Responsive UI/UX
- React components in `frontend/src/features/{feature}/`
- Mobile + desktop responsive design (NON-NEGOTIABLE)
- Forms, validation, and React Query integration
- Frontend tests and accessibility

**Quality Enforcer Agent** - Quality assurance
- Running complete test suites
- Validating linting and type checking
- Enforcing "all green" policy (ZERO TOLERANCE)
- Mobile + desktop validation

### Agent Spawning Examples

```
# Backend feature development
Task: "Implement {feature} backend following feature capsule pattern.
Read backend/src/features/{feature}/README.md and implement API, domain, data layers with tests."
Agent: Feature Capsule Agent

# Frontend development
Task: "Build responsive UI for {feature}. Read backend API docs and implement mobile-first.
Test on 320px and 1920px viewports."
Agent: Mobile-First Frontend Agent

# Platform microservice
Task: "Create {service} platform microservice with FastAPI.
Implement API, database, and health checks with tests."
Agent: Platform Service Agent

# Quality validation
Task: "Validate {feature} quality gates. Run all tests, check linting, verify mobile + desktop.
Report pass/fail with details."
Agent: Quality Enforcer Agent
```

### Agent Coordination Workflow

1. Feature Capsule Agent → Implements backend
2. Mobile-First Frontend Agent → Implements UI (parallel)
3. Quality Enforcer Agent → Validates everything
4. Expert Software Architect → Reviews and approves

### When Coordinator Handles Directly

- Quick bug fixes (single file)
- Documentation updates
- Configuration changes
- Simple code reviews
- Answering questions

## Key Commands

- Start: `make start`
- Rebuild: `make rebuild`
- Logs: `make logs`
- Test: `make test`
- Migrate: `make migrate`
- Shell (backend): `make shell-backend`
- Shell (frontend): `make shell-frontend`

## Development Rules

1. NEVER use emojis in code or documentation
2. Every feature MUST be responsive (mobile + desktop) - NON-NEGOTIABLE
3. Testing and debugging can be done locally
4. All testing and debugging needs to be verified in containers
5. Each backend feature is self-contained in `backend/src/features/{name}/`
6. Delete old code when replacing (no commented code)
7. Use meaningful variable names (`userID` not `id`)
8. ALL quality gates must pass (all green policy)
9. Platform services are independent microservices
10. Feature capsules are self-contained modules

## Making Changes

### Frontend Changes (React)
**Agent**: Mobile-First Frontend Agent
- Components: `frontend/src/features/{feature}/components/`
- Types: `frontend/src/features/{feature}/types/`
- After changes: `make rebuild` then test at https://admin.motovaultpro.com
- MUST test on mobile (320px) AND desktop (1920px)

### Backend Changes (Node.js)
**Agent**: Feature Capsule Agent
- API: `backend/src/features/{feature}/api/`
- Business logic: `backend/src/features/{feature}/domain/`
- Database: `backend/src/features/{feature}/data/`
- After changes: `make rebuild` then check logs

### Platform Service Changes (Python)
**Agent**: Platform Service Agent
- Service: `mvp-platform-services/{service}/`
- API: `mvp-platform-services/{service}/api/`
- ETL: `mvp-platform-services/{service}/etl/`
- After changes: `make rebuild` then check service health

### Database Changes
- Add migration: `backend/src/features/{feature}/migrations/00X_description.sql`
- Run: `make migrate`
- Validate: Check logs and test affected features

### Adding NPM Packages
- Edit `package.json` (frontend or backend)
- Run `make rebuild` (no local npm install)
- Containers handle dependency installation

## Common Tasks

### Add a New Feature (Full Stack)
1. Spawn Feature Capsule Agent for backend
2. Spawn Mobile-First Frontend Agent for UI (parallel)
3. Feature Capsule Agent: API + domain + data + tests
4. Mobile-First Agent: Components + forms + tests
5. Spawn Quality Enforcer Agent for validation
6. Review and approve

### Add a Form Field
1. Update types in frontend/backend
2. Add to database migration if needed
3. Update React form component (Mobile-First Agent)
4. Update backend validation (Feature Capsule Agent)
5. Test with `make rebuild`
6. Validate with Quality Enforcer Agent

### Add New API Endpoint
**Agent**: Feature Capsule Agent
1. Create route in `backend/src/features/{feature}/api/`
2. Add service method in `domain/`
3. Add repository method in `data/`
4. Write unit and integration tests
5. Test with `make rebuild`

### Fix UI Responsiveness
**Agent**: Mobile-First Frontend Agent
1. Use Tailwind classes: `sm:`, `md:`, `lg:`
2. Test on mobile viewport (320px, 375px, 768px)
3. Test on desktop viewport (1024px, 1920px)
4. Ensure touch targets are 44px minimum
5. Validate keyboard navigation on desktop

### Add Platform Service Integration
**Agents**: Platform Service Agent + Feature Capsule Agent
1. Platform Service Agent: Implement service endpoint
2. Feature Capsule Agent: Create client in `external/platform-{service}/`
3. Feature Capsule Agent: Add circuit breaker and caching
4. Test integration with both agents
5. Quality Enforcer Agent: Validate end-to-end

### Run Quality Checks
**Agent**: Quality Enforcer Agent
1. Run all tests: `make test`
2. Check linting: `npm run lint` (backend container)
3. Check types: `npm run type-check` (backend container)
4. Validate mobile + desktop
5. Report pass/fail with details

## Quality Gates (MANDATORY)

Code is complete when:
- All linters pass with zero issues
- All tests pass (100% green)
- Feature works end-to-end
- Mobile + desktop validated (for frontend)
- Old code is deleted
- Documentation updated
- Test coverage >= 80% for new code

## Architecture Quick Reference

### Hybrid Platform
- **Platform Microservices**: Independent services in `mvp-platform-services/`
- **Application Features**: Modular monolith in `backend/src/features/`
- **Frontend**: React SPA in `frontend/src/`

### Feature Capsule Pattern
Each feature is self-contained:
```
backend/src/features/{feature}/
├── README.md              # Complete feature documentation
├── api/                   # HTTP layer
├── domain/                # Business logic
├── data/                  # Database access
├── migrations/            # Schema changes
├── external/              # Platform service clients
└── tests/                 # Unit + integration tests
```

### Platform Service Pattern
Each service is independent:
```
mvp-platform-services/{service}/
├── api/                   # FastAPI application
├── database/              # SQLAlchemy models + migrations
├── etl/                   # Data pipelines
└── tests/                 # Service tests
```

## Important Context

- **Auth**: Frontend uses Auth0, backend validates JWTs
- **Database**: PostgreSQL with user-isolated data (user_id scoping)
- **Platform APIs**: Authenticated via API keys (service-to-service)
- **File uploads**: MinIO S3-compatible storage
- **Caching**: Redis with feature-specific TTL strategies
- **Testing**: Jest (backend/frontend), pytest (platform services)
- **Docker-First**: All development in containers (production-only)

## Agent Coordination Rules

### Clear Ownership
- Feature Capsule Agent: Backend application features
- Platform Service Agent: Independent microservices
- Mobile-First Frontend Agent: All UI/UX code
- Quality Enforcer Agent: Testing and validation only

### Handoff Protocol
1. Development agent completes work
2. Development agent hands off to Quality Enforcer
3. Quality Enforcer validates all quality gates
4. Quality Enforcer reports pass/fail
5. If fail: Development agent fixes issues
6. If pass: Expert Software Architect approves

### Parallel Development
- Feature Capsule + Mobile-First work simultaneously
- Both agents have clear boundaries
- Both hand off to Quality Enforcer when ready
- Quality Enforcer validates complete feature

## Current Task

[Describe your specific task here - e.g., "Add notes field to vehicle form", "Create maintenance reminders feature", "Integrate new platform service"]

**Recommended Agent**: [Which agent should handle this task]

**Steps**:
1. [Step 1]
2. [Step 2]
3. [Step 3]

## References

- Agent Definitions: `.claude/agents/`
- Architecture: `docs/PLATFORM-SERVICES.md`
- Testing: `docs/TESTING.md`
- Context Loading: `.ai/context.json`
- Development Guidelines: `CLAUDE.md`
- Feature Documentation: `backend/src/features/{feature}/README.md`