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`


### REDESIGN PROMPT

---
  You are the orchestration AI for the MotoVaultPro architecture simplification project. Your role is to coordinate
  multiple specialized AI agents working in parallel to transform the application from a 14-container microservices
  architecture to a streamlined 6-container stack.

  ## Your Mission

  Execute the complete simplification plan documented in `docs/redesign/`. This involves:
  - Removing multi-tenant architecture
  - Replacing MinIO with filesystem storage
  - Consolidating databases (3 PostgreSQL → 1)
  - Consolidating caches (3 Redis → 1)
  - Renaming all services to mvp-* convention
  - Simplifying from 14 containers to 6

  ## Getting Started

  1. **Read the master plan:**
     - Start with `docs/redesign/README.md` for overview
     - Review `docs/redesign/AGENT-MANIFEST.md` for agent assignments
     - Study `docs/redesign/DEPENDENCY-GRAPH.md` for execution order

  2. **Understand the agents:**
     You will spawn 8 specialized agents across 5 waves:
     - **Wave 1:** config-agent, docs-agent (parallel, no dependencies)
     - **Wave 2:** infra-agent, backend-agent, storage-agent (parallel, after Wave 1)
     - **Wave 3:** Continue Wave 2 agents + platform-agent
     - **Wave 4:** frontend-agent (sequential, waits for backend-agent)
     - **Wave 5:** test-agent (validates everything, runs last)

  3. **Execute the plan:**
     - Spawn agents using the Task tool with appropriate subagent_type
     - Each agent has detailed instructions in `docs/redesign/PHASE-*.md` files
     - Agents should update `docs/redesign/EXECUTION-STATE.json` as they work
     - Monitor progress and coordinate between waves

  ## Critical Requirements

  - **Follow the documentation exactly** - All procedures are documented in phase files
  - **Respect dependencies** - Check DEPENDENCY-GRAPH.md before starting each wave
  - **Validate each phase** - Use validation criteria in each PHASE-*.md file
  - **Track state** - Update EXECUTION-STATE.json throughout execution
  - **Be ready to rollback** - Use ROLLBACK-STRATEGY.md if phases fail

  ## Execution Strategy

  Spawn agents in waves, NOT all at once:

  **Wave 1 (Start immediately):**
  Spawn config-agent to execute Phase 4 (Config Cleanup)
  Spawn docs-agent to execute Phase 9 (Documentation Updates)

  **Wave 2 (After config-agent completes):**
  Spawn infra-agent to execute Phase 1 (Docker Compose)
  Spawn backend-agent to execute Phase 2 (Remove Tenant)
  Spawn storage-agent to execute Phase 3 (Filesystem Storage)

  **Wave 3 (After Wave 2 phases complete):**
  infra-agent continues with Phase 5 (Networks) and Phase 7 (Database)
  backend-agent continues with Phase 6 (Backend Updates)
  Spawn platform-agent to execute Phase 8 (Platform Service)

  **Wave 4 (After backend-agent Phase 6 completes):**
  Spawn frontend-agent to execute Phase 10 (Frontend Updates)

  **Wave 5 (After ALL phases 1-10 complete):**
  Spawn test-agent to execute Phase 11 (Testing and Validation)

  ## Success Criteria

  The project is complete when:
  - All 11 phases show "completed" status in EXECUTION-STATE.json
  - test-agent reports all validations passing
  - Exactly 6 containers running (mvp-traefik, mvp-frontend, mvp-backend, mvp-postgres, mvp-redis, mvp-platform)
  - `make test` passes with no failures
  - All features functional (auth, vehicles, documents, fuel-logs, maintenance, stations)

  ## Important Files

  - `docs/redesign/README.md` - Master coordination guide
  - `docs/redesign/AGENT-MANIFEST.md` - Agent assignments and timeline
  - `docs/redesign/DEPENDENCY-GRAPH.md` - Execution dependencies
  - `docs/redesign/FILE-MANIFEST.md` - All file changes (72 operations)
  - `docs/redesign/VALIDATION-CHECKLIST.md` - Success criteria
  - `docs/redesign/ROLLBACK-STRATEGY.md` - Recovery procedures
  - `docs/redesign/PHASE-01.md` through `PHASE-11.md` - Detailed execution steps

  ## Your First Action

  Read `docs/redesign/README.md` and `docs/redesign/AGENT-MANIFEST.md` to understand the full plan, then begin spawning
  Wave 1 agents (config-agent and docs-agent).

  Remember: You are the orchestrator. Your job is to spawn agents, monitor their progress, coordinate between waves, and
  ensure the simplification completes successfully. Each agent has complete instructions in their phase documentation
  files.

  Begin execution now.


## REDESIGN CONTINUE PROMPT

---
  You are resuming the MotoVaultPro architecture simplification project after an interruption. Your role is to assess the
  current state, validate completed work, and continue execution from the correct point.

  ## Critical First Steps

  1. **Assess Current State:**
     Read `docs/redesign/EXECUTION-STATE.json` to determine:
     - Which phases are completed
     - Which phase was in progress when interrupted
     - Which agents were running
     - Any reported errors or failures

  2. **Verify Completed Work:**
     For each phase marked "completed" in EXECUTION-STATE.json, run the validation checks from the corresponding
  `PHASE-*.md` file to confirm it actually completed successfully.

  3. **Check System Health:**
     ```bash
     # How many containers are running?
     docker compose ps

     # What's the current git status?
     git status

     # Are there any error logs?
     docker compose logs --tail=50

  Decision Tree

  If EXECUTION-STATE.json exists and has data:

  Scenario A: A phase shows "in_progress"
  - The agent was interrupted mid-phase
  - Check validation criteria for that phase
  - If validation passes: Mark as completed, continue to next phase
  - If validation fails: Decide whether to retry or rollback (see ROLLBACK-STRATEGY.md)

  Scenario B: All "in_progress" phases show "completed"
  - Determine which wave was active
  - Identify the next wave to execute
  - Spawn appropriate agents for next wave

  Scenario C: A phase shows "failed"
  - Review the error in EXECUTION-STATE.json
  - Check docs/redesign/ROLLBACK-STRATEGY.md for that phase
  - Decide: Fix and retry OR rollback that phase
  - Do NOT proceed to dependent phases until fixed

  Scenario D: Phases completed but validation failed
  - Review docs/redesign/VALIDATION-CHECKLIST.md
  - Identify what validation failed
  - Fix the issue
  - Re-run validation
  - Continue when validated

  If EXECUTION-STATE.json is empty/missing or all phases show "pending":

  Start from the beginning:
  - Initialize EXECUTION-STATE.json
  - Begin with Wave 1 (config-agent, docs-agent)
  - Follow normal execution flow

  Resume Checklist

  Before continuing, verify:

  - Read EXECUTION-STATE.json
  - Validated all "completed" phases
  - Checked container health: docker compose ps
  - Reviewed recent logs: docker compose logs --tail=100
  - Identified which wave you're in
  - Determined which agents need to spawn next
  - No blocking errors or conflicts

  Common Resume Scenarios

  Scenario: "Wave 1 complete, Wave 2 interrupted"

  EXECUTION-STATE.json shows:
  - Phase 4 (config-agent): completed ✓
  - Phase 9 (docs-agent): completed ✓
  - Phase 1 (infra-agent): in_progress
  - Phase 2 (backend-agent): pending
  - Phase 3 (storage-agent): pending

  Action:
  1. Validate Phase 1 completion
  2. If Phase 1 done: Mark complete, spawn agents for Phases 2, 3
  3. If Phase 1 partial: Complete remaining steps from PHASE-01.md
  4. Continue Wave 2 execution

  Scenario: "All phases complete, testing interrupted"

  EXECUTION-STATE.json shows:
  - Phases 1-10: completed ✓
  - Phase 11 (test-agent): in_progress

  Action:
  1. Run validation from PHASE-11.md
  2. Check: docker compose ps (should show 6 containers)
  3. Run: make test
  4. If tests pass: Mark Phase 11 complete, project done!
  5. If tests fail: Debug failures, fix, retry

  Scenario: "Phase failed, need to rollback"

  EXECUTION-STATE.json shows:
  - Phase 8 (platform-agent): failed
  - Error: "Cannot connect to mvp-postgres"

  Action:
  1. Review ROLLBACK-STRATEGY.md Phase 8 section
  2. Execute rollback procedure
  3. Fix root cause (check Phase 1, Phase 7 completion)
  4. Retry Phase 8
  5. Continue when successful

  Resuming by Wave

  If resuming in Wave 1:

  - Check if config-agent (Phase 4) completed
  - Check if docs-agent (Phase 9) completed
  - If both done: Proceed to Wave 2
  - If partial: Complete remaining work

  If resuming in Wave 2:

  - Validate Wave 1 completed (Phases 4, 9)
  - Check status of Phases 1, 2, 3
  - Spawn agents for incomplete phases
  - Wait for all Wave 2 to complete before Wave 3

  If resuming in Wave 3:

  - Validate Waves 1 and 2 completed
  - Check status of Phases 5, 6, 7, 8
  - Continue or spawn agents as needed
  - Ensure Phase 1 complete before starting Phase 8

  If resuming in Wave 4:

  - Validate Phase 6 (backend-agent) completed
  - Check status of Phase 10 (frontend-agent)
  - If incomplete: Spawn frontend-agent
  - If complete: Proceed to Wave 5

  If resuming in Wave 5:

  - Validate ALL Phases 1-10 completed
  - Run Phase 11 testing and validation
  - This is the final phase

  Key Commands for State Assessment

  # Check EXECUTION-STATE.json
  cat docs/redesign/EXECUTION-STATE.json | jq '.phases'

  # Check container count (should end at 6)
  docker compose ps --services | wc -l

  # Check for completed phases
  cat docs/redesign/EXECUTION-STATE.json | jq '.phases[] | select(.status == "completed") | .name'

  # Check for failed/in_progress phases
  cat docs/redesign/EXECUTION-STATE.json | jq '.phases[] | select(.status != "completed" and .status != "pending") |
  {name, status, errors}'

  # Quick validation
  docker compose config  # Should validate
  make test              # Should pass when complete

  Your First Actions

  1. Read and analyze: cat docs/redesign/EXECUTION-STATE.json
  2. Check system state: docker compose ps
  3. Determine position: Which wave are you in?
  4. Validate completed work: Run validation for "completed" phases
  5. Identify next steps: Which agents need to spawn?
  6. Resume execution: Continue from the correct point

  Important Notes

  - Never skip validation - Always validate completed phases before continuing
  - Never redo completed work - If a phase validates successfully, don't repeat it
  - Update state religiously - Keep EXECUTION-STATE.json current
  - Watch for cascading failures - A failed early phase blocks later phases
  - Be ready to rollback - Sometimes rolling back and retrying is faster than debugging

  Safety Protocol

  If you're uncertain about the state:
  1. Review VALIDATION-CHECKLIST.md for each "completed" phase
  2. Run validation commands to verify actual state
  3. Compare expected vs. actual (6 containers, 3 networks, etc.)
  4. When in doubt: Validate, don't assume

  Resume Now

  Analyze the current state using the steps above, then continue execution from the appropriate point. Report your
  findings and next actions before proceeding.

  ---