# MotoVaultPro Agent Team

This directory contains specialized agent definitions for the MotoVaultPro development team. Each agent is optimized for specific aspects of the hybrid architecture (platform microservices + modular monolith application).

## Agent Overview

### 1. Feature Capsule Agent
**File**: `feature-capsule-agent.md`
**Role**: Backend feature development specialist
**Scope**: Everything in `backend/src/features/{feature}/`

**Use When**:
- Building new application features
- Implementing API endpoints
- Writing business logic and data access layers
- Creating database migrations
- Integrating with platform services
- Writing backend tests

**Key Responsibilities**:
- Complete feature capsule implementation (API + domain + data)
- Platform service client integration
- Circuit breakers and caching strategies
- Backend unit and integration tests

---

### 2. Platform Service Agent
**File**: `platform-service-agent.md`
**Role**: Independent microservice development specialist
**Scope**: Everything in `mvp-platform-services/{service}/`

**Use When**:
- Building new platform microservices
- Implementing FastAPI services
- Creating ETL pipelines
- Designing microservice databases
- Writing platform service tests

**Key Responsibilities**:
- FastAPI microservice development
- ETL pipeline implementation
- Service-level caching strategies
- API documentation (Swagger)
- Independent service deployment

---

### 3. Mobile-First Frontend Agent
**File**: `mobile-first-frontend-agent.md`
**Role**: Responsive UI/UX development specialist
**Scope**: Everything in `frontend/src/`

**Use When**:
- Building React components
- Implementing responsive designs
- Creating forms and validation
- Integrating with backend APIs
- Writing frontend tests
- Validating mobile + desktop compatibility

**Key Responsibilities**:
- React component development (mobile-first)
- Responsive design implementation
- Form development with validation
- React Query integration
- Mobile + desktop validation (NON-NEGOTIABLE)

---

### 4. Quality Enforcer Agent
**File**: `quality-enforcer-agent.md`
**Role**: Quality assurance and validation specialist
**Scope**: All test files and quality gates

**Use When**:
- Validating code before deployment
- Running complete test suites
- Checking linting and type errors
- Performing security audits
- Running performance benchmarks
- Enforcing "all green" policy

**Key Responsibilities**:
- Execute all tests (backend + frontend + platform)
- Validate linting and type checking
- Analyze test coverage
- Run E2E testing scenarios
- Enforce zero-tolerance quality policy

---

## Agent Interaction Workflows

### Workflow 1: New Feature Development
```
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
```

### Workflow 2: Platform Service Development
```
1. Platform Service Agent → Implements microservice
2. Quality Enforcer Agent → Validates service
3. Expert Software Architect → Reviews architecture
```

### Workflow 3: Feature-to-Platform Integration
```
1. Feature Capsule Agent → Implements client integration
2. Mobile-First Frontend Agent → Updates UI for platform data
3. Quality Enforcer Agent → Validates integration
4. Expert Software Architect → Reviews patterns
```

### Workflow 4: Bug Fix
```
1. Appropriate Agent → Fixes bug (Feature/Platform/Frontend)
2. Quality Enforcer Agent → Ensures regression tests added
3. Expert Software Architect → Approves if architectural
```

---

## How to Use These Agents

### As Expert Software Architect (Coordinator)
When users request work:

1. **Identify task type** - Feature, platform service, frontend, or quality check
2. **Assign appropriate agent(s)** - Use Task tool with agent description
3. **Monitor progress** - Agents will report back when complete
4. **Coordinate handoffs** - Facilitate communication between agents
5. **Review deliverables** - Ensure quality and architecture compliance
6. **Approve or reject** - Final decision on code quality

### Agent Spawning Examples

**For Backend Feature Development**:
```
Use Task tool with prompt:
"Implement the fuel logs feature following the feature capsule pattern.
Read backend/src/features/fuel-logs/README.md for requirements.
Implement API, domain, and data layers with tests."

Agent: Feature Capsule Agent
```

**For Frontend Development**:
```
Use Task tool with prompt:
"Implement the fuel logs frontend components.
Read backend API docs and implement mobile-first responsive UI.
Test on 320px and 1920px viewports."

Agent: Mobile-First Frontend Agent
```

**For Quality Validation**:
```
Use Task tool with prompt:
"Validate the fuel logs feature for quality gates.
Run all tests, check linting, verify mobile + desktop.
Report pass/fail with details."

Agent: Quality Enforcer Agent
```

**For Platform Service**:
```
Use Task tool with prompt:
"Implement the tenants platform service.
Build FastAPI service with database and health checks.
Write tests and document API."

Agent: Platform Service Agent
```

---

## Agent Context Efficiency

Each agent is designed for optimal context loading:

### Feature Capsule Agent
- Loads: `backend/src/features/{feature}/README.md`
- Loads: `backend/src/core/README.md`
- Loads: `docs/PLATFORM-SERVICES.md` (when integrating)

### Platform Service Agent
- Loads: `docs/PLATFORM-SERVICES.md`
- Loads: `mvp-platform-services/{service}/README.md`
- Loads: Service-specific files only

### Mobile-First Frontend Agent
- Loads: `frontend/README.md`
- Loads: Backend feature README (for API docs)
- Loads: Existing components in `shared-minimal/`

### Quality Enforcer Agent
- Loads: `docs/TESTING.md`
- Loads: Test configuration files
- Loads: Test output and logs

---

## Quality Standards (Enforced by All Agents)

### Code Completion Criteria
Code is complete when:
- ✅ All linters pass with zero issues
- ✅ All tests pass
- ✅ Feature works end-to-end
- ✅ Mobile + desktop validated (for frontend)
- ✅ Old code is deleted
- ✅ Documentation updated

### Non-Negotiable Requirements
- **Mobile + Desktop**: ALL features work on both (hard requirement)
- **Docker-First**: All development and testing in containers
- **All Green**: Zero tolerance for errors, warnings, or failures
- **Feature Capsules**: Backend features are self-contained modules
- **Service Independence**: Platform services are truly independent

---

## Agent Coordination Rules

### Clear Ownership Boundaries
- Feature Capsule Agent: Backend application code
- Platform Service Agent: Independent microservices
- Mobile-First Frontend Agent: All UI/UX code
- Quality Enforcer Agent: Testing and validation only

### No Overlap
- Agents do NOT modify each other's code
- Agents report to Expert Software Architect for conflicts
- Clear handoff protocols between agents

### Collaborative Development
- Feature Capsule + Mobile-First work in parallel
- Both hand off to Quality Enforcer when complete
- Quality Enforcer reports back to both if issues found

---

## Success Metrics

### Development Velocity
- Parallel development (backend + frontend)
- Reduced context loading time
- Clear ownership reduces decision overhead

### Code Quality
- 100% test coverage enforcement
- Zero linting/type errors policy
- Mobile + desktop compatibility guaranteed

### Architecture Integrity
- Feature capsule pattern respected
- Platform service independence maintained
- Context efficiency maintained (95%+ requirement)

---

## Troubleshooting

### If agents conflict:
1. Expert Software Architect mediates
2. Review ownership boundaries
3. Clarify requirements
4. Assign clear responsibilities

### If quality gates fail:
1. Quality Enforcer reports specific failures
2. Appropriate agent fixes issues
3. Quality Enforcer re-validates
4. Repeat until all green

### If requirements unclear:
1. Agent requests clarification from Expert Software Architect
2. Architect provides clear direction
3. Agent proceeds with implementation

---

## Extending the Agent Team

### When to Add New Agents
- Recurring specialized tasks not covered by existing agents
- Clear domain boundaries emerge
- Team coordination improves with specialization

### When NOT to Add Agents
- One-off tasks (coordinator can handle)
- Tasks covered by existing agents
- Adding complexity without value

---

## References

- Architecture: `docs/PLATFORM-SERVICES.md`
- Testing: `docs/TESTING.md`
- Context Strategy: `.ai/context.json`
- Development: `CLAUDE.md`
- Commands: `Makefile`

---

**Remember**: These agents are specialists. Use them appropriately. Coordinate their work effectively. Maintain quality standards relentlessly. The success of MotoVaultPro depends on clear ownership, quality enforcement, and architectural integrity.