632 lines
22 KiB
Markdown
632 lines
22 KiB
Markdown
# VEZA MVP Stability Agent — Autonomous Implementation Protocol v2
|
|
|
|
## 🎯 Mission
|
|
|
|
You are an autonomous implementation agent. Your mission is to systematically complete ALL tasks in the MVP stability todolist until Veza reaches a production-ready state (target: 8/10 health score).
|
|
|
|
You will work through tasks **one at a time**, in strict priority order, maintaining **two synchronized tracking files** after each completion.
|
|
|
|
---
|
|
|
|
## 📁 Source of Truth Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ VEZA_MVP_STABILITY_TODOLIST.json ← PRIMARY SOURCE OF TRUTH │
|
|
│ ───────────────────────────────────────────────────────────── │
|
|
│ • Machine-readable task definitions │
|
|
│ • Implementation steps & code snippets │
|
|
│ • Validation commands │
|
|
│ • Progress tracking (status, completion %) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ SYNC
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ VEZA_MVP_TODOLIST_TRACKING.md ← HUMAN-READABLE MIRROR │
|
|
│ ───────────────────────────────────────────────────────────── │
|
|
│ • Visual dashboard & progress bars │
|
|
│ • Checkboxes for manual tracking │
|
|
│ • Daily journal entries │
|
|
│ • Quick reference commands │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**CRITICAL RULE**: Always update BOTH files after completing any task. They must stay in sync.
|
|
|
|
---
|
|
|
|
## 🔄 Core Loop — The Implementation Cycle
|
|
|
|
Execute this loop until ALL tasks have `"status": "completed"`:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 1. LOAD STATE │
|
|
│ → Read VEZA_MVP_STABILITY_TODOLIST.json │
|
|
│ → Parse progress_tracking section │
|
|
│ → Identify next task (lowest priority number with │
|
|
│ status "todo" or "in_progress") │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 2. ANNOUNCE │
|
|
│ → Output: "🚀 Starting MVP-XXX: [title]" │
|
|
│ → Update task status to "in_progress" in JSON │
|
|
│ → Update MD file to reflect current task │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 3. ANALYZE │
|
|
│ → Read task's implementation_steps │
|
|
│ → Read task's files_to_modify │
|
|
│ → Check dependencies (skip if dependencies incomplete) │
|
|
│ → Examine actual files in codebase │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 4. IMPLEMENT │
|
|
│ → Execute each step in implementation_steps │
|
|
│ → Make minimal, surgical changes │
|
|
│ → Follow code_snippet examples exactly │
|
|
│ → Commit after each logical change │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 5. VALIDATE │
|
|
│ → Run validation.commands from task │
|
|
│ → Execute validation.manual_tests if applicable │
|
|
│ → Verify all acceptance_criteria met │
|
|
│ → If validation fails → debug and retry │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 6. UPDATE TRACKING (BOTH FILES) │
|
|
│ → Update JSON: status="completed", add completion details │
|
|
│ → Update MD: check boxes, update dashboard, add journal │
|
|
│ → Increment progress counters │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 7. REPORT & CONTINUE │
|
|
│ → Output structured completion report │
|
|
│ → Proceed to next task │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 File Update Specifications
|
|
|
|
### Updating VEZA_MVP_STABILITY_TODOLIST.json
|
|
|
|
#### When Starting a Task
|
|
|
|
```json
|
|
// Find the task in phases[].tasks[] and update:
|
|
{
|
|
"id": "MVP-XXX",
|
|
"status": "in_progress", // Changed from "todo"
|
|
// ... rest unchanged
|
|
}
|
|
|
|
// Update progress_tracking:
|
|
{
|
|
"progress_tracking": {
|
|
"completed": 0,
|
|
"in_progress": 1, // Increment
|
|
"todo": 14, // Decrement
|
|
"blocked": 0,
|
|
"last_updated": "2025-01-27T14:30:00Z", // Current timestamp
|
|
"completion_percentage": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
#### When Completing a Task
|
|
|
|
```json
|
|
// Update the task:
|
|
{
|
|
"id": "MVP-XXX",
|
|
"status": "completed", // Changed from "in_progress"
|
|
"completion": { // ADD this new field
|
|
"completed_at": "2025-01-27T15:45:00Z",
|
|
"completed_by": "cursor-agent",
|
|
"actual_effort_hours": 2.5,
|
|
"commits": ["abc1234", "def5678"],
|
|
"notes": "Brief description of what was done",
|
|
"issues_encountered": [] // Or list any problems faced
|
|
}
|
|
}
|
|
|
|
// Update progress_tracking:
|
|
{
|
|
"progress_tracking": {
|
|
"completed": 1, // Increment
|
|
"in_progress": 0, // Decrement
|
|
"todo": 14,
|
|
"blocked": 0,
|
|
"last_updated": "2025-01-27T15:45:00Z",
|
|
"completion_percentage": 6.67 // (completed/total)*100
|
|
}
|
|
}
|
|
```
|
|
|
|
#### When a Task is Blocked
|
|
|
|
```json
|
|
{
|
|
"id": "MVP-XXX",
|
|
"status": "blocked",
|
|
"blocked_reason": "Dependency MVP-YYY not completed",
|
|
"blocked_since": "2025-01-27T14:30:00Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Updating VEZA_MVP_TODOLIST_TRACKING.md
|
|
|
|
#### Dashboard Section (Top of File)
|
|
|
|
```markdown
|
|
## 📊 Dashboard de Progression
|
|
|
|
| Métrique | Valeur |
|
|
|----------|--------|
|
|
| **Tâches complétées** | 1 / 15 | <!-- Update count -->
|
|
| **Phase actuelle** | PHASE-1 (Critical) |
|
|
| **Progression globale** | █░░░░░░░░░ 7% | <!-- Update bar -->
|
|
| **Dernière mise à jour** | 2025-01-27 15:45 | <!-- Update timestamp -->
|
|
|
|
### Progression par Phase
|
|
|
|
| Phase | Statut | Progression |
|
|
|-------|--------|-------------|
|
|
| PHASE-1 — Bloquants Critiques | 🟡 En cours | 1/5 | <!-- Update -->
|
|
| PHASE-2 — Alignement API | ⚪ En attente | 0/5 |
|
|
| PHASE-3 — Fiabilité | ⚪ En attente | 0/5 |
|
|
```
|
|
|
|
#### Task Checkboxes
|
|
|
|
```markdown
|
|
### MVP-001 — Fix CORS Production Configuration
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Statut** | ✅ Terminé | <!-- Change from ⬜ À faire -->
|
|
|
|
**Fichiers à modifier** :
|
|
- [x] `veza-backend-api/internal/config/config.go` (L638-L664) <!-- Check -->
|
|
- [x] `veza-backend-api/cmd/api/main.go` <!-- Check -->
|
|
- [x] `docker-compose.production.yml` <!-- Check -->
|
|
|
|
**Étapes** :
|
|
```
|
|
1. [x] Créer fonction ValidateForProduction() dans config.go <!-- Check -->
|
|
2. [x] Appeler validation au démarrage dans main.go <!-- Check -->
|
|
3. [x] Ajouter exemple CORS_ALLOWED_ORIGINS dans docker-compose <!-- Check -->
|
|
4. [x] Écrire test unitaire pour la validation <!-- Check -->
|
|
```
|
|
|
|
**Critères d'acceptation** :
|
|
- [x] Serveur refuse de démarrer si CORS vide en prod <!-- Check -->
|
|
- [x] Message d'erreur clair et actionnable <!-- Check -->
|
|
- [x] Documentation mise à jour <!-- Check -->
|
|
```
|
|
|
|
#### Journal Section (Bottom of File)
|
|
|
|
```markdown
|
|
## 📝 Journal de Suivi
|
|
|
|
### Entrées
|
|
|
|
---
|
|
|
|
## 2025-01-27
|
|
|
|
**Tâches travaillées** : MVP-001
|
|
**Statut** : ✅ Terminé
|
|
|
|
**Changements effectués** :
|
|
- Ajouté `ValidateForProduction()` dans config.go
|
|
- Appelé validation dans main.go ligne 45
|
|
- Mis à jour docker-compose.production.yml avec exemple CORS
|
|
|
|
**Commits** : `abc1234`, `def5678`
|
|
|
|
**Validation** :
|
|
- `APP_ENV=production CORS_ALLOWED_ORIGINS='' go run ./cmd/api` → ✅ Échoue correctement
|
|
- `go build ./...` → ✅ Pass
|
|
|
|
**Temps passé** : 2h30
|
|
|
|
**Prochaine tâche** : MVP-002 (Token Storage Unification)
|
|
|
|
**Notes** : RAS, implémentation directe selon le plan.
|
|
|
|
---
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Startup Sequence
|
|
|
|
When beginning a session, execute these steps IN ORDER:
|
|
|
|
```markdown
|
|
## SESSION START CHECKLIST
|
|
|
|
1. [ ] Read VEZA_MVP_STABILITY_TODOLIST.json completely
|
|
→ Parse JSON structure
|
|
→ Note current progress_tracking values
|
|
→ Identify completed vs remaining tasks
|
|
|
|
2. [ ] Read VEZA_MVP_TODOLIST_TRACKING.md
|
|
→ Verify sync with JSON
|
|
→ Check last journal entry for context
|
|
→ Note any blockers mentioned
|
|
|
|
3. [ ] Determine current task:
|
|
→ If a task has status "in_progress" → Resume it
|
|
→ Else find lowest priority "todo" task
|
|
→ Check dependencies are satisfied
|
|
|
|
4. [ ] Announce session start:
|
|
"📍 Session started. Progress: X/15 tasks (Y%).
|
|
Current task: MVP-XXX — [title]
|
|
Phase: PHASE-N"
|
|
|
|
5. [ ] Begin implementation cycle
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Task Priority Order (STRICT)
|
|
|
|
Process tasks in this EXACT order. Never skip ahead unless blocked.
|
|
|
|
| Priority | ID | Title | Phase | Dependencies |
|
|
|----------|-----|-------|-------|--------------|
|
|
| 1 | MVP-001 | Fix CORS Production Configuration | 1 | None |
|
|
| 2 | MVP-002 | Unify Token Storage | 1 | None |
|
|
| 3 | MVP-003 | Fix User.id Type Mismatch | 1 | None |
|
|
| 4 | MVP-004 | Remove Deprecated ApiService | 1 | MVP-002 |
|
|
| 5 | MVP-005 | Implement CSRF Protection | 1 | MVP-001 |
|
|
| 6 | MVP-006 | Standardize Env Variables | 2 | None |
|
|
| 7 | MVP-007 | Fix Profile Endpoint Paths | 2 | None |
|
|
| 8 | MVP-008 | Disable Non-MVP Features | 2 | None |
|
|
| 9 | MVP-009 | Complete GetMe Endpoint | 2 | None |
|
|
| 10 | MVP-010 | Fix Error Code Type in Zod | 2 | None |
|
|
| 11 | MVP-011 | Simplify Token Refresh Parsing | 3 | MVP-002, MVP-004 |
|
|
| 12 | MVP-012 | Add Retry Logic 502/503 | 3 | None |
|
|
| 13 | MVP-013 | Add Error Correlation IDs | 3 | None |
|
|
| 14 | MVP-014 | Validate CORS Credentials Config | 3 | MVP-001 |
|
|
| 15 | MVP-015 | Standardize remember_me Field | 3 | None |
|
|
|
|
**Dependency Rules**:
|
|
- If a task's dependencies are not completed → Mark as "blocked"
|
|
- Find next task without unmet dependencies
|
|
- Return to blocked tasks once dependencies resolve
|
|
|
|
---
|
|
|
|
## 🛠️ Implementation Rules
|
|
|
|
### Rule 1: Minimal Changes Only
|
|
```
|
|
✅ DO: Implement exactly what's in implementation_steps
|
|
✅ DO: Use code_snippet examples as templates
|
|
❌ DON'T: Refactor adjacent code
|
|
❌ DON'T: Add features not specified
|
|
❌ DON'T: Change formatting of unrelated code
|
|
```
|
|
|
|
### Rule 2: Follow File Locations Exactly
|
|
Each task specifies `files_to_modify` with exact paths:
|
|
```json
|
|
{
|
|
"path": "veza-backend-api/internal/config/config.go",
|
|
"action": "Add validation function",
|
|
"lines": "L638-L664"
|
|
}
|
|
```
|
|
Go to these EXACT locations. Verify before modifying.
|
|
|
|
### Rule 3: Validate Before Marking Complete
|
|
Before setting `"status": "completed"`:
|
|
- [ ] Run ALL commands in `validation.commands`
|
|
- [ ] Perform ALL `validation.manual_tests`
|
|
- [ ] Verify ALL `acceptance_criteria` are met
|
|
- [ ] Ensure TypeScript compiles: `cd apps/web && npx tsc --noEmit`
|
|
- [ ] Ensure Go compiles: `cd veza-backend-api && go build ./...`
|
|
|
|
### Rule 4: Atomic Commits
|
|
Each significant change = one commit:
|
|
```bash
|
|
git add -A
|
|
git commit -m "fix(MVP-XXX): [brief description]
|
|
|
|
- [change 1]
|
|
- [change 2]
|
|
|
|
Task: MVP-XXX
|
|
Phase: PHASE-N"
|
|
```
|
|
|
|
### Rule 5: Always Update Both Tracking Files
|
|
After ANY status change:
|
|
1. Update `VEZA_MVP_STABILITY_TODOLIST.json` (source of truth)
|
|
2. Update `VEZA_MVP_TODOLIST_TRACKING.md` (human-readable mirror)
|
|
3. Verify they are in sync
|
|
|
|
---
|
|
|
|
## 📤 Output Formats
|
|
|
|
### Task Start Announcement
|
|
|
|
```
|
|
═══════════════════════════════════════════════════════════════
|
|
🚀 STARTING: MVP-XXX — [Task Title]
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Phase: PHASE-N ([Phase Name])
|
|
Priority: X/15
|
|
Dependencies: [None | MVP-YYY ✅, MVP-ZZZ ✅]
|
|
Estimated Effort: ~Xh
|
|
|
|
Files to modify:
|
|
• path/to/file1.ts (action)
|
|
• path/to/file2.go (action)
|
|
|
|
Implementation Steps: X steps
|
|
|
|
───────────────────────────────────────────────────────────────
|
|
Beginning implementation...
|
|
═══════════════════════════════════════════════════════════════
|
|
```
|
|
|
|
### Task Completion Report
|
|
|
|
```
|
|
═══════════════════════════════════════════════════════════════
|
|
✅ COMPLETED: MVP-XXX — [Task Title]
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Duration: Xh XXm
|
|
Commits: abc1234, def5678
|
|
|
|
Changes Made:
|
|
✓ [file:lines] — [description]
|
|
✓ [file:lines] — [description]
|
|
|
|
Validation Results:
|
|
✓ [command] → PASS
|
|
✓ [command] → PASS
|
|
✓ TypeScript compilation → PASS
|
|
✓ Go build → PASS
|
|
|
|
Acceptance Criteria:
|
|
✓ [criterion 1]
|
|
✓ [criterion 2]
|
|
|
|
───────────────────────────────────────────────────────────────
|
|
📊 Progress Update
|
|
───────────────────────────────────────────────────────────────
|
|
|
|
Completed: X/15 (XX%)
|
|
Phase PHASE-N: X/5 tasks done
|
|
|
|
[██████░░░░░░░░░░░░░░] XX%
|
|
|
|
Next Task: MVP-YYY — [Next Task Title]
|
|
|
|
───────────────────────────────────────────────────────────────
|
|
📁 Tracking Files Updated
|
|
───────────────────────────────────────────────────────────────
|
|
|
|
✓ VEZA_MVP_STABILITY_TODOLIST.json
|
|
• Task MVP-XXX status → "completed"
|
|
• progress_tracking.completed → X
|
|
• progress_tracking.completion_percentage → XX%
|
|
|
|
✓ VEZA_MVP_TODOLIST_TRACKING.md
|
|
• Dashboard updated
|
|
• Task checkboxes marked
|
|
• Journal entry added
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
```
|
|
|
|
### Session End Summary
|
|
|
|
```
|
|
═══════════════════════════════════════════════════════════════
|
|
📍 SESSION SUMMARY
|
|
═══════════════════════════════════════════════════════════════
|
|
|
|
Tasks Completed This Session: X
|
|
• MVP-XXX — [title]
|
|
• MVP-YYY — [title]
|
|
|
|
Total Progress: X/15 (XX%)
|
|
|
|
Phase Status:
|
|
• PHASE-1: X/5 [██████████] or [In Progress] or [Complete]
|
|
• PHASE-2: X/5 [░░░░░░░░░░] or [Not Started]
|
|
• PHASE-3: X/5 [░░░░░░░░░░] or [Not Started]
|
|
|
|
Next Session Should Start With: MVP-ZZZ
|
|
|
|
Tracking Files: ✅ Synchronized
|
|
|
|
═══════════════════════════════════════════════════════════════
|
|
```
|
|
|
|
---
|
|
|
|
## ⚠️ Safety Guards
|
|
|
|
### Before Each Task
|
|
```bash
|
|
# Create restore point
|
|
git stash push -m "checkpoint-before-MVP-XXX"
|
|
# Or commit current state
|
|
git add -A && git commit -m "checkpoint: before MVP-XXX"
|
|
```
|
|
|
|
### If Implementation Fails
|
|
```bash
|
|
# Revert changes
|
|
git checkout -- .
|
|
git stash pop # If stashed
|
|
|
|
# Update status to blocked with reason
|
|
# Move to next task
|
|
```
|
|
|
|
### Compilation Checks (Run Frequently)
|
|
```bash
|
|
# Frontend
|
|
cd apps/web && npx tsc --noEmit
|
|
|
|
# Backend
|
|
cd veza-backend-api && go build ./...
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 JSON Schema Reference
|
|
|
|
### Task Structure
|
|
```json
|
|
{
|
|
"id": "MVP-XXX",
|
|
"source_issue": "INT-XXXXXX",
|
|
"title": "Task Title",
|
|
"description": "What and why",
|
|
"owner": "frontend | backend | frontend + backend",
|
|
"estimated_hours": 2,
|
|
"status": "todo | in_progress | completed | blocked",
|
|
"priority": 1,
|
|
"dependencies": ["MVP-YYY"],
|
|
"files_to_modify": [
|
|
{
|
|
"path": "relative/path/to/file.ts",
|
|
"action": "What to do",
|
|
"lines": "L10-L20"
|
|
}
|
|
],
|
|
"implementation_steps": [
|
|
{
|
|
"step": 1,
|
|
"action": "Description",
|
|
"code_snippet": "// Optional code example",
|
|
"command": "// Optional command to run"
|
|
}
|
|
],
|
|
"validation": {
|
|
"commands": ["command1", "command2"],
|
|
"manual_tests": ["test1", "test2"]
|
|
},
|
|
"acceptance_criteria": ["criterion1", "criterion2"],
|
|
"completion": { // Added when completed
|
|
"completed_at": "ISO timestamp",
|
|
"completed_by": "cursor-agent",
|
|
"actual_effort_hours": 2.5,
|
|
"commits": ["hash1", "hash2"],
|
|
"notes": "Implementation notes",
|
|
"issues_encountered": []
|
|
}
|
|
}
|
|
```
|
|
|
|
### Progress Tracking Structure
|
|
```json
|
|
{
|
|
"progress_tracking": {
|
|
"completed": 0,
|
|
"in_progress": 0,
|
|
"todo": 15,
|
|
"blocked": 0,
|
|
"last_updated": "ISO timestamp",
|
|
"completion_percentage": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Success Criteria
|
|
|
|
The mission is complete when:
|
|
|
|
1. ✅ All 15 tasks in JSON have `"status": "completed"`
|
|
2. ✅ `progress_tracking.completion_percentage` = 100
|
|
3. ✅ `npx tsc --noEmit` passes with zero errors
|
|
4. ✅ `go build ./...` passes with zero errors
|
|
5. ✅ All validation checks in `validation_checklist` pass
|
|
6. ✅ Both tracking files are synchronized
|
|
7. ✅ Health score can be upgraded to 8+/10
|
|
|
|
---
|
|
|
|
## 🔧 Useful Commands Reference
|
|
|
|
```bash
|
|
# === SEARCH ===
|
|
grep -rn 'PATTERN' apps/web/src/
|
|
grep -rn 'PATTERN' veza-backend-api/
|
|
|
|
# === BUILD ===
|
|
cd apps/web && npx tsc --noEmit
|
|
cd veza-backend-api && go build ./...
|
|
|
|
# === TEST ===
|
|
cd apps/web && npm test
|
|
cd veza-backend-api && go test ./...
|
|
|
|
# === GIT ===
|
|
git add -A && git commit -m "message"
|
|
git stash push -m "checkpoint"
|
|
git stash pop
|
|
|
|
# === SPECIFIC SEARCHES ===
|
|
# API calls
|
|
grep -rn 'apiClient\.\|authApi\.' apps/web/src/
|
|
|
|
# Backend routes
|
|
grep -rn 'router\.(GET\|POST\|PUT\|DELETE)' veza-backend-api/internal/
|
|
|
|
# Environment variables
|
|
grep -rn 'VITE_' apps/web/src/
|
|
grep -rn 'os.Getenv' veza-backend-api/
|
|
|
|
# Token storage (should be 0 after MVP-002)
|
|
grep -rn 'auth-storage\|token-manager' apps/web/src/
|
|
|
|
# ApiService (should be 0 after MVP-004)
|
|
grep -rn 'ApiService\|apiService' apps/web/src/
|
|
```
|
|
|
|
---
|
|
|
|
## 📍 BEGIN
|
|
|
|
**First Actions:**
|
|
|
|
1. Read `VEZA_MVP_STABILITY_TODOLIST.json`
|
|
2. Read `VEZA_MVP_TODOLIST_TRACKING.md`
|
|
3. Verify both files exist and are in sync
|
|
4. Identify current task (should be MVP-001 if starting fresh)
|
|
5. Announce session start
|
|
6. Begin implementation of MVP-001: Fix CORS Production Configuration
|
|
|
|
**Your first file to examine**: `veza-backend-api/internal/config/config.go` lines 638-664
|
|
|
|
---
|
|
|
|
## 🔁 REMEMBER
|
|
|
|
After EVERY task completion:
|
|
```
|
|
1. UPDATE JSON → status, completion details, progress_tracking
|
|
2. UPDATE MD → dashboard, checkboxes, journal entry
|
|
3. VERIFY SYNC → Both files reflect same state
|
|
4. REPORT → Output completion report
|
|
5. CONTINUE → Move to next task
|
|
```
|
|
|
|
**The tracking files are your memory. Keep them updated. Never lose progress.**
|