ultragoal

<Propósito> O Ultragoal divide uma solicitação breve em um conjunto ordenado de metas, registra eventos de início/checkpoint/obstáculo/falha em um registro anexável e durável, e informa ao agente Claude ativo como usar o comando /goal do Claude Code junto com o plano. Ele não pode — e não tenta — alterar o estado do /goal do Claude a partir do shell; ele persiste o estado durável do repositório e imprime um handoff voltado ao modelo, que o agente ativo deve seguir dentro da sessão. </Propósito>

<Quando_Usar>

• O usuário deseja uma forma durável e nativa do repositório para rastrear um ultragoal entre várias sessões do Claude ou árvores de trabalho
• O trabalho é grande o suficiente para justificar várias "histórias" ordenadas com contagens de tentativas e evidências por história
• O usuário deseja que a conclusão final seja protegida por aiSlop-cleaner + verificação + $code-review
• O usuário deseja que a diretiva /goal ativa do Claude seja coordenada com o registro, para que uma reinicialização da sessão não perca o progresso </Quando_Usar>

<Não_Usar_Quando>

• A tarefa é uma pequena alteração única — use delegação direta ou ralph
• O usuário deseja que o assistente execute /goal diretamente no shell — isso não é possível; omc ultragoal apenas escreve artefatos e imprime texto de handoff
• O usuário deseja um artefato apenas de planejamento sem loop de execução — use plan </Não_Usar_Quando>

<Por_que_Isso_Existe> O /goal do Claude Code é um hook de parada com escopo de sessão: ele impede que a sessão pare até que uma condição seja satisfeita e é limpo automaticamente ao ser bem-sucedido. Esse é um ótimo primitivo de execução para sessão única, mas perde o estado entre sessões e, por si só, não impõe uma etapa de revisão final. O omc ultragoal adiciona um plano durável, um registro e uma camada de proteção para que uma iniciativa longa e de várias etapas possa sobreviver a reinícios de sessão, novas árvores de trabalho e iterações de revisão, enquanto ainda aproveita o /goal do Claude para manter o agente ativo focado. </Por_que_Isso_Existe>

<Como_Usar>

1. Crie um plano a partir de uma solicitação breve:

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

   Ou com histórias explícitas:

   omc ultragoal create-goals --brief "enviar a migração" \
     --goal "Schema::Adicionar novas colunas" \
     --goal "Backfill::Preencher linhas em lotes" \
     --goal "Cutover::Remover colunas antigas e alternar leituras"
   

   O modo padrão é aggregate (um único /goal do Claude cobre toda a execução). Use --claude-goal-mode per-story se desejar que cada história tenha seu próprio /goal.

   Espaços de trabalho multi-repo / sessões paralelas: quando várias sessões do Claude no mesmo espaço de trabalho precisam executar /ultragoal simultaneamente, use --plan-id <id-estável> ou --auto-plan-id para que o plano seja escrito em .omc/ultragoal/plans/{planId}/ em vez do caminho de plano único compartilhado. Sem essa sinalização, duas sessões criando metas se sobrescreveriam. --auto-plan-id deriva {epochMs}-{slug} do título da solicitação breve. Em seguida, repasse o mesmo --plan-id <id> em todos os subcomandos subsequentes dessa sessão. Use omc ultragoal list-plans para enumerar os planIds disponíveis quando necessário.

2. Inicie (ou retome) a próxima história:

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

   Sem um id de meta, isso preserva o comportamento padrão de retomar a história ativa ou iniciar a primeira história pendente. Com um id de meta, o OMC tem como alvo exatamente essa história elegível nomeada (uma história pendente pode ser iniciada fora de ordem); ele nunca passa para outra história. Uma história ativa diferente, id desconhecido, história concluída ou bloqueada por revisão, ou história reprovada sem --retry-failed é rejeitada sem mutação de estado. Uma história nomeada em andamento é retomada sem alterar sua contagem de tentativas. Isso imprime um handoff voltado ao modelo. O agente Claude ativo deve lê-lo e:

   • Definir o /goal nativo do Claude para esta sessão — no Claude Code autônomo, nem o shell nem o agente podem fazer isso, então peça ao usuário para digitar /goal <objetivo agregado> e aguardar. --claude-goal-json (abaixo) concilia apenas o registro e não satisfaz a proteção PreToolUse /goal, que bloqueia chamadas de ferramentas até que observe um /goal ativo.
   • Trabalhar na história.
   • Quando a história estiver concluída (e para a história final, após a barreira de qualidade completa), compartilhe um instantâneo do estado ativo do /goal e chame checkpoint.

3. Faça checkpoint de uma história:

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

   Para a história final, também use --quality-gate-json contendo evidências de aiSlopCleaner, verification e codeReview (todas limpas).

4. Se a revisão final não estiver limpa, NÃO marque como concluída. Registre obstáculos:

   omc ultragoal record-review-blockers --goal-id G00X-... \
     --title "Resolver obstáculos da revisão de código final" \
     --objective "Corrigir as conclusões da revisão encontradas e executar novamente as barreiras finais" \
     --evidence "<as conclusões da revisão>" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   Isso adiciona uma nova história de obstáculo e mantém o /goal do Claude ativo.

5. Inspecione o estado a qualquer momento:

   omc ultragoal status
   

</Como_Usar>

<Limitações_Importantes>

• O shell não pode invocar ou alterar o estado do /goal do Claude Code. O omc ultragoal apenas persiste artefatos duráveis e imprime instruções que o agente Claude ativo lê e executa dentro da sessão.
• Os instantâneos passados via --claude-goal-json são provas fornecidas pelo modelo do estado ativo do /goal; o OMC os valida quanto à consistência textual com o objetivo esperado do plano e o evento do registro, mas não pode observar o estado do /goal do Claude de forma independente. Eles não satisfazem a proteção PreToolUse /goal, que exige um /goal ativo real — um instantâneo injetado pelo host ou o /goal nativo definido pelo usuário na sessão.
• Se o comando /goal do Claude for renomeado ou reestruturado, apenas a redação do handoff precisa mudar; a lógica de reconciliação é agnóstica ao nome. </Limitações_Importantes>

Cuidados com sessões paralelas

• Âncora de espaço de trabalho multi-repo: coloque um marcador .omc-workspace no diretório pai para que várias sessões em sub-repositórios compartilhem um único .omc/. Ordem de resolução: OMC_STATE_DIR > .omc-workspace > git > cwd. Consulte docs/REFERENCE.md.
• Fonte do id da sessão: A variável de ambiente OMC_SESSION_ID prevalece em contextos CLI; dados de payload da sessão do hook (data.session_id) prevalecem em contextos de hook.
• Id do plano (quando aplicável): Duas execuções no mesmo espaço de trabalho entrarão em conflito nos artefatos de plano compartilhados. Use IDs de sessão distintos (o session_id do payload do hook já é isolado por sessão do Claude Code) ou use --plan-id para manter execuções ultragoal paralelas em registros separados.
• Veredito paralelo: suportado (cada sessão escreve seu próprio estado com escopo de sessão).