Fluxo · Makuco

Na v3 você não escolhe mais um agente por etapa. O trabalho de ponta a ponta é conduzido por três skills orquestradoras autônomas, que você invoca direto no chat. Cada uma conduz o próprio fluxo em passos, mantém o próprio arquivo de sessão e sabe para onde entregar.

makuco-analisar → makuco-desenvolver → makuco-code-review → makuco-documentation
                        ↑                      │
                        └──── NECESSITA CORREÇÕES

As três skills

Skill	Entra	Sai
makuco-analisar	Uma oportunidade vaga (DESCOBERTA), um problema já entendido (SOLUÇÃO), um card já escrito (EXPRESS) ou um bug em produção (INVESTIGAÇÃO)	`feature.md` (PRD) + `decisions.md` + `pbis.md` + PBIs validados por INVEST
makuco-desenvolver	Uma PBI pronta — local ou work item do Azure DevOps	`spec.md` + `task.md` + código em commits atômicos, com gates de teste e de qualidade, revisado no fechamento
makuco-code-review	Uma mudança pronta — a PBI recém-implementada, ou uma branch/PR/working tree avulsa	`review.md` (ou `.makuco/reviews/`) + veredito APROVADO / NECESSITA CORREÇÕES

Nível Feature · uma vez por feature

Nível PBI · repita por PBIloop por PBI

Como o ciclo roda

Nível Feature — uma vez por feature

makuco-analisar — traga a ideia crua, o problema já entendido, o card pronto ou o bug a investigar. A skill pergunta o modo, explora o problema (ou a causa, numa investigação), aplica o gate do modo, escreve o PRD e decompõe a feature em PBIs atômicas validadas por INVEST — ou, no EXPRESS, numa PBI só. Para cada PBI com tela, aciona a skill makuco-ux e produz DESIGN.md + EXPERIENCE.md.

Nível PBI — repita o ciclo abaixo para cada PBI

makuco-desenvolver — pergunta de uma vez o que a codebase não decide, gera spec.md + task.md a partir da PBI e implementa task por task (RED → GREEN → VERIFY → COMMIT), com gate de qualidade antes de cada commit.
makuco-code-review — o makuco-desenvolver o chama sozinho no fechamento: roda os passes de review no perfil que a mudança pede e emite o veredito. Se for NECESSITA CORREÇÕES, o makuco-desenvolver corrige as tasks apontadas e pede nova rodada, até duas; depois, a decisão volta para você. Com o review aprovado, roda o gate completo (cobertura, checklist e, se ligado, SonarQube) e a PBI é concluída.
makuco-documentation — acionado automaticamente pelo makuco-code-review quando o veredito é APROVADO: atualiza a documentação do projeto e grava learnings.md. Não é um passo que você dispara.

Retomáveis por construção

Cada skill grava o próprio arquivo de sessão — sessao.md, sessao-dev.md, sessao-review.md. Uma interrupção volta de onde parou em vez de recomeçar. O status.yml continua sendo a fonte da verdade do fluxo, e apenas o makuco-copy-writer escreve nele.

Quem revisa não conserta

O makuco-code-review nunca altera código. Ele documenta os achados e devolve as tasks afetadas ao makuco-desenvolver. Separar quem acha de quem corrige é o ponto: um revisor que remenda os próprios achados não tem mais ninguém para checá-lo.

Outras páginas desta seção

Investigação de bug

Causa raiz com evidência, estágio adversarial e a correção pelo fluxo de sempre.

Agentes de apoio

Os 3 agentes que sobraram: copy-writer, documentation e quick.

Skills de apoio

As skills carregadas sob demanda pelas orquestradoras.

Quick Mode

Trilha expressa para mudanças pequenas.

Referências Visuais

Como entrar com mockups, telas e links do Figma.

Sessões e contexto

Use um chat por sessão de skill. O fluxo é linear por PBI, mas features diferentes podem ser tocadas em paralelo. O status.yml e os arquivos de sessão registram o estado, então trocar de chat não custa contexto perdido.

Detalhes em Boas Práticas.

Rodar o fluxo pela CLI

Desde a 3.2.0 você não precisa escolher a skill nem o PBI na mão. makuco abre uma CLI interativa que lê os artefatos, deriva qual das três skills é a próxima acionável e a invoca — fazendo a troca de sessão sozinha. As três skills continuam invocáveis direto no chat do agente, como descrito acima.