Pular para conteúdo

0006 — Skills de workflow renomeadas e realinhadas ao ACT 1.0

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-03 · Decidido em: 2026-07-03

Contexto

O ACT (Agentic Coding Toolkit) subiu para 1.0, que substituiu o fluxo antigo (act-workflow-*) por um pipeline de cinco estágios — interview → create-spec → refine → create-issues → implement — mais enxuto, com separação entrevista/spec, granularidade de tarefa e progressive disclosure via references/. Nossas seis skills de workflow (xadm-spec, xadm-refine-spec, xadm-plan, xadm-work, xadm-compound) eram derivadas do fluxo antigo e ficaram defasadas em estrutura e nomenclatura.

Decisão

Renomear e re-derivar o pipeline, o mais fiel possível ao ACT 1.0, divergindo só onde um invariante X-Adm obriga:

x-desenhar → x-definir → x-refinar → x-planejar → x-implementar → x-documentar

  • Split entrevista/spec (ACT 1.0): x-desenhar (papel do act-interview) conduz a entrevista e grava o prompt .ia/NNN-*-prompt.md com o rastro de decisões L# embutido; x-definir (papel do act-create-spec) escreve a spec referenciando os L#.
  • Tarefa = corpo de Work Item do ACT (O que construir / Contexto necessário / Critérios de aceitação / Cobre / Bloqueada por), em pt-BR, embarcada no plan.md — não GitHub Issues. x-implementar executa --single-phase ou --single-task; reconcilia na unidade "critério de aceitação da tarefa".
  • Especialização de stack via references/<stack>.md por skill, carregada pelo §0 após detectar a stack (progressive disclosure do ACT): concerns por estágio (Flutter portado do ACT + Micronaut autorado). Sem variantes-skill -flutter/-micronaut — nosso §0 autodetecta.
  • x-documentar (sem par no ACT 1.0, que deprecou o compound): destila p/ docs/ + audita lacuna de doc e de teste (§6). Fronteira declarada com xadm-meta-audit-work.
  • Cada skill é um diretório templates/<nome>/ (SKILL.md + references/), copiado inteiro para .claude/skills/<nome>/.

Invariantes X-Adm preservados: NÃO commita (REGRA Nº 2 — inverte o default do act-implement); §0 base de conhecimento da stack; gate da stack como verify; §6 definição de pronto + loop; REGRAS 1/2/3; ghost mode; lineage .ia/NNN-*; storage .ia/, sem .act//GitHub Issues; sem GLOSSARY.md raiz; pt-BR. x-definir e x-refinar sobrepõem a postura minimalista do ACT com a REGRA Nº 1 (ambiguidade → sempre perguntar).

Por quê / alternativas consideradas

  • Adotar o storage do ACT (.act/config.yaml, local/GitHub Issues) — descartado: a constituição veda acoplamento Git entre repos; o andaime único da casa é .ia/NNN-*. Mantido formato do ACT, storage nosso.
  • Variantes-skill por stack (mecanismo literal do ACT) — descartado: os wrappers -flutter do ACT existem porque o core dele é stack-cego; nosso §0 autodetecta, então wrapper é redundante e multiplicaria as skills (6×N). O valor — guidance por estágio — cabe em references/<stack>.md.
  • Aliases deprecados dos nomes antigos — descartado: nenhum repo publicou esses nomes fora da doc; rename limpo, apps migram oportunisticamente via /xadm-docs.

Consequências

  • Bump da constituição 0.17.7 → 0.17.8 (PATCH). Os hooks de sessão dos apps acusarão defasagem — esperado (migração oportunista via /xadm-docs).
  • gera-manifesto.py passou a rastrear os 16 arquivos das skills-diretório (SKILL.md + references/); xadm-docs ganhou a regra de mapeamento templates/x-<nome>/** → .claude/skills/x-<nome>/**. O Dockerfile já publicava caminhos aninhados (mkdir parents).
  • Produzida dogfoodando o próprio ACT 1.0 (interview → create-spec → refine → create-issues) sobre o central — andaime em .ia/015-*.