tomtdhzz/orquestrador-de-requisitos

Orquestrador de Requisitos

Transforme uma solicitação de software em trabalho independentemente verificável, mantendo um único agente controlador responsável pelo escopo, dependências, evidências e integração. Esta habilidade é um orquestrador, não um gerador de prompts.

Selecione um modo semântico

• analyze (analisar): investigue a solicitação e o código-fonte, mantenha o ledger e produza um blueprint de execução sem modificar código. Este é o padrão quando a implementação não foi solicitada.
• diagnose (diagnosticar): reproduza e explique uma falha relatada, separando a causa raiz confirmada, as evidências, as incógnitas e os caminhos de reparo recomendados. O diagnóstico é a entrega; não modifique código.
• execute (executar): despache trabalho delimitado, revise os resultados retornados e conclua a integração. Entre somente quando o usuário autorizar a implementação ou execução.
• challenge (desafiar): teste um requisito, decomposição ou design existente em busca de omissões e riscos, sem alterar seu objetivo de produto confirmado. Consulte references/challenge.md.

Estes são modos semânticos de nível de habilidade. Eles não invocam nem exigem o Modo Plano nativo de uma plataforma, EnterPlanMode ou agentes obrigatórios de Exploração/Planejamento. Use modos nativos apenas quando forem independentemente úteis e compatíveis com as restrições do usuário.

Para uma tarefa de causa raiz única, sem delegação, use o loop de controle diretamente. Leia references/spec-driven.md para moldar a especificação (requisitos, cenários de aceitação, contratos). Leia references/context-grounding.md antes de decompor em um código-fonte existente. Leia references/decomposition.md quando houver mais de uma tarefa candidata, um limite de serviço/domínio, uma decisão de agendamento ou uma falha de construção/implantação onde o estado do repositório pode ser causal. Leia references/verification.md para os padrões de evidência de aceitação. Leia references/ledger.md quando o trabalho tiver várias tarefas, agentes, sessões ou plataformas. Leia references/mutation.md quando a execução reescrever, excluir ou propagar uma alteração em mais de um artefato existente, ou gravar em um sistema externo. Execuções de exemplo: references/examples/feature-example.md e references/examples/bug-example.md.

Em diagnose, relate a falha observada ou reproduzida, a causa raiz confirmada e as evidências, os itens não verificados, o impacto e os caminhos de reparo recomendados. Pare aí, a menos que o usuário autorize separadamente execute.

Loop de controle

1. Estabeleça o objetivo, escopo, critérios de aceitação, restrições e fatos verificados do código. Fundamente as incógnitas primeiro (references/context-grounding.md), depois expresse o resultado como uma especificação — requisitos, cenários de aceitação e contratos (references/spec-driven.md). Investigue fatos descobríveis; pergunte ao usuário apenas sobre decisões que afetem materialmente o escopo, a aceitação ou a direção. Antes de decompor, consulte a base de conhecimento de capacidades (consulte references/knowledge-base.md) para obter as habilidades existentes relevantes para o objetivo e uma comparação de mesmo domínio; prefira reutilizar ou importar uma capacidade conhecida a pesquisar do zero e registre as capacidades escolhidas no ledger.
   • Leia as lições de projetos anteriores, se presentes (references/experience.md) e trate-as como fatos candidatos a verificar, não como evangelho.
   • Para uma construção não trivial, após a especificação, produza um design técnico (references/tech-design.md) — arquitetura, design detalhado, alternativas, preocupações transversais — e persista os artefatos sob o layout docs/ (references/deliverables.md).
2. Para um bug ou falha relatada, tente uma reprodução local proporcional antes de alegar uma causa raiz. Compare a falha observada com o relato. Até que seja reproduzida ou apoiada por evidências diretas equivalentes, rotule as declarações de causa raiz como hipóteses e indique o que permanece não verificado.
3. Escolha um eixo de decomposição primário e crie tarefas delimitadas. Derive os contratos compartilhados e congele-os antes do trabalho dependente ou paralelo (references/spec-driven.md). Registre dependências e contratos entre tarefas explicitamente. Reflita os grupos de tarefas resultantes em um TODO faseado (consulte a Superfície de progresso).
4. Mantenha exatamente um agente controlador. O controlador é o dono do ledger, das decisões de despacho, do status de revisão, do replanejamento e da integração final.
5. Despache apenas tarefas com um contrato completo. Leia references/agent-contract.md antes do primeiro despacho. Antes de despachar gravações para qualquer sistema além da árvore de trabalho local, execute a verificação prévia do sistema de destino abaixo.
6. Aceite um resultado de trabalhador em review (revisão), verifique suas evidências e limites em relação aos padrões de evidência de aceitação (references/verification.md), e então marque-o como completed (concluído) ou retorne-o com descobertas específicas. Para uma mutação em massa ou externa, verifique por meio de leitura de volta independente e um delta estrutural, não pela contagem de sucesso relatada pela ferramenta.
7. Recalcule as dependências afetadas após descobertas, falhas ou mudanças de escopo. Retrabalhe o menor ramo afetado.
8. Declare a solicitação concluída somente após as verificações no nível da tarefa, os contratos entre tarefas e cada cenário de aceitação passarem juntos; a verificação de ponta a ponta é definida em references/verification.md. Ao concluir, anexe quaisquer lições específicas do projeto que se qualificarem ao registro de experiência (references/experience.md). Melhorar a própria habilidade a partir da execução é uma ação opt-in separada — oferecida apenas quando uma lição é geral e recorrente, aplicada somente se o usuário escolher, nunca automática (consulte references/experience.md).

Superfície de progresso

Mantenha um TODO faseado visível sincronizado com o ledger para que o usuário veja o progresso em fases e etapas, não apenas prosa. O ledger permanece a fonte de verdade detalhada (dependências, escopos, contratos, evidências); o TODO faseado é sua visão de progresso.

• Inicialize uma fase por grupo de decomposição e, em seguida, uma fase de aceitação final (para um fluxo de bug, 对照 / 修复 / 验证; para um fluxo de funcionalidade, os grupos de funcionalidades seguidos por 全量验收). Cada item é uma tarefa delimitada ou etapa de verificação, expressa como um resultado em 5 a 10 palavras.
• Conduza-o com a lista de tarefas nativa da plataforma, nunca uma árvore formatada manualmente. No Claude/omp use a ferramenta todo: init com list: [{phase, items}], depois start/done por item. No Codex use seu mecanismo de plano/atualização de plano.
• Avance o estado a partir do progresso real: marque um item como em andamento quando sua tarefa for despachada e como concluído somente após o controlador registrar completed no ledger. As contagens de fase (N/M) rastreiam então a aceitação verificada, não o despacho.
• Mantenha os dois consistentes: um item de TODO corresponde exatamente a uma tarefa do ledger ou etapa de verificação. Recalcule ambos juntos durante o replanejamento.
• Em analyze e diagnose, as fases são etapas de investigação ou diagnóstico e sua conclusão não modifica código.

Artefatos entregáveis

Separe documentos publicáveis do estado de orquestração interna: documentos voltados para o leitor vão para docs/ (docs/prd/ especificação, docs/tech-design/ design); o ledger, o plano e as lições são estado de trabalho interno sob .ai-work/ — nunca sob docs/, e gitignorados para um projeto publicável. Consulte references/deliverables.md.

Para qualquer construção não trivial, produza um design técnico após a especificação e antes de execute: arquitetura, design detalhado, alternativas consideradas e preocupações transversais (references/tech-design.md). Pule para uma correção de causa raiz única onde a especificação mais uma lista de tarefas seja suficiente.

Auto-revise cada entregável Markdown gerado antes da entrega: releia-o e confirme que ele é renderizado como o leitor o verá — estrutura intacta, blocos com cerca/Mermaid realmente analisáveis (renderize-os, não apenas os inspecione visualmente), links resolvidos. Uma falha de análise/renderização é um defeito a ser corrigido agora. Consulte references/deliverables.md e a linha Document / diagram artifact em references/verification.md.

Quando o entregável for um projeto independente, "concluído" inclui ser publicável: um README (o quê/porquê, pré-requisitos, instalação, exemplos de uso, configuração, arquitetura, teste, limitações, licença, aviso legal), uma LICENSE e um .gitignore que exclua saída de construção, segredos e .ai-work/. Verifique se os comandos do README realmente são executados. Consulte references/deliverables.md.

Verificação prévia do sistema de destino

Antes de despachar gravações para qualquer sistema diferente da árvore de trabalho local — um wiki, sistema de tickets, banco de dados ou API remota — verifique antecipadamente:

• permissão de gravação e o escopo exato que as operações planejadas precisam, incluindo exclusão ou movimentação se o plano as exigir;
• limites de taxa e se as falhas são silenciosas; escolha concorrência segura e uma política de repetição ou backoff;
• que o resultado pode ser lido de volta para verificar.

Descubra uma capacidade ausente aqui, não no meio do lote. Se uma permissão ou escopo necessário estiver indisponível, trate-o como um bloqueador: indique exatamente o que está faltando e a menor concessão que desbloqueia, e pare antes de qualquer aplicação parcial.

Roteamento de plataforma

• Para Codex, leia references/codex-adapter.md.
• Para Claude, leia references/claude-adapter.md.
• Ao transferir o controle entre eles, escreva e confirme um snapshot de handoff antes que o controlador antigo pare de despachar.
• Trellis é opcional. Leia references/trellis-adapter.md apenas quando seus sinais de escalonamento se aplicarem ou o usuário o solicitar.

Limites não negociáveis

Estes são invariantes do tipo NÃO DEVE, independentemente da redação; mantenha-os poucos e precisos. Em outras partes desta habilidade, classifique a força da regra com as palavras-chave da RFC 2119 — DEVE / NÃO DEVE / PODE, significativas apenas em maiúsculas — e use moderação: reserve DEVE / NÃO DEVE para correção ou dano, deixe preferências como PODE / PODE. Emparelhe cada proibição com o "faça em vez disso" positivo: para agentes, regras apenas negativas não são confiáveis (elas estimulam o próprio comportamento que proíbem), portanto, um pequeno conjunto de limites rígidos mais padrões positivos é a forma robusta, não uma lista de verificação obrigatória cada vez maior.

• Não trate a posição na árvore de tarefas como dependência de execução.
• Não permita que trabalhadores expandam seu escopo de gravação silenciosamente.
• Não execute agentes de gravação em paralelo, a menos que as dependências estejam resolvidas, os escopos de gravação não se sobreponham, os contratos compartilhados estejam congelados e a validação seja independente.
• Um trabalhador pode enviar trabalho para revisão; apenas o controlador pode marcá-lo como concluído.
• Ao alterar artefatos existentes, não limpe e reescreva nada que a tarefa não tenha criado e não possa regenerar; insira ou corrija no local, marque-o com um marcador seguro para reexecução e verifique por meio de leitura de volta independente.
• Não afirme um valor derivado — uma classificação, rótulo, resumo, classificação de risco ou recomendação — além de sua fonte verificada; marque uma derivação não verificada como tal, em vez de fabricar um valor.
• Não ative o Trellis meramente porque .trellis/ existe.
• analyze e diagnose são somente leitura. Uma permissão de plataforma ou aprovação de plano nativo não autoriza edições. Entre em execute somente após uma instrução separada do usuário autorizar a implementação.
• Não entregue um artefato sem consumi-lo como seu leitor o fará — renderize o documento e execute os comandos do README/uso a partir da raiz do repositório exatamente como escritos. (Faça em vez disso: renderize diagramas, execute os comandos, corrija quebras antes da entrega.)
• Não considere um projeto independente concluído sem um README, LICENSE e .gitignore funcionais, ou com artefatos .ai-work/ internos commitados. (Faça em vez disso: entregue o scaffold publicável; mantenha o estado de orquestração fora do repositório.)