ultragoal

<Propósito> Ultragoal descompone un objetivo breve en un conjunto ordenado de metas, registra eventos de inicio/checkpoint/bloqueo/falla en un registro anexable y duradero, y le indica al agente activo de Claude cómo usar el comando /goal de Claude Code junto con el plan. No puede —y no debe— mutar el estado de /goal de Claude desde el shell; persiste el estado duradero del repositorio e imprime un traspaso dirigido al modelo que el agente activo debe ejecutar en-sesión. </Propósito>

<Cuándo_Usar>

• El usuario desea una forma duradera y nativa del repositorio de rastrear un ultragoal a través de múltiples sesiones de Claude o worktrees.
• El trabajo es lo suficientemente grande como para requerir múltiples "historias" ordenadas con contadores de intentos y evidencia por historia.
• El usuario desea que la finalización completa esté controlada por ai-slop-cleaner + verificación + $code-review.
• El usuario desea que la directiva /goal activa de Claude esté coordinada con el registro para que un reinicio de sesión no pierda el progreso. </Cuándo_Usar>

<Cuándo_No_Usar>

• La tarea es un cambio pequeño y único — usa delegación directa o ralph en su lugar.
• El usuario desea que el asistente invoque /goal literalmente desde el shell — eso no es posible; omc ultragoal solo escribe artefactos e imprime texto de traspaso.
• El usuario desea un artefacto de solo planificación sin bucle de ejecución — usa plan en su lugar. </Cuándo_No_Usar>

<Por_Qué_Existe> El comando /goal de Claude Code es un gancho de detención a nivel de sesión: bloquea la detención de la sesión hasta que se cumple una condición y se borra automáticamente al tener éxito. Es una excelente primitiva de ejecución para una sola sesión, pero pierde el estado entre sesiones y no impone por sí mismo una puerta de revisión final. omc ultragoal añade una capa duradera de plan, registro y control, para que una iniciativa larga de varios pasos pueda sobrevivir a reinicios de sesión, worktrees nuevos e iteraciones de revisión, mientras sigue aprovechando /goal de Claude para mantener al agente activo enfocado. </Por_Qué_Existe>

<Cómo_Usar>

1. Crear un plan a partir de un objetivo breve:

   omc ultragoal create-goals --brief-file plan.md
   

   O con historias explícitas:

   omc ultragoal create-goals --brief "ship the migration" \
     --goal "Schema::Agregar nuevas columnas" \
     --goal "Backfill::Rellenar filas en lotes" \
     --goal "Cutover::Eliminar columnas antiguas y cambiar lecturas"
   

   El modo predeterminado es aggregate (un solo /goal de Claude cubre toda la ejecución). Usa --claude-goal-mode per-story si deseas que cada historia tenga su propio /goal.

   Espacios de trabajo multirrepo / sesiones paralelas: cuando varias sesiones de Claude en el mismo espacio de trabajo necesitan ejecutar /ultragoal simultáneamente, usa --plan-id <id-estable> o --auto-plan-id para que el plan se escriba en .omc/ultragoal/plans/{planId}/ en lugar de la ruta compartida de un solo plan. Sin esa bandera, dos sesiones que crean metas se sobrescribirían mutuamente. --auto-plan-id deriva {epochMs}-{slug} del título del objetivo breve. Luego pasa el mismo --plan-id <id> en cada subcomando posterior de esa sesión. Usa omc ultragoal list-plans para enumerar los planIds disponibles cuando sea necesario.

2. Iniciar (o reanudar) la siguiente historia:

   omc ultragoal complete-goals [<goal-id>]
   

   Sin un goal-id, conserva el comportamiento predeterminado de reanudar la historia activa o iniciar la primera historia pendiente. Con un goal-id, OMC apunta exactamente a esa historia elegible nombrada (una historia pendiente puede iniciarse fuera de orden); nunca pasa a otra historia. Una historia activa diferente, un id desconocido, una historia completada o bloqueada por revisión, o una historia fallida sin --retry-failed es rechazada sin mutar el estado. Una historia nombrada en progreso se reanuda sin cambiar su contador de intentos. Esto imprime un traspaso dirigido al modelo. El agente activo de Claude debe leerlo y:

   • Establecer el /goal nativo de Claude en esta sesión — en Claude Code independiente ni el shell ni el agente pueden hacerlo, así que pide al usuario que escriba /goal <objetivo agregado> y espera. --claude-goal-json (abajo) solo reconcilia el registro y no satisface la protección PreToolUse de /goal, que bloquea las llamadas a herramientas hasta que observa un /goal activo.
   • Trabajar en la historia.
   • Cuando la historia esté completa (y para la historia final, después del control de calidad completo), compartir una instantánea del estado activo de /goal y llamar a checkpoint.

3. Hacer checkpoint de una historia:

   omc ultragoal checkpoint --goal-id G001-... --status complete \
     --evidence "tests/files/PR evidence" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   Para la historia final, pasa también --quality-gate-json que contenga la evidencia de aiSlopCleaner, verification y codeReview (todo limpio).

4. Si la revisión final no es limpia, NO marcar como completada. Registrar bloqueadores:

   omc ultragoal record-review-blockers --goal-id G00X-... \
     --title "Resolver bloqueadores de revisión de código final" \
     --objective "Corregir los hallazgos de revisión listados y volver a ejecutar las puertas finales" \
     --evidence "<los hallazgos de revisión>" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   Esto agrega una nueva historia bloqueadora y mantiene activo el /goal de Claude.

5. Inspeccionar el estado en cualquier momento:

   omc ultragoal status
   

</Cómo_Usar>

<Limitaciones_Importantes>

• El shell no puede invocar ni mutar el estado del comando /goal de Claude Code. omc ultragoal solo persiste artefactos duraderos e imprime instrucciones que el agente activo de Claude lee y ejecuta en-sesión.
• Las instantáneas pasadas a través de --claude-goal-json son prueba proporcionada por el modelo del estado activo de /goal; OMC las valida en cuanto a consistencia textual con el objetivo esperado del plan y el evento del registro, pero no puede observar de forma independiente el estado del /goal de Claude. No satisfacen la protección PreToolUse de /goal, que requiere un /goal real activo — ya sea una instantánea inyectada por el host o el /goal nativo que el usuario estableció en-sesión.
• Si el comando /goal de Claude es renombrado o reestructurado, solo el texto del traspaso necesita cambiar; la lógica de reconciliación es independiente del nombre. </Limitaciones_Importantes>

Advertencias para sesiones paralelas

• Anclaje de espacio de trabajo multirrepo: coloca un marcador .omc-workspace en el directorio padre para que múltiples sesiones en sub-repos compartan un único .omc/. Orden de resolución: OMC_STATE_DIR > .omc-workspace > git > cwd. Consulta docs/REFERENCE.md.
• Fuente del id de sesión: la variable de entorno OMC_SESSION_ID prevalece en contextos de CLI; payload.data.session_id del hook prevalece en contextos de hook.
• Id de plan (cuando aplique): dos ejecuciones en el mismo espacio de trabajo entrarán en conflicto sobre artefactos de plan compartidos. Usa IDs de sesión distintos (el session_id del payload del hook ya está aislado por sesión de Claude Code), o pasa --plan-id para mantener ejecuciones paralelas de ultragoal en registros separados.
• Veredicto paralelo: compatible (cada sesión escribe su propio estado a nivel de sesión).