314 lines
8.7 KiB
Markdown
314 lines
8.7 KiB
Markdown
# 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.
|