# Exécution des agents — 4NK_template (projet)

Ce guide décrit comment utiliser et intégrer les agents de conformité (qualité, documentation, sécurité, déploiement, etc.) fournis par le template.

## 1. Présentation

- Agents bash (recommandé) avec rapports Markdown
- Fallback PowerShell (Windows) produisant des contrôles simplifiés
- Intégration CI (agents-smoke, openia-agents) et garde `bash-required`

## 2. Prérequis

- bash disponible (Git Bash/WSL/Linux/macOS) pour les contrôles complets
- (Optionnel) `OPENAI_API_KEY` pour activer l’analyse IA
- (Option) conteneur unifié runner+agents: `docker-compose.ci.yml`

## 3. Commandes

- Bash (recommandé):
  - `scripts/agents/run.sh`
  - Options (facultatives): `scripts/agents/run.sh [target_dir] [output_dir] [agent]`
    - Par défaut: `target_dir=.` `output_dir=tests/reports/agents` `agent=all`
- PowerShell (fallback Windows):
  - `scripts/agents/run.ps1`
  - Options (facultatives): `-TargetDir . -OutputDir tests/reports/agents -Agent <nom>`

- Conteneur unifié:
  - Build: `docker compose -f docker-compose.ci.yml build`
  - Exécuter agents: `docker compose -f docker-compose.ci.yml up --abort-on-container-exit`
  - Lancer runner: `RUNNER_MODE=runner BASE_URL=... REGISTRATION_TOKEN=... docker compose -f docker-compose.ci.yml up -d`

## 4. Agents disponibles

- Documentation (`documentation`): fichiers essentiels et index
- Qualité technique (`quality-technique`): fichiers de base, lint/type-check si outillage présent
- Open source (`open-source`): LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, checklists
- Tests (`tests`): structure, logs et rapports
- Performance (`performance`): structure et recommandations
- Sécurité (`securite`): posture, CI `security-audit`
- Déploiement (`deploiement`): documentation et contrôles CI
- Dépendances (`dependances`): politique et mise à jour
- Compilation (`compilation`): étapes de build en CI
- Résolution (`resolution`): REX/archives
- SSH & scripts (`ssh-scripts`): scripts SSH et doc associée
- Frontend (`frontend`): principes génériques si applicable
- Gitea (`gitea`): templates et workflows
- Versionnage (`versionnage`): CHANGELOG/TEMPLATE_VERSION
- Synchronisation (`sync-template`): manifeste/template-sync
- Dérogations locales (`derogations-locales`): fichier de dérogations

## 5. Sorties

- Rapports Markdown: `tests/reports/agents/*.md`
- À relire avant PR; corriger les écarts signalés

## 6. Intégration CI

- `agents-smoke`: agents en mode sans IA (rapports artefacts)
- `openia-agents`: agents avec IA si `OPENAI_API_KEY` fourni
- `bash-required`: bloque si bash/runner absent
- `release-guard`: dépend des checks en amont
 - (Option) étape pour builder/lancer `docker-compose.ci.yml` si utilisation du conteneur unifié

## 7. Paramètres IA (optionnels)

- `OPENAI_API_KEY`, `OPENAI_MODEL`, `OPENAI_API_BASE`, `OPENAI_TEMPERATURE`

## 8. Auto‑corrections (optionnelles)

- `AUTO_FIX=1` permet aux agents d’appliquer des corrections minimales:
  - création des dossiers `tests/**` manquants
  - génération de squelettes Markdown basiques pour quelques fichiers de `docs/`
- Traçabilité: les actions sont listées dans les rapports `tests/reports/agents/*.md`

## 9. Bonnes pratiques

- Exécuter les agents avant chaque PR
- Archiver les rapports significatifs
- Documenter les décisions dans le changelog et la doc
- Si contrôle local complet: activer `CI_SKIP=true` côté dépôt pour ne pas consommer la CI; ajouter au besoin `[skip ci]` dans les commits automatisés