ATsikhanovich/ClaudeWorkflow

Convenciones para leer y actualizar runs/<run-id>/workflow-state.json. Úsese cada vez que el coordinador inicia, reanuda, reintenta o finaliza pasos del flujo de trabajo, y cuando los scripts de aprobación registran una aprobación o rechazo.

¿Qué es ClaudeWorkflow?

Esta habilidad define el contrato de estado de ejecución para un flujo de trabajo multiagente, centralizando toda la lógica de reanudación, reintentos y aprobación en un único archivo `workflow-state.json`. Está diseñada para coordinadores que manejan múltiples agentes (por ejemplo, Claude Code, Cursor o Codex) y necesitan una fuente de verdad robusta y atómica para el progreso de la ejecución. El fichero se actualiza automáticamente mediante un hook post-escritura y scripts de aprobación/rechazo, prohibiendo ediciones manuales. El esquema incluye claves como `execution_plan`, `artifacts`, `gate_results`, `retry_counters` y `approval`, con reglas estrictas de transición de estados (pendiente → ejecutando → hecho/fallido) y un contrato de reanudación que verifica integridad de hashes y reejecuta solo pasos necesarios. Además, gestiona la aprobación de planes de eventos mediante SHA-256 y registra razones de omisión en notas, deteniendo la ejecución si una compuerta falla tres veces.

Compatible con✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/ATsikhanovich/ClaudeWorkflow/tree/HEAD/.claude/skills/workflow-state

Documentación

workflow-state

workflow-state.json es la fuente única de verdad para la ejecución de una ejecución. Esquema: templates/workflow-state.template.json. Es actualizado por el hook post-write-state en cada escritura de artefacto y por scripts/approve_event.py / scripts/reject_event.py. Los agentes no deben editarlo manualmente.

Claves

Clave	Significado
`run_id`	debe coincidir con el nombre de la carpeta de ejecución (`runs/<run-id>`)
`requirements_hash`	SHA-256 de `artifacts/01-requirements.md` (se establece cuando se escribe)
`execution_plan`	pasos ordenados: `step`, `name`, `agents`, `depends_on`, `status` (pending/running/done/failed), `attempts`
`artifacts`	mapa de ruta relativa a la ejecución → `{owner, status, sha256, updated_at}`
`gate_results`	mapa `G1..G8` → `{status: PASS/FAIL/PASS-N/A, attempts, findings, responsible_agent}`
`retry_counters`	mapa `G1..G8` → número de rondas de reintento ya consumidas
`approval`	`{status: pending/approved/rejected, approved_at, plan_sha256, rejected_count, feedback[]}`
`notes`	registro adjunto de solo lectura (decisiones, agentes omitidos + razones)

Reglas de actualización

Los hashes son SHA-256 de los bytes del archivo (hexadecimal, minúsculas). Cuando se omite un paso porque su artefacto está done y el hash en disco coincide, no se registra nada nuevo.
Transiciones de estado: pending → running → done|failed. Un reintento dirigido re-ejecuta solo el paso del agente responsable y sus dependientes posteriores; incrementa attempts de ese paso y retry_counters[gate].
Agentes omitidos se registran en notes (p. ej. "entertainment-planner skipped: no entertainment required") y su artefacto se escribe igualmente como Not applicable — <reason>.
Resultados de compuertas se registran por compuerta con hallazgos y responsible_agent; una compuerta con status: FAIL y attempts: 3 detiene la ejecución dependiente — marca los pasos posteriores como failed y finaliza la ejecución con un informe claro.
Aprobación: solo scripts/approve_event.py puede establecer approval.status = "approved" y approval.plan_sha256. scripts/reject_event.py añade a approval.feedback e incrementa rejected_count. Una revisión de 06-event-plan.md invalida plan_sha256 para la guardia incluso si el campo está obsoleto.
Las escrituras son atómicas (archivo temporal + renombrar). Mantén updated_at en UTC ISO-8601 (...Z).

Contrato de reanudación (`/plan-event --resume <run-id>`)

Cargar el estado; si workflow-state.json falta o no es válido → detenerse con un error.
Re-hashear cada ruta en artifacts desde el disco; una discrepancia marca ese artefacto como stale.
Ejecutar solo los pasos con status en pending/running/failed, más cualquier paso cuyo artefacto esté stale (y sus dependientes posteriores).
No repetir nunca pasos cuyos artefactos estén done con hashes coincidentes.
Al completarse cada artefacto, el hook actualiza el estado automáticamente — el coordinador solo actualiza execution_plan, gate_results, retry_counters y notes.