egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: post AI agent refactor. Gitea integration

Browse Source
This commit is contained in:
Eric Gullickson
2026-01-01 22:17:25 -06:00
parent d554e8bcb5
commit ea7f2a4945
11 changed files with 501 additions and 326 deletions
Download Patch File Download Diff File Expand all files Collapse all files

330
.claude/agents/README.md
View File

@@ -1,313 +1,45 @@
# 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).
Specialized agents for MotoVaultPro development. Each agent has detailed instructions in their own file.
## Agent Overview
## Quick Reference
### 1. Feature Capsule Agent
**File**: `feature-capsule-agent.md`
**Role**: Backend feature development specialist
**Scope**: Everything in `backend/src/features/{feature}/`
| Agent | File | Use When |
|-------|------|----------|
| Feature Agent | `feature-agent.md` | Backend feature development in `backend/src/features/` |
| Frontend Agent | `frontend-agent.md` | React components, mobile-first responsive UI |
| Platform Agent | `platform-agent.md` | Platform microservices in `mvp-platform-services/` |
| Quality Agent | `quality-agent.md` | Final validation before merge/deploy |
**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
## Sprint Workflow
**Key Responsibilities**:
- Complete feature capsule implementation (API + domain + data)
- Platform service client integration
- Circuit breakers and caching strategies
- Backend unit and integration tests
All agents follow the sprint workflow defined in `.ai/workflow-contract.json`:
---
1. Pick issue from current sprint with `status/ready`
2. Move to `status/in-progress`, create branch `issue-{index}-{slug}`
3. Implement with commits referencing issue
4. Open PR, move to `status/review`
5. Quality Agent validates before `status/done`
### 2. Platform Service Agent
**File**: `platform-service-agent.md`
**Role**: Independent microservice development specialist
**Scope**: Everything in `mvp-platform-services/{service}/`
## Coordination
**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
- Feature + Frontend agents can work in parallel
- Quality Agent validates all work before completion
- Conflicts escalate to Expert Software Architect
### 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
## Context Loading
---
Each agent loads minimal context:
- `.ai/context.json` - Architecture overview
- `.ai/workflow-contract.json` - Sprint workflow
- Their specific agent file - Role and responsibilities
- Feature/component README - Task-specific context
## Success Metrics
## Quality Standards (All Agents)
### 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.
- All linters pass (zero errors)
- All tests pass
- Mobile + desktop validated
- Old code deleted
- Documentation updated