ia_dev/projects/ia_dev/docs/agents-scripts-split.md

Répartition agent / script (agents lançant des scripts)

Objectif : Exploiter au mieux la valeur ajoutée de l'agent (orchestration, contenu structuré, règles projet) et du script (déterminisme, reproductibilité, exécutable sans LLM).

Principes

Rôle	Agent	Script
Orchestration	Ordre des étapes, invocation d'autres agents (push, docupdate, etc.)	Une seule responsabilité par script
Contenu	Message de commit structuré, CHANGELOG, décisions métier	Pas de génération de texte
Règles projet	Clôture (cloture-evolution.mdc), 5 sub-agents, docupdate	Contraintes techniques (auteur, chemins sensibles, branche)
Déterminisme	—	Vérifications git, chemins, options reproductibles
Réutilisabilité	Contexte Cursor	CLI / humain / CI sans agent

---

1. branch-align-by-script-from-test

Agent aujourd'hui :

• Horodatage, clôture
• cd racine projet
• Lancer push-by-script puis docupdate puis ./deploy/branch-align.sh <env>
• Ne pas masquer la sortie

Script branch-align.sh aujourd'hui :

• Vérif repo git, argument env, branche courante = env
• Fetch, force-push with lease, alignement test/pprod/prod, vérifications

Déplacé dans le script :

• Exécution depuis racine du dépôt : si le script est invoqué hors racine, se ré-exécuter depuis git rev-parse --show-toplevel pour que ./deploy/branch-align.sh soit utilisable depuis n'importe quel sous-dossier.

Reste dans l'agent :

• Ordre push → docupdate → branch-align
• Invocation des agents push-by-script et docupdate
• Clôture complète

---

2. change-to-all-branches

Agent aujourd'hui :

• Vérifier branche = test (sinon retour 1)
• Lancer /push-by-script, /branch-align-by-script-from-test, /deploy-by-script
• Retour 0

Déplacé dans un script :

• Nouveau script deploy/change-to-all-branches.sh :
  • Vérifier que la branche courante est test (sinon exit 1)
  • Exécuter ./deploy/branch-align.sh test
  • Exécuter ./deploy/scripts_v2/deploy.sh test --import-v1 --skipSetupHost
  • À lancer depuis la racine du dépôt (le script peut faire cd vers la racine git au démarrage)

Reste dans l'agent :

• Lancer /push-by-script (message de commit fourni par l'agent)
• Puis lancer le script deploy/change-to-all-branches.sh (alignement + déploiement)
• Pas d'appel à branch-align-by-script-from-test ni deploy-by-script séparés : un seul script enchaîne align + deploy

---

3. deploy-by-script

Agent aujourd'hui :

• Vérifier le suivi des branches (main/test/pprod/prod → origin/…), corriger avec git branch --set-upstream-to
• S'assurer que la branche courante est à jour : git fetch origin puis git reset --hard origin/$(git branch --show-current)
• mkdir -p logs, puis exécuter le script avec tee logs/deploy_*.log
• Ne pas masquer la sortie

Script deploy.sh aujourd'hui :

• Env, options, dotenv, vérifs git (DEPLOY_GIT_REMOTE, synchro), déploiement

Déplacé dans le script :

• Pré-vérification du suivi des branches : au début de deploy.sh, après PROJECT_ROOT et validation de ENV : git fetch origin puis pour chaque branche locale parmi main, test, pprod, prod définir l'upstream origin/<branch> si la branche existe. Pas de reset --hard dans le script (le sync avec origin reste à l'agent avant d'appeler le script).

Reste dans l'agent :

• S'assurer que la branche courante est à jour avec sa branche distante (git fetch puis git reset --hard origin/$(git branch --show-current))
• Créer logs/ et lancer le script avec tee vers un log daté
• Clôture complète

---

4. push-by-script

Agent aujourd'hui :

• Construire le message de commit (toutes les sections obligatoires)
• Mettre à jour CHANGELOG.md
• Mettre à jour VERSION (incrément sous-sous-version)
• Exécuter ./deploy/pousse.sh avec le message sur STDIN

Script pousse.sh aujourd'hui :

• Lire le message sur STDIN, git add -A, vérifications (auteur, chemins sensibles, branche distante), commit, push

Déplacé dans le script :

• Option --bump-version : avant le git add -A, lire le fichier VERSION à la racine du dépôt, incrémenter le troisième segment (patch), réécrire VERSION. Ensuite git add -A inclura le fichier modifié. L'agent n'a plus à éditer VERSION à la main ; il fournit le message (en mentionnant la nouvelle sous-sous-version si besoin) et peut appeler pousse.sh --bump-version.

Reste dans l'agent :

• Construction du message de commit (toutes les sections)
• Mise à jour de CHANGELOG.md
• Invocation de ./deploy/pousse.sh (avec --bump-version si souhaité)
• Clôture complète

---

Synthèse des implémentations

Fichier	Modification
deploy/branch-align.sh	Ré-exécution depuis la racine git si nécessaire
deploy/scripts_v2/deploy.sh	Suivi branches origin ; par défaut sync (--sync-origin) et log (--log-to-dir logs) ; --no-sync-origin, --no-log pour désactiver
deploy/pousse.sh	Ré-exéc depuis racine si besoin ; option --bump-version ; build check (ressources, backend, frontend) avant staging
deploy/change-to-all-branches.sh	Vérif branche test, branch-align.sh test, deploy.sh test --import-v1 --skipSetupHost --no-sync-origin (log par défaut)
Agents .cursor/agents/*.md	Adapter les consignes pour utiliser les nouvelles options/scripts et alléger les étapes redondantes

---

Deuxième passe (agent = contrôle / script = exécution)

Principe : L'agent assure vérifications, corrections, relances, synthèses et textes. Le script assure l'exécution et l'orchestration déterministe.

deploy-by-script / deploy.sh

• Dans le script : option --sync-origin (git fetch + reset --hard origin/current) ; option --log-to-dir <dir> (création du répertoire et tee vers un fichier daté). L'agent n'exécute plus ces commandes ni tee à la main.
• Dans l'agent : lancer le script avec --sync-origin --log-to-dir logs, contrôler la sortie et le code de retour.

push-by-script / pousse.sh

• Dans le script : build check (npm run build pour les répertoires listés dans projects/<id>/conf.json build_dirs) avant staging ; en cas d'échec, sortie en erreur sans commit ni push.
• Dans l'agent : construire le message, mettre à jour CHANGELOG, lancer le script, contrôler sortie et code de retour.

Tous les agents

• Chaque agent précise en en-tête Rôle de l'agent et Rôle du script.
• Consignes redondantes retirées ou raccourcies au profit du contrôle (sortie non masquée, code de retour, rapport succès ou erreur).

---

Troisième passe (priorité : exécution standardisée dans le script)

Principe : Tout ce qui peut être standardisé est dans le script pour garantir la même exécution à chaque run.

deploy.sh

• Par défaut : SYNC_ORIGIN=true, LOG_TO_DIR="logs". Chaque invocation fait sync avec origin et tee vers logs/deploy_YYYYMMDD_HHMMSS.log sans que l'agent ait à passer des options.
• Désactivation : --no-sync-origin et --no-log. L'agent invoque simplement deploy.sh <env> --import-v1 --skipSetupHost.

pousse.sh

• Ré-exécution depuis la racine : si le script est appelé hors racine du dépôt, il se ré-exécute depuis git rev-parse --show-toplevel. Exécution toujours depuis la racine (comme branch-align.sh et change-to-all-branches.sh).

change-to-all-branches.sh

• Appelle deploy.sh test --import-v1 --skipSetupHost --no-sync-origin (après push, la branche est déjà à jour ; log dans logs/ reste le défaut).

Agents

• deploy-by-script : une seule commande sans options sync/log (comportement par défaut).
• push-by-script : le script peut être appelé depuis n'importe quel sous-dossier.