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 Syst...

v1.5.0

🚀 Novidades

Português do Brasil como idioma padrão

O afyapowers agora fala português do Brasil (pt-BR) por padrão em toda a interação com o usuário e em todos os artefatos gerados. A diretiva de idioma é injetada uma vez por sessão pelo hook session-start e reforçada a cada invocação de skill por um novo hook lang-directive, garantindo que mensagens ao usuário sejam traduzidas para pt-BR mesmo quando os templates internos das skills estão em inglês (eles passam a ser apenas guias de conteúdo, não o texto final).

Todos os templates de artefato (design.md, plan.md, review.md, completion.md, feature-data-models.md) e as skills do workflow (design, plan, implement, review, complete, status, switch, etc.) foram reescritos para produzir saída em pt-BR. Termos técnicos e de produto convencionais (Tech Stack, endpoint, deploy, payload, PR, merge, changelog) e os identificadores de fase do workflow permanecem em inglês; código, identificadores e caminhos de arquivo nunca são traduzidos.

A injeção é feita de forma específica por agente: no Claude via PreToolUse (tool Skill) e UserPromptExpansion (comandos /afyapowers:...); no Gemini via BeforeTool (activate_skill). Cursor e Copilot não possuem um hook capaz de observar a invocação de skills, então dependem apenas do session-start.

---

🐛 Correções

Download de assets do Figma pelos subagentes

Corrige o comportamento em que os subagentes de implementação do Figma (figma-design-implementer e figma-component-implementer) identificavam os assets no design mas não conseguiam salvá-los, por estarem restritos à lista de arquivos permitidos da tarefa. Agora salvar arquivos de asset (ícones/imagens) é sempre permitido, mesmo fora do [OUTPUT_DIRECTORY], e o subagente é obrigado a escrever cada asset em disco e referenciá-lo no código — encontrar o ícone no Figma deixou de ser suficiente.

A regra de assets foi reforçada com uma árvore de decisão explícita: usar um arquivo existente apenas em caso de correspondência exata (um "quase igual" não conta), caso contrário baixar obrigatoriamente do Figma para o diretório de assets do projeto (detectado por convenção do codebase, declaração na tarefa, ou um default sensato). Assets referenciados-mas-ausentes, inlined "no chute" ou substituídos por placeholder passam a ser uma concern BLOCKING.

Além disso, o uso da ferramenta download_assets foi documentado (até 20 nós por chamada, ícones vetoriais exportados como SVG e imagens raster via binário de origem original) e foi adicionada uma política de backoff em erros 429 / rate limit (espera de 30–60s com jitter e retry, em vez de desistir ou repetir imediatamente), já que o Figma MCP tem limite de 15 requisições/minuto.

---

📦 Resumo

• Português do Brasil (pt-BR) passa a ser o idioma padrão de interação e de todos os artefatos.
• Novo hook lang-directive reinjeta a diretiva de idioma a cada invocação de skill (Claude e Gemini); Cursor/Copilot seguem via session-start.
• Templates de artefato e skills do workflow reescritos para gerar saída em pt-BR, preservando termos técnicos e identificadores de fase em inglês.
• Subagentes do Figma agora podem salvar arquivos de asset fora da lista de arquivos permitidos, e são obrigados a baixá-los e referenciá-los no código.
• Regra de assets endurecida: reúso só com correspondência exata; caso contrário, download obrigatório e concern BLOCKING se faltar.
• Documentado o uso de download_assets (SVG para vetores, binário original para raster) e adicionado backoff em rate limit (429) do Figma MCP.

v1.4.0

🚀 Novidades

Skill address-review para tratamento de comentários de PR

Nova skill /afyapowers:address-review: o agente entra em Plan Mode, percorre os comentários de revisão de um PR aberto e monta um plano de correção. Os comentários são apresentados e explicados um por um para o desenvolvedor, dando a opção de incluir ou não no plano.

---

⚡ Melhorias

Leitura de Figma como skill dedicada

A leitura de designs do Figma foi extraída do passo de design para a skill reading-figma-designs. Além de interpretar a URL e montar o mapa de nós, ela passa a extrair as anotações do Dev Mode, que agora são incorporadas ao design técnico.

Agente requirements-interrogator

Novo agente que analisa os requisitos reunidos (JIRA, Figma, anotações, respostas do usuário) em busca de contradições, lacunas, casos de borda e suposições não validadas, antes da escrita do design. Antecipa problemas que apareceriam durante a implementação.

Execução standalone da autodoc

A skill auto-documentation foi renomeada para autodoc e desacoplada do fluxo de 5 fases. Pode ser invocada diretamente: define-se o que documentar, a skill explora o código e cria ou atualiza os docs. O uso dentro do fluxo permanece inalterado.

Reorganização da documentação de feature

A documentação deixa de concentrar tudo em feature-doc.md e passa a ser dividida por assunto em docs/<feature>/: business-rules.md, architecture.md, data-models.md (opcional) e CHANGELOG.md.

Documentação em PT-BR e sem commit automático

A geração de documentação passa a escrever em PT-BR e não realiza mais commit automático dos docs. O versionamento fica a cargo do usuário.

Retrabalho da etapa de design

A etapa de design foi reestruturada para integrar a leitura do Figma e o agente de requisitos, com revisão dos templates de design e review. O design técnico chega mais completo ao planejamento.

Infraestrutura

Ajustes no sync.py para as novas skills e templates, atualização da config do Cursor e bump do plugin para a versão 1.4.0 em todos os IDEs (Claude, Cursor, Gemini, GitHub Copilot).

---

📦 Resumo

• address-review: processa comentários de PR individualmente e planeja as correções.
• reading-figma-designs: lê o Figma e incorpora as anotações do Dev Mode ao design.
• requirements-interrogator: agente que valida requisitos antes do design.
• autodoc (ex-auto-documentation): execução standalone, fora do fluxo de 5 fases.
• Documentação dividida em business-rules.md, architecture.md, data-models.md e CHANGELOG.md.
• Documentação em PT-BR e sem commit automático.
• Passo de design integrado com Figma e validação de requisitos.
• Ajustes no sync.py, config do Cursor e bump para a versão 1.4.0.

---

Full Changelog: v1.3.1...v1.4.0

v1.3.0

🚀 Novidades

Histórico de conversas (Debug Tool)

Adicionado um novo sistema de histórico baseado em hooks que registra automaticamente a execução dos agentes.

Os registros são armazenados em:

.afyapowers/history/<NOME_DO_AGENT>

Cada execução gera um arquivo HTML com uma visualização estruturada da conversa, facilitando análises e debugging. Além disso, também é gerado um index.html com um índice de todas as conversas, permitindo navegar facilmente entre os históricos.

O histórico inclui:

• Blocos de thinking
• Tool calls
• Tool outputs
• Execuções de subagentes
• Fluxo completo da execução

---

⚡ Melhorias

Centralização do fluxo de commits

A responsabilidade de realizar commits foi movida dos subagentes para o orquestrador.

Essa mudança evita problemas em execuções paralelas, como:

• Stage de arquivos de outras tarefas
• Commits com alterações não relacionadas
• Conflitos entre subagentes
• Interferência em commits concorrentes

Com isso, o processo de versionamento fica mais previsível e seguro.

Simplificação das skills de componentes

As skills component e figma-component foram consolidadas em uma única implementação.

Essa mudança remove redundâncias herdadas do antigo sistema de commands e simplifica a manutenção da plataforma.

---

🐛 Correções

Controle de spawn entre agentes Figma

Corrigido um comportamento em que o agente figma-design-implementer podia invocar o figma-component-implementer durante sua execução.

Foi adicionado um guard para impedir esse encadeamento e garantir que cada agente opere apenas dentro do fluxo esperado.

---

📦 Resumo

• Adicionado sistema automatizado de histórico em HTML para agentes.
• Adicionado índice navegável de conversas através de index.html.
• Registro visual de conversas, pensamentos, ferramentas e subagentes.
• Centralizada a responsabilidade de commits no orquestrador.
• Reduzidos conflitos em workflows com múltiplos subagentes.
• Corrigido spawn indevido entre agentes Figma.
• Unificadas as skills component e figma-component.

---

Full Changelog: [v1.2.0 → v1.3.0](v1.2.0...v1.3.0)

v1.2.0

O que mudou

• feat: adiciona instruções para detectar convenções/regras de commits e evitar problemas com hooks de commit, por @rafaelpapastamatiou-afya em #17

Changelog completo: v1.1.0...v1.2.0