Skip to content
← Todos os capítulos

Capítulo 02

O loop central

O DWP define um pequeno conjunto de operações que levam um plano de um objetivo a um trabalho concluído e revisável: create → execute → refine → resume → status, com verify como a verificação de conformidade que confirma o resultado. Juntas, elas formam o loop que um agente segue ao longo da vida de um plano. Os agentes executam uma tarefa por vez, validando cada passo antes de seguir em frente.

Esse loop é a forma operacional do desenvolvimento orientado a especificação. O plano é a especificação contra a qual um agente executa, cada tarefa carrega critérios de aceitação explícitos e o passo de validação é o gate que transforma uma afirmação de conclusão em evidência dela. Como o plano e seu registro de progresso vivem no repositório, o loop é retomável entre sessões e agentes.

As operações

A skill de metodologia delega a intenção a nove sub-skills especializadas: seis operações centrais de execução, dois auxiliares de ciclo de vida e um motor de autoria:

  • create — Gera um novo plano a partir de um objetivo. O agente analisa o objetivo, decompõe-o em tarefas sequenciais e escreve os arquivos do plano. No modo guiado, materializa diretamente um plano Lite (compacto e em linha no README.md), permitindo ao desenvolvedor mantê-lo, promovê-lo a plano Full ou editá-lo; no modo trust, materializa diretamente a representação solicitada sem confirmações interativas. A análise de requisitos e a verificação de qualidade ocorrem em ambos os modos.
  • execute — Executa o plano tarefa a tarefa de forma sequencial. O agente atualiza o registro de progresso, executa os gates de validação e confirma cada tarefa no git. No modo trust, a execução continua de forma não supervisionada sem perguntas entre tarefas.
  • refine — Modifica um plano existente (adicionando, editando, dividindo ou reordenando tarefas, ou promovendo um plano Lite a Full) preservando estritamente a evidência concluída e proibindo o enfraquecimento de critérios sem confirmação.
  • resume — Continua um plano interrompido. O agente lê o journal de apenas anexação e os arquivos de tarefas para reconstruir o estado, continuando a partir da primeira tarefa incompleta sem repetir trabalho concluído.
  • status — Relata o progresso sem executar nada (estritamente somente leitura). Resume as tarefas concluídas, em andamento e pendentes sem alterar arquivos.
  • verify — Verifica a conformidade sem alterar nada (estritamente somente leitura). Relata se o repositório atende ao padrão AI-first e se as tarefas do plano possuem critérios explícitos e gates de validação.
  • onboard — Inspeciona o repositório para raciocinar —nunca copiar e colar— um AGENTS.md adaptado, a hierarquia padrão de docs/, documentação por módulo e o kit .agents/ com links simbólicos de compatibilidade.
  • upgrade — Verifica versões publicadas upstream, solicita consentimento antes do download, instala tags estáveis fixadas e reconcilia adaptações locais deixando os planos .dwp/ intactos.
  • author — Cria ou evolui skills, agentes ou comandos locais do repositório para atender a fluxos de trabalho recorrentes reais, mantendo sincronizado o catálogo em .agents/docs/.

O diretório de saída .dwp/

Todos os artefatos do DWP vivem em um diretório .dwp/ ignorado pelo git, na raiz do repositório. Manter o espaço de trabalho fora do controle de versão significa que o estado de trabalho de um plano nunca polui o histórico do projeto. A configuração de extensões no nível do repositório é gravada em .dwp/config.json (dwp-config/v1), enquanto os planos residem em diretórios numerados:

.dwp/
├── config.json
└── plans/
    └── PLAN_001_<slug>/
        ├── manifest.json
        ├── contract.json
        ├── journal.ndjson
        ├── state.json
        ├── README.md
        ├── PROGRESS.md
        ├── 1.task_<slug>.md
        ├── 2.task_<slug>.md
        └── analysis_results/

A anatomia de dez seções da tarefa

Todo arquivo de tarefa contém estas dez seções, em ordem. A estrutura garante que cada unidade de trabalho seja autocontida e revisável:

  1. Goal — um parágrafo declarando o que a tarefa alcança.
  2. Context — contexto, links e por que esta tarefa existe.
  3. Superfície tocada: o que a tarefa muda e a classe de risco que seleciona sua validação.
  4. Steps — ações ordenadas e concretas a executar.
  5. Acceptance criteria — uma lista de verificação de condições que definem o concluído.
  6. Validation — comandos ou testes a executar para verificar o trabalho.
  7. Files — caminhos que se espera criar ou modificar.
  8. Dependencies — outras tarefas ou pré-requisitos externos.
  9. Risks — o que pode dar errado e as mitigações.
  10. Completion & Log — um marcador de status mais notas cronológicas.

Validação, conclusão e retomada

A validação faz parte da tarefa, não é um detalhe posterior: cada tarefa nomeia os comandos ou testes que provam que ela está concluída, e o agente os executa antes de marcar a conclusão. Os testes são de primeira classe aqui — uma tarefa que adiciona nova funcionalidade ou altera o comportamento deve adicionar ou atualizar testes automatizados para esse comportamento e executar a verificação completa de qualidade de código do repositório (testes mais lint e type-check), não apenas confirmar que o build foi bem-sucedido; os testes existentes devem permanecer verdes, atualizados para o comportamento pretendido em vez de pulados. A segurança é de primeira classe da mesma forma — qualquer tarefa que toca autenticação, tratamento de entradas, secrets, superfície de rede ou dependências carrega as expectativas de segurança dessa mudança em seus critérios de aceitação e mantém todo commit livre de secrets, e todo plano se encerra com o Final Review — o passe de segurança sobre todo o conjunto de alterações, a validação completa sobre o estado final e a reconciliação das decisões de skills. A conclusão é registrada com um marcador de status explícito ([ ] não iniciada, [~] em andamento, [x] concluída, [!] bloqueada) na seção Completion & Log. A retomada depende desses marcadores e do registro de progresso — um agente pode reconstruir exatamente onde o plano parou e continuar a partir da primeira tarefa incompleta sem refazer o trabalho já concluído.

v6 e v7: a mesma metodologia, estrutura mais rigorosa

O padrão DWP atual é 7.0.0, implementado pela linha 7.x da skill. Esse pacote usa v7 por padrão para cada novo plano; uma solicitação explícita de v6 ainda materializa um plano v6. Os planos v1, v2, v5 e v6 existentes mantêm a geração registrada e nunca são migrados silenciosamente; passar um plano v5 para v6 exige uma solicitação explícita de migração.

v6 mantém a mesma metodologia de plano → tarefa → gate de validação → conclusão, os comandos slash e o local .dwp/plans/. Torna a estrutura de engenharia mais rigorosa com um contrato, um journal somente de acréscimo, manifestos de contexto por tarefa, um scheduler e declarações explícitas das capacidades do runtime. v7 mantém essa camada de registros e acrescenta um marcador de tarefa opcional parallel_safe, um evento de journal delegation para trabalho delimitado entregue a outro agente e o registro de addons .dwp/config.json; sem nenhum addon de delegação habilitado, todo plano continua sendo executado sequencialmente na sessão atual. A decisão de arquitetura é GO; não foi medida superioridade nem não inferioridade empírica nos resultados dos agentes.