# Workflows et composants IA

**Version** : 1.0.0
**Dernière mise à jour** : 2026-02-27
**Périmètre** : Règles Cursor, subagents, commandes, skills, workflows de développement

Ce document formalise chaque workflow et chaque composant utilisés par l'IA pour le développement du projet LeCoffre.io.

---

## Table des matières

1. [Vue d'ensemble](#1-vue-densemble)
2. [Workflows](#2-workflows)
3. [Plans Cursor (déclenchables)](#3-plans-cursor-déclenchables)
4. [Composants : Règles](#4-composants--règles)
5. [Composants : Subagents](#5-composants--subagents)
6. [Composants : Commandes](#6-composants--commandes)
7. [Composants : Skills](#7-composants--skills)
8. [MCP et outils](#8-mcp-et-outils)
9. [Usage](#9-usage)
10. [Protocole de développement](#10-protocole-de-développement)

---

## 1. Vue d'ensemble

| Type | Emplacement | Portée |
|------|-------------|--------|
| Règles | `.cursor/rules/*.mdc` | Projet |
| Plans | `~/.cursor/plans/*.plan.md` | Utilisateur (utilisables depuis ce projet) |
| Commandes projet | `.cursor/commands/*.md` | Projet (priorité sur global, invoquent plans utilisateur) |
| Commandes globales | `~/.cursor/commands/*.md` | Utilisateur (tous projets) |
| Subagents | `~/.cursor/agents/*.md` | Utilisateur (tous projets) |
| Skills | `~/.cursor/skills-cursor/*/SKILL.md` | Utilisateur (tous projets) |

---

## 2. Workflows

### 2.1 Workflow de clôture évolution / correction

**Déclencheur** : Fin de toute évolution ou correction.
**Règle** : `.cursor/rules/cloture-evolution.mdc` (alwaysApply: true).

**Ordre d'exécution** : Chaque bloc est bouclé jusqu'à stabilisation (rien à optimiser). **Réponse non partielle** : répondre à toutes les questions de clôture et lancer les subagents/plans concernés.

**Checklist de clôture (obligatoire)** : (1) Modifications similaires ailleurs ? (2) Optimisations/mutualisations possibles ? (3) Fichiers exempts d'erreurs lint ? (4) Types OK ? (5) Projet compile ?

**Orchestration** : Après correction, lancer en boucle : fix-lint (generalPurpose) si erreurs ; deploy (mcp_task) si validé ; en cas d'échec subagent, prendre le relais et corriger sans s'arrêter.

| Étape | Actions |
|-------|---------|
| 1. Tests | Compléter tests manquants (user stories) ; lancer ; corriger échecs ; rationaliser (supprimer doublons, mutualiser) |
| 2. Types | Chercher optimisations types (`npm run typecheck`, `npx tsc --noEmit`) ; implémenter si pertinent |
| 3. Reproductions | Chercher changements similaires à reproduire ailleurs ; implémenter si pertinent |
| 4. Factorisation | Chercher factorisation, mutualisation, centralisation ; implémenter si pertinent |
| 5. Lint | Chercher erreurs lint (`npm run lint`, `ReadLints`) ; corriger ; sinon vérifier si plus exigeant possible |
| 6. Sécurité | Chercher améliorations (`docs/CODE_SECURITY.md`) ; implémenter si pertinent |
| 7. Documentation | Mettre à jour REX + descriptions (README consolidation, FRONTEND.md, CODE_STANDARDS.md) ; rationaliser |
| 8. Déploiement | Après validation utilisateur : déployer ; analyser logs ; corrections/optimisations/sécurité déploiement ; doc déploiement |

**Contraintes** : Déploiement uniquement après validation. Pas de tâches en arrière-plan.

**Plan** : `.cursor/plans/workflow-cloture-evolution.plan.md`
**Commande** : `/cloture-evolution`
**Référence** : `docs/README.md#consolidation-operationnelle-ex-operationsmd`.

---

### 2.2 Workflow de déploiement

**Déclencheur** : Commande `/deploy` ou invocation subagent deploy.
**Script** : `deploy/scripts_v2/deploy.sh` — s'exécute **localement** et orchestre le déploiement **à distance** (SSH vers la cible, git pull, build, restart services).

| Étape | Action |
|-------|--------|
| 0 | Hook pre-deploy : arrêter (SIGTERM) les processus concurrents (lint, fix-lint, typecheck, turbopack) dont le cwd est dans le projet. Si des processus restent (hors projet), bloquer. Après déploiement : message pour relancer /fix-lint si nécessaire. |
| 1 | Vérifier que les modifications sont commitées |
| 2 | Exécuter `./deploy/scripts_v2/deploy.sh <env>` depuis la racine du projet, avec `test`, `pprod` ou `prod` |
| 3 | **En cas d'échec** : orchestrer la correction automatique (boucle jusqu'à succès ou impossibilité) : (a) analyser la cause (logs, journalctl, fichiers sur cible, dist) ; (b) corriger la root cause sans contournement ; (c) committer/pousser si besoin ; (d) relancer le script ; (e) répéter |

**Options** : `--skipSetupHost`, `--checkLint`. **Env** : `DEPLOY_SKIP_CONCURRENCY_CHECK=1` pour désactiver le hook pre-deploy.
**Plan** : `.cursor/plans/workflow-deploy.plan.md`
**Commande** : `/deploy <env>`
**Référence** : docs/DEPLOYMENT.md, deploy/README.md.

---

### 2.3 Workflow de correction lint

**Déclencheur** : Commande `/fix-lint` ou invocation subagent fix-lint.
**Périmètre** : lecoffre-back-main, lecoffre-front-main, lecoffre-ressources-dev.

| Étape | Action |
|-------|--------|
| 1 | Exécuter `npm run lint` dans chaque application pour lister les erreurs |
| 2 | Corriger par lots de 10 erreurs maximum |
| 3 | Entre chaque lot : lancer test build/typecheck |
| 4 | Ne jamais contourner (pas de `eslint-disable`) |
| 5 | Appliquer patterns : extraction helpers, découpage fichiers, objets de configuration |

**Règles applicables** : max-lines 250, max-lines-per-function 40, max-params 4, max-depth 4, complexity 10, max-nested-callbacks 3.

**Contournement mcp_task** : `subagent_type="fix-lint"` via mcp_task échoue ; utiliser `generalPurpose` avec prompt détaillé. Voir la consolidation dans `docs/README.md`.
**Plan** : `.cursor/plans/workflow-fix-lint.plan.md`
**Commande** : `/fix-lint`

---

### 2.4 Workflow de commit et push (pousse)

**Déclencheur** : Commande `/pousse` ou demande de commit/push.

| Étape | Action |
|-------|--------|
| 1 | `git add -A` |
| 2 | `git commit -m "..."` avec format structuré (Motivations, Root causes, Correctifs, Evolutions, Pages affectées) |
| 3 | `git push` (sans déclencher CI si règle projet) |

**Format commit** : Titre court ; sections en bullets ; pas de `--no-verify` sauf cas documenté.
**Plan** : `.cursor/plans/workflow-pousse.plan.md`
**Commande** : `/pousse`

---

### 2.5 Workflow de mise à jour documentation (docupdate)

**Déclencheur** : Commande `/docupdate`.

**docs/features extract** : Extraire données de docs/features vers docs/ ; supprimer docs/features.

**docs/fixKnowledge extract** : Extraire données de docs/fixKnowledge vers docs/ ; supprimer docs/fixKnowledge.

**docs/ cleanup** : Réunir et optimiser en max 20 documents ; supprimer infos fausses/obsolètes ; ventiler dans doc existante (pas de FEATURES.md ni FIXKNOWLEDGE.md).
**Plan** : `.cursor/plans/workflow-docupdate.plan.md`
**Commande** : `/docupdate`

---

### 2.6 Workflow d'audit sécurité

**Déclencheur** : Commande `/audit-security`.

**Processus** : Analyse surface d'attaque ; revue OWASP Top 10 ; évaluation risque ; recommandations ; checklist Security Headers.

**Format rapport** : [SEVERITY] Titre ; Location ; Description ; Impact ; Reproduction ; Remediation ; Références.
**Plan** : `.cursor/plans/workflow-audit-security.plan.md`
**Commande** : `/audit-security`

---

### 2.7 Workflow lintit (qualité code)

**Déclencheur** : Commande `/lintit`.

**Processus** : Vérifier règles qualité ; liste actions à mener. Couvre : analyse préalable, non-duplication, généricité, design patterns, gestion erreurs, interdiction fallback, interdiction facilités IA ; corriger erreurs et warnings lint sans contournement.
**Plan** : `.cursor/plans/workflow-lintit.plan.md`
**Commande** : `/lintit`

---

### 2.8 Workflow banch-align

**Déclencheur** : Commande `/banch-align <env>`.

**Processus** : Aligner test, pprod, prod (sauf `<env>`) sur la branche de `<env>` sans modifier `<env>`. Merge en conflit : `<env>` prioritaire. Stash si conflits. Vérifier 30 derniers commits équivalents.

**Résultat** : origin/test, origin/pprod, origin/prod au même commit ; branches locales à jour.
**Plan** : `.cursor/plans/workflow-banch-align.plan.md`
**Commande** : `/banch-align <env>`

---

### 2.9 Workflow banch-align-update

**Déclencheur** : Commande `/banch-align-update <env>`.

**Processus** : Aligner branche actuelle sur `<env>` sans modifier `<env>`. Stash avant ; liste modifications ; confirmation. Branche locale alignée sur commits de `<env>` ; reste sur même branche.
**Plan** : `.cursor/plans/workflow-banch-align-update.plan.md`
**Commande** : `/banch-align-update <env>`

---

## 3. Plans Cursor (déclenchables)

Les workflows sont migrés en plans Cursor stockés au niveau utilisateur (`~/.cursor/plans/`) et déclenchables via les commandes projet `.cursor/commands/`.

### Format Cursor attendu

- **Frontmatter YAML** : `name`, `overview`, `todos` (id, content, status), `isProject: false`
- **Corps Markdown** : phases, étapes, liens vers fichiers `[fichier](chemin/relatif)`

### Liste des plans

| Plan | Commande | Description |
|------|----------|-------------|
| workflow-cloture-evolution.plan.md | /cloture-evolution | Clôture évolution/correction |
| workflow-deploy.plan.md | /deploy | Déploiement test/pprod/prod |
| workflow-fix-lint.plan.md | /fix-lint | Correction lint |
| workflow-pousse.plan.md | /pousse | Commit et push |
| workflow-docupdate.plan.md | /docupdate | Mise à jour documentation |
| workflow-audit-security.plan.md | /audit-security | Audit sécurité |
| workflow-lintit.plan.md | /lintit | Qualité code |
| workflow-banch-align.plan.md | /banch-align | Aligner branches |
| workflow-banch-align-update.plan.md | /banch-align-update | Aligner branche actuelle |

### Déclenchement

- **Commande** : Taper `/` dans le chat puis le nom (ex. `/cloture-evolution`, `/deploy test`)
- **Plan mode** : Shift+Tab pour créer un plan ; ouvrir `~/.cursor/plans/workflow-*.plan.md` et cliquer « Build » pour exécuter
- **Priorité** : Les commandes projet (`.cursor/commands/`) ont priorité sur les commandes globales (`~/.cursor/commands/`)

**Référence** : .cursor/plans/README.md, ~/.cursor/plans/

---

## 4. Composants : Règles

**Emplacement** : `.cursor/rules/*.mdc` (projet).

| Règle | Description | alwaysApply |
|-------|-------------|-------------|
| rules.mdc | Règles générales (langues, restrictions, processus, qualité, doc, déploiement) | true |
| cloture-evolution.mdc | Workflow de clôture à la fin de chaque évolution/correction | true |
| development-autonomy.mdc | Références user stories, patterns, qualité, sécurité, tests | true |
| error-fixing.mdc | Corriger l'erreur et jamais contourner | true |
| investigation-analysis.mdc | Investigation via logs, données ; services host-native | true |

**Format** : YAML frontmatter (description, globs, alwaysApply) + contenu markdown.

---

## 5. Composants : Subagents

**Emplacement** : `~/.cursor/agents/*.md` (utilisateur).

| Subagent | Description | is_background | mcp_task |
|----------|-------------|---------------|----------|
| deploy | Exécute `./deploy/scripts_v2/deploy.sh <env>` (script local, déploie à distance) | false | subagent_type="deploy" |
| fix-lint | Corrige erreurs lint backend, frontend, ressources | true | Non fonctionnel (utiliser generalPurpose) |

**Invocation** : `/deploy`, `/fix-lint` ou « Utilise le subagent X » dans le chat.

**Tâches de fond** : fix-lint avec `is_background: true` retourne immédiatement ; écrit état dans `~/.cursor/subagents/` ; reprise possible via ID.

**Référence** : ~/.cursor/agents/README.md.

---

## 6. Composants : Commandes

**Emplacements** : `.cursor/commands/*.md` (projet, priorité) ; `~/.cursor/commands/*.md` (global).

Les commandes projet invoquent les plans `.cursor/plans/*.plan.md`.

| Commande | Description |
|----------|-------------|
| deploy | Déploie sur test/pprod/prod |
| fix-lint | Corrige erreurs lint |
| lintit | Vérifie règles qualité, liste actions |
| docupdate | Mise à jour et rationalisation docs |
| pousse | Commit + push avec format structuré |
| audit-security | Audit sécurité OWASP |
| banch-align | Aligne branches test/pprod/prod sur `<env>` |
| banch-align-update | Aligne branche actuelle sur `<env>` |
| science-redaction | Rédaction scientifique |
| scientifi-check | Vérification scientifique |

---

## 7. Composants : Skills

**Emplacement** : `~/.cursor/skills-cursor/*/SKILL.md` (utilisateur).

| Skill | Description |
|-------|-------------|
| create-rule | Créer règles Cursor (.mdc) |
| create-skill | Créer skills |
| create-subagent | Créer subagents |
| update-cursor-settings | Modifier settings.json |
| migrate-to-skills | Migration vers skills |

---

## 8. MCP et outils

### MCP mcp_task

**Types disponibles** : generalPurpose, explore, deploy, fix-lint.

| Type | Usage | Remarque |
|------|-------|-----------|
| generalPurpose | Tâches complexes, recherche, corrections | Toujours fonctionnel |
| explore | Exploration codebase rapide | Niveaux : quick, medium, very thorough |
| deploy | Déploiement test/pprod/prod | Lance deploy.sh |
| fix-lint | Correction lint | Non fonctionnel ; utiliser generalPurpose |

### Outils MCP browser

Tests E2E : navigation, snapshot, click, type, fill, etc. Référence : user_stories/.

### Outils projet

| Outil | Usage |
|-------|-------|
| npm run lint | ESLint |
| npm run typecheck | TypeScript (front) |
| npx tsc --noEmit | TypeScript (back, ressources) |
| npm run lint:markdown | Markdown (MD032, MD033, MD040) |
| ReadLints | Diagnostics IDE |

---

## 9. Usage

### 9.1 Quand utiliser quoi

| Situation | Action |
|-----------|--------|
| Démarrer une évolution ou correction | Formuler la demande ; l'IA applique les règles (rules.mdc, development-autonomy) |
| Fin d'évolution ou correction | `/cloture-evolution` ou workflow automatique (cloture-evolution.mdc) ; l'humain valide le déploiement si demandé |
| Erreurs de lint à corriger | `/fix-lint` ou « Corrige les erreurs de lint » |
| Déployer sur un environnement | `/deploy test` (ou pprod, prod) ; valider avant exécution |
| Commiter et pousser | `/pousse` après validation du message de commit |
| Vérifier qualité du code | `/lintit` |
| Audit sécurité | `/audit-security` |
| Mise à jour documentation | `/docupdate` |
| Aligner les branches | `/banch-align <env>` ou `/banch-align-update <env>` |
| Créer une règle, skill ou subagent | Demander à l'IA d'utiliser le skill create-rule, create-skill ou create-subagent |

### 9.2 Invocation des commandes

- **Slash** : `/deploy`, `/fix-lint`, `/pousse`, etc. dans le chat Cursor.
- **Phrase** : « Déploie sur test », « Corrige les erreurs de lint », « Commit et push ».
- **Subagents** : « Utilise le subagent fix-lint » ou invocation automatique si la description correspond.
- **Plans** : Les commandes projet (`/cloture-evolution`, `/deploy`, etc.) chargent et exécutent les plans correspondants.

### 9.3 Règles appliquées automatiquement

Les règles avec `alwaysApply: true` sont actives à chaque conversation : rules.mdc, cloture-evolution.mdc, development-autonomy.mdc, error-fixing.mdc, investigation-analysis.mdc. Aucune action requise.

### 9.4 Validation requise

- **Déploiement** : L'IA demande validation avant d'exécuter deploy.sh.
- **Commits** : L'utilisateur valide le message (format structuré) avant exécution de pousse.
- **Modifications sensibles** : Modèle de données, architecture, nouvelles dépendances : validation avant implémentation.

---

## 10. Protocole de développement

Ce protocole décrit comment l'humain utilise l'outil IA pour développer sur le projet.

### 10.1 Avant de commencer

1. Consulter `user_stories/INDEX.md` pour le contexte des parcours.
2. Consulter `docs/CODE_STANDARDS.md` et `docs/CODE_SECURITY.md` pour les contraintes.
3. S'assurer d'être sur la bonne branche (test, pprod ou prod selon l'environnement cible).

### 10.2 Pendant le développement

1. **Formuler la demande** : Décrire l'évolution ou la correction de façon précise (objectif, périmètre, contraintes).
2. **Valider les choix** : Si l'IA propose une solution (architecture, design, modèle de données), valider avant implémentation.
3. **Suivre les boucles** : L'IA applique le workflow de clôture à la fin ; l'humain peut demander d'arrêter une boucle ou de prioriser une étape.
4. **Investiguer** : En cas de bug, demander une investigation (logs, données, doc) ; l'IA utilise investigation-analysis.mdc.
5. **Concurrence des actions** : Voir [10.2.1 Concurrence des actions](#1021-concurrence-des-actions).

#### 10.2.1 Concurrence des actions

Les actions longues (lint, fix-lint, déploiement, typecheck, turbopack) ne doivent pas se chevaucher. Règles :

| Priorité | Action | Comportement |
|----------|--------|--------------|
| 1 | Déploiement | Arrêter proprement toute action en cours (lint, fix-lint, typecheck, turbopack) avant de lancer le déploiement. Le déploiement s'exécute seul. |
| 2 | Lint / fix-lint | Ne pas lancer si un déploiement est en cours. Arrêter (Ctrl+C ou annulation subagent) avant de lancer un déploiement. |
| 3 | Typecheck / turbopack | S'exécutent entre les lots de fix-lint ; ne pas lancer en parallèle d'un déploiement. |

**Avant de lancer un déploiement** : Le script `deploy/scripts_v2/deploy.sh` exécute un hook `hooks/pre-deploy.sh` qui arrête (SIGTERM) les processus concurrents dont le cwd est dans le projet (eslint, tsc, turbopack). Si des processus restent hors projet, le script bloque. Après déploiement, un message suggère de relancer /fix-lint si nécessaire.

**Si une action est lancée alors qu'une autre tourne** : Arrêter proprement l'action en cours (Ctrl+C pour processus foreground ; annulation du subagent pour fix-lint) avant de démarrer la nouvelle.

**Une action à la fois** : Ne pas lancer lint, fix-lint, déploiement ou build/typecheck en parallèle dans des terminaux distincts sans coordination.

**Contournement** : `DEPLOY_SKIP_CONCURRENCY_CHECK=1` désactive le hook pre-deploy (CI, cas documentés).

### 10.3 À la fin d'une évolution ou correction

1. **Workflow de clôture** : L'IA exécute automatiquement (tests, types, reproductions, factorisation, lint, sécurité, doc).
2. **Validation déploiement** : Si déploiement demandé, valider explicitement avant exécution.
3. **Commit** : Valider le message de commit proposé ; utiliser `/pousse` pour commiter et pousser.
4. **Vérification** : Consulter les logs de déploiement si applicable ; vérifier que la doc est à jour.

### 10.4 Bonnes pratiques

- **Une demande à la fois** : Éviter les demandes multiples non liées dans un même message.
- **Précision** : Donner le contexte (fichier, fonction, user story) pour limiter les allers-retours.
- **Validation** : Ne pas valider un déploiement ou un commit sans avoir vérifié les changements.
- **Documentation** : Signaler si la doc existante est obsolète ou incomplète.
- **Pas de contournement** : Refuser toute proposition de désactiver des règles, d'ignorer des erreurs ou de contourner un problème.

### 10.5 En cas de problème

- **L'IA contourne** : Rappeler « Corrige l'erreur et jamais contourner » (error-fixing.mdc).
- **Subagent fix-lint échoue** : Utiliser « Corrige les erreurs de lint avec generalPurpose » ou exécuter manuellement `npm run lint` et demander les corrections.
- **Déploiement en échec** : Analyser les logs ; ne pas relancer sans avoir identifié et corrigé la cause.
- **Règle trop stricte** : Documenter l'exception dans `docs/README.md` (consolidation opérationnelle) avec justification ; ne pas modifier les règles sans validation.

### 10.6 Ordre typique d'une session

1. Lire le contexte (user story, doc, code existant).
2. Formuler la demande d'évolution ou de correction.
3. Valider les propositions de l'IA.
4. Laisser l'IA implémenter et exécuter le workflow de clôture.
5. Valider déploiement si pertinent.
6. Valider et exécuter le commit (`/pousse`).

---

**Références** : docs/README.md, docs/CODE_STANDARDS.md, docs/DEPLOYMENT.md, CLAUDE.md.