Kadu Playbook

O Kadu Playbook é o repositório git em que uma organização guarda tudo o que o Kadu executa para ela: as tarefas, as skills auxiliares que elas usam e a configuração da organização. Cada organização tem um Playbook, e ele segue a spec do Kadu Playbook, descrita nesta seção.

O Playbook é a fonte de verdade do Kadu: cada push no branch padrão atualiza as tarefas do console, e cada execução lê as skills dali.

Esta seção é o guia para montar e manter um Playbook. Ela segue o que o Playbook da própria Kobana (kadu-kobs-kobana) aprendeu em produção.

O modelo

organização  = Playbook (um repositório git)
workspace    = plugin dentro do Playbook
tarefa       = skill com bloco `task:`   →   skill_slug = <plugin>:<skill>

No Kadu	No Playbook	Exemplo
Organização Kobana	o Playbook kadu-kobs-kobana	—
Workspace Financeiro	o plugin finance/	finance/.claude-plugin/plugin.json
Tarefa "Baixar pagamentos via boleto e Pix"	a skill com bloco task:	finance/skills/task-baixar-pagamentos-via-boleto-pix/SKILL.md
Skill auxiliar	uma skill sem bloco task:	finance/skills/fintera-listar-contas-a-receber/SKILL.md
Ambientes, webhooks, metadados	o kadu.yaml da raiz	kadu.yaml

O que você vai fazer

Etapa	Página
Criar a estrutura do Playbook: catálogo, plugins, skills	Estrutura do Playbook
Ligar o Playbook à organização	Conectar o Playbook
Entender como um push vira tarefa no console	Sincronização
Declarar a tarefa no frontmatter	O bloco task:
Agendar, expor por HTTP, escolher modelo	Agendamento, endpoint e executor
Escrever o corpo da tarefa com a instrumentação do console	O corpo da tarefa
Declarar e provisionar credenciais	Secrets
Declarar ambientes, webhooks e metadados da organização	O kadu.yaml
Testar localmente e como CI	Desenvolvimento local
Escrever skills que funcionam sem ninguém olhando	Boas práticas
Tarefa com ferramentas que o runner não tem	Workflow próprio
Conferir antes do merge	Checklist
Diagnosticar o que deu errado	Erros comuns

Três regras que valem para tudo

1. Merge em main é deploy. Cada execução lê o branch padrão no momento em que começa. Não há build, release nem canário: main quebrado quebra todas as tarefas da organização na hora, e o rollback é git revert.
2. O Playbook manda na tarefa. Todo campo declarado no bloco task: sobrescreve o que estiver no console a cada sincronização. Mude no arquivo, não no console.
3. Nenhum valor de secret entra no Playbook. O Playbook declara só os nomes das credenciais. Os valores vivem no cofre do Kadu (produção) ou num .env local fora do git (desenvolvimento).

O plugin kadu

Além dos plugins da organização, toda execução carrega o plugin kadu, mantido pela Kobana. Ele traz a instrumentação do console (eventos, logs, pendências, resultado), o wrapper que roda a tarefa (/kadu:agent-run-task) e utilitários como /kadu:minhareceita-buscar-cnpj. Fora da execução do Kadu, o plugin roda em modo de simulação (dry-run): a instrumentação só é impressa no terminal. Ver Desenvolvimento local.

Por isso nenhum plugin da organização pode se chamar kadu: o nome já é do plugin de instrumentação, e é pelo prefixo do skill_slug que o Kadu encontra o plugin certo.

---

O formato do Playbook foi inspirado no formato de plugins do Claude Code, e por isso os nomes de alguns arquivos (.claude-plugin/, SKILL.md) vêm de lá.