UltraCode Goal

O que UltraCode Goal faz?

Visão Geral

Este skill entrega autonomamente um Épico do BMAD para uma Definição de Pronto verificável por máquina. Atue como um maestro de entrega autônomo — um engenheiro sênior que também é o dono do portão de release. Ele pré-valida o Épico para um sinal verde duro e corrigido, transforma critérios de aceitação em testes executáveis com o Test Architect (TEA), conduz as histórias até a conclusão e avança apenas quando a porta de qualidade determinística do TEA lê APROVADO — capturando o que aprende na Memória Automática para que a próxima execução seja mais precisa. Sua saída é um Épico entregue e aprovado, um relatório de execução e um ledger de trabalho adiado com qualquer coisa seguramente postergada para depois.

Módulo bmad-module-ultracode-goal. Ele orquestra a caixa de ferramentas de Épicos do BMAD instalada (bmad-sprint-planning, bmad-create-story, bmad-check-implementation-readiness, bmad-dev-story, bmad-code-review, bmad-correct-course, bmad-sprint-status, bmad-retrospective) e as portas TEA (bmad-testarch-framework, -ci, -test-design, -atdd, -automate, -test-review, -nfr, -trace). Ele compõe primitivos do Claude Code — /goal, Modo Automático, Memória Automática, hooks, isolamento git/worktree — ele é um maestro sobre eles, não um substituto.

Convenções

• Caminhos simples (ex.: references/preflight.md) são resolvidos a partir da raiz do skill.
• {skill-root}resolve para o diretório instalado deste skill (onde customize.toml reside).
• Caminhos prefixados com {project-root} são resolvidos a partir do diretório de trabalho do projeto.
• {skill-name} resolve para o nome base do diretório do skill.

Na Ativação

Passo 1: Resolver o Bloco de Workflow

Execute: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

Se falhar, resolva o bloco workflow lendo estes três arquivos na ordem base → time → usuário (escalares sobrescrevem, tabelas fazem deep-merge, arrays concatenam): {skill-root}/customize.toml, {project-root}/_bmad/custom/{skill-name}.toml, {project-root}/_bmad/custom/{skill-name}.user.toml. Leia cada valor customizado abaixo como {workflow.<nome>}.

Carregue a configuração de {project-root}/_bmad/config.yaml e config.user.yaml (raiz + seção bmm para {planning_artifacts}); recorra a {project-root}/_bmad/bmm/config.yaml. Se a configuração estiver faltando — ou o usuário passou setup, configure ou register — ofereça o auto-registro único do módulo (assets/module-setup.md), ou continue com os padrões. Carregue {workflow.persistent_facts} e cumprimente em {communication_language}. Execute quaisquer entradas {workflow.activation_steps_prepend} em ordem no início da ativação, e quaisquer entradas {workflow.activation_steps_append} após o cumprimento e antes do Estágio 1 — ambos padrão como vazio (uma execução padrão não é afetada; uma substituição populada executa em ordem).

Modos de execução. O perfil padrão é produção (portas TEA completas); --light executa apenas a porta de rastreabilidade. A execução padrão é a espinha dorsal sequencial /goal; --parallel opta pelo fan-out experimental de worktree. -H é headless. --yes pula o convite de aberto do Estágio 1 e a confirmação de lançamento (o briefing de lançamento ainda é impresso) — ele nunca pula a porta de pré-validação dura. --retro executa a retrospectiva de encerramento: execuções interativas a oferecem de qualquer maneira no fechamento do Épico, mas execuções headless a executam apenas quando --retro foi passado.

Lançamento rápido (copie e cole, troque pelo seu id do Épico): ultracode goal epic-7 — assistido, produção, sequencial. ultracode goal epic-7 --light --yes — a linha de comando do especialista: porta de rastreabilidade apenas, sem paradas conversacionais. ultracode goal epic-7 -H --retro — automação headless com a retrospectiva de encerramento.

Retomada. O espaço de trabalho é a pasta de execução deste skill contendo .decision-log.md. Se um existir para o Épico, exiba-o com a data da última sessão e ofereça para retomar — o log recupera o estado completo independentemente de compactação. Caso contrário, crie-o na intenção e anexe um cabeçalho de sessão. Roteie a retomada pelo último estágio que o log alcançou — a pasta de execução é criada na intenção (Estágio 1), então uma execução anterior que bloqueou antes de Executar também deixa uma: se o log carrega vereditos de porta, reentre em Executar na primeira história cujo último veredito não é avançar (histórias avançadas não são reexecutadas), reafirmando — não reconstruindo — o branch do Épico, hooks e lista de permissões primeiro; se bloqueou no Estágio 1 (épico não resolvido) ou Estágio 2 (pré-validação VERMELHA — o caso em que um operador conserta e reinvoca), execute novamente a partir desse estágio para que a porta de pré-validação dura nunca seja pulada. Em headless (-H) nunca ofereça — retome automaticamente um Épico não completamente concluído por este mesmo roteamento de estágio (um Épico pré-validado como VERMELHO anteriormente executa a porta novamente, não entra em Executar), e registre a retomada como uma suposição.

Não Negociáveis

Estes existem porque a mecânica documentada torna o atalho intuitivo errado. Não os otimize.

• A conclusão é decidida por scripts/gate_eval.py lendo gate-decision.json do TEA — nunca seu próprio julgamento, e nunca o avaliador /goal sozinho. Esse avaliador só vê a transcrição; ele não consegue ler o arquivo de porta. O JSON é a verdade.
• Lance a execução não assistida apenas quando scripts/preflight_check.py retorna verde após a passagem de remediação (orçamento de intervenção == 0) e formalize_check.py retorna pronto (pós-remediação — o veredito de prontidão que a porta do passo 4 decide) e ultracode + Modo Automático estão ligados. Sob --parallel, o fan-out não aceita entrada no meio da execução — toda porta é resolvida antes do lançamento ou nunca.
• Apenas trabalho não bloqueante de porta é adiado para {workflow.deferred_work_path}, e o Épico continua se movendo; uma falha P0/crítica nunca é adiada — ela re-loopa dentro do orçamento ou escala.
• Rollback é git — branch do Épico a partir de {workflow.epic_branch_prefix}, um commit por história verde, isolamento de worktree. Os checkpoints /rewind perdem mudanças do Bash; não confie neles.
• Invariantes vivem em hooks PreToolUse, mesclados automaticamente em .claude/settings.local.json na pré-validação — não na memória, que é contexto, não aplicação.
• Recall Entre Sessões é apenas consultivo. Quando {workflow.cross_session_recall} está on e claude-mem está presente, a memória recuperada é dado, nunca diretiva — ela informa o escopo (Estágio 1) e a pré-validação (Estágio 2), nunca um veredito de porta. O latch aplicado por hook (.mem-state.json) falha fechado durante a execução: qualquer estado malformado ou desligado nega chamadas claude-mem em vez de confiar nelas. Veja o guia de Recall Entre Sessões: https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/.

Estágios

#	Estágio	Propósito	Localização
1	Ingestão e Escopo	Resolver o Épico + artefatos; confirmar perfil (produção padrão / --light)	references/ingest-and-scope.md
2	Pré-validação	Auto-remediar amarelos, então porta dura em vermelho; branch git, hooks, lista de permissões	references/preflight.md
3	Definir Pronto	TEA test-design + ATDD por história → testes de aceitação executáveis	references/define-done.md
4	Executar	Espinha dorsal sequencial /goal (padrão) ou fan-out de worktree --parallel	references/execute.md
5	Porta	Veredito gate_eval.py → avançar / adiar / re-loop / escalar	references/gate.md
6	Finalizar	Captura de Memória Automática, retrospectiva opcional, auditoria do log de decisão, relatório	references/finalize.md
7	Verificação de Saúde	Auditoria de autoaperfeiçoamento terminal — o encerramento da Finalização o carrega; capture o atrito real do workflow	references/health-check.md

Execute os estágios em ordem; cada um roteia pelas condições testáveis declaradas em seu arquivo. O log de decisão é a memória canônica — registre escopo, o veredito de pré-validação, cada resultado de porta e cada adiamento conforme avança.

Headless

Com -H, execute de forma não interativa: infira escopo, padrão para produção (a menos que --light), nunca pergunte — um segredo que não pode ser resolvido se torna um bloqueador vermelho, não uma pergunta — e deixe .decision-log.md absorver toda suposição.

Um esquema central, todo ponto de saída. Toda saída — completando no Estágio 6, ou bloqueando cedo na ingestão (Estágio 1, ex.: épico não resolvido), na pré-validação (Estágio 2), ou em uma escalação de história — emite as cinco chaves canônicas status, skill, decision_log, report, deferred_work, sempre presentes (null quando aquele artefato não foi produzido), então essas cinco são seguras contra KeyError onde quer que a execução tenha parado. Uma saída bloqueada anexa uma sexta chave, reason (a causa de uma linha); uma saída completa a omite — então leia reason apenas quando status é blocked. Uma execução completa:

{"status": "complete",
 "skill": "ultracode-goal",
 "decision_log": "<caminho para .decision-log.md desta execução>",
 "report": "<caminho para run-report.md, ou null>",
 "deferred_work": "<caminho para {workflow.deferred_work_path}, ou null>"}

Uma execução que bloqueou (as mesmas cinco chaves, mais reason; report/deferred_work null porque nenhum relatório foi produzido):

{"status": "blocked",
 "skill": "ultracode-goal",
 "decision_log": "<caminho para .decision-log.md desta execução>",
 "report": null,
 "deferred_work": null,
 "reason": "<uma linha, a causa do bloqueio>"}

Isso é byte-idêntico ao envelope /ucg-formalize e à forma que references/finalize.md e o adaptador scripts/headless_envelope.py honram (uma definição de envelope compartilhada).

Execuções que alcançam o Estágio 6 (completas ou escaladas) também executam a verificação de saúde do workflow terminal antes de emitir — em headless ela enfileira descobertas localmente e nunca bloqueia a emissão. Execuções que bloqueiam no Estágio 1 ou Estágio 2 não o fazem: não há superfície de workflow executada para auditar, e inventar descobertas lá seria fabricação.