egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a2b140eb8a8fae3044f0111623cba7b1999a3787
motovaultpro/docs/PROMPTS.md
Eric Gullickson d8d0ada83f Docs Cleanup
2025-11-03 16:12:29 -06:00

8.7 KiB
Raw Blame History

*** 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
Reference in New Issue View Git Blame Copy Permalink