Agentes de apoio

Na v3 sobraram 3 agentes, e você invoca apenas um deles. O trabalho de ponta a ponta é conduzido pelas três skills orquestradoras.

Agente	Para que serve	Resultado esperado	Tier	Modelo Claude sugerido
makuco-copy-writer	Acionado pelas skills ao final de uma etapa que produz artefato canônico: formata, persiste com o frontmatter obrigatório e atualiza o `status.yml`. É o único que escreve no `status.yml`. Você não o invoca.	Artefato formatado + `status.yml` atualizado	Rápido	Haiku 4.5
makuco-documentation	Acionado pelo `makuco-code-review` quando o veredito é APROVADO: compara o implementado com a documentação atual, atualiza só o que mudou e captura aprendizados. Você não o invoca.	`learnings.md` + docs do projeto atualizadas	Equilibrado	Sonnet 5
makuco-quick	Express lane para mudanças pequenas (≤3 arquivos, ≤1h, causa conhecida, sem novas deps/arquitetura). Pula o fluxo completo. É o único que você chama direto.	`quick/NNN-<slug>/{TASK.md, SUMMARY.md}` + commit atômico	Equilibrado	Sonnet 5

Sobre os modelos

Todos os agentes são entregues com model: inherit no frontmatter — ou seja, herdam o modelo da sua sessão. A tabela acima é uma recomendação de como configurá-los conforme o equilíbrio entre custo e qualidade. Os tiers genéricos ("raciocínio avançado", "equilibrado", "rápido") servem para mapear em qualquer ferramenta (Claude, Copilot, etc.); a coluna Claude indica o equivalente sugerido na família Anthropic.

makuco-copy-writer

Agente de apoio, sempre o último a agir numa sessão. Ele não analisa nem decide, apenas organiza e salva: pega o que a skill produziu, formata no template do artefato, grava o arquivo final com o frontmatter obrigatório e anota o progresso no status.yml.

Restrição absoluta: ele nunca adiciona, remove ou reinterpreta fatos, decisões, requisitos ou recomendações. Se o conteúdo recebido não tem algo que o template pede, a seção fica como está (ou com um _não informado_ explícito) — nunca inventado.

Contrato de entrada

A skill que o chama passa: o conteúdo produzido, o caminho de destino exato, o campo do status.yml a atualizar, os metadados (stage, feature, pbi) e o rótulo legível do estágio atual. Faltando qualquer um, ele pergunta em vez de adivinhar caminhos.

Skills carregadas

Todas as makuco-artifact-*: feature, pbi, discovery, structure, business, technical, spec, plan, task, review, learnings, reference.

Exemplo de saída — `status.yml`

module: module_001_pedidos
feature: feature_003_gestao-cupons
created_at: 2026-08-10
feature_prd_artifact: .makuco/docs/modules/module_001_pedidos/feature_003_gestao-cupons/feature.md
current_stage: PBIs propostas (makuco-analisar)
stages:                 # pending | in-progress | done
  discovery: done
  structure: done
pbis:
  aplicar-cupom:
    current_stage: Desenvolvimento
    business: done       # pending | done
    technical: done
    spec: done
    plan: done
    review: pending      # pending | approved | changes-requested
    documentation: pending

O status.yml não mudou na v3

Fora da remoção do stage estimate, nada mudou nos artefatos nem no status.yml. Os mesmos stages continuam sendo gravados, com os mesmos nomes — quem gravava era um agente, agora é uma skill.

makuco-documentation

Roda uma vez por PBI, e só depois que status.yml → pbis.{slug}.review está approved. Se não estiver, ele pára e avisa.

Lê todos os artefatos da PBI e a documentação existente do projeto, compara o implementado com a doc atual e atualiza apenas o que mudou — nunca recria do zero, nunca duplica. Se nada é genuinamente novo, ele documenta isso explicitamente.

Ao final, entrega ao makuco-copy-writer: os docs atualizados + o conteúdo do learnings.md, com destino .makuco/docs/{module}/{feature}/pbis/{slug}/learnings.md e campo de status pbis.{slug}.documentation = done.

Exemplo de saída — `learnings.md`

---
stage: documentation
feature: gestao-cupons
pbi: aplicar-cupom
created_at: 2026-08-10
status: done
---
 
# Learnings: Aplicar cupom
 
## O que foi implementado
Endpoint de aplicação de cupom + validações no carrinho.
 
## Decisões tomadas
| Decisão | Alternativa considerada | Motivo da escolha |
|---|---|---|
| Validação no backend | Validação no front | Segurança do limite de uso |
 
## Desvios do planejado
Nenhum.
 
## Documentação atualizada
| Arquivo | O que mudou |
|---|---|
| `docs/api/cart.md` | Novo endpoint de cupom |
 
## Aprendizados para próximas PBIs
Centralizar regras de pricing reduz retrabalho.

makuco-quick

Trilha expressa para mudanças pequenas. Detalhes, guardrails e exemplos em Quick Mode.

Agentes removidos na v3

Nove agentes saíram do pacote, junto com os prompts que os disparavam. Oito faziam uma etapa que hoje uma das três skills orquestradoras já faz de ponta a ponta, e manter as duas entradas significava manter duas descrições da mesma etapa, divergindo com o tempo.

Agente removido	Substituto
`makuco-discovery`	`makuco-analisar`
`makuco-structure`	`makuco-analisar`
`makuco-business-analyst`	`makuco-analisar`
`makuco-technical-analyst`	`makuco-analisar`
`makuco-specify`	`makuco-desenvolver`
`makuco-plan`	`makuco-desenvolver`
`makuco-codegen`	`makuco-desenvolver`
`makuco-reviewer`	`makuco-code-review`
`makuco-estimate`	sem substituto — a estimativa saiu do fluxo

Com o makuco-estimate saíram também a skill de formatação makuco-artifact-estimate e o stage estimate do status.yml — sem produtor, os dois eram peso morto. Os campos horas_ia/horas_humano/horas_estimadas continuam no frontmatter das tasks, agora opcionais.

Os prompts makuco-specify, makuco-plan e makuco-codegen também saíram. Sobra o start-makuco, que monta a base de conhecimento do projeto e não depende de agente nenhum.

Quem tinha os agentes antigos os perde

Quem tinha os nove agentes instalados os perde no próximo makuco init. Se você dependia de um deles, a substituição está na tabela acima — exceto a estimativa, que não tem.