chore: post AI agent refactor. Gitea integration
This commit is contained in:
Eric Gullickson
162
.ai/WORKFLOW-PROMPTS.md
Normal file
162
.ai/WORKFLOW-PROMPTS.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# MotoVaultPro Workflow Prompts
|
||||
|
||||
Ready-to-use prompts for the sprint workflow. Copy and customize as needed.
|
||||
|
||||
---
|
||||
|
||||
## Prompt 1: Start Sprint Work (Pick Up an Issue)
|
||||
|
||||
```
|
||||
*** ROLE ***
|
||||
You are senior software architect on MotoVaultPro. Follow the sprint workflow in `.ai/workflow-contract.json`.
|
||||
|
||||
*** ACTION ***
|
||||
1. Read `.ai/context.json` and `.ai/workflow-contract.json`
|
||||
2. Check the current sprint milestone via Gitea MCP
|
||||
3. List issues with `status/ready` label
|
||||
4. If none ready, show me `status/backlog` issues and recommend which to promote
|
||||
5. Present the top 3 candidates ranked by priority/size
|
||||
6. Dispatch multiple agents for their specific tasks.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt 2: Work On a Specific Issue
|
||||
|
||||
```
|
||||
*** ROLE ***
|
||||
You are the [feature-agent | frontend-agent | platform-agent]. Read your agent file at `.claude/agents/[agent]-agent.md`.
|
||||
|
||||
*** CONTEXT ***
|
||||
- Read `.ai/workflow-contract.json` for sprint workflow
|
||||
- Issue to work on: #[NUMBER]
|
||||
|
||||
*** ACTION ***
|
||||
1. Get issue details via `mcp__gitea-mcp__get_issue_by_index`
|
||||
2. Move issue to `status/in-progress`
|
||||
3. Create branch `issue-[NUMBER]-[slug]`
|
||||
4. Implement the acceptance criteria
|
||||
5. Open PR when complete and move to `status/review`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt 3: Quality Validation
|
||||
|
||||
```
|
||||
*** ROLE ***
|
||||
You are the quality-agent. Read `.claude/agents/quality-agent.md`.
|
||||
|
||||
*** ACTION ***
|
||||
1. List issues with `status/review` label
|
||||
2. For each issue awaiting validation:
|
||||
- Read acceptance criteria
|
||||
- Run all quality gates (linting, type-check, tests, mobile+desktop)
|
||||
- Report PASS or FAIL with specific details
|
||||
3. If PASS: approve PR, move issue to `status/done` after merge
|
||||
4. If FAIL: comment on issue with required fixes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt 4: Sprint Planning Session
|
||||
|
||||
```
|
||||
*** ROLE ***
|
||||
You are helping plan Sprint [YYYY-MM-DD].
|
||||
|
||||
*** ACTION ***
|
||||
1. Check if milestone exists via `mcp__gitea-mcp__list_milestones`
|
||||
2. If not, create it via `mcp__gitea-mcp__create_milestone`
|
||||
3. List all `status/backlog` issues
|
||||
4. Recommend issues to promote to `status/ready` for this sprint
|
||||
5. Consider: dependencies, priority, size, and sprint capacity
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt 5: Create New Issue
|
||||
|
||||
```
|
||||
*** ROLE ***
|
||||
Use the Gitea MCP to create a new issue.
|
||||
|
||||
*** CONTEXT ***
|
||||
- Type: [feature | bug | chore | docs]
|
||||
- Title: [TITLE]
|
||||
- Description: [DESCRIPTION]
|
||||
|
||||
*** ACTION ***
|
||||
1. Create issue via `mcp__gitea-mcp__create_issue`
|
||||
2. Add labels: `type/[type]` and `status/backlog`
|
||||
3. Optionally assign to current sprint milestone
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt 6: Sprint Status Report
|
||||
|
||||
```
|
||||
*** ROLE ***
|
||||
Generate a sprint status report.
|
||||
|
||||
*** ACTION ***
|
||||
1. Get current sprint milestone via `mcp__gitea-mcp__list_milestones`
|
||||
2. List all issues in the sprint milestone
|
||||
3. Group by status label (ready, in-progress, review, done, blocked)
|
||||
4. Calculate: total issues, completed, remaining, blocked
|
||||
5. Present summary with any blockers highlighted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt 7: End of Sprint Review
|
||||
|
||||
```
|
||||
*** ROLE ***
|
||||
Conduct end-of-sprint review for Sprint [YYYY-MM-DD].
|
||||
|
||||
*** ACTION ***
|
||||
1. List all issues that were in this sprint milestone
|
||||
2. Summarize: completed (status/done), incomplete, blocked
|
||||
3. For incomplete issues: recommend carry-over to next sprint or return to backlog
|
||||
4. Create next sprint milestone if it doesn't exist
|
||||
5. Move carry-over issues to new sprint milestone
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: MCP Tools
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `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__create_issue` | Create new issue |
|
||||
| `mcp__gitea-mcp__edit_issue` | Update issue (title, body, state) |
|
||||
| `mcp__gitea-mcp__add_issue_labels` | Add labels to issue |
|
||||
| `mcp__gitea-mcp__remove_issue_label` | Remove label from issue |
|
||||
| `mcp__gitea-mcp__replace_issue_labels` | Replace all labels on issue |
|
||||
| `mcp__gitea-mcp__list_milestones` | List sprint milestones |
|
||||
| `mcp__gitea-mcp__create_milestone` | Create new sprint |
|
||||
| `mcp__gitea-mcp__create_branch` | Create feature branch |
|
||||
| `mcp__gitea-mcp__create_pull_request` | Open PR |
|
||||
| `mcp__gitea-mcp__list_repo_pull_requests` | List PRs |
|
||||
|
||||
---
|
||||
|
||||
## Label Reference
|
||||
|
||||
**Status Labels** (exactly one per issue):
|
||||
- `status/backlog` - Not yet ready to work on
|
||||
- `status/ready` - Ready to be picked up
|
||||
- `status/in-progress` - Currently being worked on
|
||||
- `status/review` - PR open, awaiting validation
|
||||
- `status/blocked` - Cannot proceed (document blocker)
|
||||
- `status/done` - Completed and merged
|
||||
|
||||
**Type Labels** (exactly one per issue):
|
||||
- `type/feature` - New capability
|
||||
- `type/bug` - Something broken
|
||||
- `type/chore` - Maintenance/refactor
|
||||
- `type/docs` - Documentation only
|
||||
@@ -1,6 +1,36 @@
|
||||
{
|
||||
"version": "6.0.0",
|
||||
"version": "6.1.0",
|
||||
"architecture": "simplified-5-container",
|
||||
"ai_quick_start": {
|
||||
"load_order": [
|
||||
".ai/context.json (this file) - architecture and metadata",
|
||||
".ai/workflow-contract.json - sprint workflow for issue tracking",
|
||||
".ai/WORKFLOW-PROMPTS.md - ready-to-use prompts for common tasks",
|
||||
"docs/README.md - documentation hub"
|
||||
],
|
||||
"work_modes": {
|
||||
"feature_work": "backend/src/features/{feature}/ (start with README.md)",
|
||||
"frontend_work": "frontend/README.md",
|
||||
"core_backend": "backend/src/core/README.md"
|
||||
},
|
||||
"commands": {
|
||||
"setup": "make setup | start | rebuild | migrate | logs",
|
||||
"shells": "make shell-backend | make shell-frontend",
|
||||
"database": "make db-shell-app"
|
||||
},
|
||||
"docs_hubs": {
|
||||
"main": "docs/README.md",
|
||||
"testing": "docs/TESTING.md",
|
||||
"database": "docs/DATABASE-SCHEMA.md",
|
||||
"security": "docs/SECURITY.md",
|
||||
"vehicles_api": "docs/VEHICLES-API.md"
|
||||
},
|
||||
"urls": {
|
||||
"frontend": "https://motovaultpro.com",
|
||||
"backend_health": "https://motovaultpro.com/api/health",
|
||||
"hosts_entry": "127.0.0.1 motovaultpro.com"
|
||||
}
|
||||
},
|
||||
"critical_requirements": {
|
||||
"mobile_desktop_development": "ALL features MUST be implemented and tested on BOTH mobile and desktop",
|
||||
"context_efficiency": "95%",
|
||||
|
||||
119
.ai/workflow-contract.json
Normal file
119
.ai/workflow-contract.json
Normal file
@@ -0,0 +1,119 @@
|
||||
{
|
||||
"name": "MotoVaultPro Solo Sprint Workflow",
|
||||
"version": "1.0",
|
||||
"principles": [
|
||||
"Issues are the source of truth.",
|
||||
"One status label per issue.",
|
||||
"Work is timeboxed into 14-day sprints using milestones.",
|
||||
"Every PR must link to at least one issue and satisfy its acceptance criteria."
|
||||
],
|
||||
"sprints": {
|
||||
"length_days": 14,
|
||||
"milestone_naming": "Sprint YYYY-MM-DD (start date)",
|
||||
"default_start_day": "Monday",
|
||||
"calendar_reference": ".gitea/SPRINTS.md",
|
||||
"process": [
|
||||
"If a milestone for the current sprint does not exist, create it.",
|
||||
"Assign selected issues to the current sprint milestone."
|
||||
]
|
||||
},
|
||||
"labels": {
|
||||
"status_prefix": "status/",
|
||||
"status_values": [
|
||||
"status/backlog",
|
||||
"status/ready",
|
||||
"status/in-progress",
|
||||
"status/review",
|
||||
"status/blocked",
|
||||
"status/done"
|
||||
],
|
||||
"type_prefix": "type/",
|
||||
"type_values": [
|
||||
"type/feature",
|
||||
"type/bug",
|
||||
"type/chore",
|
||||
"type/docs"
|
||||
],
|
||||
"rules": [
|
||||
"Exactly one status/* label must be present on open issues.",
|
||||
"Exactly one type/* label must be present on issues.",
|
||||
"When moving status, remove the previous status/* label first."
|
||||
]
|
||||
},
|
||||
"branching": {
|
||||
"branch_format": "issue-{index}-{slug}",
|
||||
"target_branch": "main",
|
||||
"example": "issue-42-add-fuel-efficiency-report"
|
||||
},
|
||||
"commit_conventions": {
|
||||
"message_format": "{type}: {short summary} (refs #{index})",
|
||||
"allowed_types": ["feat", "fix", "chore", "docs", "refactor", "test"],
|
||||
"examples": [
|
||||
"feat: add fuel efficiency calculation (refs #42)",
|
||||
"fix: correct VIN validation for pre-1981 vehicles (refs #1)"
|
||||
]
|
||||
},
|
||||
"pull_requests": {
|
||||
"title_format": "{type}: {summary} (#{index})",
|
||||
"body_requirements": [
|
||||
"Link issue(s) using 'Fixes #123' or 'Relates to #123'.",
|
||||
"Include test plan and results.",
|
||||
"Confirm acceptance criteria completion."
|
||||
],
|
||||
"merge_policy": "squash_or_rebase_ok",
|
||||
"template_location": ".gitea/PULL_REQUEST_TEMPLATE.md"
|
||||
},
|
||||
"execution_loop": [
|
||||
"List repo issues in current sprint milestone with status/ready; if none, pull from status/backlog and promote the best candidate to status/ready.",
|
||||
"Select one issue (prefer smallest size and highest priority).",
|
||||
"Move issue to status/in-progress.",
|
||||
"Create branch issue-{index}-{slug}.",
|
||||
"Implement changes with focused commits.",
|
||||
"Open PR targeting main and linking issue(s).",
|
||||
"Move issue to status/review.",
|
||||
"If CI/tests fail, iterate until pass.",
|
||||
"When PR is merged, move issue to status/done and close issue if not auto-closed."
|
||||
],
|
||||
"gitea_mcp_tools": {
|
||||
"repository": {
|
||||
"owner": "egullickson",
|
||||
"repo": "motovaultpro"
|
||||
},
|
||||
"issue_operations": {
|
||||
"list_issues": "mcp__gitea-mcp__list_repo_issues",
|
||||
"get_issue": "mcp__gitea-mcp__get_issue_by_index",
|
||||
"create_issue": "mcp__gitea-mcp__create_issue",
|
||||
"edit_issue": "mcp__gitea-mcp__edit_issue"
|
||||
},
|
||||
"label_operations": {
|
||||
"list_labels": "mcp__gitea-mcp__list_repo_labels",
|
||||
"add_labels": "mcp__gitea-mcp__add_issue_labels",
|
||||
"remove_label": "mcp__gitea-mcp__remove_issue_label",
|
||||
"replace_labels": "mcp__gitea-mcp__replace_issue_labels"
|
||||
},
|
||||
"milestone_operations": {
|
||||
"list_milestones": "mcp__gitea-mcp__list_milestones",
|
||||
"create_milestone": "mcp__gitea-mcp__create_milestone",
|
||||
"get_milestone": "mcp__gitea-mcp__get_milestone"
|
||||
},
|
||||
"branch_operations": {
|
||||
"list_branches": "mcp__gitea-mcp__list_branches",
|
||||
"create_branch": "mcp__gitea-mcp__create_branch"
|
||||
},
|
||||
"pr_operations": {
|
||||
"list_prs": "mcp__gitea-mcp__list_repo_pull_requests",
|
||||
"create_pr": "mcp__gitea-mcp__create_pull_request",
|
||||
"get_pr": "mcp__gitea-mcp__get_pull_request_by_index"
|
||||
}
|
||||
},
|
||||
"fallbacks": {
|
||||
"if_label_update_not_available_in_mcp": [
|
||||
"Use REST API issue label endpoints to add/replace labels.",
|
||||
"If REST is unavailable, add a comment 'STATUS: <status/...>' and proceed, but do not leave multiple status labels."
|
||||
],
|
||||
"if_milestone_ops_not_available_in_mcp": [
|
||||
"Use REST API to create/list milestones and assign issues to the sprint milestone.",
|
||||
"If milestone cannot be set, add a comment 'SPRINT: <milestone name>'."
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
|
||||
22
AI-INDEX.md
22
AI-INDEX.md
@@ -1,22 +0,0 @@
|
||||
# MotoVaultPro AI Index
|
||||
|
||||
- Load Order: `.ai/context.json`, then `docs/README.md`.
|
||||
- Architecture: Simplified 5-container stack (Traefik, Frontend, Backend, PostgreSQL, Redis) with platform feature integrated into backend.
|
||||
- Work Modes:
|
||||
- Feature work: `backend/src/features/{feature}/` (start with `README.md`).
|
||||
- Commands (containers only):
|
||||
- `make setup | start | rebuild | migrate | logs | logs-backend | logs-frontend`
|
||||
- Shells: `make shell-backend` | `make shell-frontend`
|
||||
- Docs Hubs:
|
||||
- Docs index: `docs/README.md`
|
||||
- Testing: `docs/TESTING.md`
|
||||
- Database: `docs/DATABASE-SCHEMA.md`
|
||||
- Security: `docs/SECURITY.md`
|
||||
- Vehicles API: `docs/VEHICLES-API.md`
|
||||
- Core Backend Modules: `backend/src/core/` (see `backend/src/core/README.md`).
|
||||
- Frontend Overview: `frontend/README.md`.
|
||||
- URLs and Hosts:
|
||||
- Frontend: `https://motovaultpro.com`
|
||||
- Backend health: `https://motovaultpro.com/api/health`
|
||||
- Add to `/etc/hosts`: `127.0.0.1 motovaultpro.com`
|
||||
|
||||
18
CLAUDE.md
18
CLAUDE.md
@@ -108,13 +108,25 @@ Leverage subagents aggressively for better results:
|
||||
|
||||
## AI Loading Context Strategies
|
||||
|
||||
Canonical sources only — avoid duplication:
|
||||
- Loading strategy and metadata: `.ai/context.json`
|
||||
- Documentation hub and links: `docs/README.md`
|
||||
Canonical sources only - avoid duplication:
|
||||
- Architecture and metadata: `.ai/context.json`
|
||||
- Sprint workflow contract: `.ai/workflow-contract.json`
|
||||
- Documentation hub: `docs/README.md`
|
||||
- Feature work: `backend/src/features/{feature}/README.md`
|
||||
- Platform architecture: `docs/PLATFORM-SERVICES.md`
|
||||
- Testing workflow: `docs/TESTING.md`
|
||||
|
||||
## Sprint Workflow
|
||||
|
||||
Issues are the source of truth. See `.ai/workflow-contract.json` for complete workflow.
|
||||
|
||||
### Quick Reference
|
||||
- Every PR must link to at least one issue
|
||||
- Use Gitea MCP tools for issue/label/branch/PR operations
|
||||
- Labels: `status/backlog` -> `status/ready` -> `status/in-progress` -> `status/review` -> `status/done`
|
||||
- Branches: `issue-{index}-{slug}` (e.g., `issue-42-add-fuel-report`)
|
||||
- Commits: `{type}: {summary} (refs #{index})` (e.g., `feat: add fuel report (refs #42)`)
|
||||
|
||||
## Architecture Context for AI
|
||||
|
||||
### Simplified 5-Container Architecture
|
||||
|
||||
@@ -17,7 +17,8 @@ make migrate # run DB migrations
|
||||
```
|
||||
|
||||
## Documentation
|
||||
- AI quickload: `AI-INDEX.md`
|
||||
- AI context: `.ai/context.json` (architecture, quick start, metadata)
|
||||
- Sprint workflow: `.ai/workflow-contract.json` (issue tracking)
|
||||
- Docs hub: `docs/README.md`
|
||||
- Features: `backend/src/features/{name}/README.md`
|
||||
- Frontend: `frontend/README.md`
|
||||
|
||||
Reference in New Issue
Block a user