chore: post AI agent refactor. Gitea integration
This commit is contained in:
Eric Gullickson
@@ -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
|
||||
|
||||
@@ -81,6 +81,40 @@ backend/src/features/{feature}/
|
||||
- Avoid loading unrelated features
|
||||
- Trust feature README as source of truth
|
||||
|
||||
## Sprint Workflow Integration
|
||||
|
||||
Follow the workflow contract in `.ai/workflow-contract.json`.
|
||||
|
||||
### Before Starting Work
|
||||
1. Check current sprint milestone via `mcp__gitea-mcp__list_milestones`
|
||||
2. List issues with `status/ready` via `mcp__gitea-mcp__list_repo_issues`
|
||||
3. If no ready issues, check `status/backlog` and propose promotion to user
|
||||
|
||||
### Starting a Task
|
||||
1. Verify issue has `status/ready` and `type/*` labels
|
||||
2. Remove `status/ready`, add `status/in-progress` via `mcp__gitea-mcp__replace_issue_labels`
|
||||
3. Create branch `issue-{index}-{slug}` via `mcp__gitea-mcp__create_branch`
|
||||
4. Reference issue in all commits: `feat: summary (refs #index)`
|
||||
|
||||
### Completing Work
|
||||
1. Ensure all quality gates pass (linting, type-check, tests)
|
||||
2. Open PR via `mcp__gitea-mcp__create_pull_request` with:
|
||||
- Title: `feat: summary (#index)`
|
||||
- Body: `Fixes #index` + test plan + acceptance criteria
|
||||
3. Move issue to `status/review`
|
||||
4. Hand off to Quality Agent for final validation
|
||||
5. After merge: issue moves to `status/done`
|
||||
|
||||
### MCP Tools Reference
|
||||
```
|
||||
mcp__gitea-mcp__list_repo_issues - List issues (filter by state/milestone)
|
||||
mcp__gitea-mcp__get_issue_by_index - Get issue details
|
||||
mcp__gitea-mcp__replace_issue_labels - Update status labels
|
||||
mcp__gitea-mcp__create_branch - Create feature branch
|
||||
mcp__gitea-mcp__create_pull_request - Open PR
|
||||
mcp__gitea-mcp__list_milestones - Check current sprint
|
||||
```
|
||||
|
||||
## Key Skills and Technologies
|
||||
|
||||
### Backend Stack
|
||||
|
||||
@@ -95,6 +95,41 @@ frontend/
|
||||
- Avoid loading backend implementation details
|
||||
- Reference existing components before creating new ones
|
||||
|
||||
## Sprint Workflow Integration
|
||||
|
||||
Follow the workflow contract in `.ai/workflow-contract.json`.
|
||||
|
||||
### Before Starting Work
|
||||
1. Check current sprint milestone via `mcp__gitea-mcp__list_milestones`
|
||||
2. List issues with `status/ready` via `mcp__gitea-mcp__list_repo_issues`
|
||||
3. Coordinate with Feature Agent if frontend depends on backend API
|
||||
|
||||
### Starting a Task
|
||||
1. Verify issue has `status/ready` and `type/*` labels
|
||||
2. Remove `status/ready`, add `status/in-progress` via `mcp__gitea-mcp__replace_issue_labels`
|
||||
3. Create branch `issue-{index}-{slug}` via `mcp__gitea-mcp__create_branch`
|
||||
4. Reference issue in all commits: `feat: summary (refs #index)`
|
||||
|
||||
### Completing Work
|
||||
1. Ensure all quality gates pass (TypeScript, ESLint, tests)
|
||||
2. Validate mobile (320px) AND desktop (1920px) viewports
|
||||
3. Open PR via `mcp__gitea-mcp__create_pull_request` with:
|
||||
- Title: `feat: summary (#index)`
|
||||
- Body: `Fixes #index` + test plan + mobile/desktop validation notes
|
||||
4. Move issue to `status/review`
|
||||
5. Hand off to Quality Agent for final validation
|
||||
6. After merge: issue moves to `status/done`
|
||||
|
||||
### MCP Tools Reference
|
||||
```
|
||||
mcp__gitea-mcp__list_repo_issues - List issues (filter by state/milestone)
|
||||
mcp__gitea-mcp__get_issue_by_index - Get issue details
|
||||
mcp__gitea-mcp__replace_issue_labels - Update status labels
|
||||
mcp__gitea-mcp__create_branch - Create feature branch
|
||||
mcp__gitea-mcp__create_pull_request - Open PR
|
||||
mcp__gitea-mcp__list_milestones - Check current sprint
|
||||
```
|
||||
|
||||
## Key Skills and Technologies
|
||||
|
||||
### Frontend Stack
|
||||
|
||||
@@ -89,6 +89,40 @@ mvp-platform-services/{service}/
|
||||
- No cross-service dependencies to consider
|
||||
- Service directory is self-contained
|
||||
|
||||
## Sprint Workflow Integration
|
||||
|
||||
Follow the workflow contract in `.ai/workflow-contract.json`.
|
||||
|
||||
### Before Starting Work
|
||||
1. Check current sprint milestone via `mcp__gitea-mcp__list_milestones`
|
||||
2. List issues with `status/ready` via `mcp__gitea-mcp__list_repo_issues`
|
||||
3. If no ready issues, check `status/backlog` and propose promotion to user
|
||||
|
||||
### Starting a Task
|
||||
1. Verify issue has `status/ready` and `type/*` labels
|
||||
2. Remove `status/ready`, add `status/in-progress` via `mcp__gitea-mcp__replace_issue_labels`
|
||||
3. Create branch `issue-{index}-{slug}` via `mcp__gitea-mcp__create_branch`
|
||||
4. Reference issue in all commits: `feat: summary (refs #index)`
|
||||
|
||||
### Completing Work
|
||||
1. Ensure all quality gates pass (pytest, Swagger docs, health checks)
|
||||
2. Open PR via `mcp__gitea-mcp__create_pull_request` with:
|
||||
- Title: `feat: summary (#index)`
|
||||
- Body: `Fixes #index` + test plan + API changes documented
|
||||
3. Move issue to `status/review`
|
||||
4. Hand off to Quality Agent for final validation
|
||||
5. After merge: issue moves to `status/done`
|
||||
|
||||
### MCP Tools Reference
|
||||
```
|
||||
mcp__gitea-mcp__list_repo_issues - List issues (filter by state/milestone)
|
||||
mcp__gitea-mcp__get_issue_by_index - Get issue details
|
||||
mcp__gitea-mcp__replace_issue_labels - Update status labels
|
||||
mcp__gitea-mcp__create_branch - Create feature branch
|
||||
mcp__gitea-mcp__create_pull_request - Open PR
|
||||
mcp__gitea-mcp__list_milestones - Check current sprint
|
||||
```
|
||||
|
||||
## Key Skills and Technologies
|
||||
|
||||
### Python Stack
|
||||
|
||||
@@ -88,6 +88,44 @@ Your role is validation, not implementation. You ensure quality, not create func
|
||||
- Avoid deep diving into business logic
|
||||
- Reference documentation for standards
|
||||
|
||||
## Sprint Workflow Integration
|
||||
|
||||
Follow the workflow contract in `.ai/workflow-contract.json`.
|
||||
|
||||
**CRITICAL ROLE**: You are the gatekeeper for `status/review` -> `status/done` transitions.
|
||||
|
||||
### Receiving Issues for Validation
|
||||
1. Check issues with `status/review` via `mcp__gitea-mcp__list_repo_issues`
|
||||
2. Issues in `status/review` are awaiting your validation
|
||||
3. Do NOT proceed with work until validation is complete
|
||||
|
||||
### Validation Process
|
||||
1. Read the linked issue to understand acceptance criteria
|
||||
2. Pull the PR branch and run complete validation suite
|
||||
3. Execute all quality gates (see checklists below)
|
||||
4. If any gate fails: report specific failures, do NOT approve
|
||||
|
||||
### Completing Validation
|
||||
**If ALL gates pass:**
|
||||
1. Approve the PR
|
||||
2. After merge: move issue to `status/done` via `mcp__gitea-mcp__replace_issue_labels`
|
||||
3. Issue can be closed or left for sprint history
|
||||
|
||||
**If ANY gate fails:**
|
||||
1. Comment on issue with specific failures and required fixes
|
||||
2. Move issue back to `status/in-progress` if major rework needed
|
||||
3. Leave at `status/review` for minor fixes
|
||||
4. Do NOT approve PR until all gates pass
|
||||
|
||||
### MCP Tools Reference
|
||||
```
|
||||
mcp__gitea-mcp__list_repo_issues - List issues with status/review
|
||||
mcp__gitea-mcp__get_issue_by_index - Get issue details and acceptance criteria
|
||||
mcp__gitea-mcp__replace_issue_labels - Move to status/done or status/in-progress
|
||||
mcp__gitea-mcp__create_issue_comment - Report validation results
|
||||
mcp__gitea-mcp__get_pull_request_by_index - Check PR status
|
||||
```
|
||||
|
||||
## Key Skills and Technologies
|
||||
|
||||
### Testing Frameworks
|
||||
|
||||
Reference in New Issue
Block a user