v1.6.1

Release v1.6.1

🚀 Novidades

Quality gate para handoff do Figma

A fase de design agora começa avaliando a qualidade do arquivo do Figma como handoff, antes mesmo de analisar o conteúdo dos designs.

O novo agente figma-handoff-reviewer executa quatro verificações em paralelo, cobrindo estrutura e Auto Layout, nomenclatura de camadas, tokens de biblioteca e consistência de estilos, espaçamento, cores e tipografia. O resultado completo é salvo em artifacts/figma-handoff-review.md, enquanto apenas um resumo compacto é devolvido para a thread, evitando adicionar o relatório inteiro ao contexto.

Cada categoria de finding possui uma criticidade fixa (Bloqueante ou Sugestão). Com base nesses resultados, o workflow gera automaticamente uma recomendação:

• FALAR_COM_PD quando existem bloqueantes;
• PROSSEGUIR quando não existem.

Nesse ponto, a fase entra em um hard gate e pergunta ao usuário como deseja continuar, sempre apresentando primeiro a opção recomendada. Como o agente principal recebe apenas o resumo da auditoria, ele não tenta interpretar os problemas, citar telas específicas ou estimar esforço.

Se o MCP do Figma não estiver disponível ou o arquivo não tiver nenhuma biblioteca habilitada, a auditoria não é executada e a fase é interrompida. Isso evita seguir sem uma análise confiável justamente quando URLs do Figma foram fornecidas como referência.

Árvore de Componentes de DS e nova skill analyzing-design-system

A nova skill analyzing-design-system centraliza toda a análise de Design System do workflow e é usada tanto pela fase de design quanto pelo /afyapowers:figma-component.

Ela resolve cada instância do Figma até seu componente original, no arquivo em que ele foi definido. Isso evita analisar apenas a variante presente em uma tela e acabar criando uma implementação duplicada ou incompleta. Quando o componente original está em outro arquivo, como um Design System separado, o link desse arquivo passa a ser obrigatório; sem ele, o componente fica pendente e bloqueia a fase.

Cada nó da árvore recebe um veredito validado contra o código existente:

• Implementar
• Importar
• Atualizar
• Derivar

Essas decisões são registradas na nova seção ## Árvore de Componentes de DS do design. O agente apresenta suas recomendações em lotes para reduzir idas e vindas, mas cada decisão precisa ser confirmada explicitamente pelo usuário.

A tabela ## Decisões de Reúso de Componentes também foi atualizada. Correspondências exatas não são mais adotadas automaticamente: agora existem colunas separadas para a recomendação do agente e a decisão do usuário, deixando qualquer divergência registrada.

Contrato de Layout e layout de página

O documento de design agora inclui um ## Contrato de Layout, derivado diretamente da geometria dos frames do Figma. Ele registra informações como:

• largura máxima do container;
• margens laterais;
• gaps;
• número de colunas;
• dimensões mínimas e máximas;
• comportamento por breakpoint.

A partir desse contrato, toda task de UI recebe Medidas de aceite dentro do bloco **Figma:**, considerando apenas os breakpoints relevantes para aquela task. Essas medidas também alimentam o novo figma-token-verifier.

O layout de página passa a fazer parte da task da própria tela, em vez de gerar uma task separada. A regra é reutilizar o wrapper, layout ou shell de rota já utilizado pelo projeto. Um layout novo só deve ser criado quando realmente não existir uma solução equivalente, sempre seguindo as convenções existentes.

Componentes também ficam explicitamente proibidos de controlar propriedades de layout de página, como max-width, centralização ou margens laterais. Conteúdo full-bleed deve usar o mecanismo já existente no projeto; caso ele não exista, o implementer registra uma CONCERN em vez de inventar uma nova abstração dentro do componente.

Verificação de fidelidade no código com figma-token-verifier

O novo figma-token-verifier adiciona uma etapa read-only de validação depois que o figma-design-implementer termina de escrever o código.

Ele compara os valores definidos no Figma com o que realmente foi implementado, incluindo:

• cores;
• tipografia;
• espaçamento;
• border radius;
• sombras;
• medidas de layout.

Tokens do projeto são resolvidos antes da comparação e unidades equivalentes são normalizadas, portanto valores como 1rem e 16px não são tratados como divergência.

Os problemas encontrados são classificados em dois grupos:

• Estruturais: medidas, colunas e sizing — bloqueantes;
• Cosméticos: cores, pesos, sombras etc. — não bloqueantes.

Cada finding inclui arquivo:linha e o valor esperado, permitindo que o implementer corrija o problema e execute novamente a verificação. Esse ciclo pode acontecer no máximo duas vezes.

A validação também é estrita: se uma propriedade esperada não puder ser encontrada no código, o resultado é FAIL, nunca um PASS por suposição.

Essa abordagem substitui a verificação visual via browser MCP que chegou a ser desenvolvida, mas foi removida antes do release. A comparação direta com o código se mostrou mais determinística e elimina o custo de renderização.

Roteamento de tasks por Type

As tasks do plano agora podem declarar explicitamente um **Type:**:

• UI Screen
• UI Component
• UI Logic
• Backend
• General

O orquestrador usa esse campo para escolher o implementer correto:

UI Screen → figma-design-implementer
UI Component → figma-component-implementer
Demais tipos → tdd-implementer

Tasks antigas sem Type continuam funcionando por meio da heurística anterior.

Para componentes, o bloco **Design System:** completo é enviado ao implementer, incluindo veredito, base e composição. Quando esse bloco não existe, os campos são enviados vazios e o agente primeiro verifica se já existe uma implementação antes de criar uma nova. Isso reduz o risco de duplicar silenciosamente componentes do Design System.

Conformidade de Design System na review

A review ganhou uma nova seção ## Conformidade de Design System, com uma entrada para cada nó da árvore indicando:

• o veredito confirmado;
• onde o componente foi implementado;
• se a decisão original foi respeitada.

O spec-reviewer passa a tratar essas decisões como parte da conformidade da especificação, e não apenas como uma preferência de estilo.

Por exemplo, um componente marcado como Importar que aparece no diff como uma nova implementação é considerado uma duplicação e gera um finding crítico. Da mesma forma, Atualizar precisa ser estritamente aditivo, enquanto Derivar deve importar e compor sua base em vez de reimplementá-la.

A review também passa a validar anotações do Figma e estados de borda definidos nas tasks, como hover e outros comportamentos confirmados durante a fase de design.

Gate de impedimentos aplicado pelo preflight.py

O bloqueio de transição entre implementação e review deixou de depender apenas das instruções da skill.

Agora o preflight.py lê implementation-concerns.md e impede a transição implement → review enquanto houver qualquer item aberto na seção ## Impedimentos.

Para liberar a transição, cada impedimento precisa estar explicitamente marcado com:

[ACCEPTED BY USER: <motivo>]

Ressalvas continuam não bloqueando o workflow.

---

⚡ Melhorias

Concorrência do Figma baseada em chamadas MCP

A concorrência de tasks do Figma agora é calculada pelo orçamento estimado de chamadas MCP, em vez de simplesmente limitar a quantidade de tasks.

O limite anterior permitia quatro tasks simultâneas assumindo três chamadas por task. Na prática, assets e fallbacks de truncamento adicionavam uma ou duas chamadas extras, ultrapassando facilmente o limite de 15 req/min e causando erros 429, retries de 30–60 segundos e serialização da execução.

O novo orçamento considera aproximadamente quatro chamadas por task e busca manter cada onda em até 12 chamadas. Na prática, isso significa até três tasks com MCP por ciclo, independentemente do tipo. Tasks que não utilizam Figma continuam sem esse limite.

Contexto mais enxuto para subagents

Os implementers não recebem mais o documento de design inteiro.

Agora cada agente recebe somente o contexto necessário para executar sua task, incluindo:

• os nós relevantes da árvore de DS e suas dependências;
• decisões de reúso relacionadas;
• para telas, as partes relevantes do Contrato de Layout.

Tasks executadas pelo tdd-implementer não recebem a árvore de Design System.

Isso reduz significativamente o contexto enviado e, principalmente, o volume de informação que seria retransmitido em todos os turnos do subagent.

Verificação adiada agora é impedimento

Concerns que apenas adiam uma validação — por exemplo, "validar na review" ou "alguém precisa conferir antes de subir" — passam a ser automaticamente classificadas como bloqueantes, mesmo quando originalmente registradas pelo implementer como ressalva.

Adiar uma verificação não é evidência de que algo funciona; é justamente a ausência dessa evidência. O impedimento só é resolvido quando a validação realmente acontece.

Recursos do Figma reestruturados

A seção ## Recursos do Figma deixou de usar um único Node Map e passou a ter uma estrutura mais organizada:

Arquivos → Telas (T#) → Componentes (C#) → Anotações

Cada arquivo registra seu papel e fileKey, enquanto telas e componentes recebem identificadores estáveis como T1, T2, C1 e C2.

Esses IDs passam a ser utilizados pelo Contrato de Layout e pela árvore de Design System, evitando repetir coordenadas em vários lugares e eliminando o risco de referências divergentes.

A nova estrutura também suporta naturalmente componentes que pertencem a um arquivo de Design System diferente daquele que contém a tela.

Infraestrutura de build e manutenção

O sync.py agora possui uma pipeline dedicada para src/scripts/. Os arquivos são copiados diretamente para dist/<agent>/scripts/, sem prefixos ou parsing de frontmatter, garantindo que os caminhos relativos usados por skills e agents permaneçam consistentes.

Os modelos utilizados pelas skills e agentes também foram atualizados para claude-opus-5 e sonnet.

Além disso, a skill de TDD agora documenta explicitamente que existe uma versão condensada de suas instruções dentro do tdd-implementer. Como subagents não leem arquivos de skill de forma confiável, alterações nessas instruções precisam ser mantidas sincronizadas no mesmo commit.

---

🐛 Correções

Referências {{skill:NAME}} em arquivos de agents

O sync.py resolvia placeholders {{skill:NAME}} apenas dentro dos arquivos de skills. Como consequência, referências usadas em arquivos de agents chegavam ao dist/ sem serem processadas.

A substituição agora também acontece na pipeline de agents, utilizando o prefixo correto para cada IDE.

---

📦 Resumo

• Novo quality gate para avaliar o handoff do Figma antes da análise dos designs.
• Nova skill analyzing-design-system, responsável por resolver componentes até sua origem e definir os vereditos Implementar, Importar, Atualizar ou Derivar.
• Nova ## Árvore de Componentes de DS, com confirmação explícita das decisões pelo usuário.
• Novo ## Contrato de Layout, com medidas de aceite incorporadas às tasks de UI.
• Layout de página passa a fazer parte da task de tela e deve reutilizar os padrões existentes no projeto.
• Componentes não podem mais assumir responsabilidades de layout de página.
• Novo figma-token-verifier para validar fidelidade ao Figma diretamente no código.
• Tasks agora podem declarar Type, permitindo roteamento explícito entre os diferentes implementers.
• Nova validação de ## Conformidade de Design System durante a review.
• preflight.py agora bloqueia a review enquanto existirem impedimentos não resolvidos.
• Concorrência de tasks do Figma passa a considerar o orçamento de chamadas MCP.
• Subagents recebem apenas o contexto necessário para cada task.
• Verificações adiadas passam a ser tratadas como impedimentos.
• ## Recursos do Figma foi reorganizado em Arquivos, Telas, Componentes e Anotações.
• Decisões de reúso deixam de ser automáticas e passam a separar recomendação do agente e decisão do usuário.
• sync.py ganhou suporte a src/scripts/ e os modelos foram atualizados para Opus 5.
• Corrigida a resolução de {{skill:NAME}} em arquivos de agents.