helm — Tablero de tarea única en vivo

helm

Un tablero en vivo para una tarea. El humano lo mantiene abierto en un navegador; tú lo actualizas con llamadas baratas helm mientras trabajas; un servidor local de corta duración transmite los cambios a la página en su lugar. El humano puede tomar el volante — editar el objetivo / las indicaciones — y tú lo sigues en tu siguiente punto de control.

Las dos reglas

1. Solo debes llamar a helm. Nunca escribas ni edites HTML, el servidor o state.json manualmente. Cada llamada a helm son unos pocos tokens, que es el objetivo: mantener el tablero honesto mientras trabajas sigue siendo barato. Volver a emitir una página estilizada costaría 10 veces más y lo arruinaría.
2. Relee las indicaciones del humano en cada punto de control (entre pasos del plan, antes de algo irreversible) con helm goal. Ellos indican a través de la página; tú solo lo ves si miras. Si el objetivo o las indicaciones cambiaron, sigue la nueva versión y menciónalo en un event.

El ayudante

helm se distribuye como un script Node compilado y sin dependencias en dist/helm.mjs (se ejecuta en un node básico — sin npm install, sin compilación al instalarlo). Captura su ruta una vez y reutilízala:

HELM="<ruta-de-este-skill>/dist/helm.mjs"   # p.ej. ~/.claude/skills/helm/dist/helm.mjs

Llámalo por esta ruta — "$HELM" … funciona a través de su shebang, o usa node "$HELM" …. No le pongas un alias a helm si usas Kubernetes — ese es otro helm. Después de init, el tablero se encuentra automáticamente subiendo desde el directorio de trabajo, por lo que las llamadas posteriores no necesitan --dir.

Flujo de trabajo

1. Inicia una vez, al comienzo de una tarea que valga la pena observar. Dale el objetivo para que el humano pueda indicar desde el primer segundo:

   "$HELM" init --title "Migrar auth a JWT" --agent "Claude Code" --model claude-opus-4-8 \
                --goal "Mover sesiones de cookies a JWT sin estado, no perder a nadie"
   

   Esto inicia el servidor y abre el navegador. Indica al usuario que el tablero está listo y que puede editar el objetivo / las indicaciones en cualquier momento.

2. Describe el plan para que vean la forma del trabajo, luego avanza a través de él. step N marca los pasos anteriores como hechos, convierte a N en la actividad actual y establece el progreso — una llamada lo mueve todo:

   "$HELM" plan "Respaldar usuarios" "Agregar RS256 emitir/verificar" "Migrar sesiones" "Corte" "Regresión"
   "$HELM" step 2
   

3. Narra mientras avanzas — pequeñas, frecuentes, honestas. Cada una es una llamada:

   "$HELM" event ok   "tabla de usuarios respaldada en backups/users.sql"
   "$HELM" event warn "3 sesiones usan la forma de cookie heredada, necesitan migración manual"  # los escollos también van aquí
   "$HELM" decide "RS256 sobre HS256 para que los servicios verifiquen solo con la clave pública"
   "$HELM" decide "Por defecto a staging primero, producción espera un sí humano" --assumption     # marca suposiciones no confirmadas
   

4. Punto de control — lee las indicaciones del humano y obedece:

   "$HELM" goal      # imprime el OBJETIVO + INDICACIONES; si las editaron, esa línea lo indica — síguelas
   

   Si cambiaron de dirección, adáptate y registralo: "$HELM" event info "indicaciones cambiadas → haciendo solo staging".

5. Saca a relucir los bloqueadores reales en el momento que aparecen; resuélvelos una vez respondidos:

   "$HELM" ask "¿Migrar base de datos de staging o producción primero?"   # solo preguntas genuinas de humano-en-el-bucle
   "$HELM" status "Esperando tu decisión sobre producción" --state blocked   # bloqueado/nuevas preguntas notifican al humano
   "$HELM" resolve 1
   

6. Finaliza: "$HELM" done "Todas las sesiones migradas, tests verdes". El tablero sigue visible, luego el servidor se cierra solo cuando nadie lo mira. "$HELM" stop lo termina ahora; "$HELM" open lo vuelve a abrir.

Actualiza a menudo y en pequeño. Un cambio de estado, un paso terminado, un escollo, una decisión, un nuevo artefacto — cada uno es una llamada. El tablero se gana su lugar solo cuando sigue la realidad minuto a minuto.

Comandos

Comando	Qué hace
helm init --title T [--subtitle S] [--agent A] [--model M] [--goal G] [--theme light|dark] [--no-open]	Crea el tablero, inicia su servidor, lo abre.
helm status TEXTO [--state running|blocked|waiting|done] [--phase P] [--pct N]	Establece la línea de actividad actual (AHORA). blocked notifica al humano.
helm plan A B C … · helm plan --add TEXTO	Establece los pasos del plan, o agrega uno.
helm step N [--text AHORA]	Avanza al paso N: pasos anteriores hechos, N activo, AHORA + progreso actualizados.
helm event KIND TEXTO	Agrega una entrada en la línea de tiempo. KIND ∈ ok fail warn info run. Escollos/puntos muertos → warn/fail.
helm decide TEXTO [--assumption]	Registra una decisión; --assumption la marca como no confirmada (para que el humano la corrija).
helm ask PREGUNTA · helm resolve N	Agrega / elimina un elemento "necesita tu opinión" (notifica al humano).
helm goal · helm goal --set TEXTO	Lee el objetivo + las indicaciones del humano (hazlo en los puntos de control), o establece el objetivo.
helm link ETIQUETA URL · helm image RUTA [--label L] · helm data ETIQUETA VALOR	Adjunta un artefacto (enlace / imagen / estadística).
helm meta [--title …] [--subtitle …] [--theme …] [--agent …] [--model …]	Edita campos del encabezado más tarde.
helm done [TEXTO] · helm stop · helm open	Finalizar · detener el servidor ahora · reabrir el tablero.

Convenciones (manejadas por ti, o requeridas)

• ask es solo para decisiones genuinas. Nunca lo llenes con preguntas resueltas o retóricas. Si nada necesita al humano, déjalo vacío — un tablero tranquilo es un tablero veraz.
• --state maneja el pulso en vivo, el color y las notificaciones. Usa running mientras trabajas, blocked/waiting cuando estés atascado o esperando al humano (esto les avisa con una notificación de escritorio + un contador 🔴 en el título de la pestaña), done al final.
• Decisiones vs suposiciones. decide simple para elecciones que has asumido; --assumption para cosas que supones pero no has confirmado. La etiqueta de suposición es exactamente donde el humano te atrapará equivocándote temprano, así que márcalas con honestidad.
• El pie de página de procedencia y la leyenda de actividad se renderizan automáticamente — no los construyas.
• El proceso es de corta duración. Se cierra solo cuando la tarea termina y nadie lo mira, y nunca se reinicia solo. Si se producen actualizaciones mientras la página está cerrada, se guardan igual; helm open muestra lo último.

Archivos

Lo que se ejecuta (comprometido, sin dependencias — dist/):

• dist/helm.mjs — la CLI que llamas para cada actualización.
• dist/server.mjs — el servidor local de corta duración: sirve la UI, transmite el estado vía SSE, acepta escrituras de indicaciones, se cierra solo cuando se abandona.
• dist/board.html — la UI del tablero (dos columnas, lavanda claro + oscuro) que sirve el servidor.

Cómo se construye (solo desarrollo, no necesario para ejecutar): src/*.ts (TypeScript escrito, un types.ts compartido para el modelo de datos), build.mjs (esbuild), package.json. Después de editar src/, ejecuta npm run build. Consulta DEVRULES.md para lo no negociable.