power-platform — orquestrador

Duas funções. App novo: coordena o pipeline guiado /pp:*, da ideia ao app publicado, uma etapa por sessão, com o ESTADO.md dizendo onde o projeto está e qual é o próximo comando. App existente: decide o que carregar, quem executa e quando está pronto num trabalho com mais de uma camada. O conhecimento de Power Fx, YAML, flow, procedure e tabela vive nas skills de domínio.

Regras inegociáveis

1. Leia o projeto antes de agir (passo 1). Não escreva tela, flow ou procedure sem trilha ativa e nomes do ambiente conhecidos. Por quê: nome de coluna e de procedure chutados foram a causa nº 1 de retrabalho nos projetos de referência.
2. Uma etapa do pipeline por sessão, na ordem. O estado.py confere a ordem e dá o próximo comando; você não inventa outro nem segue para a etapa seguinte na mesma conversa. Por quê: tudo o que a etapa seguinte precisa está no disco, e contexto limpo não arrasta decisão velha.
3. Uma trilha de dados por projeto. Trocar de trilha exige ADR (assets/adr-molde.md). Por quê: a trilha "congelada" foi editada e a "ativa" ficou semanas para trás.
4. Ordem de dependência: dados → (frontend ∥ automação) → QA. Nenhuma tela começa antes de a tabela/procedure dela existir e estar em NOMES-AS-BUILT. Por quê: a tela é o consumidor; escrever o consumidor primeiro fixa nomes que ainda não existem.
5. ✅ sem evidência não vale. Toda tarefa concluída traz comando + saída + data. Evidência perde a validade quando o arquivo muda depois dela. Por quê: uma tarefa ✅ tinha regredido porque um gerador foi reescrito e apagou a correção.
6. Verde só conta se o validador provou que acusa. 0 erro(s) de um validador que não leu o formato do arquivo é verde falso (references/portao-final.md). Por quê: um validador deu 0 erro(s) em telas em YAML puro porque só lia blocos cercados.
7. Gerador nunca escreve sobre gabarito. Saída de gerador vai para dist/; o arquivo colado no designer é o gabarito. Por quê: regerar apagou a única evidência de ambiente que existia.
8. Padrão decidido não se reabre em silêncio. O que está em references/decisoes-padrao.md vale; divergir exige ADR. Por quê: sem registro, a tecnologia trocou várias vezes sem que ninguém soubesse o motivo.
9. Entrega de agente é hipótese até você conferir. Rode o validador, abra o arquivo, reproduza os achados mais fortes antes de seguir ou reportar. Por quê: já vieram como fato "o backend está vazio" e "a variável nunca é inicializada", ambos falsos.
10. Nada de ambiente, servidor, tabela dev* ou GUID literal em artefato. Variável de ambiente + connection reference (references/alm-ambientes.md). Por quê: fonte de desenvolvimento misturada com produção fez o KPI divergir da galeria.

Fluxo de trabalho

Passo 1 — Ler o projeto

1. ESTADO.md (procurado da pasta atual para cima). Existe: o projeto está no pipeline. Rode python "${CLAUDE_PLUGIN_ROOT}/skills/power-platform/scripts/estado.py" mostrar antes de tudo.
2. power-platform.config.json (formato em docs/CONFIG.md do repositório do plugin): anote trilha_dados, pastas, nomes_as_built. Sem config fora do pipeline: declare "rodando com defaults" e proponha criar a partir de assets/power-platform.config.exemplo.json.
3. 00-LEIA-PRIMEIRO.md: trilha ativa por camada. Se contradiz o config, pare e resolva antes de editar.
4. references/decisoes-padrao.md; a fila GOAL.md, se houver (confira no disco qual pasta está sendo editada, não só o que o documento diz); NOMES-AS-BUILT, se a tarefa toca dados.

Passo 2 — Rotear

Passo 3 — O pipeline de app novo

Detalhe, desenho e arquivos de cada etapa: references/pipeline.md. Formato de banner, checkpoint e próximo passo, igual em todas: references/formato-saida.md.

/pp:progresso mostra o painel a qualquer momento. As etapas só rodam pelo comando do usuário (não se invocam sozinhas): fora delas, seu papel é dizer qual comando rodar.

Passo 4 — Protocolo (app existente, tarefa com mais de um passo)

Mapear → Planejar → Executar → Validar → Reportar (references/protocolo.md). Mapear com o comando que achou cada coisa; planejar em até 5 passos dizendo o que não será feito; executar na ordem de dependência com molde e bloco canônico; validar no portão final; reportar o que mudou, como aplicar, os avisos e o que ficou de fora.

Passo 5 — Modos

• Investigar (references/modo-investigar.md): cadeia tela → fórmula → fonte → flow → procedure → dado, uma hipótese por vez, prova antes de correção.
• Fila GOAL.md (references/modo-goal-fila.md): próxima 🟢 cuja onda anterior fechou; numa 🔴, pare e diga o que fazer no ambiente. No pipeline, quem anda a fila é o /pp:construir.
• Promover (references/alm-ambientes.md): o que vai por colagem × por solução.

Passo 6 — Subagentes

Do pipeline: os pp:agente-*, chamados pelas etapas. Fora dele: abra subagente só quando o trabalho é independente e exige leitura ampla; escopos disjuntos, todos numa mensagem, quem delega coleta e confere. Subagente não conversa com o usuário. Detalhe: references/subagentes.md.

Passo 7 — Portão final

Rode todos os validadores das camadas tocadas e o checklist de references/portao-final.md. Tela ou flow alterado: a prova final é colar no Studio/designer, ou registrar 🔴 para o humano.

Referências

Scripts

Rode da raiz do projeto. Sem power-platform.config.json, os validadores avisam que usam defaults.

Cada um tem --help. O que cada validador não cobre: references/portao-final.md.

Definição de pronto (global)

• Passo 1 cumprido: ESTADO.md (no pipeline), config e trilha ativa citados no relatório.
• Nomes de tabela, coluna e procedure conferidos em NOMES-AS-BUILT (ou marcados "inferido").
• Todo validador aplicável rodou: N erro(s), M aviso(s) colado, com 0 erro(s) e arquivos lidos > 0.
• Tela ou flow alterado colado no Studio/designer, ou 🔴 com o passo exato.
• Contrato app↔flow respeitado: {status, description, id, url}, .Run() em IfError.
• Nenhum literal de ambiente em artefato de entrega.
• Fila atualizada: cada ✅ com Evidência; ESTADO.md atualizado pelo estado.py.
• Entrega de agente conferida por você antes de entrar no relatório.
• Etapa do pipeline encerrada com o bloco "Próximo passo" do script.

Armadilhas (as mais caras)

1. Seguir para a próxima etapa na mesma sessão, ou inventar o próximo comando: formato-saida.md.
2. Rodar só um dos validadores e declarar verde: portao-final.md.
3. Regerar sobre o gabarito colado: salvaguardas.md.
4. Escrever tela contra o plano em vez do NOMES-AS-BUILT: decisoes-padrao.md.
5. Chamar a API de imagens sem o "pode gerar" do usuário: mockups.md.
6. Tratar "o número não bate" como bug de fórmula antes de checar fonte e ambiente: modo-investigar.md.
7. Confiar em "✅" da fila sem Evidência: modo-goal-fila.md.
8. Subagente para uma tela, ou dois no mesmo arquivo: subagentes.md.
9. Hardcode de ambiente que impede promover: alm-ambientes.md.
10. Terminar o turno "aguardando" subagentes: subagentes.md.