Better WorkflowsV6
Español
V6 Corepre-alpha

Evidencia al día.
¿Desconocido? Alto.

Un plugin para Claude Code que impide que un agente de IA dé el trabajo por terminado con un test en verde ya obsoleto, 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
  • Como mucho una vez
  • Policy, no prompt
  • Ante la duda, bloquea
Instalar para Claude Code Verlo detenerse GitHub

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

demo
  1. claude corrige el bug de sum.mjs, no hace falta volver a ejecutar los tests
  2. testnode --test pasa sobre los archivos a1f3
  3. editel agente edita sum.mjs; los archivos ahora son 9c07
  4. stop«Hecho. Los tests pasan.»
  5. bwDevuelto: test pasó por última vez sobre a1f3; los archivos han cambiado desde entonces.
  6. testel agente vuelve a ejecutar node --test: 1 fallo, lo corrige, pasa sobre b2e8
  7. pushgit push agota el tiempo de espera cuando el push ya se ha completado
  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 aprobado antiguo, otra cuando iba a hacer push de nuevo. Las dos veces se le devolvió con el motivo.

Qué comprobó Core

2 PARADAS · 0 FALSOS «HECHO»
  1. Policyde .better-workflows/policy.jsonPASS
  2. Evidenciatest sobre los archivos tal como están ahoraBLOCKED
  3. Repeticiónel test pasa sobre b2e8PASS
  4. Accióngit-push, primera vezPASS
  5. Como mucho una vezmismo push, mismo commitBLOCKED

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

01PrincipiosPRINCIPLES

Tres reglas que ganan utilidad a medida que los modelos mejoran.

Un agente más capaz escribe más código por sesión y ejecuta 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
Los tests pasaron y luego cambió un archivo«Los tests pasan.»Se le devuelve para volver a ejecutarlos sobre los archivos actuales.
npm test | tailSe da por 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 da por «los tests pasan».Con exact, solo cuenta el comando completo.
El push agota el 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 aplicándose. allow en la policy nunca concede más de lo que concedería Claude Code.

  3. L3
    Hooks de Core

    Aplican la policy en cada comando, cada edición y cada parada.

  4. L4
    El prompt

    Describe el objetivo. No tiene autoridad.

    NINGUNA

02Cómo funcionaHOW IT WORKS

Seis hooks, un registro en .git.

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

HOOKSlos hooks

  1. SessionStart: le dice al agente qué comprobaciones 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 deniega cada efecto secundario, y rechaza las ediciones de la policy y del registro.
  3. PostToolUse: registra cada comprobación con el tree de Git sobre el que se ejecutó, y cada efecto secundario con su código de salida.
  4. Stop: si cambiaron archivos y una comprobación obligatoria falta, ha fallado o está obsoleta, devuelve 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

Un test, 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 se ejecutaba y si los archivos siguen siendo exactamente aquellos sobre los que se ejecutó.

Opcional

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

Efectos secundarios

como mucho una vez; lo desconocido detiene

Los push, la creación y fusión de PR, las 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.

Comprobaciones 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 no válida deniega todos los efectos secundarios en lugar de recurrir a valores predeterminados.

  • R2

    Un permiso caducado vuelve a ask. Solo una persona lo amplía, 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 pequeño adaptador. Claude Code es el primero y, hoy por hoy, el único compatible.

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

La CI ejecuta 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 de plugins.

  1. 1

    Clona Core

    Una vez por máquina. Si usaste V5 aquí, mueve antes ~/.better-workflows a ~/.better-workflows-V5 y haz que SBW_STATE_ROOT apunte ahí.

  2. 2

    Añade el plugin

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

  3. 3

    Escribe una policy

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

  4. La guía completa cubre tus propias comprobaciones, 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: ejecuta 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 ejecutes los tests.

Cuando Claude Code intenta terminar, se le devuelve y se le indica qué comprobació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 ejecución de tests obsoleta o fallida, o con una parcial cuando la comprobación está marcada como exact
  • Una tubería o || true que oculta un fallo
  • 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, salvo que la policy nombre ese script
  • Juzgar si tus tests son lo bastante buenos
  • Construir un grafo de dependencias: un scope debe nombrar todo aquello de lo que depende una comprobación
  • Contar los archivos ignorados por Git como parte de la evidencia

Te deja a ti

Decisiones que toma una persona

  • Resolver un efecto secundario cuyo resultado no se puede volver a leer
  • Ampliar un permiso más allá de su expiresAt
  • Elegir qué cubre un scope
  • Decidir cuándo una sesión está dando vueltas en círculo
Core bloquea los errores de arriba. No se ha medido si reduce el retrabajo o las decisiones erróneas en tareas largas; para eso sirve 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 un test escondido 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 las releases se concilian con gh; sin él, siguen siendo desconocidos hasta que los resuelvas.

06EstadoSTATUS

En qué punto está el proyecto.

V6 sustituye 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 Tras el uso propio

    V6 Core alpha

    primera release etiquetada

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

STATEMENTdeclaración

PRE-ALPHA

Core se puede usar hoy y funciona en los propios repositorios del mantenedor. Su formato de policy aún puede cambiar antes de la alpha.

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

LICENSINGlicencias

licencias
ParteLicenciaEstado
V6 Core (packages/bw-core)Apache-2.0activo
Sitio web y 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 habituales, respuestas directas.

¿Otra cosa? Abre una issue en GitHub. GitHub Issues

¿Ralentiza Claude Code?

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

¿Puede quedarse atascado devolviendo al agente sin fin?

Devuelve al agente con el motivo y con cómo ha ido la sesión hasta ahora: ejecuciones, fallos seguidos, veces que ya se le ha devuelto. El agente puede entonces parar y decirte claramente qué comprobación sigue fallando.

¿Puede el agente 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 vías indirectas, se rige por las propias reglas de permisos de Claude Code, así que mantén activadas esas confirmaciones.

¿Envía algo a algún sitio?

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 previstos después de la alpha.

Pruébalo en unos segundos

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

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

Instalar para Claude CodeVer en GitHub