Merge branch 'main' of 172.30.1.72:egullickson/motovaultpro

chore: post AI agent refactor. Gitea integration
chore: pre-AI Agent gitea workflow changes
2026-01-03 09:54:04 -06:00 · 2026-01-01 22:17:25 -06:00 · 2026-01-01 21:38:50 -06:00
19 changed files with 761 additions and 352 deletions
--- a/.ai/WORKFLOW-PROMPTS.md
+++ b/.ai/WORKFLOW-PROMPTS.md
@@ -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
--- a/.ai/context.json
+++ b/.ai/context.json
@@ -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%",
--- a/.ai/workflow-contract.json
+++ b/.ai/workflow-contract.json
@@ -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>'."
+    ]
+  }
+}
--- a/.claude/agents/README.md
+++ b/.claude/agents/README.md
@@ -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
--- a/.claude/agents/feature-agent.md
+++ b/.claude/agents/feature-agent.md
@@ -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
--- a/.claude/agents/frontend-agent.md
+++ b/.claude/agents/frontend-agent.md
@@ -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
--- a/.claude/agents/platform-agent.md
+++ b/.claude/agents/platform-agent.md
@@ -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
--- a/.claude/agents/quality-agent.md
+++ b/.claude/agents/quality-agent.md
@@ -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
--- a/.gitea/ISSUE_TEMPLATE/bug.yaml
+++ b/.gitea/ISSUE_TEMPLATE/bug.yaml
@@ -0,0 +1,56 @@
+name: "Bug"
+about: "Something is broken or incorrect"
+title: "[Bug]: "
+labels:
+  - "type/bug"
+  - "status/backlog"
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: "Bug summary"
+      description: "What’s wrong?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: "Steps to reproduce"
+      placeholder: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: "Expected behavior"
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: "Actual behavior"
+    validations:
+      required: true
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: "Impact / severity"
+      placeholder: "Who is affected? How badly? Workaround?"
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: "Logs / screenshots"
+      description: "Paste logs or link images. Redact secrets."
+      render: shell
+    validations:
+      required: false
--- a/.gitea/ISSUE_TEMPLATE/chore.yaml
+++ b/.gitea/ISSUE_TEMPLATE/chore.yaml
@@ -0,0 +1,41 @@
+name: "Chore"
+about: "Refactor, maintenance, dependency updates, cleanup"
+title: "[Chore]: "
+labels:
+  - "type/chore"
+  - "status/backlog"
+body:
+  - type: textarea
+    id: goal
+    attributes:
+      label: "Goal"
+      description: "What needs to be done and why?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: "Scope"
+      placeholder: |
+        - Includes:
+        - Excludes:
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: "Acceptance criteria"
+      placeholder: |
+        - [ ] ...
+        - [ ] ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: test_plan
+    attributes:
+      label: "Test plan"
+    validations:
+      required: true
--- a/.gitea/ISSUE_TEMPLATE/config.yaml
+++ b/.gitea/ISSUE_TEMPLATE/config.yaml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: "Docs / Architecture"
+    url: "https://<YOUR-DOCS-URL>"
+    about: "System design notes, decisions, and reference docs"
--- a/.gitea/ISSUE_TEMPLATE/feature.yml
+++ b/.gitea/ISSUE_TEMPLATE/feature.yml
@@ -0,0 +1,70 @@
+name: "Feature"
+about: "New capability or enhancement"
+title: "[Feature]: "
+labels:
+  - "type/feature"
+  - "status/backlog"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for a new feature or enhancement. Keep scope tight and include clear acceptance criteria.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: "Problem / user need"
+      description: "What problem are we solving, and for whom?"
+      placeholder: "As a user, I want..., so that..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: "Proposed solution"
+      description: "Describe the expected behavior at a high level."
+      placeholder: "When the user does X, the system should..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: non_goals
+    attributes:
+      label: "Non-goals / out of scope"
+      description: "What are we explicitly not doing in this feature?"
+      placeholder: "- Not doing...\n- Not doing..."
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: "Acceptance criteria"
+      description: "Concrete checks for ‘done’. Prefer bullets and testable statements."
+      placeholder: |
+        - [ ] ...
+        - [ ] ...
+        - [ ] ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: "Implementation notes (optional)"
+      description: "Links, APIs, file paths, edge cases."
+    validations:
+      required: false
+
+  - type: textarea
+    id: test_plan
+    attributes:
+      label: "Test plan"
+      description: "How will we verify? Include commands or steps."
+      placeholder: |
+        - Unit:
+        - Integration:
+        - Manual:
+    validations:
+      required: true
--- a/.gitea/PULL_REQUEST_TEMPLATE.md
+++ b/.gitea/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,29 @@
+## Summary
+- What does this PR change?
+
+## Linked issues
+- Fixes #
+- Relates to #
+
+## Type
+- [ ] Feature
+- [ ] Bug fix
+- [ ] Chore / refactor
+- [ ] Docs
+
+## Test plan
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] Manual verification
+
+**Commands / steps:**
+1.
+2.
+
+## Screenshots / UI notes (if applicable)
+
+## Checklist
+- [ ] Acceptance criteria met (from linked issue)
+- [ ] No secrets committed
+- [ ] Logging is appropriate (no PII)
+- [ ] Docs updated (if needed)
--- a/.gitea/SPRINTS.md
+++ b/.gitea/SPRINTS.md
@@ -0,0 +1,36 @@
+# SPRINTS.md — MotoVaultPro Sprint Calendar (2026)
+
+**Cadence:** 2 weeks (14 days)  
+**Sprint weeks:** Monday → Sunday  
+**Naming convention:** `Sprint YYYY-MM-DD` (the Monday start date)
+
+> Note: Sprint 26 ends on **2027-01-03** (it crosses into the next year).
+
+| # | Sprint | Start (Mon) | End (Sun) |
+|---:|---|---|---|
+| 1 | Sprint 2026-01-05 | 2026-01-05 | 2026-01-18 |
+| 2 | Sprint 2026-01-19 | 2026-01-19 | 2026-02-01 |
+| 3 | Sprint 2026-02-02 | 2026-02-02 | 2026-02-15 |
+| 4 | Sprint 2026-02-16 | 2026-02-16 | 2026-03-01 |
+| 5 | Sprint 2026-03-02 | 2026-03-02 | 2026-03-15 |
+| 6 | Sprint 2026-03-16 | 2026-03-16 | 2026-03-29 |
+| 7 | Sprint 2026-03-30 | 2026-03-30 | 2026-04-12 |
+| 8 | Sprint 2026-04-13 | 2026-04-13 | 2026-04-26 |
+| 9 | Sprint 2026-04-27 | 2026-04-27 | 2026-05-10 |
+| 10 | Sprint 2026-05-11 | 2026-05-11 | 2026-05-24 |
+| 11 | Sprint 2026-05-25 | 2026-05-25 | 2026-06-07 |
+| 12 | Sprint 2026-06-08 | 2026-06-08 | 2026-06-21 |
+| 13 | Sprint 2026-06-22 | 2026-06-22 | 2026-07-05 |
+| 14 | Sprint 2026-07-06 | 2026-07-06 | 2026-07-19 |
+| 15 | Sprint 2026-07-20 | 2026-07-20 | 2026-08-02 |
+| 16 | Sprint 2026-08-03 | 2026-08-03 | 2026-08-16 |
+| 17 | Sprint 2026-08-17 | 2026-08-17 | 2026-08-30 |
+| 18 | Sprint 2026-08-31 | 2026-08-31 | 2026-09-13 |
+| 19 | Sprint 2026-09-14 | 2026-09-14 | 2026-09-27 |
+| 20 | Sprint 2026-09-28 | 2026-09-28 | 2026-10-11 |
+| 21 | Sprint 2026-10-12 | 2026-10-12 | 2026-10-25 |
+| 22 | Sprint 2026-10-26 | 2026-10-26 | 2026-11-08 |
+| 23 | Sprint 2026-11-09 | 2026-11-09 | 2026-11-22 |
+| 24 | Sprint 2026-11-23 | 2026-11-23 | 2026-12-06 |
+| 25 | Sprint 2026-12-07 | 2026-12-07 | 2026-12-20 |
+| 26 | Sprint 2026-12-21 | 2026-12-21 | 2027-01-03 |
--- a/.mcp.json
+++ b/.mcp.json
@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "gitea-mcp": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "--env",
+        "GITEA_ACCESS_TOKEN=88f2ac07f148676a79ce413c7f5ca4912468c500",
+        "--env",
+        "GITEA_HOST=https://git.motovaultpro.com",
+        "docker.gitea.com/gitea-mcp-server"
+      ],
+      "env": {}
+    }
+  }
+}
--- a/AI-INDEX.md
+++ b/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`
-
--- a/CLAUDE.md
+++ b/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
--- a/README.md
+++ b/README.md
@@ -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`
--- a/docs/PROMPTS.md
+++ b/docs/PROMPTS.md
@@ -30,8 +30,10 @@ You are a senior software engineer specializsing in NodeJS, Typescript, front en
 *** CHANGES TO IMPLEMENT ***
 - Research this code base and ask iterative questions to compile a complete plan.
 - We will pair troubleshoot this. Tell me what logs and things to run and I will 
- There is a backup system built into the admin settings.
- Uploading a backup to restore throws a 400 API error. 
+- There is current a Dark / Light theme option for this application
+- There is logic somewhere in the code that detects the operating systems' theme and uses that. Remove this. 
+- Default to the
+


 *** ROLE ***
@@ -56,30 +58,6 @@ You are a senior software engineer specializsing in NodeJS, Typescript, front en
 - We will pair plan this. Ask me for options for various levels of redundancy and automation


-*** STAGING CONTAINER IMAGES ***
-egullickson@mvp-build:~$ sudo docker image ls
-                                                                                                                                                                                                                  i Info →   U  In Use
-IMAGE                                                         ID             DISK USAGE   CONTENT SIZE   EXTRA
-git.motovaultpro.com/egullickson/backend:3321d82              67b2480ddac5        485MB         76.3MB    U
-git.motovaultpro.com/egullickson/frontend:3321d82             e3e1ee18df42       96.1MB         28.7MB    U
-git.motovaultpro.com/egullickson/mirrors/postgres:18-alpine   6723ec6d445f        402MB          112MB    U
-git.motovaultpro.com/egullickson/mirrors/redis:8.4-alpine     8360960f5fb5        130MB         33.4MB    U
-git.motovaultpro.com/egullickson/mirrors/traefik:v3.6         13e903c820df        239MB           52MB    U
-egullickson@mvp-build:~$
-
-*** PRODUCTION CONTAINER IMAGES ***
-
-egullickson@mvp-prod:~$ sudo docker image ls
-                                                                                                                                                                                                                  i Info →   U  In Use
-IMAGE                                                         ID             DISK USAGE   CONTENT SIZE   EXTRA
-git.motovaultpro.com/egullickson/backend:latest               67b2480ddac5        485MB         76.3MB    U
-git.motovaultpro.com/egullickson/frontend:latest              e3e1ee18df42       96.1MB         28.7MB    U
-git.motovaultpro.com/egullickson/mirrors/postgres:18-alpine   6723ec6d445f        402MB          112MB    U
-git.motovaultpro.com/egullickson/mirrors/redis:8.4-alpine     8360960f5fb5        130MB         33.4MB    U
-git.motovaultpro.com/egullickson/mirrors/traefik:v3.6         13e903c820df        239MB           52MB    U
-egullickson@mvp-prod:~$
-
-

 *** ROLE ***
 - You are a senior DBA with expert knowledge in Postgres SQL.
Author	SHA1	Message	Date
Eric Gullickson	01297424e1	Merge branch 'main' of 172.30.1.72:egullickson/motovaultpro All checks were successful Deploy to Staging / Build Images (push) Successful in 23s Details Deploy to Staging / Deploy to Staging (push) Successful in 36s Details Deploy to Staging / Verify Staging (push) Successful in 6s Details Deploy to Staging / Notify Staging Ready (push) Successful in 5s Details Deploy to Staging / Notify Staging Failure (push) Has been skipped Details	2026-01-03 09:54:04 -06:00
Eric Gullickson	ea7f2a4945	chore: post AI agent refactor. Gitea integration	2026-01-01 22:17:25 -06:00
Eric Gullickson	d554e8bcb5	chore: pre-AI Agent gitea workflow changes	2026-01-01 21:38:50 -06:00