Better WorkflowsV6
Español (México)
V6 Corepre-alpha

Evidencia al día.
¿No se sabe? Alto.

Un plugin para Claude Code que evita que un agente de IA dé el trabajo por terminado con una prueba en verde ya desactualizada, y que repita o acumule efectos secundarios cuyo resultado nunca vio. Lo que puede hacer lo decide un archivo de policy que escribes tú, nunca el prompt.

  • Evidencia actual
  • A lo mucho una vez
  • Policy, no prompt
  • Ante la duda, bloquea
Instalar para Claude Code Ver cómo se detiene GitHub

stale-green · un verde desactualizado y luego un push reintentado

demo
  1. claude corrige el bug en sum.mjs, no hace falta volver a correr las pruebas
  2. testnode --test pasa sobre los archivos a1f3
  3. editel agente edita sum.mjs; los archivos ahora son 9c07
  4. stop“Listo. Las pruebas pasan.”
  5. bwRegresado: test pasó por última vez sobre a1f3; los archivos cambiaron desde entonces.
  6. testel agente vuelve a correr node --test: 1 falla, la corrige, pasa sobre b2e8
  7. pushgit push se agota por tiempo cuando el push ya se completó
  8. pushel agente reintenta git push
  9. bwDenegado: git-push ya tuvo éxito en este commit.

SENT BACKCore detuvo al agente dos veces: una cuando iba a terminar con un resultado aprobado viejo, otra cuando iba a hacer push otra vez. Las dos veces se le regresó con el motivo.

Qué revisó Core

2 ALTOS · 0 FALSOS “LISTO”
  1. Policyde .better-workflows/policy.jsonPASS
  2. Evidenciaprueba sobre los archivos como están ahoraBLOCKED
  3. Nueva corridala prueba pasa sobre b2e8PASS
  4. Accióngit-push, primera vezPASS
  5. A lo mucho una vezmismo push, mismo commitBLOCKED

Resumido a partir de la demo stale-green del repositorio; los identificadores de tree son ilustrativos. Corre tú mismo la demo completa en unos segundos, sin Claude.

01PrincipiosPRINCIPLES

Tres reglas que se vuelven más útiles conforme mejoran los modelos.

Un agente más capaz escribe más código por sesión y corre más comandos por su cuenta. Estas reglas no dependen de que el agente sea cuidadoso; se cumplen diga lo que diga.

WITHOUT vs WITHla misma sesión

SituaciónAgente soloCon Core
Las pruebas pasaron y luego cambió un archivo“Las pruebas pasan.”Se le regresa para volver a correrlas sobre los archivos actuales.
npm test | tailSe cuenta como verde; el código de salida es el de tail.Nunca cuenta; Stop explica por qué.
Un archivo de spec en lugar de toda la suiteSe cuenta como “las pruebas pasan”.Con exact, solo cuenta el comando completo.
El push se agota por tiempo después de completarseVuelve a hacer push.Se rechaza el mismo push en el mismo commit.
El prompt dice “puedes publicar”Publica.Decide la policy: allow, ask o deny.

AUTHORITYde dónde viene la autoridad

  1. L1
    policy.json

    La escribe y la cambia una persona. Core rechaza las ediciones directas del agente.

    ORIGEN
  2. L2
    Permisos de Claude Code

    Siguen aplicando. allow en la policy nunca otorga más de lo que otorgaría Claude Code.

  3. L3
    Hooks de Core

    Aplican la policy en cada comando, cada edición y cada intento de terminar.

  4. L4
    El prompt

    Describe el objetivo. No tiene autoridad.

    NINGUNA

02Cómo funcionaHOW IT WORKS

Seis hooks, un registro en .git.

Core corre dentro de los propios hooks de Claude Code. Nada que iniciar, sin servidor ni cuenta; el estado vive en .git/better-workflows/ de cada repositorio.

HOOKSlos hooks

  1. SessionStart: le dice al agente qué verificaciones deben pasar y qué efectos secundarios están sin resolver, y avisa si la policy no es válida o si se necesita gh pero no se puede usar.
  2. PreToolUse: permite, pregunta o niega cada efecto secundario, y rechaza las ediciones a la policy y al registro.
  3. PostToolUse: registra cada verificación con el tree de Git sobre el que corrió, y cada efecto secundario con su código de salida.
  4. Stop: si cambiaron archivos y una verificación requerida falta, falló o está desactualizada, regresa al agente una vez con el motivo; la siguiente vez solo avisa.
  5. bw status (un comando, no un hook): te muestra ese mismo estado.
STOP

Terminar

evidencia ligada a los archivos

Una prueba, lint, typecheck o build solo cuenta si pasó, si su propio código de salida decidió el resultado de la línea, si ningún archivo cambió mientras corría y si los archivos siguen siendo exactamente aquellos sobre los que corrió.

Opcional

  • exact: solo cuenta el comando completo, y cwd define dónde debe correr.
  • scope (con exact): un cambio fuera de los directorios indicados no invalida el resultado.
  • ignore (toda la policy): lo que escribe una verificación, como la cobertura, no cuenta como cambio.
PRETOOLUSE

Efectos secundarios

a lo mucho una vez; lo desconocido detiene

Los push, la creación y el merge de PR, los releases, la publicación de paquetes y tus propios tipos personalizados necesitan cada uno allow en la policy. Solo el código de salida 0 es un resultado conocido.

Verificaciones de solo lectura para resolver un resultado desconocido

  • git ls-remote
  • gh pr list / view
  • gh release view
  • npm view

RULESreglas que se mantienen

  • R1

    Una policy inválida niega todos los efectos secundarios en lugar de recurrir a valores predeterminados.

  • R2

    Un permiso vencido regresa a ask. Solo una persona lo extiende, editando la policy.

  • R3

    Los comandos que Core no puede leer, como eval o sh -c, se tratan como opacos y se pregunta por ellos.

  • R4

    El registro es de solo anexado y está encadenado por hash; bw verify detecta entradas editadas o eliminadas y una última línea escrita a medias, pero no entradas completas recortadas del final.

03HostsHOSTS

Primero, Claude Code.

Core es independiente del host; cada host necesita un adaptador pequeño. Claude Code es el primero y, por ahora, el único compatible.

Compatibilidad por host y sistema operativo
HostmacOSLinuxWindows
Claude CodePrimer hostCompatible, probado en CICompatible, probado en CISin probar
CodexSolo V5, congeladoPlaneadoPlaneadoPlaneado
Gemini CLISolo V5, congeladoPlaneadoPlaneadoPlaneado
Qwen CodeSolo V5, congeladoPlaneadoPlaneadoPlaneado

La CI corre Core en cada pull request.macOS 15 y Ubuntu 24.04, Node 22.23.3 y 24.21.0.

04Primeros pasosGET STARTED

Tres comandos y luego pide un cambio.

Requiere Node.js 22.14 o posterior, Git y Claude Code con soporte para plugins.

  1. 1

    Clona Core

    Una vez por computadora. Si usaste V5 aquí, primero mueve ~/.better-workflows a ~/.better-workflows-V5 y haz que SBW_STATE_ROOT apunte ahí.

  2. 2

    Agrega el plugin

    Instálalo por repositorio con --scope local, para que no se escriba nada en archivos a los que les haces commit.

  3. 3

    Escribe una policy

    bw init escribe .better-workflows/policy.json. Hazle commit para que todos tengan las mismas reglas.

  4. La guía completa cubre tus propias verificaciones, efectos secundarios y resultados desconocidos. Guía de inicio

Claude Code

git clone https://github.com/stephen-taipei/better-workflows ~/.better-workflows
claude plugin marketplace add ~/.better-workflows/packages/bw-core
claude plugin install better-workflows-core@better-workflows --scope local
node ~/.better-workflows/packages/bw-core/bin/bw.mjs init

Opcional: corre los dos escenarios sin Claude, en unos segundos.

node ~/.better-workflows/packages/bw-core/examples/stale-green/demo.mjs

Después, pruébalo

Cambia una línea de este repositorio y no corras las pruebas.

Cuando Claude Code intenta terminar, se le regresa y se le dice qué verificación falta.

05LímitesLIMITS

Qué detiene y qué no puede ver.

Un control solo sirve si conoces sus límites.

Detiene

Errores observables

  • Terminar con una corrida de pruebas desactualizada o fallida, o con una parcial cuando la verificación está marcada como exact
  • Un pipe o || true que oculta una falla
  • Un push, merge, release o publicación repetidos
  • Efectos secundarios mientras uno anterior sigue siendo desconocido
  • Que el agente edite directamente su policy o el registro

No hace

Fuera de su vista

  • Ver efectos secundarios dentro de un script, a menos que la policy nombre ese script
  • Juzgar si tus pruebas son lo bastante buenas
  • Construir un grafo de dependencias: un scope debe nombrar todo aquello de lo que depende una verificación
  • Contar los archivos ignorados por Git como parte de la evidencia

Te lo deja a ti

Decisiones que toma una persona

  • Resolver un efecto secundario cuyo resultado no se puede volver a leer
  • Extender un permiso más allá de su expiresAt
  • Elegir qué cubre un scope
  • Decidir cuándo una sesión está dando vueltas en círculos
Core bloquea los errores de arriba. No se ha medido si reduce el retrabajo o las decisiones equivocadas en tareas largas; para eso es el periodo actual de uso propio.
  1. B1El parser de shell no crece: por un comando que no puede leer se pregunta antes de que se ejecute, y una prueba escondida dentro de eval o sh -c nunca cuenta como evidencia.
  2. B2Core solo lleva la cuenta de cómo va una sesión. Si está convergiendo, lo juzga el agente o lo juzgas tú.
  3. B3Los pull requests y los releases se concilian con gh; sin él, siguen siendo desconocidos hasta que los resuelvas.

06EstadoSTATUS

En qué punto está el proyecto.

V6 reemplaza el motor de workflows de V5 por un núcleo pequeño. Las fechas se anuncian cuando se cumplen.

  1. DONE Congelado

    V5.0 RC1

    tag V5.0.rc1

    Motor de workflows multihost. Congelado en la rama frozen/v5; sin trabajo nuevo.

  2. NOW En curso

    V6 Core pre-alpha

    packages/bw-core

    Hooks de Claude Code, scope de la evidencia, uso propio en dos repositorios.

  3. NEXT Después del uso propio

    V6 Core alpha

    primer release etiquetado

    Se publicará cuando el periodo de uso propio muestre detecciones reales y pocos bloqueos falsos. Después llegarán más hosts como adaptadores pequeños.

STATEMENTdeclaración

PRE-ALPHA

Core se puede usar hoy y corre en los propios repositorios del mantenedor. Su formato de policy todavía puede cambiar antes de la alpha.

Todo aquí es gratuito y de código abierto. No hay plan de pago, cuenta ni telemetría.

LICENSINGlicencias

licencias
ParteLicenciaEstado
V6 Core (packages/bw-core)Apache-2.0activo
Sitio web y el resto del repositorioAGPL-3.0-onlyactivo
Plugin V5AGPL-3.0-onlyen frozen/v5congelado

07DocumentaciónDOCS

Todo está en el repositorio.

Las guías están escritas en inglés y en chino tradicional. Cada idioma de este sitio tiene un README breve en GitHub.

08Preguntas frecuentesFAQ

Preguntas comunes, respuestas directas.

¿Algo más? Abre un issue en GitHub. GitHub Issues

¿Hace más lento a Claude Code?

Los hooks que manejan una verificación o un efecto secundario calculan el hash del árbol de trabajo con Git, lo que toma milisegundos en un repositorio normal. Los repositorios muy grandes pagan más en cada una de esas llamadas.

¿Se puede quedar atorado regresando al agente para siempre?

Regresa al agente con el motivo y con cómo ha ido la sesión hasta ahora: corridas, fallas seguidas, veces que ya se le regresó. Entonces el agente puede detenerse y decirte claramente qué verificación sigue fallando.

¿El agente puede desactivarlo?

No directamente. Core rechaza las ediciones del agente a la policy y al registro, y rechaza bw init y resolver una acción a mano. Desinstalar el plugin, o cambiar esos archivos por caminos indirectos, se rige por las propias reglas de permisos de Claude Code, así que mantén activadas esas confirmaciones.

¿Envía algo a algún lado?

No hay servidor ni telemetría. Sus únicas llamadas de red son consultas de solo lectura con tus propios git, gh y npm, para confirmar si un efecto secundario ocurrió. El registro se queda en .git/better-workflows/.

¿Y Codex, Gemini CLI o Qwen Code?

Usaban V5, que está congelado. Core es independiente del host, y hay adaptadores para ellos planeados después de la alpha.

Pruébalo en unos segundos

Correr un comando no demuestra nada. Los archivos sí.

Corre la demo sin Claude, luego instálalo en un repositorio y pide un cambio.

Instalar para Claude CodeVer en GitHub