261 lines
8.7 KiB
Markdown
261 lines
8.7 KiB
Markdown
*** 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 Feature Agent** - Integrated platform module
|
|
- Enhancing `backend/src/features/platform/`
|
|
- Vehicle lookup + VIN decoding logic
|
|
- Redis/SQL performance tuning for platform endpoints
|
|
- Platform module tests and documentation
|
|
|
|
**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 module work
|
|
Task: "Enhance platform feature capsule (backend/src/features/platform).
|
|
Implement API/domain/data changes with accompanying tests."
|
|
Agent: Platform Feature 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. 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 Module Changes (TypeScript)
|
|
**Agent**: Platform Feature Agent
|
|
- Feature capsule: `backend/src/features/platform/`
|
|
- API routes: `backend/src/features/platform/api/`
|
|
- Domain/data: `backend/src/features/platform/domain/` and `data/`
|
|
- After changes: `make rebuild` then verify platform endpoints via backend logs/tests
|
|
|
|
### 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 Integration
|
|
**Agents**: Platform Feature Agent + Feature Capsule Agent
|
|
1. Platform Feature Agent: Implement/update platform endpoint logic
|
|
2. Feature Capsule Agent: Update consuming feature client (e.g. `external/platform-vehicles/`)
|
|
3. Feature Capsule Agent: Adjust caching/circuit breaker strategies as needed
|
|
4. Joint testing: run targeted unit/integration suites
|
|
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
|
|
|
|
### Application Stack
|
|
- **Backend Feature Capsules**: Modular monolith in `backend/src/features/`
|
|
- **Platform Module**: Vehicle data + VIN decoding in `backend/src/features/platform/`
|
|
- **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
|
|
```
|
|
|
|
|
|
## Important Context
|
|
|
|
- **Auth**: Frontend uses Auth0, backend validates JWTs
|
|
- **Database**: PostgreSQL with user-isolated data (user_id scoping)
|
|
- **Platform APIs**: Exposed via `/api/platform/*`, secured with Auth0 JWTs
|
|
- **Caching**: Redis with feature-specific TTL strategies
|
|
- **Testing**: Jest (backend + frontend)
|
|
- **Docker-First**: All development in containers (production-only)
|
|
|
|
## Agent Coordination Rules
|
|
|
|
### Clear Ownership
|
|
- Feature Capsule Agent: Backend application features
|
|
- Platform Feature Agent: Platform capsule inside backend
|
|
- 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`
|