diff --git a/.ai-agents/chains/custom/azure-devops-parent-processor.chain.yaml b/.ai-agents/chains/custom/azure-devops-parent-processor.chain.yaml index 31df28c..c6b5607 100644 --- a/.ai-agents/chains/custom/azure-devops-parent-processor.chain.yaml +++ b/.ai-agents/chains/custom/azure-devops-parent-processor.chain.yaml @@ -42,14 +42,14 @@ parameters: target_branch: type: string required: false - default: "main" - description: "Branche cible pour les PRs" - + default: "develop" + description: "Branche cible pour les PRs (develop par défaut)" + auto_complete_prs: type: boolean required: false default: false - description: "Auto-merge les PRs si tous les checks passent" + description: "❌ TOUJOURS false - Auto-merge INTERDIT (review humaine requise)" # Phases du workflow phases: @@ -130,11 +130,37 @@ phases: max_iterations: "{{ max_iterations }}" checkpoint_enabled: true instructions: | + ⚠️ **RÈGLES STRICTES DE WORKFLOW GIT** ⚠️ + + ❌ **INTERDICTIONS ABSOLUES** : + 1. NE JAMAIS pousser directement sur develop + 2. NE JAMAIS pousser directement sur main + 3. NE JAMAIS pousser directement sur master + 4. NE JAMAIS merger automatiquement les PRs + 5. NE JAMAIS réutiliser une branche pour plusieurs tickets + + ✅ **OBLIGATIONS** : + 1. TOUJOURS créer une branche feature depuis develop à jour + 2. TOUJOURS pousser sur la branche feature uniquement + 3. TOUJOURS créer une PR pour review humaine + 4. TOUJOURS référencer le ticket dans les commits (#) + + 📚 **Documentation** : Voir .ai/mcp/WORKFLOW_BRANCHES.md pour détails complets + + --- + Pour chaque ticket enfant (séquentiellement): - + + ## 0. Vérification initiale ⚠️ + - Vérifier que la branche actuelle N'EST PAS develop/main/master + - Si sur develop/main/master → ERREUR et arrêt + - Git checkout develop UNIQUEMENT pour créer la nouvelle branche + ## 1. Préparation - - Créer une branche: feature/{{ ticket.type }}-{{ ticket.id }}-{{ ticket.title | slugify }} - - Checkout la branche + - Git checkout develop (temporairement pour créer branche) + - Git pull origin develop (mise à jour) + - Créer une branche: feature/{{ ticket.id }}-{{ ticket.title | slugify }} + - Git checkout feature/{{ ticket.id }}-{{ ticket.title | slugify }} - Mettre à jour le statut Azure DevOps: "Active" (In Progress) - Via MCP: mcp:ado:update_work_item({{ ticket.id }}, state="Active") @@ -185,14 +211,22 @@ phases: ``` **Push:** + ⚠️ **CRITICAL - Vérifier la branche avant push** : ```bash - git push origin feature/{{ ticket.type }}-{{ ticket.id }}-{{ ticket.title | slugify }} + # ✅ CORRECT - Push sur branche feature UNIQUEMENT + git push origin feature/{{ ticket.id }}-{{ ticket.title | slugify }} + + # ❌ INTERDIT - NE JAMAIS faire ces commandes + # git push origin develop ← INTERDIT + # git push origin main ← INTERDIT + # git push origin master ← INTERDIT ``` - + **Créer PR via MCP:** + ⚠️ **IMPORTANT** : auto_complete doit TOUJOURS être false (review humaine requise) ``` mcp:ado:create_pull_request( - title: "{{ ticket.type }} #{{ ticket.id }}: {{ ticket.title }}", + title: "[#{{ ticket.id }}] {{ ticket.title }}", description: " ## Ticket Azure DevOps [AB#{{ ticket.id }}]({{ ticket.url }}) @@ -440,3 +474,27 @@ recovery: checkpoint_enabled: true checkpoint_file: ".checkpoints/azure-parent-{{ parent_ticket_id }}.json" resume_command: "@resume-chain azure-devops-parent-processor --checkpoint {{ checkpoint_file }}" + +# Documentation +documentation: + guides: + - path: "docs/guides/azure-devops-parent-tickets-guide.md" + description: "Guide complet d'utilisation du workflow" + - path: ".ai/mcp/WORKFLOW_BRANCHES.md" + description: "⚠️ IMPORTANT - Stratégie Git et règles de branches strictes" + - path: ".ai/mcp/PROMPT_WORKFLOW_TICKETS.md" + description: "Prompt optimisé avec gestion branches détaillée" + - path: ".ai/mcp/servers/README.md" + description: "Configuration MCP modulaire (Azure DevOps + SonarQube)" + + quick_reference: + usage: "@chain:azure-devops-parent-processor --parent-id 586655" + target_branch_default: "develop" + auto_merge: "TOUJOURS false (review humaine requise)" + + critical_rules: + - "❌ NE JAMAIS pousser sur develop/main/master" + - "❌ NE JAMAIS merger automatiquement les PRs" + - "✅ TOUJOURS créer branche feature depuis develop" + - "✅ TOUJOURS pousser sur branche feature uniquement" + - "✅ TOUJOURS créer PR pour review humaine" diff --git a/.ai/mcp/PROMPT_WORKFLOW_TICKETS.md b/.ai/mcp/PROMPT_WORKFLOW_TICKETS.md new file mode 100644 index 0000000..ebb3b7c --- /dev/null +++ b/.ai/mcp/PROMPT_WORKFLOW_TICKETS.md @@ -0,0 +1,355 @@ +# Prompt Optimisé : Workflow Automatisé Azure DevOps + +## 🎯 Prompt Principal + +``` +@loop "Traiter automatiquement les tickets fils du parent Azure DevOps #586655" + +## CONTEXTE +- Organisation: ebp-informatique +- Projet: MéCa +- Parent: https://dev.azure.com/ebp-informatique/MéCa/_workitems/edit/586655 +- Stack: .NET + SonarQube +- Architecture MCP: Modulaire (Config projet + Variables env) +- Stratégie de branches: Feature branches + PR (PAS de push direct sur develop) + +## MCP SERVERS DISPONIBLES +✅ azure-devops (wrapper custom projet) +✅ sonarqube (wrapper custom projet) +✅ github, git, filesystem (standards) +✅ ai-agent-kit (agents: @dotnet-developer, @dotnet-unit-tester) + +## WORKFLOW AUTOMATISÉ + +### Phase 1: Récupération +1. Via MCP azure-devops: Lister enfants de #586655 +2. Trier par Priority DESC, filtrer State != "Closed" +3. Logger: "📋 Trouvé X tickets à traiter" + +### Phase 2: Traitement par ticket +Pour chaque enfant: + +#### A. Analyse initiale +- Récupérer détails via MCP azure-devops +- Vérifier dépendances bloquantes +- Logger: "🎫 Traitement de # - " + +#### B. Gestion des branches +**IMPORTANT - Stratégie de branches** : + +1. **Créer UNE nouvelle branche par ticket** : + ```bash + git checkout develop + git pull origin develop + git checkout -b feature/- + ``` + Exemples : + - `feature/586656-authentification-jwt` + - `feature/586657-fix-validation-email` + +2. **Commits sur la branche feature** : + - Format: `feat/fix/refactor(scope): message` + - Référencer le ticket: `feat(auth): Add JWT validation #586656` + - Commits atomiques et descriptifs + +3. **NE PAS pousser directement sur develop** ❌ : + ```bash + # ❌ INTERDIT + git push origin develop + + # ✅ CORRECT + git push origin feature/- + ``` + +4. **Créer la Pull Request** : + - Via MCP github ou gh CLI + - Base branch: `develop` + - Head branch: `feature/-` + - Titre: `[#] ` + - Description: Résumé des changements + référence ticket Azure DevOps + - **NE PAS merger automatiquement** (attendre review) + +#### C. Routing par type +- **Bug** → @chain:bugfix --ticket-id + - Reproduire le bug + - Identifier root cause + - Fix + tests de régression + - Commits: `fix(scope): description #` + +- **User Story / Feature** → @chain:backend-feature --ticket-id + - Implémenter fonctionnalité + - Tests unitaires (>90% coverage) + - Tests d'intégration si API + - Commits: `feat(scope): description #` + +- **Task / Technical Debt** → @chain:quickfix --ticket-id + - Implémenter changement + - Tests adaptés au contexte + - Commits: `refactor(scope): description #` ou `chore(scope): description #` + +#### D. Développement avec agents +- Agents: @dotnet-developer + @dotnet-unit-tester +- Branche active: `feature/-` +- Commits conventionnels avec référence ticket + +#### E. Quality Gates (avant PR) +Vérifications obligatoires sur la branche feature : + +1. **Build .NET** : Aucune erreur + ```bash + dotnet build --configuration Release + ``` + +2. **Tests** : >90% coverage + ```bash + dotnet test --collect:"XPlat Code Coverage" + ``` + +3. **SonarQube Quality Gate** (via MCP sonarqube) : + - 0 bugs bloquants + - 0 vulnérabilités critiques + - Maintainability rating ≥ B + - Coverage ≥ 90% + +4. **Si échec** : Fix + retry (max 2 tentatives) + - Logger les erreurs + - Corriger sur la même branche + - Re-vérifier Quality Gates + +#### F. Création Pull Request +**Workflow PR** : + +1. **Push de la branche feature** : + ```bash + git push origin feature/- + ``` + +2. **Créer PR via gh CLI** (MCP github) : + ```bash + gh pr create \ + --base develop \ + --head feature/- \ + --title "[#] " \ + --body "$(cat <<'EOF' + ## 🎫 Ticket Azure DevOps + https://dev.azure.com/ebp-informatique/MéCa/_workitems/edit/ + + ## 📝 Résumé + + + ## ✅ Quality Gates + - [x] Build .NET OK + - [x] Tests >90% coverage + - [x] SonarQube Quality Gate PASSED + + ## 🧪 Tests effectués + + + ## 📊 Métriques SonarQube + - Coverage: X% + - Bugs: 0 + - Vulnérabilités: 0 + + 🤖 Generated with Claude Code + EOF + )" + ``` + +3. **NE PAS merger automatiquement** : + - La PR reste ouverte pour review + - Un humain validera et mergera sur develop + - Logger: "✅ PR créée : " + +#### G. Synchronisation Azure DevOps +Via MCP azure-devops : + +1. **Mettre à jour le State** : + - New/Active → "Ready for Review" ou "Resolved" + +2. **Ajouter commentaire** avec : + - Lien vers la PR GitHub + - Résumé des changements + - Métriques Quality Gates + +3. **Logger confirmation** : + ``` + ✅ # complété + - Branche: feature/- + - PR: + - State: Ready for Review + ``` + +### Phase 3: Gestion des blocages +Si **bloqué 3x** sur même ticket : + +1. **Via MCP azure-devops** : + - State → "Blocked" + - Ajouter commentaire détaillé: + - Cause du blocage + - Tentatives effectuées (avec logs) + - Actions nécessaires pour débloquer + - Personnes à consulter + +2. **Nettoyer la branche** (optionnel) : + ```bash + git checkout develop + git branch -D feature/- # Supprimer localement si nécessaire + ``` + +3. **Skip et continuer** : + - Logger: "⚠️ # bloqué - documenté et skippé" + - Passer au ticket suivant + +### Phase 4: Finalisation +Quand **tous tickets traités** (ou skippés si bloqués) : + +1. **Générer rapport récapitulatif** : + ```markdown + ## 📊 Rapport de Traitement - Parent #586655 + + ### ✅ Tickets Complétés (X/Y) + | ID | Titre | Branche | PR | State | + |----|-------|---------|----|----| + | #586656 | Auth JWT | feature/586656-auth-jwt | PR#123 | Ready for Review | + | #586657 | Fix Email | feature/586657-fix-email | PR#124 | Ready for Review | + + ### ⚠️ Tickets Bloqués (Z) + | ID | Titre | Raison | Action requise | + |----|-------|--------|----------------| + | #586658 | API Gateway | Dépendance externe manquante | Contacter équipe infra | + + ### 📊 Métriques Globales + - Total traité: X tickets + - PRs créées: X + - Coverage moyen: Y% + - Quality Gates OK: X/X + ``` + +2. **Mettre à jour parent #586655** (via MCP azure-devops) : + - Ajouter commentaire avec rapport + - Progress: X% complété + - Lien vers toutes les PRs créées + +3. **Logger finalisation** : + ``` + COMPLETE + + 📊 Résumé : + - ✅ X tickets traités + - ⚠️ Z tickets bloqués + - 🔀 X PRs créées (en attente de review) + - 📈 Coverage global: Y% + ``` + +## CRITÈRES DE SUCCÈS + +- [ ] Tous enfants traités OU documentés si bloqués +- [ ] Une branche feature par ticket (nomenclature: `feature/-`) +- [ ] Aucun push direct sur develop ❌ +- [ ] Une PR par ticket avec description complète +- [ ] PRs en attente de review (non mergées automatiquement) +- [ ] Tests passants (>90% coverage par ticket) +- [ ] Build .NET clean (0 erreurs) +- [ ] SonarQube Quality Gates OK pour chaque ticket +- [ ] Azure DevOps sync complet (states + commentaires + liens PR) +- [ ] Documentation générée dans tickets et parent + +## PARAMÈTRES +--max-iterations 50 +--mode standard +--retry-on-fail 2 +--skip-after-blocks 3 + +## RÈGLES CRITIQUES + +### ❌ INTERDICTIONS +1. **NE JAMAIS** pousser directement sur `develop` +2. **NE JAMAIS** merger automatiquement les PRs +3. **NE JAMAIS** réutiliser une branche pour plusieurs tickets +4. **NE JAMAIS** committer sans référence au ticket + +### ✅ OBLIGATIONS +1. **TOUJOURS** créer une nouvelle branche depuis `develop` à jour +2. **TOUJOURS** préfixer les branches avec `feature/-` +3. **TOUJOURS** référencer le ticket dans les commits (`#`) +4. **TOUJOURS** créer une PR avec description complète +5. **TOUJOURS** valider les Quality Gates avant de créer la PR +6. **TOUJOURS** synchroniser l'état dans Azure DevOps + +## EXEMPLES DE COMMANDES + +### Exemple complet pour ticket #586656 + +```bash +# 1. Créer branche depuis develop à jour +git checkout develop +git pull origin develop +git checkout -b feature/586656-authentification-jwt + +# 2. Développer (via agents @dotnet-developer) +# ... code ... + +# 3. Commits +git add . +git commit -m "feat(auth): Add JWT token validation #586656" +git commit -m "test(auth): Add JWT validation unit tests #586656" + +# 4. Vérifications +dotnet build --configuration Release +dotnet test --collect:"XPlat Code Coverage" + +# 5. Push branche feature +git push origin feature/586656-authentification-jwt + +# 6. Créer PR (NE PAS merger) +gh pr create --base develop --head feature/586656-authentification-jwt \ + --title "[#586656] Authentification JWT" \ + --body "Implémentation de la validation JWT. Ticket: https://dev.azure.com/ebp-informatique/MéCa/_workitems/edit/586656" + +# 7. Sync Azure DevOps (via MCP) +# State: Active → Ready for Review +# Commentaire: "PR créée: " +``` +``` + +--- + +## 📋 Checklist par Ticket + +Utilisez cette checklist pour chaque ticket traité : + +```markdown +## Ticket # - + +### 🔀 Gestion des branches +- [ ] Branche `develop` à jour (`git pull origin develop`) +- [ ] Nouvelle branche créée: `feature/-` +- [ ] Aucun push sur `develop` + +### 💻 Développement +- [ ] Code implémenté selon acceptance criteria +- [ ] Tests unitaires écrits (>90% coverage) +- [ ] Commits conventionnels avec `#` + +### ✅ Quality Gates +- [ ] Build .NET OK +- [ ] Tests passants +- [ ] SonarQube Quality Gate PASSED + +### 🔀 Pull Request +- [ ] Branche feature poussée sur origin +- [ ] PR créée (base: develop, head: feature/-) +- [ ] PR description complète (ticket, résumé, métriques) +- [ ] PR NON mergée (en attente review) + +### 📊 Azure DevOps +- [ ] State mis à jour (Ready for Review / Resolved) +- [ ] Commentaire ajouté avec lien PR +- [ ] Métriques SonarQube documentées +``` + +--- + +**Dernière mise à jour** : 2026-02-04 +**Projet** : AI Agent Kit - MéCa +**Mainteneur** : Thomas Le Berre diff --git a/.ai/mcp/START_HERE.md b/.ai/mcp/START_HERE.md index 29658c4..dfeae99 100644 --- a/.ai/mcp/START_HERE.md +++ b/.ai/mcp/START_HERE.md @@ -427,6 +427,32 @@ ROI: 30-50% faster development --- +## 🆕 NOUVELLE DOCUMENTATION (2026-02-04) + +### Architecture Modulaire & Workflow Azure DevOps + +**🔧 Configuration MCP Modulaire (Option C)** +→ Lire `.ai/mcp/servers/README.md` +- Architecture hybride (Projet + Global) +- Configuration des tokens Azure DevOps et SonarQube +- Wrappers custom portables + +**🔀 Stratégie de Gestion des Branches Git** +→ Lire `.ai/mcp/WORKFLOW_BRANCHES.md` +- Nomenclature: `feature/-` +- Workflow complet par ticket +- ❌ JAMAIS push direct sur `develop` +- ✅ TOUJOURS une PR par ticket + +**🎫 Prompt Workflow Automatisé Azure DevOps** +→ Lire `.ai/mcp/PROMPT_WORKFLOW_TICKETS.md` +- Traitement automatique des tickets fils +- Intégration avec agents (@dotnet-developer, etc.) +- Quality Gates SonarQube +- Synchronisation Azure DevOps automatique + +--- + ## ✅ Checklist Before you start using MCP: diff --git a/.ai/mcp/WORKFLOW_BRANCHES.md b/.ai/mcp/WORKFLOW_BRANCHES.md new file mode 100644 index 0000000..8c4c7c4 --- /dev/null +++ b/.ai/mcp/WORKFLOW_BRANCHES.md @@ -0,0 +1,449 @@ +# Stratégie de Gestion des Branches - Projet MéCa + +## 🎯 Principes Fondamentaux + +### Règle d'Or +**Une branche feature par ticket, une PR par branche, aucun push direct sur develop.** + +--- + +## 🌳 Structure des Branches + +### Branches Principales +- **`main`** : Production (protégée, merges via PR uniquement) +- **`develop`** : Intégration (protégée, merges via PR uniquement) + +### Branches de Travail +- **`feature/-`** : Nouvelles fonctionnalités / User Stories +- **`fix/-`** : Corrections de bugs +- **`refactor/-`** : Refactoring / Technical Debt + +--- + +## 📋 Workflow Standard par Ticket + +### 1. Récupération du Ticket +Via MCP Azure DevOps : +``` +Récupérer ticket #586656 +Titre: "Implémenter authentification JWT" +Type: User Story +``` + +### 2. Création de la Branche +**TOUJOURS partir de `develop` à jour** : + +```bash +# Mise à jour de develop +git checkout develop +git pull origin develop + +# Création de la branche feature +git checkout -b feature/586656-authentification-jwt +``` + +**Nomenclature des branches** : +- Format: `/-` +- Type: `feature`, `fix`, `refactor` +- Ticket ID: Numéro Azure DevOps +- Slug: Description courte en kebab-case + +**Exemples valides** : +``` +feature/586656-authentification-jwt +fix/586657-validation-email +refactor/586658-clean-architecture +``` + +**Exemples invalides** ❌ : +``` +feature/auth # Manque ticket-id +586656-auth # Manque type +feature-auth-jwt # Format incorrect +feature/586656_auth_jwt # Underscores au lieu de tirets +``` + +### 3. Développement sur la Branche + +**Commits conventionnels** : +```bash +# Format +(): # + +# Exemples +git commit -m "feat(auth): Add JWT token validation #586656" +git commit -m "test(auth): Add unit tests for JWT service #586656" +git commit -m "docs(auth): Update authentication README #586656" +``` + +**Types de commits** : +- `feat`: Nouvelle fonctionnalité +- `fix`: Correction de bug +- `refactor`: Refactoring sans changement fonctionnel +- `test`: Ajout/modification de tests +- `docs`: Documentation +- `chore`: Tâches techniques (build, config, etc.) +- `style`: Formatage code (sans changement logique) +- `perf`: Amélioration de performance + +**Scope** : Module concerné (`auth`, `api`, `db`, `ui`, etc.) + +### 4. Vérifications Avant PR + +**Checklist obligatoire** : + +```bash +# Build sans erreurs +dotnet build --configuration Release +# ✅ Build succeeded + +# Tests avec coverage +dotnet test --collect:"XPlat Code Coverage" +# ✅ >80% coverage + +# SonarQube Analysis (via MCP) +# ✅ Quality Gate PASSED +``` + +**Quality Gates SonarQube** : +- ✅ 0 bugs bloquants +- ✅ 0 vulnérabilités critiques +- ✅ Maintainability rating ≥ B +- ✅ Code coverage ≥ 80% +- ✅ 0 code smells critiques + +### 5. Push de la Branche Feature + +**IMPORTANT** : Push sur la branche feature, **PAS sur develop** ❌ + +```bash +# ✅ CORRECT - Push sur la branche feature +git push origin feature/586656-authentification-jwt + +# ❌ INTERDIT - Push direct sur develop +git push origin develop +``` + +### 6. Création de la Pull Request + +**Via GitHub CLI (MCP github)** : + +```bash +gh pr create \ + --base develop \ + --head feature/586656-authentification-jwt \ + --title "[#586656] Implémenter authentification JWT" \ + --body "$(cat <<'EOF' +## 🎫 Ticket Azure DevOps +https://dev.azure.com/ebp-informatique/MéCa/_workitems/edit/586656 + +## 📝 Résumé des Changements +- Implémentation du service JWT pour validation des tokens +- Ajout middleware d'authentification dans le pipeline ASP.NET +- Configuration des clés RSA pour signature/vérification +- Tests unitaires complets du service JWT + +## ✅ Quality Gates +- [x] Build .NET OK (0 erreurs, 0 warnings) +- [x] Tests passants (127/127) +- [x] Coverage: 87% +- [x] SonarQube Quality Gate: PASSED + +## 🧪 Tests Effectués +- Tests unitaires: Service JWT (15 tests) +- Tests unitaires: Middleware Auth (8 tests) +- Tests d'intégration: Pipeline complet (5 tests) + +## 📊 Métriques SonarQube +- **Coverage**: 87% +- **Bugs**: 0 +- **Vulnérabilités**: 0 +- **Code Smells**: 2 (mineurs) +- **Maintainability**: A + +## 🔗 Références +- Ticket Azure DevOps: #586656 +- Documentation: docs/authentication.md + +## ⚠️ Breaking Changes +Aucun + +## 📝 Notes pour Review +- Configuration des clés RSA à vérifier en staging +- Durée de vie des tokens définie à 15min (configurable) + +🤖 Generated with Claude Code +EOF +)" +``` + +**Template PR simplifié** : +```markdown +## 🎫 Ticket +[Lien Azure DevOps] + +## 📝 Résumé +[Description des changements] + +## ✅ Quality Gates +- [ ] Build OK +- [ ] Tests OK +- [ ] Coverage >80% +- [ ] SonarQube OK + +## 🧪 Tests +[Liste des tests] + +## 📊 Métriques +[Coverage, Bugs, Vulnérabilités] +``` + +### 7. Synchronisation Azure DevOps + +**Via MCP azure-devops** : + +1. **Mettre à jour le State** : + ``` + Active → "Ready for Review" + ``` + +2. **Ajouter commentaire** : + ```markdown + ✅ Développement terminé + + **Pull Request créée** : https://github.com/org/repo/pull/123 + + **Quality Gates** : + - Build: OK + - Tests: 127/127 passants + - Coverage: 87% + - SonarQube: PASSED + + **Métriques** : + - Bugs: 0 + - Vulnérabilités: 0 + - Maintainability: A + + En attente de code review. + ``` + +### 8. Attente de Review + +**La PR reste ouverte** : +- ❌ **NE PAS merger automatiquement** +- ✅ Un reviewer humain validera le code +- ✅ Le reviewer mergera sur `develop` après approbation +- ✅ La branche feature sera supprimée après merge + +--- + +## ❌ Anti-Patterns à Éviter + +### 1. Push Direct sur Develop +```bash +# ❌ INTERDIT +git checkout develop +git merge feature/586656-auth-jwt +git push origin develop +``` + +**Pourquoi ?** : +- Bypass du processus de review +- Pas de traçabilité via PR +- Risque d'introduire des bugs + +**Solution** : TOUJOURS passer par une PR + +### 2. Réutiliser une Branche pour Plusieurs Tickets +```bash +# ❌ INTERDIT +git checkout feature/586656-auth-jwt +# Travailler sur ticket #586657 +git commit -m "feat(email): Fix validation #586657" +``` + +**Pourquoi ?** : +- Mélange de contextes différents +- PR incohérente +- Difficile à reviewer + +**Solution** : Une branche = Un ticket + +### 3. Commits sans Référence au Ticket +```bash +# ❌ MAUVAIS +git commit -m "Fix bug" +git commit -m "Add feature" + +# ✅ BON +git commit -m "fix(auth): Correct token expiration #586656" +git commit -m "feat(auth): Add JWT validation #586656" +``` + +### 4. Ne Pas Mettre à Jour Develop Avant de Créer la Branche +```bash +# ❌ RISQUÉ +git checkout develop +# ... (develop est en retard de 10 commits) +git checkout -b feature/586656-auth-jwt + +# ✅ CORRECT +git checkout develop +git pull origin develop +git checkout -b feature/586656-auth-jwt +``` + +### 5. Merger Automatiquement les PRs +```bash +# ❌ INTERDIT +gh pr merge --auto --squash + +# ✅ CORRECT +gh pr create # Créer et laisser en attente de review +``` + +--- + +## 🔄 Cas Particuliers + +### Branche Bloquée (Ticket Blocked) + +Si un ticket est bloqué après 3 tentatives : + +```bash +# 1. Documenter le blocage dans Azure DevOps +# State → "Blocked" +# Commentaire détaillé avec raison + +# 2. Nettoyer la branche locale (optionnel) +git checkout develop +git branch -D feature/586656-auth-jwt + +# 3. Supprimer la branche remote si poussée (optionnel) +git push origin --delete feature/586656-auth-jwt + +# 4. Passer au ticket suivant +``` + +### Corrections après Review + +Si le reviewer demande des modifications : + +```bash +# 1. Récupérer la branche +git checkout feature/586656-auth-jwt + +# 2. Effectuer les corrections +# ... code ... + +# 3. Committer les corrections +git commit -m "fix(auth): Address review comments #586656" + +# 4. Pousser les modifications +git push origin feature/586656-auth-jwt + +# 5. La PR est automatiquement mise à jour +``` + +### Conflits avec Develop + +Si develop a évolué pendant le développement : + +```bash +# 1. Mettre à jour develop +git checkout develop +git pull origin develop + +# 2. Rebaser la branche feature +git checkout feature/586656-auth-jwt +git rebase develop + +# 3. Résoudre les conflits +# ... résolution ... +git add . +git rebase --continue + +# 4. Forcer le push (car l'historique a changé) +git push --force-with-lease origin feature/586656-auth-jwt +``` + +--- + +## 📊 Résumé des Commandes + +### Workflow Complet pour un Ticket + +```bash +# 0. Récupérer le ticket via MCP Azure DevOps +# Ticket #586656: "Implémenter authentification JWT" + +# 1. Créer branche depuis develop à jour +git checkout develop +git pull origin develop +git checkout -b feature/586656-authentification-jwt + +# 2. Développer (avec agents @dotnet-developer) +# ... code, tests, etc. ... + +# 3. Commits conventionnels +git add . +git commit -m "feat(auth): Add JWT token validation #586656" +git commit -m "test(auth): Add JWT service unit tests #586656" +git commit -m "docs(auth): Update authentication docs #586656" + +# 4. Vérifier Quality Gates +dotnet build --configuration Release +dotnet test --collect:"XPlat Code Coverage" +# SonarQube via MCP + +# 5. Pousser la branche feature +git push origin feature/586656-authentification-jwt + +# 6. Créer PR (NE PAS merger) +gh pr create \ + --base develop \ + --head feature/586656-authentification-jwt \ + --title "[#586656] Implémenter authentification JWT" \ + --body "Description complète..." + +# 7. Synchroniser Azure DevOps (via MCP) +# State: Active → Ready for Review +# Commentaire avec lien PR + +# 8. Attendre review et merge par un humain +``` + +--- + +## 🎯 Points Clés à Retenir + +### ✅ À FAIRE +1. **Une branche par ticket** depuis `develop` à jour +2. **Nomenclature stricte** : `feature/-` +3. **Commits conventionnels** avec `#` +4. **Quality Gates validés** avant PR +5. **PR avec description complète** +6. **Sync Azure DevOps** après PR +7. **Attendre review** humaine + +### ❌ À NE PAS FAIRE +1. Push direct sur `develop` +2. Merger automatiquement les PRs +3. Réutiliser une branche pour plusieurs tickets +4. Commits sans référence au ticket +5. Créer PR sans valider Quality Gates +6. Oublier de mettre à jour Azure DevOps + +--- + +## 📚 Voir Aussi + +- **Prompt complet** : `.ai/mcp/PROMPT_WORKFLOW_TICKETS.md` +- **Configuration MCP** : `.ai/mcp/servers/README.md` +- **Documentation MCP** : `.ai/mcp/README.md` + +--- + +**Dernière mise à jour** : 2026-02-04 +**Projet** : AI Agent Kit - MéCa +**Mainteneur** : Thomas Le Berre diff --git a/.ai/mcp/mcp.json b/.ai/mcp/mcp.json index c6b7ee7..fc7fa13 100644 --- a/.ai/mcp/mcp.json +++ b/.ai/mcp/mcp.json @@ -41,13 +41,13 @@ "sonarqube": { "type": "stdio", "command": "node", - "args": ["mcp0-sonarqube.js"], + "args": [".ai/mcp/servers/mcp-sonarqube.js"], "description": "SonarQube integration for code quality analysis" }, "azure-devops": { "type": "stdio", "command": "node", - "args": ["mcp0-ado.js"], + "args": [".ai/mcp/servers/mcp-azure-devops.js"], "description": "Azure DevOps integration for work items and pipelines" } }, diff --git a/.ai/mcp/servers/README.md b/.ai/mcp/servers/README.md new file mode 100644 index 0000000..622b835 --- /dev/null +++ b/.ai/mcp/servers/README.md @@ -0,0 +1,197 @@ +# MCP Servers Custom - Configuration Modulaire + +Ce dossier contient les wrappers custom pour les serveurs MCP, permettant une **configuration portable** du projet. + +## 🎯 Architecture Modulaire (Option C) + +### Niveau 1 : Configuration Projet (Portable) ✅ +**Fichier** : `.ai/mcp/mcp.json` +- **Utilisateurs** : Tous les développeurs qui clonent le repo +- **Contenu** : Références aux wrappers custom +- **Avantage** : Configuration automatique, zéro setup manuel + +### Niveau 2 : Configuration Globale (Personnelle) 🔐 +**Fichier** : `C:\Users\\AppData\Roaming\Claude\claude_desktop_config.json` (Windows) +**Fichier** : `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) +- **Utilisateurs** : Vous uniquement +- **Contenu** : Tokens personnels, surcharge optionnelle +- **Avantage** : Tokens sécurisés, non versionnés Git + +**Claude Desktop merge automatiquement les deux !** + +--- + +## 📦 Serveurs MCP Disponibles + +### 1. Azure DevOps (`mcp-azure-devops.js`) +**Wrapper pour** : `@modelcontextprotocol/server-azure-devops` + +**Variables d'environnement** : +```bash +# Obligatoire +AZURE_DEVOPS_PAT=your_personal_access_token + +# Optionnelles (valeurs par défaut pour projet MéCa) +AZURE_DEVOPS_ORG=ebp-informatique +AZURE_DEVOPS_PROJECT=MéCa +``` + +**Obtenir un PAT** : +1. https://dev.azure.com/ebp-informatique/_usersSettings/tokens +2. **New Token** avec scopes : + - ✅ Work Items : Read & Write + - ✅ Code : Read + +### 2. SonarQube (`mcp-sonarqube.js`) +**Wrapper pour** : `@modelcontextprotocol/server-sonarqube` + +**Variables d'environnement** : +```bash +# Obligatoires +SONAR_HOST_URL=https://votre-sonarqube.com +SONAR_TOKEN=your_sonarqube_token + +# Optionnelle (valeur par défaut pour projet MéCa) +SONAR_PROJECT_KEY=meca +``` + +**Obtenir un token** : +1. Connectez-vous à votre SonarQube +2. **My Account** → **Security** → **Generate Tokens** + +--- + +## 🚀 Utilisation + +### Option A : Variables d'environnement système (Portable) + +**Windows PowerShell** (session) : +```powershell +$env:AZURE_DEVOPS_PAT = "votre_pat" +$env:SONAR_HOST_URL = "https://votre-sonarqube.com" +$env:SONAR_TOKEN = "votre_token" +``` + +**Windows PowerShell** (permanent) : +```powershell +[System.Environment]::SetEnvironmentVariable('AZURE_DEVOPS_PAT', 'votre_pat', 'User') +[System.Environment]::SetEnvironmentVariable('SONAR_HOST_URL', 'https://votre-sonarqube.com', 'User') +[System.Environment]::SetEnvironmentVariable('SONAR_TOKEN', 'votre_token', 'User') +``` + +**Linux/macOS** (ajouter dans `~/.bashrc` ou `~/.zshrc`) : +```bash +export AZURE_DEVOPS_PAT="votre_pat" +export SONAR_HOST_URL="https://votre-sonarqube.com" +export SONAR_TOKEN="votre_token" +``` + +### Option B : Configuration globale Claude Desktop (Sécurisé) + +**Éditez** : `%APPDATA%\Claude\claude_desktop_config.json` (Windows) + +```json +{ + "mcpServers": { + "azure-devops": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-azure-devops"], + "env": { + "AZURE_DEVOPS_ORG": "ebp-informatique", + "AZURE_DEVOPS_PROJECT": "MéCa", + "AZURE_DEVOPS_PAT": "VOTRE_PAT_ICI" + } + }, + "sonarqube": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sonarqube"], + "env": { + "SONAR_HOST_URL": "https://votre-sonarqube.com", + "SONAR_TOKEN": "VOTRE_TOKEN_ICI", + "SONAR_PROJECT_KEY": "meca" + } + } + } +} +``` + +**Redémarrez** Claude Desktop après modification. + +### Option C : Hybride (RECOMMANDÉ) ✅ + +1. **Variables d'environnement** pour les tokens (sécurisé, portable) +2. **Config projet** (`.ai/mcp/mcp.json`) pour les wrappers +3. **Config globale** optionnelle pour surcharger + +--- + +## 🔒 Sécurité + +### ✅ Bonnes pratiques +- **JAMAIS** committer les tokens dans Git +- Utiliser des variables d'environnement ou config globale +- Scopes minimaux pour les PAT (principe du moindre privilège) +- Rotation régulière des tokens + +### ❌ À éviter +- Hardcoder les tokens dans les fichiers JS +- Partager les tokens en clair (Slack, email, etc.) +- Utiliser le même token pour tous les projets + +--- + +## 🧪 Test de Configuration + +**Vérifiez que les wrappers fonctionnent** : + +```bash +# Test SonarQube +node .ai/mcp/servers/mcp-sonarqube.js + +# Test Azure DevOps +node .ai/mcp/servers/mcp-azure-devops.js +``` + +**Résultat attendu** : +- ✅ Sans tokens : Avertissement affiché, serveur démarre en mode découverte +- ✅ Avec tokens : Serveur démarre et se connecte aux services + +--- + +## 📊 Comparaison des Options + +| Critère | Config Projet | Config Globale | Variables Env | +|---------|--------------|----------------|---------------| +| **Portable** | ✅ Versionné Git | ❌ Par machine | ✅ Documenté | +| **Sécurisé** | ⚠️ Risque si tokens hardcodés | ✅ Hors Git | ✅ Hors Git | +| **Setup** | ✅ Automatique | ❌ Manuel | ⚠️ Par session | +| **Partage équipe** | ✅ Oui | ❌ Non | ✅ Oui (doc) | + +**Recommandation** : **Hybride** (Projet + Variables Env) + +--- + +## 🐛 Dépannage + +### Erreur : "Cannot find module '@modelcontextprotocol/server-*'" +**Solution** : Les wrappers utilisent `npx` qui télécharge automatiquement les packages. Vérifiez votre connexion Internet. + +### Erreur : "Authentication failed" +**Solution** : Vérifiez que vos tokens sont valides et ont les bons scopes. + +### Serveur ne démarre pas +**Solution** : Vérifiez que Node.js est installé (`node --version`). + +--- + +## 🔗 Ressources + +- [MCP Protocol Documentation](https://modelcontextprotocol.io/) +- [Azure DevOps PAT Guide](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) +- [SonarQube Authentication](https://docs.sonarqube.org/latest/user-guide/user-token/) + +--- + +**Projet** : AI Agent Kit - MéCa +**Dernière mise à jour** : 2026-02-04 +**Mainteneur** : Thomas Le Berre diff --git a/.ai/mcp/servers/mcp-azure-devops.js b/.ai/mcp/servers/mcp-azure-devops.js new file mode 100644 index 0000000..46bec1d --- /dev/null +++ b/.ai/mcp/servers/mcp-azure-devops.js @@ -0,0 +1,65 @@ +#!/usr/bin/env node + +/** + * MCP Server Wrapper for Azure DevOps + * + * Ce wrapper permet d'utiliser le serveur MCP Azure DevOps officiel + * avec une configuration projet-spécifique portable pour le projet MéCa. + * + * Variables d'environnement (optionnelles) : + * - AZURE_DEVOPS_ORG : Organisation Azure DevOps (par défaut : "ebp-informatique") + * - AZURE_DEVOPS_PROJECT : Nom du projet (par défaut : "MéCa") + * - AZURE_DEVOPS_PAT : Personal Access Token pour authentification + * - AZURE_DEVOPS_TOKEN : Alias pour AZURE_DEVOPS_PAT + * + * Utilisation : + * 1. Sans PAT : le serveur démarre mais nécessitera une authentification + * 2. Avec PAT : connexion directe au projet MéCa + */ + +const { spawn } = require('child_process'); + +// Configuration par défaut pour le projet MéCa +const DEFAULT_CONFIG = { + AZURE_DEVOPS_ORG: process.env.AZURE_DEVOPS_ORG || 'ebp-informatique', + AZURE_DEVOPS_PROJECT: process.env.AZURE_DEVOPS_PROJECT || 'MéCa', + AZURE_DEVOPS_PAT: process.env.AZURE_DEVOPS_PAT || process.env.AZURE_DEVOPS_TOKEN +}; + +// Validation : afficher un avertissement si le PAT manque +if (!DEFAULT_CONFIG.AZURE_DEVOPS_PAT) { + console.error('⚠️ [MCP Azure DevOps] Token d\'authentification manquant'); + console.error(' Pour activer Azure DevOps, définissez cette variable d\'environnement :'); + console.error(' - AZURE_DEVOPS_PAT : votre_personal_access_token'); + console.error(' \n Obtenir un PAT : https://dev.azure.com/ebp-informatique/_usersSettings/tokens'); + console.error(' Scopes requis : Work Items (Read & Write), Code (Read)\n'); +} + +// Lancer le serveur MCP Azure DevOps officiel via npx +const args = [ + '-y', + '@modelcontextprotocol/server-azure-devops' +]; + +const child = spawn('npx', args, { + stdio: 'inherit', + env: { + ...process.env, + ...DEFAULT_CONFIG + } +}); + +// Gestion de la terminaison propre +process.on('SIGINT', () => { + child.kill('SIGINT'); + process.exit(0); +}); + +process.on('SIGTERM', () => { + child.kill('SIGTERM'); + process.exit(0); +}); + +child.on('exit', (code) => { + process.exit(code || 0); +}); diff --git a/.ai/mcp/servers/mcp-sonarqube.js b/.ai/mcp/servers/mcp-sonarqube.js new file mode 100644 index 0000000..7d47315 --- /dev/null +++ b/.ai/mcp/servers/mcp-sonarqube.js @@ -0,0 +1,64 @@ +#!/usr/bin/env node + +/** + * MCP Server Wrapper for SonarQube + * + * Ce wrapper permet d'utiliser le serveur MCP SonarQube officiel + * avec une configuration projet-spécifique portable. + * + * Variables d'environnement (optionnelles) : + * - SONAR_HOST_URL : URL de votre instance SonarQube + * - SONAR_TOKEN : Token d'authentification SonarQube + * - SONAR_PROJECT_KEY : Clé du projet (par défaut : "meca") + * + * Utilisation : + * 1. Sans variables d'environnement : le serveur démarre en mode "découverte" + * 2. Avec variables : connexion directe à votre instance SonarQube + */ + +const { spawn } = require('child_process'); + +// Configuration par défaut pour le projet +const DEFAULT_CONFIG = { + SONAR_PROJECT_KEY: process.env.SONAR_PROJECT_KEY || 'meca', + SONAR_HOST_URL: process.env.SONAR_HOST_URL || process.env.SONARQUBE_HOST, + SONAR_TOKEN: process.env.SONAR_TOKEN +}; + +// Validation : afficher un avertissement si les tokens manquent +if (!DEFAULT_CONFIG.SONAR_TOKEN || !DEFAULT_CONFIG.SONAR_HOST_URL) { + console.error('⚠️ [MCP SonarQube] Configuration incomplète'); + console.error(' Pour activer SonarQube, définissez ces variables d\'environnement :'); + console.error(' - SONAR_HOST_URL : https://votre-sonarqube.com'); + console.error(' - SONAR_TOKEN : votre_token_sonarqube'); + console.error(' - SONAR_PROJECT_KEY (optionnel) : meca\n'); +} + +// Lancer le serveur MCP SonarQube officiel via npx +const args = [ + '-y', + '@modelcontextprotocol/server-sonarqube' +]; + +const child = spawn('npx', args, { + stdio: 'inherit', + env: { + ...process.env, + ...DEFAULT_CONFIG + } +}); + +// Gestion de la terminaison propre +process.on('SIGINT', () => { + child.kill('SIGINT'); + process.exit(0); +}); + +process.on('SIGTERM', () => { + child.kill('SIGTERM'); + process.exit(0); +}); + +child.on('exit', (code) => { + process.exit(code || 0); +}); diff --git a/README.md b/README.md index 067377a..62eb9ea 100644 --- a/README.md +++ b/README.md @@ -500,11 +500,10 @@ bash scripts/completions/generate-ide-completions.sh --all ```bash # Traiter tous les tickets fils d'un parent Azure DevOps @chain:azure-devops-parent-processor --parent-id 586655 - -# Avec auto-merge des PRs -@chain:azure-devops-parent-processor --parent-id 586655 --auto-complete-prs true ``` +> ⚠️ **Note** : L'option `--auto-complete-prs` est désactivée par défaut (review humaine requise). Les PRs sont créées en attente de validation. + **Ce workflow automatise** : - ✅ Récupération des tickets fils via MCP Azure DevOps - ✅ Implémentation avec agents appropriés (dotnet-developer, etc.)