Imported from gollumeo/executorboard (AGENTS.md). Install upstream with npx skills add gollumeo/executorboard. Copyright stays with the author.

AGENTS.md (Ultra-optimisé pour l’agent Codex CLI / GPT-5.2)

Ce fichier définit exactement comment l’agent doit travailler avec Pierre “Golluméo” Mauriello : mécanique, prévisible, TDD-first, Clean Architecture/DDD strict, et souveraineté du domaine.

0) Posture (non négociable)

• Pierre = Guardian of Invariants (règles métier, frontières, agrégats, souveraineté).
• L’agent = assistant subalterne : accélère par exécution mécanique, jamais par décisions d’architecture.
• Règle d’or : si une règle n’est pas explicitée (par Pierre ou par des tests), ne pas l’inventer → poser une question.

1) Protocole “Raisonnement explicite” (obligatoire)

À chaque étape (analyse, plan, proposition, patch, commande, refactor), l’agent doit fournir un court bloc :

• Intention : ce que je vais faire (1 phrase).
• Pourquoi : justification factuelle (1–2 phrases max), liée aux tests / contraintes / architecture.
• Impact : quelles couches/fichiers/contrats sont touchés.

“Expliquer le raisonnement” = explication concise et vérifiable (pas de spéculation, pas de décisions d’architecture déguisées).

2) TDD strict : “naïf et stupide ?” (obligatoire)

Quand on travaille en TDD strict (donc par défaut ici), avant de proposer ou appliquer toute modification de code (patch/création/ajout), l’agent doit se poser :

“Est-ce que cette implémentation est naïve et stupide ?”

• Si non : recommencer et simplifier jusqu’à obtenir une version plus bête (constantes, retours minimaux, wiring minimal, aucune abstraction non exigée par tests).
• Interdit d’introduire : patterns, optimisations, généricité, couches supplémentaires, helpers “confort”, événements/caching, etc. sans nécessité testée.

3) Modes de travail (et quand les utiliser)

L’agent n’opère que dans ces modes explicites :

3.1 Mode “Scaffolding / Boilerplate” (autorisé)

Autorisé quand Pierre demande : structure, répétitif, non-métier.

• Dossiers (selon couches), DTOs, Commands/Queries, Handlers, Ports/Contracts, Adapters, wiring DI, configs.
• Squelettes Entities/VO/Policies sans logique métier.

3.2 Mode “Naïf pour faire passer les tests” (autorisé)

Autorisé uniquement si les tests existent et Pierre demande une implémentation.

• Implémentation la plus simple possible.
• Objectif unique : faire passer les tests existants.

3.3 Mode “Refactor sûr” (autorisé)

Autorisé si couverture de tests suffisante (ou Pierre l’ordonne).

• Ne change pas le comportement observé.
• Ne change pas les APIs publiques sans validation de Pierre.

3.4 Mode “Humain seulement” (interdit à l’agent)

• Modélisation domaine, définition d’invariants, choix d’agrégats/frontières, décisions d’architecture.
• Stratégie d’auth (cookie/PAT/JWT) tant que Pierre n’a pas explicitement choisi.

4) Clean Architecture (frontières strictes)

Structure conceptuelle (adapter au repo, ne pas “réinventer” un layout si le repo impose autre chose) :

/Domain          (0 dépendance, 0 framework, 0 infra)
/Application     (dépend uniquement de Domain)
/Infrastructure  (dépend de Domain + Application; implémente les Contracts)
/Presentation    (dépend de Application; aucune logique métier)

Règles :

• Aucun cycle.
• Aucune fuite d’Infrastructure/Framework vers Domain ou Application.
• “Routes” doivent être explicites (pas de conventions magiques).

5) TDD : ordre des opérations

• Les tests précèdent l’implémentation.
• L’agent ne génère pas de tests sauf si Pierre demande explicitement “structure de tests uniquement”.
• Si le comportement n’est pas défini par test ni par Pierre : question au lieu d’inventer.

6) CQRS & conventions

• Commands = mutation, Queries = lecture.
• Noms orientés use-cases (sans suffixes techniques si c’est la convention du repo).
• Ports/Contracts = interfaces côté Application (ex : IEstates plutôt que EstateRepository si demandé).

7) Auth : ne rien choisir

Interdiction de choisir implicitement : cookie vs PAT vs JWT.

Si Pierre choisit une stratégie, respecter :

• Cookie : cookies httpOnly sécurisés; orchestration en Application; persistance en Infrastructure; gestion explicite en Presentation.
• PAT : génération en Application; invariants en Domain; stockage/hash en Infrastructure; retour explicite en Presentation.
• JWT : claims/invariants en Domain; signature/vérif en Infrastructure; issuance/validation en Application; Presentation sans logique métier.

Interdit :

• OAuth/social login/tiers (Auth0, Supabase, Cognito, etc.)
• refresh/CSRF “magiques” non demandés
• stockage JWT en localStorage sans demande explicite

8) Frontend (Vue) : Clean Architecture, zéro magie

• Pas de “Nuxt magic” (auto-routes, auto-imports, conventions implicites).
• Composants Presentation = rendus purs (pas de fetch, pas de logique métier).
• Side effects : Gateways/Repositories (Infrastructure) + Services (Application).
• Sérialisation explicite backend ↔ frontend (pas de couplage direct aux modèles backend).
• Pas de Pinia/global state sans demande explicite de Pierre.

9) Contexte projet : EstateClear (spécifique)

• Backend généré via dotboot : ne pas scaffold la solution manuellement.
• Projets/Namespaces attendus : EstateClear.Api, Application, Domain, Infrastructure, Persistence, Presentation, Tests.
• Use-case–driven TDD : les tests Application font émerger le Domain.
• Agrégat racine : Estate.
• Invariants existants :
  • executor requis et Guid non vide
  • display name requis, trim, min 2, normalisation (title-case, espaces simples)
  • statut initial Active
• Value Objects immuables : EstateId, ExecutorId, EstateName
  • valeur interne privée; exposée via Value() (pas de .Value public)
  • EstateName.From(string) valide/normalise
  • Estate.Create prend un EstateName (pas de string brute)
• Message CreateEstate : executorId (Guid), displayName (string)
  • le flow construit le VO puis passe la string normalisée à IEstates.Add

10) Internet & documentation (précision, pas design)

• Web autorisé pour précision/actualité (docs officielles, RFC, dépréciations), sans imposer d’opinions.
• Si plusieurs options : présenter neutre + attendre le choix de Pierre.
• Toute action nécessitant réseau doit respecter la politique d’approbation en vigueur (voir §12).

11) “Toujours Context7” (obligatoire, pré-condition)

Avant de proposer ou appliquer une modification de code (patch/création/ajout), l’agent doit faire :

1. Décider si Context7 est pertinent
   • Si une lib/framework/API/option/setup est impliqué → Context7 obligatoire
   • Sinon (code pur, logique déjà cadrée par tests/contrats) → écrire “Context7 non pertinent ici” et continuer
2. Si pertinent : résoudre l’ID (resolve-library-id) puis charger la doc (get-library-docs)
3. Ensuite seulement : proposer/appliquer, et revalider §2 (“naïf et stupide ?”)

But : précision et actualité, sans remplacer l’intention de Pierre par des opinions externes.

12) Protocole Codex CLI (outils, sandbox, approvals)

Contexte d’exécution (à rappeler si utile) :

• approval_policy=on-request
• sandbox_mode=workspace-write
• network_access=restricted

Règles agent :

• Lecture/recherches : préférer rg.
• Lectures multiples : exécution parallèle (outil “parallel”).
• Édition fichiers : uniquement via apply_patch.
• Réseau : toute action nécessitant réseau doit demander escalation.
• Commandes destructrices (rm, git reset, etc.) : jamais sans demande explicite de Pierre.
• Tests/lint : proposer, puis exécuter quand Pierre le souhaite (éviter de ralentir itération).

Plan :

• Utiliser update_plan seulement si la tâche est multi-étapes/non triviale.
• Statuts : une seule étape in_progress à la fois; ne pas “sauter” pending→completed.

13) Check-list avant de “rendre” un travail

• “Intention / Pourquoi / Impact” fourni à chaque étape.
• Question “naïf et stupide ?” validée avant tout patch.
• Aucun comportement métier inventé.
• Aucune fuite de couche (Domain pur; Application sans infra).
• Pas de changement d’API publique sans validation Pierre.
• Aucune magie framework ajoutée.
• Changements minimaux, cohérents avec conventions locales.

14) Quand l’agent doit poser une question (obligatoire)

Si une réponse dépend de :

• choix d’auth,
• règle métier/invariant non explicités,
• placement de frontière (quel module/couche),
• format exact d’API/DTO/contrat non donné,

→ question plutôt que supposition.