crazyht-ai-process-setup

Un workflow IA de développement prêt à l'emploi : des agents et des skills (revue de code, traitement de bug/US, specs, plateforme…) projetés dans vos repos pour GitHub Copilot, Claude Code et Codex — écrits une fois, déclinés pour les trois outils.

Un seul jeu d'agents et de conventions, cohérent entre les outils et entre les repos. Vous éditez la source ; le package projette .github/agents/, .claude/, .codex/, les skills, AGENTS.md et les configs MCP.

Installation

# ponctuel, sans installer globalement
npx crazyht-ai-process-setup <commande>

# ou en devDependency d'un repo (recommandé pour la mise à jour via Renovate)
npm i -D crazyht-ai-process-setup

Node ≥ 20 requis.

Démarrage rapide — équiper un repo

Depuis la racine du repo à équiper :

npx crazyht-ai-process-setup init-repo --types app --tools copilot,claude --stacks dotnet,react

• --types app,ops : type(s) de repo (applicatif, infra/ops) — cumulables.
• --tools copilot,claude,codex : clients IA à projeter (seuls ceux-ci sont écrits et vérifiés).
• --stacks dotnet,react : technologies (filtre les agents/skills non pertinents). Auto-détecté si omis.

Cela écrit les agents, les skills, AGENTS.md, les configs MCP, un squelette de mémoire d'équipe (.ai/memory/) et un guide d'usage (.ai/guide-usage.md — quel agent pour quelle tâche). Ouvrez ensuite le repo dans VS Code (Copilot), Claude Code ou Codex : les agents sont disponibles.

| Commande | Rôle | |---|---| | init-repo --types … --tools … | Première mise en place (écrit .ai-process.json + projette) | | apply | Régénère les fichiers projetés selon .ai-process.json | | check | Vérifie que les fichiers projetés n'ont pas dérivé (à mettre en CI) | | configure | (Re)saisit les URLs des serveurs MCP, puis apply | | doctor | Sonde chaque service MCP (lecture seule) |

Les fichiers projetés sont générés : on ne les édite pas à la main. Toute évolution se fait dans le repo source du package, puis apply.

Configurer les serveurs MCP

Les serveurs MCP (GitLab, Jira/Confluence, Kroki) ont besoin de deux choses de nature très différentes, et le package ne les traite pas au même endroit :

| | URLs, e-mail de compte | Tokens | |---|---|---| | Secret ? | non | oui | | Vit dans | .ai-process.json (committé) | le magasin de secrets du poste | | Dans les fichiers projetés | substitué à l'apply | reste ${VAR}, expansé au runtime | | Saisi par | init-repo / configure | init-repo / configure / install |

C'est ce qui rend check reproductible : la CI recalcule les mêmes octets à partir du dépôt, sans jamais avoir besoin d'un secret.

init-repo propose la saisie des URLs à la première mise en place ; configure la reprend plus tard. Un service dont la sonde répond déjà n'est pas réinterrogé — la question n'est posée que là où il manque quelque chose, ou avec --reconfigure.

npx crazyht-ai-process-setup configure            # complète ce qui manque
npx crazyht-ai-process-setup configure --reconfigure   # tout redemander
npx crazyht-ai-process-setup doctor               # « est-ce que ça répond ? », sans rien écrire

Magasin de secrets

Les tokens sont déposés dans ~/.config/ai-secrets/ (surchargeable par AI_SECRETS_DIR), à raison de deux fichiers par secret :

• <service>@<hôte>.key — la valeur brute, une seule ligne, sans nom de variable ; un fichier commençant par NOM= est refusé, c'est l'erreur de copier-coller qui produit un 401 silencieux ;
• <service>@<hôte>.meta.json — les métadonnées non secrètes (URLs, compte, contrat d'environnement), lisibles sans jamais ouvrir le secret.

La portée est l'instance, pas le dépôt. Un token appartient à un compte sur une instance : scoper par dépôt recopierait le même secret autant de fois qu'il y a de dépôts sur le même GitLab, et la rotation deviendrait une chasse aux copies. L'hôte se déduit de l'URL que le dépôt déclare déjà (instanceFrom au catalogue) — rien de plus à stocker, et aucun dépôt ne nomme jamais un fichier du magasin.

[email protected]        # client A
[email protected]       # client B — pas de conflit
[email protected]

Un fichier au nom nu (atlassian.key, sans instance) est ignoré, y compris s'il est déposé à la main, et son écriture est refusée. La raison est le multi-client : une clé sans instance serait relue pour n'importe quel hôte, donc le jeton d'un client partirait vers l'instance d'un autre. Pour l'enregistrer correctement, renseigner l'URL du service puis relancer configure, qui écrira <service>@<hôte>.key.

Rien de tout cela n'entre dans un dépôt, et check ne lit jamais ce dossier.

En CI

--non-interactive (ou simplement l'absence de TTY) désactive toute question : les valeurs existantes sont conservées et la commande rend la main. Un pipeline ne peut pas se retrouver bloqué sur une invite.

Cas d'usage

Côté développeur

| Je veux… | Agent (invoque-le par son nom dans ton outil) | |---|---| | Relire mon diff avant d'ouvrir la MR | self-review (corrige les conventions, bugs évidents, tests) | | Traiter un bug (depuis un ticket ou une cause) | jira-triage → bug-fix (reproduit, délègue le fix en TDD) | | Implémenter une User Story | us-implement (plan validé, puis implémentation en tranches TDD) |

Côté architecte / lead

| Je veux… | Agent | |---|---| | Une revue de code formelle d'une MR | architect-review (back, front, sécurité, archi, intégration, plateforme) | | Auditer un repo entier | repo-audit (rapport scoré + issues proposées) | | Chasser les bugs d'un module | bug-hunter (fan-out + contre-vérification) | | Écrire une spec technique/fonctionnelle | spec-writer | | Brainstormer une évolution | brainstorm (3 angles + synthèse) | | Rédiger des User Stories | us-writer (format INVEST, critères testables) |

Côté plateforme / DevOps (repos --types ops)

| Je veux… | Agent | |---|---| | Modifier un déploiement Helm/ArgoCD | ops-change (rendu validé, MR uniquement) | | Modifier la chaîne CI | ci-change |

Les agents suivent une doctrine commune : en cas de doute, ils posent une question (avec options, avantages/inconvénients et recommandation) au lieu de décider seuls ; les actions sortantes (MR, tickets) attendent votre validation.

Ce qu'une review garantit

Ces règles vivent dans le skill shared-review-protocol et valent pour toutes les dimensions — back, front, sécurité, architecture, intégration, plateforme, tests.

| Garantie | Ce que ça évite | |---|---| | La review porte sur le HEAD poussé de la branche, pas sur votre arbre de travail — sauf demande explicite, et alors c'est déclaré. Le SHA revu est annoncé en tête du rapport. | Des findings sur un état que personne d'autre ne voit, et un rapport qu'on ne peut pas rejouer. | | Un finding est confronté à la doctrine du dépôt — décisions (ADR), spécifications, conventions, ticket lié — avant d'être rapporté. | Des constats justes dans l'absolu mais déjà tranchés, qui font perdre du temps et décrédibilisent le reste du rapport. | | Sur une divergence entre le code et un écrit, les options de correction incluent corriger l'écrit, à égalité avec les corrections de code. | Demander une régression au nom d'une spec périmée que plus personne ne défend. | | Une seule échelle de sévérité : bloquant / majeur / mineur / suggestion. Ce qui vient d'un outil (Trivy, Sonar, npm audit) est converti par l'impact réel, en gardant le label d'origine comme preuve. | Un rapport où un MEDIUM de tests et un mineur de sécurité ne se comparent pas. | | Tout finding majeur ou plus porte son contrat de mise en œuvre — solution retenue, options écartées, fichiers, invariant, tests attendus — et ce contrat voyage là où sera le correcteur : commentaire inline sur la PR, fichier de correction en auto-revue, corps du ticket en audit. | Un rapport qui constate sans donner de quoi corriger, et renvoie le travail à celui qui l'a déjà fait. | | Une matrice de couverture auditable : chaque item porte sa preuve, aucun N/A muet, aucun OK outil-vérifiable sans avoir lancé l'outil. | Ne pas pouvoir distinguer « vérifié, rien à signaler » de « jamais regardé ». |

La publication des commentaires inline fonctionne sur GitLab (draft notes groupées), GitHub (une review unique via gh) et Azure DevOps (un thread par finding). Sans forge joignable, le rapport est rendu prêt à coller, contrats compris.

Deux façons de l'utiliser

| Mode | Commande | Pour qui | |---|---|---| | Repo synchronisé | init-repo / apply / check (+ Renovate) | Les équipes : fichiers committés, à jour automatiquement, CI anti-dérive | | Local autonome | install … --full | Ceux qui veulent les agents/skills sans rien committer ni synchroniser |

Mode local autonome (--full)

Installe le jeu complet d'agents + skills dans votre profil utilisateur — disponible dans tous vos repos, rien n'est committé, aucune synchronisation :

# tout le set applicatif .NET en local
npx crazyht-ai-process-setup install --personas dev --tools claude,copilot --full --stacks dotnet

# architecte : ajoute les agents d'audit multi-repos
npx crazyht-ai-process-setup install --personas architecte --tools claude --full

• --full écrit dans ~/.claude/agents, ~/.copilot/agents, ~/.codex/agents (+ skills). Pas de .ai-process.json, pas de fichiers dans vos repos.
• Sans --full, install ne pose que le store de mémoire perso + le hook (et, pour l'architecte, les agents d'audit multi-repos).
• Idempotent ; n'écrit que dans votre profil (jamais déployé par une CI). Les choix sont mémorisés : relancer install sans argument les rejoue (mise à jour).
• memory-init / memory-reset gèrent le store de mémoire personnelle.

Le compromis : en mode local autonome, la mise à jour est manuelle (relancer install). En mode repo synchronisé, Renovate s'en charge. À vous de choisir selon que vous voulez la gouvernance d'équipe ou l'autonomie.

Mise à jour

Le repo cible déclare le package en devDependency. Avec Renovate (postUpgradeTasks → npx crazyht-ai-process-setup apply), chaque montée de version arrive en MR contenant le bump et les fichiers régénérés. Le job CI check garantit qu'aucune copie n'a été éditée à la main.

Comment le jeton arrive au serveur MCP

Les configurations MCP n'appellent pas le serveur directement : elles passent par crazyht-ai-process-setup exec --service <nom> -- <commande>. Ce lanceur lit le magasin, pose les variables pour ce seul processus, puis passe la main.

Ce qui en découle, et c'est le point :

• Le jeton ne quitte jamais ~/.config/ai-secrets. Il n'y a pas de seconde copie dans un fichier de configuration ni dans votre environnement, donc pas de rotation à faire à deux endroits.
• Rien d'autre sur le poste ne le voit. Un jeton placé dans l'environnement du profil serait lisible par tout ce que vous lancez — le moindre script d'installation d'un paquet, la moindre extension.
• Un service ne reçoit que ses propres identifiants. Être sur la même machine n'est pas une raison de voir le jeton du voisin.
• Une absence se dit. Si le magasin n'a rien pour ce service, le lanceur l'écrit sur la sortie d'erreur — jamais sur la sortie standard, qui porte le protocole — et démarre quand même : un serveur dégradé vaut mieux qu'un serveur qui refuse de se lancer.

Ce que le lanceur ne couvre pas, et il vaut mieux le savoir maintenant : un serveur MCP joint par URL n'est pas un processus qu'on lance, il n'y a donc rien à envelopper. Le seul serveur dans ce cas ici est une documentation publique, sans jeton. Si un jour un serveur HTTP demande une authentification, il faudra le mécanisme natif de l'outil — côté VS Code, une saisie rangée dans le coffre-fort du système.

Migration 0.1.x → 0.2.0 — une action est requise

Avant 0.2.0, les configs MCP projetées portaient des valeurs littérales. Elles portent désormais des marqueurs substitués depuis .ai-process.json. Pour un dépôt équipé avant cette version, la MR Renovate remplace donc ses valeurs par des marqueurs, et les serveurs GitLab et Jira/Confluence ne démarreront plus tant que personne n'a lancé la configuration.

La CI ne le verra pas : check reste vert, puisque les octets correspondent bien à ce que la nouvelle version doit produire. La garde anti-dérive fait son travail — c'est la valeur attendue qui a changé. Le seul signal est la ligne AI-PROCESS-ENDPOINTS-MANQUANTS émise par apply sur stdout, repérable dans le log de la tâche Renovate.

La remise en route tient en une commande, sur un poste et non en CI :

npx crazyht-ai-process-setup configure

Elle demande les URLs manquantes, vérifie qu'elles répondent, puis rejoue apply. Les tokens ne changent pas de canal : ils restent hors du dépôt.

Sous le capot

Le package embarque sa source de projection (payload/) : définitions d'agents, skills, tables de correspondance (capacités→outils, classes de modèle, stacks), templates de mémoire et configs MCP. La commande projette le sous-ensemble pertinent selon types/tools/stacks.

Licence et contributions : voir le dépôt source.