helm

Que fait helm ?

Un tableau de bord vivant pour une seule tâche. L'humain le garde ouvert dans un navigateur ; vous le mettez à jour avec des appels helm peu coûteux pendant que vous travaillez ; un serveur local éphémère diffuse les changements vers la page en direct. L'humain peut prendre le volant — modifier l'objectif / la direction — et vous le suivez à votre prochain point de contrôle.

Les deux règles

1. Appelez uniquement helm. N'écrivez et ne modifiez jamais HTML, le serveur ou state.json à la main. Chaque appel helm ne consomme que quelques tokens, ce qui est tout l'intérêt : maintenir le tableau de bord honnête pendant que vous travaillez reste peu coûteux. Réémettre une page stylisée coûterait 10× plus et le rendrait inutile.
2. Relisez la consigne de l'humain à chaque point de contrôle (entre les étapes du plan, avant toute action irréversible) avec helm goal. L'humain dirige via la page ; vous ne voyez la consigne que si vous la lisez. Si l'objectif ou la direction a changé, suivez la nouvelle version et mentionnez-le dans un event.

L'assistant

helm est fourni sous forme de script Node.js précompilé, sans dépendances, dans dist/helm.mjs (il fonctionne sur un node nu — pas de npm install, pas de construction à l'installation). Capturez son chemin une fois et réutilisez-le :

HELM="<dossier-de-cette-compétence>/dist/helm.mjs"   # ex. ~/.claude/skills/helm/dist/helm.mjs

Appelez-le via ce chemin — "$HELM" … fonctionne grâce à son shebang, ou utilisez node "$HELM" …. Ne créez pas d'alias vers helm nu si vous utilisez Kubernetes — c'est un autre helm. Après init, le tableau est retrouvé automatiquement en remontant l'arborescence depuis le répertoire courant, donc les appels ultérieurs n'ont pas besoin de --dir.

Workflow

1. Initialisez une fois, au début d'une tâche qui mérite d'être suivie. Donnez-lui l'objectif pour que l'humain puisse diriger dès la première seconde :

   "$HELM" init --title "Migrer l'auth vers JWT" --agent "Claude Code" --model claude-opus-4-8 \
                --goal "Passer les sessions des cookies vers JWT sans état, ne perdre personne"
   

   Ceci démarre le serveur et ouvre le navigateur. Dites à l'utilisateur que le tableau est prêt et qu'il peut modifier l'objectif / la direction à tout moment.

2. Définissez le plan pour qu'ils voient la forme du travail, puis avancez à travers lui. step N marque les étapes précédentes comme terminées, définit N comme activité en cours, et met à jour la progression — un seul appel déplace tout :

   "$HELM" plan "Sauvegarder les utilisateurs" "Ajouter le mécanisme RS256 signer/vérifier" "Migrer les sessions" "Basculer" "Tests de régression"
   "$HELM" step 2
   

3. Narrez au fur et à mesure — petites annonces, fréquentes, honnêtes. Chacune est un appel :

   "$HELM" event ok   "table des utilisateurs sauvegardée dans backups/users.sql"
   "$HELM" event warn "3 sessions utilisent encore l'ancien format cookie, nécessitent une migration manuelle"
   "$HELM" decide "RS256 plutôt que HS256 pour que les services vérifient avec la seule clé publique"
   "$HELM" decide "Par défaut sur staging d'abord, la production attend un accord humain" --assumption
   

4. Point de contrôle — lisez la consigne de l'humain et obéissez :

   "$HELM" goal      # affiche l'OBJECTIF + la DIRECTION ; si l'humain a modifié, la ligne le signale — suivez-la
   

   S'ils ont changé de cap, adaptez-vous et enregistrez-le : "$HELM" event info "direction changée → on ne fait que le staging".

5. Remontez les vrais blocages dès qu'ils apparaissent ; résolvez-les une fois répondus :

   "$HELM" ask "Migrer la base de staging ou la production en premier ?"
   "$HELM" status "En attente de votre décision pour la production" --state blocked
   "$HELM" resolve 1
   

6. Terminez : "$HELM" done "Toutes les sessions migrées, tests verts". Le tableau reste visible, puis le serveur s'arrête automatiquement quand personne ne le regarde. "$HELM" stop termine immédiatement ; "$HELM" open le rouvre.

Mettez à jour souvent et par petites touches. Un changement de statut, une étape terminée, un écueil, une décision, un nouvel artefact — chacun est un appel. Le tableau ne mérite sa place que s'il suit la réalité minute par minute.

Commandes

Commande	Ce qu'elle fait
helm init --title T [--subtitle S] [--agent A] [--model M] [--goal G] [--theme light|dark] [--no-open]	Crée le tableau, démarre son serveur, l'ouvre.
helm status TEXTE [--state running|blocked|waiting|done] [--phase P] [--pct N]	Définit la ligne d'activité en cours (MAINTENANT). blocked notifie l'humain.
helm plan A B C … · helm plan --add TEXTE	Définit les étapes du plan, ou en ajoute une.
helm step N [--text MAINTENANT]	Avance à l'étape N : les étapes précédentes sont marquées terminées, N devient active, MAINTENANT + progression mis à jour.
helm event KIND TEXTE	Ajoute une entrée dans la frise chronologique. KIND ∈ ok fail warn info run. Les écueils / impasses → warn/fail.
helm decide TEXTE [--assumption]	Enregistre une décision ; --assumption la marque comme non confirmée.
helm ask QUESTION · helm resolve N	Ajoute / supprime un élément « nécessite votre avis » (notifie l'humain).
helm goal · helm goal --set TEXTE	Lit l'objectif + la direction de l'humain (à faire aux points de contrôle), ou définit l'objectif.
helm link LABEL URL · helm image CHEMIN [--label L] · helm data LABEL VALEUR	Attache un artefact (lien / image / statistique).
helm meta [--title …] [--subtitle …] [--theme …] [--agent …] [--model …]	Modifie les champs d'en-tête ultérieurement.
helm done [TEXTE] · helm stop · helm open	Terminer · arrêter le serveur maintenant · rouvrir le tableau.

Conventions (gérées pour vous, ou requises)

• ask est réservé aux décisions authentiques. Ne le garnissez jamais de questions résolues ou rhétoriques. Si rien ne nécessite l'humain, laissez-le vide — un tableau silencieux est un tableau honnête.
• --state pilote l'impulsion en direct, la couleur et les notifications. Utilisez running pendant le travail, blocked/waiting quand vous êtes bloqué ou que vous attendez l'humain (ils reçoivent une notification de bureau + un comptage 🔴 dans le titre de l'onglet), done à la fin.
• Décisions vs hypothèses. decide simple pour les choix que vous avez engagés ; --assumption pour les choses que vous supposez mais n'avez pas confirmées. L'étiquette d'hypothèse est précisément l'endroit où l'humain vous attrapera tôt en cas d'erreur, donc marquez-les honnêtement.
• Le pied de page de provenance et la légende des activités sont rendus automatiquement — ne les construisez pas.
• Le processus est éphémère. Il s'arrête automatiquement quand la tâche est terminée et que personne ne regarde, et il ne se relance jamais tout seul. Si des mises à jour se produisent pendant que la page est fermée, elles sont tout de même sauvegardées ; helm open montre les dernières.

Fichiers

Ce qui s'exécute (commitée, sans dépendances — dist/) :

• dist/helm.mjs — la CLI que vous appelez pour chaque mise à jour.
• dist/server.mjs — le serveur local éphémère : sert l'interface, diffuse l'état via SSE, accepte les retours de consigne, s'arrête tout seul quand abandonné.
• dist/board.html — l'interface du tableau (deux colonnes, lavande clair + foncé) servie par le serveur.

Comment c'est construit (développement uniquement, pas nécessaire à l'exécution) : src/*.ts (TypeScript, un types.ts partagé pour le modèle de données), build.mjs (esbuild), package.json. Après avoir modifié src/, lancez npm run build. Voir DEVRULES.md pour les non-négociables.