formal-you/agent-skills-suite

Dev — Implementação de Tarefa

Implemente um pacote de tarefas e entregue ao QA. Esta skill define o processo e carrega seus próprios limites de função em references/role-boundaries.md. Se o repositório adotante define regras para agentes (AGENTS.md, um diretório de regras de função ou equivalente), leia e siga-os quando presentes; a skill nunca concede acesso extra.

Use quando

• Uma tarefa sob tasks/<task-id>/ tem um 01-contract.md completo e você é o papel Dev.
• Você precisa implementar uma fatia vertical, executar seus comandos DoD, registrar evidências e entregar.
• Você está retrabalhando uma tarefa após o QA emitir REWORK_REQUIRED.

Não use quando

• O contrato está ausente, incompleto ou contestado — devolva-o ao Planejador.
• Você é solicitado a planejar, dividir ou revisar tarefas, ou verificar o trabalho de outro agente.
• A alteração solicitada está fora dos touch_files do contrato — escale ou divida a tarefa.

Entradas

• tasks/<task-id>/01-contract.md — frontmatter YAML autoritativo, touch_files, dod, Seção 4 cenários comportamentais BDD (Given-When-Then invariantes) e ADRs herdados.
• Âncoras de especificação referenciadas pelo contrato.
• Comandos do projeto para type check e lint, o conjunto de testes existente e o alvo de aceitação de propriedade do QA declarado em dod.test_file.
• tasks/<task-id>/02-dev-workspace.md — o formulário em branco que você preenche.

Saídas

• Alterações de código apenas para caminhos listados em touch_files.
• Código aderindo aos invariantes BDD e aos limites de complexidade ciclomática (padrão $V(G) \le 10$, aviso $11-15$ justificado em 02, crítico $> 15$ proibido).
• Um 02-dev-workspace.md completo com metadados, alterações reais, auto-verificação e a tabela Desvios de Implementação (linhas DEV-001, DEV-002, ... ou uma linha explícita Nenhum).
• Exatamente um marcador de entrega: - [x] WAITING_FOR_QA, marcado apenas quando todos os itens DoD passam.
• Nenhuma edição em 01-contract.md, 03-qa-verification.md, 04-process.md ou tests/acceptance/**.

Fluxo de Trabalho

1. Confirmar escopo e contrato BDD. Leia o frontmatter de 01-contract.md e a Seção 4 de cenários BDD. Verifique se task_id é igual ao nome do diretório e se touch_files, dod, adherence_adrs e os invariantes Given-When-Then estão definidos. Reporte itens ausentes ou contraditórios ao Planejador.
2. Preparar o trabalho. Anote o commit base e siga as convenções de branch/commit do projeto. Não reabra uma tarefa já aceita a menos que um revisor a reabra.
3. Implementar fatia vertical sob limites BDD e de complexidade. Altere apenas arquivos em touch_files. Implemente a lógica cumprindo os invariantes Given-When-Then declarados na Seção 4 e em dod.edge_cases. Controle a complexidade ciclomática de funções individuais (padrão $V(G) \le 10$). Se a complexidade se aproximar do limite de aviso ($11-15$), aplique padrões de refatoração (Extrair Método, Strategy / Tabela de Consulta, Cláusulas Guarda). Se $V(G) > 15$, refatore antes de prosseguir. Não edite ou crie tests/acceptance/**.
4. Executar DoD verificável por máquina e auto-verificação. Execute dod.type_check e dod.lint, depois execute os testes existentes do projeto; considere cada item de dod.edge_cases. Faça uma auto-auditoria de complexidade ciclomática em todas as funções tocadas. O alvo de aceitação (dod.test_file) é de propriedade do QA: execute-o apenas se ele já existir, nunca o crie ou edite. Se ainda não existir, registre isso em 02 e deixe o QA executá-lo durante a verificação. Capture comandos/resultados.
5. Preencher 02-dev-workspace.md. Registre branch, commit base/entrega, notas de design, uma linha por arquivo realmente alterado, contagens líquidas de linhas e marque cada item de auto-verificação que for verdadeiro. Inclua justificativa arquitetural explícita para qualquer função com complexidade de aviso ($11 \le V(G) \le 15$). Deixe itens desmarcados se não passaram. Complete a tabela Desvios de Implementação: uma linha para cada lugar onde o código difere do contrato ou especificação (DEV-001, DEV-002, ...; operação add | modify | remove; uma âncora #sec-*), ou escreva Nenhum em cada célula quando nada divergiu.
6. Entregar para o QA. Apenas quando todos os itens de auto-verificação passarem e os limites de complexidade forem satisfeitos, altere - [ ] WAITING_FOR_QA para - [x] WAITING_FOR_QA. Essa única caixa marcada é o gatilho de entrega. Não edite 03 ou 04.
7. Sobre retrabalho. Leia os rastros de falha do QA em 03-qa-verification.md, corrija apenas dentro do contrato, execute novamente o DoD, atualize 02 para a nova tentativa e entregue novamente. Escale falhas repetidas em vez de contornar o contrato.

Portão de qualidade (antes de declarar concluído)

• Cada caminho alterado está listado em 01-contract.md → touch_files.
• Nenhum arquivo fora do raio de explosão foi criado ou modificado.
• A implementação honra todos os cenários BDD Given-When-Then e invariantes comportamentais.
• Type check e lint saem com sucesso; os testes existentes do projeto passam.
• A auto-auditoria de complexidade ciclomática passa: todas as funções atendem $V(G) \le 10$ (ou $11-15$ com justificativa em 02); nenhuma excede $V(G) > 15$.
• O alvo de aceitação de propriedade do QA (dod.test_file) está declarado; se ainda não foi criado, isso está registrado para o QA.
• Cada item de dod.edge_cases tem uma justificativa de implementação/teste.
• 02-dev-workspace.md está completo para esta tentativa, incluindo a tabela Desvios de Implementação (linha explícita Nenhum quando nada divergiu).
• Apenas WAITING_FOR_QA está marcado; 03 e 04 não foram tocados.

Tratamento de falhas

• Contrato ausente ou contraditório: pare; reporte o campo e peça ao Planejador para corrigi-lo.
• Alteração fora do escopo necessária: divida a tarefa ou escale; nunca edite fora de touch_files.
• Comando DoD ausente ou não executável: reporte-o com o comando e erro; não deixe de lado a verificação.
• DoD falha: corrija a implementação e execute novamente. Não marque a caixa de entrega enquanto uma verificação falhar.
• Complexidade excede o limite ($V(G) > 15$): refatore usando Extrair Método, Strategy / Tabela de Consulta, Cláusulas Guarda ou padrões de Estado antes da entrega; nunca entregue complexidade crítica.
• Ferramenta indisponível: use os comandos manuais do projeto e registre evidências em 02; o fluxo de trabalho não deve depender de ferramentas opcionais.

04-process.md e ferramentas

04-process.md é uma saída derivada. Após a caixa de entrega ser marcada, ferramentas opcionais do repositório adicionam HANDOFF_QA_REQUESTED e atualizam macro_status/current_lock_holder. Nunca edite 04 manualmente; sem ferramentas, confie em git/CI e na caixa marcada.

Após QA_PASSED: propriedade de write-back de especificação

A tabela Desvios de Implementação é a última entrega do Dev para a tarefa. Após o QA registrar QA_PASSED, a skill converge é responsável pelo write-back de especificação: ela incorpora os desvios confirmados em .specs/02-tech-spec.md, arquiva o pacote de tarefas e fecha a proposta de alteração.

• O Dev nunca edita .specs/02-tech-spec.md e nunca arquiva o pacote.
• Um desvio estrutural (novo componente, limite alterado, nova decisão de nível ADR) é escalado para o Planejador/spec-generator em vez de ser convergido silenciosamente.
• Se o QA solicitar retrabalho, atualize a tabela de desvios para a nova tentativa; não pré-escreva prosa de especificação.

Referências

• references/dev-protocol.md — listas de verificação detalhadas, verificação de escopo, limites de complexidade ciclomática de McCabe, padrões de refatoração, procedimento de entrega e retrabalho.
• Limites de função: references/role-boundaries.md — escopo de escrita, escopo somente leitura, invariantes e o modelo de aplicação honesta (agrupado; nenhum arquivo externo necessário).
• Regras do repositório: leia AGENTS.md e quaisquer arquivos de regras de função quando o projeto adotante os definir; eles podem adicionar requisitos, mas não são necessários para que esta skill funcione.
• Formato do pacote de tarefas: skill task-decomposition (irmão opcional; esta skill apenas consome seus artefatos).

Limites honestos

Esta skill não concede acesso de escrita e não pode impor isolamento de função. Onde o repositório tem CI (por exemplo, uma auditoria de função baseada em git) ou proteção de branch, essa é a camada autoritativa. O contrato, não este documento, define o raio de explosão permitido.