chore: post AI agent refactor. Gitea integration

2026-01-01 22:17:25 -06:00
parent d554e8bcb5
commit ea7f2a4945
11 changed files with 501 additions and 326 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>'."
+    ]
+  }
+}