chasey-myagi/helm

Was macht helm?

Ein Live-Board für eine einzelne Aufgabe. Der Mensch behält es im Browser offen; Sie aktualisieren es mit günstigen helm-Aufrufen während der Arbeit; ein kurzlebiger lokaler Server streamt Änderungen direkt auf die Seite. Der Mensch kann jederzeit eingreifen – das Ziel / die Steuerung bearbeiten – und Sie folgen ihm beim nächsten Checkpoint.

Die zwei Regeln

1. Rufen Sie ausschließlich helm auf. Bearbeiten oder schreiben Sie niemals HTML, den Server oder state.json von Hand. Jeder helm-Aufruf kostet nur wenige Tokens, und das ist der ganze Sinn: Das Board ehrlich auf dem Laufenden zu halten, bleibt günstig. Eine gestaltete Seite neu auszugeben, würde das Zehnfache kosten und das Ziel verfehlen.
2. Lesen Sie die Steuerung des Menschen bei jedem Checkpoint erneut (zwischen Planungsschritten, vor allem Unumkehrbaren) mit helm goal. Der Mensch steuert über die Seite; Sie sehen es nur, wenn Sie hinschauen. Wenn sich Ziel oder Steuerung geändert haben, folgen Sie der neuen Version und dokumentieren Sie dies in einem event.

Das Hilfsprogramm

helm wird als fertiges, abhängigkeitsfreies Node-Skript unter dist/helm.mjs ausgeliefert (es läuft auf einem einfachen node – kein npm install, kein Build zur Installationszeit). Merken Sie sich den Pfad einmal und verwenden Sie ihn wieder:

HELM="<this-skill-dir>/dist/helm.mjs"   # z.B. ~/.claude/skills/helm/dist/helm.mjs

Rufen Sie es über diesen Pfad auf – "$HELM" … funktioniert via Shebang, oder verwenden Sie node "$HELM" …. Legen Sie kein Alias auf das bloße helm an, wenn Sie Kubernetes nutzen – das ist ein anderes helm. Nach dem init wird das Board durch Aufwärtssuchen ab dem aktuellen Arbeitsverzeichnis automatisch gefunden, daher brauchen spätere Aufrufe kein --dir.

Arbeitsablauf

1. Einmal initialisieren zu Beginn einer überwachungswürdigen Aufgabe. Geben Sie das Ziel an, damit der Mensch von der ersten Sekunde an steuern kann:

   "$HELM" init --title "Migration zu JWT" --agent "Claude Code" --model claude-opus-4-8 \
                --goal "Wechsel von Cookies zu zustandslosem JWT, niemanden verlieren"
   

   Dies startet den Server und öffnet den Browser. Teilen Sie dem Benutzer mit, dass das Board bereit ist und er jederzeit das Ziel / die Steuerung darin bearbeiten kann.

2. Plan erstellen, damit der Mensch den Umfang der Arbeit sieht, dann Schritt für Schritt voranschreiten. step N markiert frühere Schritte als erledigt, setzt N als aktuelle Aktivität und aktualisiert den Fortschritt – ein Aufruf erledigt alles:

   "$HELM" plan "Benutzer sichern" "RS256 Issue/Verify hinzufügen" "Sitzungen migrieren" "Umschalten" "Regressionstest"
   "$HELM" step 2
   

3. Erzählen Sie während der Arbeit – kleine, häufige, ehrliche Hinweise. Jeder ist ein Aufruf:

   "$HELM" event ok   "Benutzertabelle nach backups/users.sql gesichert"
   "$HELM" event warn "3 Sitzungen verwenden die alte Cookie-Struktur, manuelle Migration nötig"  # Fallstricke gehören auch hierher
   "$HELM" decide "RS256 statt HS256, damit Dienste nur mit dem öffentlichen Schlüssel verifizieren"
   "$HELM" decide "Standardmäßig zuerst Staging, Produktion wartet auf menschliches Ja" --assumption     # unbestätigte Annahmen kennzeichnen
   

4. Checkpoint – Steuerung des Menschen lesen und befolgen:

   "$HELM" goal      # gibt das ZIEL + die STEUERUNG aus; wenn der Mensch sie bearbeitet hat, wird das entsprechend angezeigt – folgen Sie dieser Vorgabe
   

   Wenn die Richtung geändert wurde, passen Sie sich an und dokumentieren Sie es: "$HELM" event info "Steuerung geändert → mache nur Staging".

5. Echte Blockaden sofort anzeigen, sobald sie auftreten; auflösen, sobald beantwortet:

   "$HELM" ask "Staging oder Produktions-DB zuerst migrieren?"   # nur echte Human-in-the-Loop-Fragen
   "$HELM" status "Warte auf Ihre Entscheidung für Produktion" --state blocked   # blockierte/neue Fragen benachrichtigen den Menschen
   "$HELM" resolve 1
   

6. Abschluss: "$HELM" done "Alle Sitzungen migriert, Tests grün". Das Board bleibt sichtbar, dann beendet sich der Server selbst, sobald niemand mehr zusieht. "$HELM" stop beendet ihn sofort; "$HELM" open öffnet ihn erneut.

Häufig und klein aktualisieren. Ein Statuswechsel, ein erledigter Schritt, ein Fallstrick, eine Entscheidung, ein neues Artefakt – jeder ist ein Aufruf. Das Board verdient seinen Platz nur, wenn es die Realität Minute für Minute abbildet.

Befehle

Befehl	Beschreibung
helm init --title T [--subtitle S] [--agent A] [--model M] [--goal G] [--theme light|dark] [--no-open]	Board erstellen, Server starten, öffnen.
helm status TEXT [--state running|blocked|waiting|done] [--phase P] [--pct N]	Die aktuell-aktivitäts-Zeile (NOW) setzen. blocked benachrichtigt den Menschen.
helm plan A B C … · helm plan --add TEXT	Planschritte setzen oder einen anhängen.
helm step N [--text NOW]	Zu Schritt N vorrücken: frühere Schritte erledigt, N aktiv, NOW + Fortschritt aktualisiert.
helm event KIND TEXT	Timeline-Eintrag anhängen. KIND ∈ ok fail warn info run. Fallstricke/Sackgassen → warn/fail.
helm decide TEXT [--assumption]	Entscheidung aufzeichnen; --assumption kennzeichnet sie als unbestätigt (damit der Mensch sie korrigieren kann).
helm ask FRAGE · helm resolve N	Item „braucht Ihre Eingabe“ hinzufügen / entfernen (benachrichtigt den Menschen).
helm goal · helm goal --set TEXT	Ziel + Steuerung des Menschen lesen (bei Checkpoints tun) oder Ziel setzen.
helm link LABEL URL · helm image PATH [--label L] · helm data LABEL VALUE	Artefakt anhängen (Link / Bild / Statistik).
helm meta [--title …] [--subtitle …] [--theme …] [--agent …] [--model …]	Kopffelder später bearbeiten.
helm done [TEXT] · helm stop · helm open	Abschließen · Server jetzt stoppen · Board erneut öffnen.

Konventionen (werden für Sie erledigt oder sind erforderlich)

• ask ist nur für echte Entscheidungen. Füllen Sie es niemals mit bereits gelösten oder rhetorischen Fragen. Wenn nichts den Menschen braucht, lassen Sie es leer – ein ruhiges Board ist ein ehrliches Board.
• --state steuert den Live-Puls, die Farbe und Benachrichtigungen. Verwenden Sie running während der Arbeit, blocked/waiting wenn Sie feststecken oder auf den Menschen warten (diese erzeugen eine Desktop-Benachrichtigung + einen 🔴-Zähler im Tab-Titel), done am Ende.
• Entscheidungen vs. Annahmen. Einfaches decide für getroffene Entscheidungen; --assumption für Dinge, die Sie annehmen aber noch nicht bestätigt haben. Das Annahmen-Tag ist genau die Stelle, an der der Mensch Sie frühzeitig auf Fehlentwicklungen hinweist – kennzeichnen Sie sie daher ehrlich.
• Die Fußzeile mit der Herkunft und die Aktivitätslegende werden automatisch gerendert – bauen Sie sie nicht selbst.
• Der Prozess ist kurzlebig. Er beendet sich selbst, wenn die Aufgabe erledigt ist und niemand mehr zusieht, und startet nie von selbst neu. Wenn Updates bei geschlossener Seite erfolgen, werden sie dennoch gespeichert; helm open zeigt den aktuellen Stand.

Dateien

Was läuft (fest eingecheckt, abhängigkeitsfrei – dist/):

• dist/helm.mjs – das CLI, das Sie für jedes Update aufrufen.
• dist/server.mjs – der kurzlebige lokale Server: bedient die UI, streamt den Zustand über SSE, nimmt Steuerungsänderungen entgegen, beendet sich selbst, wenn niemand zuguckt.
• dist/board.html – die Board-Oberfläche (zweispaltig, Lavendel hell + dunkel), die der Server ausliefert.

Wie es gebaut wird (nur für die Entwicklung, nicht zum Ausführen nötig): src/*.ts (getipptes TypeScript, eine gemeinsame types.ts für das Datenmodell), build.mjs (esbuild), package.json. Nach Bearbeiten von src/ führen Sie npm run build aus. Siehe DEVRULES.md für unverhandelbare Regeln.