ia_dev/projects/kogus/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 orchestrator.sh ou ./deploy/scripts_v2/deploy.sh test --no-sync-origin (métier via $SECRETS_BASE/test/deploy.conf) ; setup hôte : run-setup-host.sh, pas deploy.sh
  • À 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 vers logs/deploy_<env>_<site>_kogus_*.log (multisite via deploy-site.sh) ou logs/deploy_<env>_*.log si SITE_CODE absent
• 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 flux deploy utilise le remote lecoffre_ng ; 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 sans --build lorsque l’invocation est la commande Cursor /push-by-script (compilation interdite dans cet agent). Builds ou --build : hors ce flux ou demande utilisateur explicite dans le même message.

Script pousse.sh aujourd’hui :

• Par défaut : pas de build ; message sur STDIN, git add -A, vérifications (auteur, chemins sensibles, branche distante), commit, push. Avec --build : même boucle npm run build / build:all-sites que l’historique, puis add/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	Par défaut sync --sync-origin ; tee vers logs/deploy_*_kogus_*.log quand SITE_CODE est défini (deploy-site.sh), sinon logs/deploy_<env>_*.log ; --no-sync-origin pour désactiver le sync local ; métier uniquement deploy.conf
deploy/pousse.sh	Ré-exéc depuis racine si besoin ; options --bump-version, --build ; sans --build : pas de compilation dans le script
deploy/change-to-all-branches.sh	Vérif branche test, branch-align.sh test, puis sauf --align-only : orchestrateur ou deploy-multisite-lines.sh / deploy.sh test --no-sync-origin ; logs ./logs/ ; --align-only = alignement seul (usage /deploy-pprod-or-prod étape 2)
Agents .smartIde/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 : --sync-origin / --no-sync-origin ; tee vers logs/deploy_* (voir nom de fichier avec site + kogus ci-dessus).
• Dans l'agent : lancer le script depuis ia_dev ou racine projet selon conf, contrôler la sortie et le code de retour.

push-by-script / pousse.sh

• Dans le script : avec --build uniquement : build check (npm run build / build:all-sites selon build_dirs) avant staging ; en cas d'échec, sortie en erreur sans commit ni push. Sans --build : staging/commit/push seulement.
• Dans l'agent : construire le message, mettre à jour CHANGELOG, lancer pousse.sh sans --build pour /push-by-script ; sinon (hors slash-commande ou demande explicite) builds explicites (étape 4 bis) ou pousse.sh --build ; 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, journalisation fichier toujours active sous logs/. Désactivation sync : --no-sync-origin. Métier : deploy.conf uniquement. Setup OS : deploy/scripts_v2/run-setup-host.sh (agent /setup-host).

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). Build : opt-in --build ; sinon compilation hors script (agent ou opérateur).

change-to-all-branches.sh

• Par défaut (sans --align-only) : après branch-align.sh test, appelle deploy-multisite-lines.sh test --no-sync-origin / orchestrateur ou deploy.sh test --no-sync-origin (métier dans deploy.conf).
• Avec --align-only : s’arrête après branch-align.sh test (pas de déploiement test ; réservé au flux /deploy-pprod-or-prod ia_dev).

Agents

• deploy-by-script : commande alignée sur deploy.conf ; sync/log gérés par deploy.sh (voir usage actuel).
• push-by-script : le script peut être appelé depuis n'importe quel sous-dossier.