From ea7f2a4945f138883e77a8b13186a2e074274b9a Mon Sep 17 00:00:00 2001 From: Eric Gullickson <16152721+ericgullickson@users.noreply.github.com> Date: Thu, 1 Jan 2026 22:17:25 -0600 Subject: [PATCH] chore: post AI agent refactor. Gitea integration --- .ai/WORKFLOW-PROMPTS.md | 162 +++++++++++++++ .ai/context.json | 32 ++- .ai/workflow-contract.json | 119 +++++++++++ .claude/agents/README.md | 330 +++---------------------------- .claude/agents/feature-agent.md | 34 ++++ .claude/agents/frontend-agent.md | 35 ++++ .claude/agents/platform-agent.md | 34 ++++ .claude/agents/quality-agent.md | 38 ++++ AI-INDEX.md | 22 --- CLAUDE.md | 18 +- README.md | 3 +- 11 files changed, 501 insertions(+), 326 deletions(-) create mode 100644 .ai/WORKFLOW-PROMPTS.md create mode 100644 .ai/workflow-contract.json delete mode 100644 AI-INDEX.md diff --git a/.ai/WORKFLOW-PROMPTS.md b/.ai/WORKFLOW-PROMPTS.md new file mode 100644 index 0000000..cdaa650 --- /dev/null +++ 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 diff --git a/.ai/context.json b/.ai/context.json index 63a57f1..07e3b11 100644 --- 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%", diff --git a/.ai/workflow-contract.json b/.ai/workflow-contract.json new file mode 100644 index 0000000..e052583 --- /dev/null +++ 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: ' 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: '." + ] + } +} diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 16801ec..17f7eca 100644 --- 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 diff --git a/.claude/agents/feature-agent.md b/.claude/agents/feature-agent.md index 069266a..d7f8b18 100644 --- 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 diff --git a/.claude/agents/frontend-agent.md b/.claude/agents/frontend-agent.md index a75e055..639759d 100644 --- 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 diff --git a/.claude/agents/platform-agent.md b/.claude/agents/platform-agent.md index bbea8af..81e20a3 100644 --- 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 diff --git a/.claude/agents/quality-agent.md b/.claude/agents/quality-agent.md index e7d1c04..b098f7d 100644 --- 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 diff --git a/AI-INDEX.md b/AI-INDEX.md deleted file mode 100644 index 472cf1c..0000000 --- a/AI-INDEX.md +++ /dev/null @@ -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` - diff --git a/CLAUDE.md b/CLAUDE.md index 7dce2bd..d1d0b5a 100644 --- 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 diff --git a/README.md b/README.md index 86f1ea7..13c2208 100644 --- 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`