grahama1970/agent-status

¿Qué hace agent-status?

Usa esta habilidad siempre que un agente de proyecto esté realizando trabajo de múltiples pasos y el humano necesite saber qué está sucediendo realmente.

Esta habilidad es intencionalmente no un generador de paneles. Produce una superficie de verdad respaldada por artefactos legibles por máquina:

.plan-iterate/<campaign-id>/status/
  status.json
  events.jsonl
  proof_manifest.json
  STATUS.html

El HTML solo renderiza el artefacto de estado actual. No debe inventar progreso, porcentajes ni afirmaciones de finalización.

Principio central

artefacto de estado primero → HTML renderiza el artefacto → humano puede inspeccionar la prueba

Nunca hagas esto:

página bonita primero → lenguaje verde vago → humano infiere progreso

Respuestas requeridas en la primera vista

Una página de estado generada debe responder:

1. ¿Qué está tratando de terminar el agente?
2. ¿Dónde estamos exactamente?
3. ¿Qué acaba de pasar?
4. ¿Qué aún no está probado?
5. ¿Cuál es la siguiente acción?
6. ¿El agente está ejecutándose, bloqueado, inactivo o esperando al humano?
7. ¿Qué prueba respalda la afirmación actual?
8. ¿Qué no debería hacer el agente a continuación?

Modelo de estados

Estados permitidos:

• not_started
• running
• needs_attention
• blocked
• failed
• passed_scoped_gate
• done
• idle

Distinción importante:

passed_scoped_gate != done

Usa únicamente done cuando el objetivo final declarado tenga un artefacto de prueba final explícito.

Comandos comunes

Inicializar una campaña:

./run.sh init \
  --campaign refactor-harness-e2e \
  --goal "Finalizar la prueba E2E del arnés de refactorización delimitada"

Marcar una puerta como en ejecución:

./run.sh update \
  --campaign refactor-harness-e2e \
  --state running \
  --current-step "Ejecutar puerta de resumen LLM concurrente endurecido + OpenCode"

Registrar una puerta de alcance superada:

./run.sh gate-passed \
  --campaign refactor-harness-e2e \
  --label "A01-A18 LLM concurrente endurecido + resumen OpenCode" \
  --verdict PASS_SPEC \
  --proof ".plan-iterate/refactor-harness-e2e/proof/refactor-concurrent-mixed.json" \
  --next-action "Iniciar paquete de revisor + fase de incorporación de revisores" \
  --not-proven "Transport Room B1 UI" \
  --not-proven "build_review_packet incorporación de revisores" \
  --not-proven "Entrega completa de mensajes OpenCode"

Preguntar al humano por una decisión:

./run.sh needs-human \
  --campaign refactor-harness-e2e \
  --question "¿Qué campaña debería ejecutar el agente a continuación?" \
  --option "A=Continuar arnés: paquete de revisor + incorporación de revisores" \
  --option "B=UI de Transporte: iniciar Transport Room B1" \
  --option "C=Solo estabilizar: punto de control y detener"

Renderizar la página de estado nuevamente:

./run.sh render --campaign refactor-harness-e2e

Reglas contra el teatro de paneles

1. Sin porcentajes.
2. Sin marcas verdes de "completado" a menos que exista una prueba del objetivo final.
3. Cada PASS debe nombrar su artefacto de prueba.
4. Cada estado debe mostrar qué no está probado.
5. Cada estado inactivo debe decir por qué el agente está inactivo.
6. Cada estado de espera humana debe incluir un menú de decisión.
7. Cada estado bloqueado debe nombrar el artefacto, servicio, puerta o decisión faltante.
8. Se permite la actualización automática solo si la página lee status.json.
9. Si status.json está desactualizado, la página debe decirlo.
10. Los veredictos de los revisores son recibos, no pruebas de finalización.

Cuándo usarlo

Úsalo para:

• /plan-iterate
• /orchestrate
• /review-design
• /review-code
• /debugger
• /ask deep-review
• /code-runner
• /subagent-runner
• cualquier trabajo de agente de proyecto de múltiples pasos que dure más de un comando enfocado

Expectativas de artefactos

status.json es la fuente de verdad.

events.jsonl es de solo adición y registra transiciones de estado.

proof_manifest.json enumera artefactos de prueba mencionados por las afirmaciones de estado.

STATUS.html se genera, es consciente de desactualización y es seguro abrirlo en un navegador.

Estándar de finalización

Una respuesta final para trabajos de agente de larga duración debe resumir el artefacto de estado actual y enlazar o citar la ruta de STATUS.html cuando esté disponible.

No afirmes finalización a menos que:

• el estado sea done;
• last_completed.proof_path apunte a un artefacto de prueba final;
• not_proven esté vacío o explícitamente fuera del alcance;
• los bloqueadores estén vacíos.