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

34
.claude/agents/feature-agent.md
View File

@@ -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

35
.claude/agents/frontend-agent.md
View File

@@ -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

34
.claude/agents/platform-agent.md
View File

@@ -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

38
.claude/agents/quality-agent.md
View File

@@ -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