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:

Identify task type - Feature, platform service, frontend, or quality check
Assign appropriate agent(s) - Use Task tool with agent description
Monitor progress - Agents will report back when complete
Coordinate handoffs - Facilitate communication between agents
Review deliverables - Ensure quality and architecture compliance
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:

Expert Software Architect mediates
Review ownership boundaries
Clarify requirements
Assign clear responsibilities

If quality gates fail:

Quality Enforcer reports specific failures
Appropriate agent fixes issues
Quality Enforcer re-validates
Repeat until all green

If requirements unclear:

Agent requests clarification from Expert Software Architect
Architect provides clear direction
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.