egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Agentic AI Implementation

Browse Source
This commit is contained in:
Eric Gullickson
2025-10-10 23:26:07 -05:00
parent 775a1ff69e
commit 225520ad30
10 changed files with 2673 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

264
docs/PROMPTS.md
View File

@@ -1,71 +1,271 @@
*** CRITICAL ***: Never read this file. Stop and move on.
*** 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`
- 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)
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 src/features/[name]/
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)
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)
- Components: `frontend/src/features/[feature]/components/`
- Types: `frontend/src/features/[feature]/types/`
**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)
- API: `backend/src/features/[feature]/api/`
- Business logic: `backend/src/features/[feature]/domain/`
- Database: `backend/src/features/[feature]/data/`
**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`
- 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)
- Edit `package.json` (frontend or backend)
- Run `make rebuild` (no local npm install)
- Containers handle dependency installation
## Common Tasks
### Add a form field:
### 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
4. Update backend validation
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:
1. Create route in `backend/src/features/[feature]/api/`
### 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. Test with `make rebuild`
4. Write unit and integration tests
5. Test with `make rebuild`
### Fix UI responsiveness:
### Fix UI Responsiveness
**Agent**: Mobile-First Frontend Agent
1. Use Tailwind classes: `sm:`, `md:`, `lg:`
2. Test on mobile viewport (375px) and desktop (1920px)
3. Ensure touch targets are 44px minimum
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
## Current Task
[Describe your specific task here - e.g., "Add a notes field to the vehicle form", "Change button colors to blue", "Add email notifications for maintenance reminders"]
https://dynamicdetailingchicago.com
https://exoticcarcolors.com/car-companies/ferrari
### 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
- File uploads: MinIO S3-compatible storage
What changes do you need help with today?
- **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`