Fase 3: Handoff (Passagem de Controle)

Skill declarativo de fase. Invocado pelo orquestrador prd-taskmaster quando current_phase é HANDOFF. Nunca chamado diretamente pelo usuário.

A regra única: detectar o que o usuário possui, recomendar UM modo, dar ao usuário uma escolha estruturada, despachar o modo escolhido. O Modo D é executado apenas em tier=premium; caso contrário, é um teaser bloqueado.

Portão de Entrada

Chamar mcp__plugin_prd_go__check_gate(phase="HANDOFF", evidence={}) para diagnósticos.

check_gate é um portão de SAÍDA: ele requer user_mode_choice e plan_file_exists — ambos produzidos pelo próprio HANDOFF, ou seja, evidências para avançar, não para entrar. Na primeira entrada, nenhum dos dois existe ainda, então um gate_passed: false aqui é ESPERADO — as transições legais da máquina de estado já garantem apenas a entrada legal.
- Primeira entrada (ainda sem evidências): anote o resultado e continue com o Procedimento.
- Reentrada: se o portão relatar violações, reporte-as e pare — ele protege contra a reexecução de uma fase concluída ou o avanço antecipado a partir de GENERATE.
Ler as saídas de GENERATE — .taskmaster/docs/prd.md, .taskmaster/tasks/tasks.json, .taskmaster/reports/task-complexity-report.json. Se alguma estiver faltando, reporte e pare. O portão deveria ter capturado isso, mas é uma redundância.

Lista de Verificação de Handoff

Copie para sua resposta antes de executar o procedimento:

LISTA DE VERIFICAÇÃO DE HANDOFF:
- [ ] Capacidades detectadas (tier + flags por capacidade)
- [ ] Modo recomendado: ___ (motivo: ___)
- [ ] Resumo exibido (localização do documento, contagem de tarefas, capacidades)
- [ ] Fluxo de trabalho de tarefas anexado ao CLAUDE.md (idempotente)
- [ ] Seletor de modo AskUserQuestion apresentado (ou fallback textual se o hook estiver bloqueado)
- [ ] Escolha do usuário despachada (Modo A / B / C, ou D quando tier=premium)
- [ ] Esqueleto de debrief emitido (opcional, tolerado silenciosamente)
- [ ] Handoff concluído

Etapa 1: Detectar Capacidades

MCP (preferencial): mcp__plugin_prd_go__detect_capabilities()

Fallback via CLI: python3 script.py detect-capabilities

Retorna um campo tier ("free" ou "premium") mais flags por capacidade. Sinais principais:

Capacidade	O Que Habilita
plugin superpowers	Modos A, C (brainstorm, planos, subagentes)
task-master-ai (CLI ou MCP)	Modo B (loop nativo de auto-execução)
plugin ralph-loop	Modo C (loop de execução iterativa)
atlas-launcher MCP (licenciado)	Modo D — Atlas Fleet (tier=premium)
habilidades atlas-loop / atlas-cdd	sementes legadas do Modo D — substituídas pela detecção do atlas-launcher
Modelo de pesquisa (task-master ou MCP)	Pesquisa aprofundada por tarefa
Playwright MCP	Verificação de navegador Tier S

O Modo D (Atlas Fleet) é desbloqueado apenas em tier: "premium" — ou seja, um registro licenciado de atlas-launcher MCP detectado por detect_atlas_launcher(). Habilidades locais atlas-loop/atlas-cdd NÃO o desbloqueiam. Consulte a Etapa 2 e a seção Modo D abaixo.

Etapa 2: Recomendar UM Modo

Lógica de decisão (a primeira correspondência vence):

superpowers + ralph-loop presente → Modo C (recomendado gratuito)
superpowers apenas → Modo A (apenas plano, condução manual)
task-master-ai apenas → Modo B (auto-execução nativa)
Fallback → Modo A

Modos de ferramentas externas (E–J: Cursor, RooCode, Codex, Gemini, CodeRabbit, Aider) são oferecidos como alternativas via o campo alternative_modes, não como recomendações principais. O Modo D é recomendado se tier == "premium" E o grafo de tarefas paralelizar (>= 2 cadeias de dependência independentes — verifique a saída de fleet-waves: qualquer onda com >= 2 blocos). Premium + grafo serial: recomende o melhor modo gratuito e explique porquê ("suas tarefas formam uma única cadeia de dependência — o Verified Loop é a ferramenta certa aqui"); Fleet permanece selecionável, mas não como padrão. Tier gratuito: o Modo D é um teaser bloqueado do Atlas Pro, nunca selecionável, independentemente de quais plugins locais estejam instalados.

Modo A: Apenas Plano (Manual)

Recomendado: Apenas Plano
  superpowers:writing-plans cria seu plano de implementação
  O plano referencia os IDs das tarefas do TaskMaster em tasks.json
  Você conduz a execução manualmente

Modo B: Auto-Execução TaskMaster (Modo B — apenas backend TaskMaster)

Recomendado: Auto-Execução TaskMaster
  MCP:  mcp__task-master-ai__next_task -> implement -> set_task_status(id, "done") (Modo B — apenas backend TaskMaster)
  CLI:  task-master next -> implement -> task-master set-status --id N --status done (Modo B — apenas backend TaskMaster)
  Loop de execução nativo do TaskMaster (nenhum orquestrador externo necessário)

Modo C: Plano + Ralph Loop (Recomendado Gratuito)

Recomendado: Plano + Ralph Loop
  superpowers:writing-plans → plano de implementação referenciando IDs de tasks.json
  ralph-loop envolve cada tarefa:
    next_task → set_task_status("in-progress") → pesquisar se <80% de confiança
    → desenvolvimento orientado por subagente → portão de execução (evidência Tier A+)
    → verificação pós-dúvida → registrar em .claude/verification-log.md
    → set_task_status("done") → TodoWrite → repetir
  Conclusão: agente de dúvida revisa o log de verificação antes de satisfazer a promessa.

Modo D: Atlas Fleet (selecionável em tier=premium; 🔒 teaser bloqueado em gratuito)

🔒 Atlas Fleet                                          Atlas Pro · $29/mês
  Execução paralela em múltiplas sessões entre Claude, Codex e Gemini:
    seu grafo de tarefas dividido em ondas de dependência de worktrees git isolados
    mesclagens com verificação de portão em um branch de integração, um PR final
    coleta de resultados em caixa de entrada durável (verificada, não narrada)
    cartão de evidência CDD por tarefa; um SHIP_CHECK_OK no final
    Saia, volte para a prova.

  Desbloqueie: https://atlas-ai.au/pro   (os modos gratuitos acima permanecem gratuitos para sempre)

Quando tier == "premium" (atlas-launcher licenciado detectado): o Modo D é um modo real e selecionável — seu despacho invoca /prd:execute-fleet (o skill orquestrador de ondas). Mostre o cartão desbloqueado:

▸ Atlas Fleet                     ★ Pro · licença ativa
  <N> ondas · estimado a partir do seu grafo de dependência · saia e volte

Quando tier == "free": o Modo D é um teaser bloqueado — não selecionável, nunca executado. Se o usuário selecioná-lo enquanto bloqueado, responda com:

"O Atlas Fleet faz parte do Atlas Pro ($29/mês). Neste projeto, ele dividiria suas tarefas em ondas paralelas entre worktrees isolados com mesclagens verificadas por portão e um PR final. Desbloqueie em https://atlas-ai.au/pro — suas especificações e tarefas estão salvas. Enquanto isso, todo o resto é gratuito para sempre: escolha um dos modos gratuitos abaixo."

Em seguida, re-invoque o seletor de modo (AskUserQuestion) com o Modo D removido das opções.

Modos Alternativos E–J (ferramentas de IA externas)

detect_capabilities retorna alternative_modes quando essas ferramentas estão instaladas. Os usuários podem escolher qualquer uma delas em vez dos Modos A–D. Todos são wrappers agnósticos em relação à ferramenta em torno do mesmo .taskmaster/tasks/tasks.json.

Modo	Ferramenta	Invocação
E	Cursor Composer	`cursor --open .taskmaster/tasks/tasks.json`, @-ref no Composer
F	RooCode	Paleta de comandos do VS Code → `RooCode: Run tasks.json`
G	Codex CLI	`python3 script.py next-task
H	Gemini CLI	`gemini --file .taskmaster/tasks/tasks.json implement next` (gratuito via Google)
I	CodeRabbit	Implemente via A–H, abra um PR, CodeRabbit revisa por tarefa. Combina com outros modos.
J	Aider	`aider --read .taskmaster/tasks/tasks.json` — estilo de programação em par

Etapa 3: Anexar Fluxo de Trabalho de Tarefas ao CLAUDE.md

Use o subcomando determinístico — não faça Leitura+Edição brutas. Este caminho é idempotente, faz um backup com timestamp ao modificar um arquivo existente e usa sentinelas de comentário HTML para que reexecuções sejam no-ops.

O conteúdo do fluxo de trabalho é o mesmo a cada execução — escreva-o em um arquivo temporário:

## Fluxo de Trabalho de Execução de Tarefas (prd-taskmaster)

Ao implementar tarefas, prefira operações de backend:
1. `python3 script.py next-task` — obtém a próxima tarefa pronta
2. `python3 script.py set-status --id <id> --status in-progress` — note o hífen; sublinhado é rejeitado
3. Implemente a tarefa (siga o plano vinculado a esta tarefa)
4. `python3 script.py set-status --id <id> --status done` — marca como concluída
5. Atualize o TodoWrite com o progresso
6. Repita a partir da etapa 1

Status válidos: `pending`, `in-progress`, `done`, `review`, `blocked`, `deferred`, `cancelled`.

### Acompanhamento de Progresso
- Atualize o TodoWrite ANTES e APÓS cada tarefa
- Não é possível prosseguir para a próxima tarefa sem atualizar o TodoWrite
- TodoWrite = visibilidade do usuário. TaskMaster = fonte da verdade.

Execute o comando de anexação. Nenhuma visualização do Modo Plano — o próprio subcomando é idempotente (sentinelas de comentário HTML controlam a escrita), portanto, as informações são apresentadas ao usuário por meio do resumo da Etapa 4 e das opções do AskUserQuestion (Etapa 5) antes do despacho, não por meio de um diálogo de plano:
```
python3 $SKILL_DIR/script.py append-workflow \
  --target ./CLAUDE.md \
  --content-file /tmp/pdtm-workflow-section.md
```
A resposta JSON relata um dos seguintes:
- action: "created" — nenhum CLAUDE.md anterior, arquivo novo com marcadores
- action: "skipped" (motivo: markers_present) — já configurado, no-op
- action: "appended" — CLAUDE.md existente inalterado, exceto pelo bloco de marcador anexado; backup_path aponta para CLAUDE.md.prd-taskmaster-backup-<ts>
Se o usuário quiser uma visualização antes da escrita, apresente o conteúdo planejado dentro das opções do AskUserQuestion ou como um parágrafo informativo no resumo da Etapa 4 — descreva o que seria escrito sem invocar nenhuma ferramenta de diálogo de plano.

Etapa 4: Exibir Resumo

Renderize o painel de handoff e imprima-o: MCP render_status(phase="HANDOFF") → imprima rendered; CLI python3 script.py status --phase HANDOFF. (Fallback — emita um bloco compacto antes do seletor de modo para que o usuário tenha contexto completo:)

Especificação Gerada: .taskmaster/docs/prd.md
Validação: <GRAU> (<pontuação>/<máx>)
Tarefas: <contagem> tarefas analisadas com dependências (consulte .taskmaster/tasks/tasks.json)
Complexidade: analisada via TaskMaster (.taskmaster/reports/task-complexity-report.json)
Pesquisa: <expandida|ignorada>

Capacidades:
  [check] TaskMaster (MCP|CLI)
  [check|circle] Playwright (verificação de navegador)
  [check|circle] Provedor de pesquisa
  [check|circle] Plugin Ralph-loop
  [check|circle] Atlas Fleet (premium: selecionável · gratuito: bloqueado)

Etapa 5: AskUserQuestion Obrigatório para Seleção de Modo

HANDOFF é o momento de agência do usuário. Recomendações em prosa são opcionais; chamadas de ferramenta não são. Você DEVE invocar AskUserQuestion nesta etapa. Isso é aplicado rigorosamente — fallback apenas em prosa é um bug, não um atalho.

AskUserQuestion dá ao usuário uma escolha explícita, estruturada e legível por máquina. Esse é o registro durável do handoff. A seleção do usuário é registrada programaticamente e as etapas posteriores despacham diretamente com base nela — sem analisar afirmações afirmativas em linguagem natural, sem ambiguidade.

Sequência

Emita um resumo de handoff cobrindo:
- Caminho do PRD + nota de validação
- Contagem de tarefas + detalhamento da complexidade
- Modo recomendado (A/B/C) + motivo em uma linha
- Modos alternativos disponíveis (E–J quando detectados, recolhidos em "Usar outra ferramenta…")
- Modo D 🔒 Teaser Atlas Fleet com o preço do Atlas Pro e URL /pro
- Uma descrição do "próximo passo" com escopo no modo recomendado (por exemplo, para o Modo B: "execute task-master next" com o ID da primeira tarefa pronta (Modo B — apenas backend TaskMaster))
Chame AskUserQuestion com uma pergunta de múltiplas opções listando cada modo de execução disponível. Use os nomes voltados ao usuário (os IDs internos entre parênteses são apenas para este skill — nunca mostrados ao usuário):
- Plano e Direção (Modo A) — obtenha o plano, implemente você mesmo
- Auto-Execução (Modo B) — loop nativo do TaskMaster, verificação mais leve
- Verified Loop (Modo C) — loop de sessão única com portão de evidência (recomendado quando superpowers + um executor de loop estão presentes)
- 🔒 Atlas Fleet (Modo D) — Atlas Pro $29/mês, multissessão paralela
- "Usar outra ferramenta…" — expande as alternativas aplicáveis de E–J
- "Mostre-me mais detalhes antes de decidir" — retorna ao resumo da Etapa 4
Marque o modo recomendado como padrão (o Atlas Fleet pode ser o padrão apenas quando tier=premium E o grafo paralelizar). Selecionar Atlas Fleet enquanto bloqueado (tier gratuito) retorna a resposta de upgrade (consulte o bloco Modo D na Etapa 2) e solicita novamente apenas com os modos gratuitos (mais quaisquer alternativas aplicáveis).
Despache o modo escolhido:
- Handoff do Modo A: invoque superpowers:writing-plans com o caminho da especificação .taskmaster/docs/prd.md
- Handoff do Modo B (Modo B — apenas backend TaskMaster): mostre o comando task-master next + o primeiro ID de tarefa pronto obtido de .taskmaster/tasks/tasks.json
- Handoff do Modo C: escreva .claude/atlas-loop-prompt.md descrevendo o contrato de execução de tarefas e, em seguida, invoque /goal com a condição:
  
  "SHIP_CHECK_OK foi emitido por .atlas-ai/ship-check.py E todas as tarefas em .taskmaster/tasks/tasks.json mostram status=done E /sync foi invocado nesta sessão"
  
  A sessão /goal continua até que o avaliador Haiku verifique a condição. Cada iteração executa o ciclo de 13 etapas de execução de tarefas e verifica a condição após a etapa 13. /sync DEVE ser a última ação antes de SHIP_CHECK_OK ser emitido (de acordo com a Terminação da execução de tarefas). (Migrado de /ralph-loop:ralph-loop em 2026-06-04 — o avaliador /goal embutido do Claude Code resolve estruturalmente a podridão de tripla-verificação de que o controlador usa chapéus diferentes, capturada na auditoria de 2026-06-03.)
- Handoff do Modo D (tier=premium): invoque /prd:execute-fleet — ele é responsável pelo loop de ondas, despacho de trabalhadores, verificação, mesclagens e terminação SHIP_CHECK_OK. (tier gratuito: apenas resposta de upgrade, nova solicitação)

Fallback com Hook Bloqueado (Degradação Graciosa)

Se PreToolUse:AskUserQuestion estiver bloqueado por hook (sessão automatizada / orquestrador / frota), recorra a uma tabela de opções em prosa preservando a mesma semântica — rótulos, descrições, Modo D bloqueado como teaser, alternativas E–J. Anexe uma nota:

"Seleção de modo via AskUserQuestion bloqueada pelo ambiente atual. O modo pode ser redefinido em uma reinicialização natural da sessão (sem modo definido).

E então continue com o modo recomendado. Não pare; o código do orquestrador lida com essa degradação em toda a máquina de estado.

Etapa 6: Concluir Handoff

Registrar user_mode_choice no armazenamento de evidências (via set_evidence) para que check_gate na próxima entrada veja o registro durável.
Invocar mcp__plugin_prd_go__transition(state="EXECUTE", phase="EXECUTE") — sinalizar para o orquestrador que HANDOFF está completo e EXECUTE pode começar.
Declarar ao usuário:

"Handoff concluído. Modo selecionado. O orquestrador agora entrará na Fase EXECUTE. Você pode ver o status atual a qualquer momento com python3 script.py status."

Contrato Pós-Handoff

Reentrada: se o orquestrador chamar HANDOFF novamente (por exemplo, o usuário solicita reseleção de modo), a Etapa 1 verificará user_mode_choice e plan_file_exists e sinalizará violação. O orquestrador deve redefinir explicitamente essas evidências antes da reentrada.
Idempotência: anexar o fluxo de trabalho ao CLAUDE.md, detectar capacidades e mostrar o resumo são seguros para reexecução. A anexação é protegida por sentinela de comentário HTML; a detecção de capacidades é somente leitura.
Responsabilidade de Despacho: a chamada de ferramenta real para o modo selecionado (por exemplo, superpowers:writing-plans, /goal) acontece na Fase EXECUTE, não durante HANDOFF. HANDOFF seleciona e registra; EXECUTE age. No entanto, o Modo D (Atlas Fleet) quando tier=premium é uma exceção: seu despacho invoca /prd:execute-fleet imediatamente como parte do Handoff do Modo D, pois o orquestrador de frota contém seu próprio loop de execução de ondas (EXECUTE torna-se uma transição de estado vazia).

prd-taskmaster - Fase 3: Handoff

O que é prd-taskmaster - Fase 3: Handoff?

Perguntar na sua IA favorita

Documentação