O que AgentFlow faz?
Visão Geral
O AgentFlow transforma seu quadro Kanban existente em um pipeline de desenvolvimento de IA totalmente autônomo. Em vez de construir infraestrutura de orquestração personalizada, ele trata sua ferramenta de gerenciamento de projetos (Asana, GitHub Projects, Linear) como uma máquina de estado distribuída — as tarefas avançam por estágios, os agentes de IA leem e escrevem estado por meio de comentários, e os humanos intervêm pela mesma interface que já usam.
O resultado é observabilidade completa do pipeline pelo seu celular, recuperação gratuita de falhas (o estado reside na sua ferramenta de PM, não na memória) e substituição humana a qualquer momento arrastando um cartão.
Quando Usar Esta Skill
- Use quando precisar orquestrar vários workers do Claude Code em um ciclo de desenvolvimento completo (construir, revisar, testar, integrar)
- Use quando quiser portões de qualidade determinísticos (tsc/eslint/testes) antes da revisão de IA em código gerado por IA
- Use quando quiser visibilidade total do pipeline pelo seu quadro Kanban ou celular
- Use ao gerenciar um projeto solo ou em equipe que precisa de despacho autônomo de tarefas com rastreamento de custo
- Use quando precisar de orquestração à prova de falhas que sobreviva a reinícios de sessão
Conceitos Principais
Pipeline Kanban de 7 Estágios
As tarefas fluem por: Backlog, Research, Build, Review, Test, Integrate, Done. Cada estágio possui portões específicos. O quadro Kanban É a camada de orquestração — sem banco de dados separado, sem fila de mensagens, sem infraestrutura personalizada.
Orquestrador Stateless
Uma varredura one-shot acionada por crontab é executada a cada 15 minutos. Sem daemon, sem dependência de sessão. Se falhar, a próxima varredura retoma de onde parou porque todo o estado reside na sua ferramenta de PM.
Determinístico Antes de Probabilístico
Portões rígidos (tsc + eslint + testes) são executados antes de qualquer revisão de IA, capturando aproximadamente 60% dos problemas a custo quase zero. A revisão de IA vem depois, como uma segunda camada.
Revisão Adversarial
Um agente de IA diferente revisa o código e deve listar 3 problemas antes de decidir aprovar. Isso evita aprovações automáticas.
Despacho por Prioridade Transitiva
As tarefas que desbloqueiam mais trabalho downstream são construídas primeiro, calculando automaticamente o caminho crítico.
Skills / Comandos
/spec-to-board
Decompõe um SPEC.md em tarefas atômicas no seu quadro Kanban com dependências mapeadas.
/sdlc-orchestrate
Despacha tarefas para workers com base em prioridade transitiva e detecção de conflitos. Executado como uma varredura crontab.
/sdlc-worker --slot <N>
Executa um worker em um slot de terminal que pega tarefas, constrói código e cria PRs. Execute 3-4 workers em paralelo.
/sdlc-health
Painel de status do pipeline em tempo real mostrando estágio atual, agente atribuído, contagem de tentativas e custo acumulado para cada tarefa.
/sdlc-stop
Desligamento gracioso: workers ativos finalizam a tarefa atual, tarefas não iniciadas retornam ao Backlog.
Guia Passo a Passo
1. Escreva Sua Especificação
Crie um SPEC.md para seu projeto descrevendo o que deseja construir.
2. Decomponha em Tarefas
claude -p "/spec-to-board"
Isso lê seu SPEC.md, decompõe em tarefas atômicas, mapeia dependências e as cria no seu quadro Kanban.
3. Inicie os Workers
Abra 3-4 janelas de terminal, cada uma como um slot de worker:
# Terminal 2 — Construtor
claude -p "/sdlc-worker --slot T2"
# Terminal 3 — Construtor
claude -p "/sdlc-worker --slot T3"
# Terminal 4 — Revisor
claude -p "/sdlc-worker --slot T4"
# Terminal 5 — Testador
claude -p "/sdlc-worker --slot T5"
4. Inicie o Orquestrador
# Adicione ao crontab (executa a cada 15 minutos)
crontab -e
# Adicione: */15 * * * * ~/.claude/sdlc/agentflow-cron.sh >> /tmp/agentflow-orchestrate.log 2>&1
5. Monitore e Intervenha
Abra seu quadro Kanban no celular. Veja as tarefas fluírem pelo pipeline. Arraste qualquer cartão para "Needs Human" para intervir. Execute /sdlc-health para um painel no terminal.
6. Pare o Pipeline
claude -p "/sdlc-stop"
Portões de Qualidade
Cada estágio impõe portões específicos antes da promoção:
- Build para Review:
tsc+eslint+npm testdevem passar (determinístico) - Review para Test: O revisor adversarial deve listar 3 problemas antes de aprovar
- Test para Integrate: Limiar de 80% de cobertura em novos arquivos
- Integrate para Done: Suite de testes completa em main após merge; auto-reversão em caso de falha
Rastreamento de Custo
Rastreamento de custo por tarefa com tetos por estágio (padrões Sonnet):
- Research: ~$0.10
- Build: ~$0.40
- Review: ~$0.10
- Test: ~$0.05
- Integrate: ~$0.03
Guardrails automáticos: aviso em $3/$8, parada forçada em $10/$20 (Sonnet/Opus) com escalonamento humano.
Segurança e Recuperação
- Auto-reversão: Falhas de integração acionam
git revert(novo commit, nunca force-push) - Tarefas bloqueadas: Após 2 tentativas falhas, as tarefas são escaladas para revisão humana
- Detecção de agente morto: Heartbeat a cada 5 min, reatribuição após timeout de 10 min
- Desligamento gracioso:
/sdlc-stopdrena workers, retorna tarefas não iniciadas ao backlog - Detecção de scope creep: Arquivos do diff do PR comparados com a lista de arquivos prevista
- Detecção de desvio de especificação: Comparação de hash SHA-256 captura mudanças de requisitos no meio da sprint
Instalação
# Clone o repositório
git clone https://github.com/UrRhb/agentflow.git
# Copie skills e prompts para sua configuração do Claude Code
cp -r agentflow/skills/* ~/.claude/skills/
cp -r agentflow/prompts/* ~/.claude/sdlc/prompts/
cp agentflow/conventions.md ~/.claude/sdlc/conventions.md
Ou instale como plugin do Claude Code:
/plugin marketplace add UrRhb/agentflow
/plugin install agentflow
Melhores Práticas
- Faça: Escreva um SPEC.md claro antes de executar
/spec-to-board - Faça: Comece com 3-4 workers para um projeto típico
- Faça: Monitore pelo seu quadro Kanban e arraste cartões para "Needs Human" quando necessário
- Faça: Revise LEARNINGS.md periodicamente — ele captura padrões comuns de falha
- Não faça: Pule os portões de qualidade determinísticos — eles capturam a maioria dos problemas de forma barata
- Não faça: Force-push para main — AgentFlow usa
git revertpara segurança - Não faça: Execute mais workers do que o paralelismo do seu projeto suporta
Solução de Problemas
Problema: Worker parece travado ou morto
Sintomas: Cartão de tarefa não se moveu por 15+ minutos, sem novos comentários
Solução: O orquestrador detecta agentes mortos via heartbeat e reatribui após 10 minutos. Se o problema persistir, execute /sdlc-health para verificar o status e arraste manualmente o cartão de volta para Backlog.
Problema: Guardrail de custo acionado
Sintomas: Tarefa movida para "Needs Human" com tag COST:CRITICAL Solução: Revise o thread de comentários da tarefa para contexto acumulado. Decida se deve aumentar o orçamento, simplificar a tarefa ou dividi-la em partes menores.
Problema: Falha no teste de integração após merge
Sintomas: Tarefa revertida automaticamente de main Solução: A auto-reversão preserva a estabilidade de main. Verifique o contexto de tentativas da tarefa nos comentários, que carrega o que foi tentado e o que falhou. O próximo worker atribuído usará esse contexto.
Skills Relacionadas
@brainstorming- Use antes do AgentFlow para projetar seu SPEC.md@writing-plans- Complementa a escrita de especificações para decomposição de tarefas@test-driven-development- Funciona bem com os portões de qualidade do AgentFlow@subagent-driven-development- Abordagem alternativa para coordenação multi-agente
Recursos Adicionais
- Repositório do AgentFlow
- Documentação de Arquitetura
- Registro de Gaps (45 modos de falha)
- Guia de Introdução
Limitações
- Use esta skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
- Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
- Pare e peça esclarecimentos se entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.