🤖 unac-agents

Agentes e skills para Claude Code — do card Jira ao código revisado.

Fluxo spec-driven e test-first, com gates humanos nas bordas críticas, verificação adversarial e perfis de execução que dosam custo pela complexidade do item.

npx unac-agents

✨ Destaques

• Pipeline completo — Product Owner → Jira card → arquitetura → plano → testes → implementação → QA → review → fix, com handoffs explícitos entre agentes atômicos.
• Perfis de execução (novo) — o pipeline classifica a complexidade do item e propõe um perfil (Leve / Padrão / Rigoroso); você confirma ou ajusta num único gate. Itens simples rodam mais rápido, mais barato e com modelos menores — sem abrir mão das fases núcleo.
• TDD ou SDD, você escolhe (novo) — test-first com Red gate (default) ou spec-driven com testes escritos após a implementação, quando velocidade importa mais.
• Verificação adversarial — fatos de exploração, matriz de rastreabilidade, força dos testes e blockers de review são desafiados por céticos independentes antes de virarem decisão.
• Contexto sob controle — workers nunca spawnam workers; cada task roda em subagente isolado; paralelismo só em fases read-only.

🚀 Instalação

npx unac-agents

O instalador pergunta onde instalar e adapta a cópia ao alvo escolhido:

| Alvo | Destino | O que instala | |------|---------|---------------| | Claude Code (recomendado) | ~/.claude/ (global) ou ./.claude/ (local do repositório) | 11 agentes · 7 skills de orquestração · 10 skills de conteúdo | | VS Code / Copilot (legado) | ~/.copilot/ | 8 agentes · 10 skills de conteúdo · servidor interactive-mcp |

• Claude Code: instalação em overlay — arquivos de mesmo nome são sobrescritos, os demais são preservados. Não instala MCP.
• VS Code: faz um backup timestampado de ~/.copilot antes de sobrescrever e registra o interactive-mcp no mcp.json. ⚠️ Este alvo está congelado (não recebe os recursos novos do pipeline) e será descontinuado em uma versão futura.

Flags

| Flag | Descrição | |------|-----------| | --target=claude-code\|vscode | Escolhe o alvo sem prompt interativo | | --scope=global\|local | (Claude Code) instala em ~/.claude/ ou em ./.claude/ | | --yes, -y | Pula a confirmação interativa (útil em scripts/CI) | | --dry-run | Lista o que seria instalado sem gravar nada | | --version, -v | Mostra a versão do CLI e sai | | --installed, --status | Mostra as instalações existentes (versão, data e contagem de agents/skills) e sai |

# Claude Code, no repositório atual, sem confirmação
npx unac-agents --target=claude-code --scope=local --yes

# Prévia do que seria instalado
npx unac-agents --target=claude-code --dry-run

# O que já está instalado nesta máquina
npx unac-agents --installed

Em ambiente não-interativo (CI), informe --target (e --scope, no Claude Code) e --yes.

Cada instalação grava um manifesto .unac-agents.json na raiz do destino, que alimenta o --installed.

🔁 Pipeline de agentes

Agentes atômicos que rodam em sequência, com handoffs explícitos e gates humanos nas bordas críticas:

unac-product-owner → unac-jira-maker → unac-solution-architect → unac-tech-lead
  → unac-developer → unac-qa-engineer → unac-code-reviewer → unac-code-fix

| Agente | Responsabilidade | |--------|-----------------| | unac-product-owner | Pesquisa o codebase e o contexto externo; produz os artefatos de pesquisa | | unac-jira-maker | Formata o card Jira (HU / Task / Bug) com critérios de aceitação em GIVEN/WHEN/THEN | | unac-solution-architect | Define arquitetura, tasks, NFRs e decisões-chave (ADRs) | | unac-tech-lead | Valida o plano e decompõe as tasks em unidades developer-ready | | unac-developer | Implementa 1 task por vez (fase Green), respeitando a constitution | | unac-qa-engineer | Escreve/roda os testes de aceitação derivados dos ACs do card (modos red, verify e test-after) | | unac-code-reviewer | Revisa qualidade, segurança, performance e aderência ao plano | | unac-code-fix | Correção cirúrgica de 1 issue 🔴 BLOCKING por vez |

Workers read-only de apoio (apenas no alvo Claude Code):

| Worker | Responsabilidade | |--------|-----------------| | unac-explorer | Investiga 1 ângulo do codebase por invocação (fan-out paralelo) | | unac-finding-verifier | Cético atômico que tenta refutar fatos/findings (verificação adversarial) | | unac-test-verifier | Cético de testes — tenta provar que um teste de aceitação é fraco antes do Red gate |

Cada agente grava seus artefatos em .unac/{item-id}/ e só avança quando os gates de fase passam.

🎛️ Perfis de execução

Nem todo item precisa do pipeline inteiro na potência máxima. Após a aprovação do card, o pipeline classifica a complexidade do item (nº de critérios de aceitação, alcance no codebase, sinais de risco, multi-repo) e propõe um perfil — você confirma ou ajusta num único gate (Gate B.5):

| Recurso | 🪶 Leve | ⚖️ Padrão | 🛡️ Rigoroso | |---------|--------|-----------|-------------| | Verificação adversarial da rastreabilidade (Gate C) | — | ✅ | ✅ | | Verificação adversarial dos testes (Fase 4.6) | — | ✅ | ✅ | | Verificação adversarial dos blockers (verify-review) | — | ✅ | ✅ + final-sweep opcional | | Fan-out de review | reviewer único | 1 por task | 1 por task | | Modelos (developer/QA/reviewer/architect) | sonnet | opus | opus |

• A heurística é fail-closed: qualquer sinal de risco (segurança, dados, contrato, migração, concorrência) força a classificação COMPLEXO; na dúvida, sobe de nível. A recomendação nunca trava sua escolha.
• A opção Personalizar abre a seleção granular de cada recurso.
• As fases núcleo nunca são puladas em nenhum perfil — o que muda é a intensidade das camadas de verificação e os modelos usados.
• O perfil escolhido fica registrado em .unac/{item-id}/{item-id}_execution-profile.md e sobrevive a retomadas de sessão.

TDD ou SDD

No mesmo gate você escolhe a metodologia:

• TDD (default, sempre recomendado): os testes de aceitação nascem dos ACs do card, são confirmados falhando antes de qualquer implementação (Red gate) e ficam imutáveis durante a fase Green.
• SDD (spec-driven): a implementação vem primeiro e o QA escreve os testes depois (mode: test-after), mapeados AC a AC. Mais rápido e mais barato — com o trade-off honesto de que testes escritos depois tendem a confirmar a implementação em vez de desafiá-la.

🧠 Skills de orquestração (Claude Code)

| Skill | Função | |-------|--------| | unac-pipeline | Meta-orquestrador do fluxo completo — gates humanos, perfis de execução, TDD/SDD | | unac-explore | Exploração de contexto via fan-out paralelo + verificação adversarial (knob depth) | | unac-execute-plan | Loop de implementação serial — 1 unac-developer por task | | unac-review-implementation | Review em fan-out paralelo read-only — 1 unac-code-reviewer por task (ou reviewer único no perfil Leve) | | unac-verify-review | Verificação adversarial dos blockers 🔴 antes do fix (só os sobreviventes seguem) | | unac-fix-blockers | Loop de correção — 1 unac-code-fix por issue 🔴 | | unac-multirepo | Orquestração multi-repo contract-first (provider antes do consumer) |

Workers nunca spawnam workers — só as skills dispatcham, então cada task roda em um subagente isolado, sem contexto herdado, evitando exaustão da janela de contexto. Paralelismo só em fases read-only (exploração, verificação e review); a escrita é sempre serial.

📚 Skills de conteúdo (Claude Code e Copilot)

| Skill | Descrição | |-------|-----------| | clean-code | Princípios SOLID, DRY, KISS aplicados ao código | | architecture | Fronteiras de módulo, direção de dependências, acoplamento/coesão, ADRs | | api-patterns | REST, GraphQL, tRPC, autenticação, rate limiting e mais | | frontend-design | UI/UX, sistema de cores, tipografia, animações | | database-design | Schema design, migrações, indexação, seleção de ORM | | code-review | Revisão de arquitetura, segurança, performance e testes | | code-review-checklist | Checklist estruturado para revisões de código | | jira-card-maker | Templates e framework para criação de cards Jira | | haskell-engineering | Padrões de engenharia Haskell | | testing-patterns | Padrões e boas práticas de testes (unit, integração, mocks) |

🧩 Conceitos-chave

• Spec-driven + test-first: uma .unac/constitution.md global governa arquiteto, tech-lead, developer, reviewer e code-fix. Em TDD, os testes de aceitação derivam exclusivamente dos ACs do card Jira, são confirmados falhando antes da implementação e ficam imutáveis na fase Green (com verificação de hash). Em SDD, os testes vêm depois — por escolha explícita sua, nunca do pipeline.
• Perfis de execução: a heurística classifica, você decide. Itens simples não pagam o custo de itens críticos — e itens críticos nunca rodam com menos verificação do que merecem.
• Exploração acurada: vários exploradores independentes rodam em paralelo e seus fatos passam por verificação adversarial antes de virarem premissa do plano.
• Review adversarial: cada blocker 🔴 é desafiado por um painel cético; só os que sobrevivem viram correção (corta falsos positivos sem arriscar os reais).
• Multi-repo: quando um item abrange mais de um repositório, o fluxo roda contract-first, repo a repo, ancorado em um contrato de interface — reusando as mesmas skills com o perfil do item.

🖥️ MCP interativo (alvo VS Code — legado)

No alvo VS Code, o instalador também sobe o servidor interactive-mcp localmente e o registra no mcp.json, expondo-o como ferramenta interactive (pop-ups de terminal com opções navegáveis, input livre e sessões de chat persistentes).

⚠️ O alvo VS Code e o interactive-mcp estão descontinuados: seguem funcionais nesta versão, mas não recebem os recursos novos (perfis de execução, TDD/SDD, verificação adversarial) e serão removidos futuramente. O alvo Claude Code usa os mecanismos nativos de pergunta do próprio Claude Code.

📋 Requisitos

• Node.js >= 18
• Claude Code (recomendado) — ou VS Code com GitHub Copilot (legado)

☕ Apoie o projeto

Se este pacote foi útil para você, considere apoiar o desenvolvimento:

📄 Licença

MIT © Ueslei Nascimento