ia_dev/projects/lecoffreio/docs/WORKFLOWS_AND_COMPONENTS.md

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
2. Workflows
3. Plans Cursor (déclenchables)
4. Composants : Règles
5. Composants : Subagents
6. Composants : Commandes
7. Composants : Skills
8. MCP et outils
9. Usage
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.

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.