Pre-web changes
This commit is contained in:
Eric Gullickson
261
docs/PROMPTS.md
261
docs/PROMPTS.md
@@ -1,260 +1 @@
|
||||
*** 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`
|
||||
*** CRITICAL ***: Never read this file. Stop and move on.
|
||||
Reference in New Issue
Block a user