Kadu Playbook
El Kadu Playbook es el repositorio git en el que una organización guarda todo lo que Kadu ejecuta para ella: las tareas, las skills auxiliares que usan y la configuración de la organización. Cada organización tiene un Playbook, y este sigue la spec del Kadu Playbook, descrita en esta sección.
El Playbook es la fuente de verdad de Kadu: cada push a la rama predeterminada actualiza las tareas de la consola, y cada ejecución lee las skills de allí.
Esta sección es la guía para armar y mantener un Playbook. Sigue lo que
aprendió en producción el Playbook de la propia Kobana (kadu-kobs-kobana).
El modelo
organización = Playbook (un repositorio git)
workspace = plugin dentro del Playbook
tarea = skill con bloque `task:` → skill_slug = <plugin>:<skill>
| En Kadu | En el Playbook | Ejemplo |
|---|---|---|
| Organización Kobana | el Playbook kadu-kobs-kobana | — |
| Workspace Financeiro | el plugin finance/ | finance/.claude-plugin/plugin.json |
| Tarea "Baixar pagamentos via boleto e Pix" | la skill con bloque task: | finance/skills/task-baixar-pagamentos-via-boleto-pix/SKILL.md |
| Skill auxiliar | una skill sin bloque task: | finance/skills/fintera-listar-contas-a-receber/SKILL.md |
| Entornos, webhooks, metadatos | el kadu.yaml de la raíz | kadu.yaml |
Qué vas a hacer
| Etapa | Página |
|---|---|
| Crear la estructura del Playbook: catálogo, plugins, skills | Estructura del Playbook |
| Vincular el Playbook a la organización | Conectar el Playbook |
| Entender cómo un push se convierte en tarea en la consola | Sincronización |
| Declarar la tarea en el frontmatter | El bloque task: |
| Programar, exponer por HTTP, elegir modelo | Programación, endpoint y ejecutor |
| Escribir el cuerpo de la tarea con la instrumentación de la consola | El cuerpo de la tarea |
| Declarar y provisionar credenciales | Secrets |
| Declarar entornos, webhooks y metadatos de la organización | El kadu.yaml |
| Probar localmente y como CI | Desarrollo local |
| Escribir skills que funcionen sin que nadie las mire | Buenas prácticas |
| Tarea con herramientas que el runner no tiene | Workflow propio |
| Revisar antes del merge | Checklist |
| Diagnosticar lo que salió mal | Errores comunes |
Tres reglas que valen para todo
- El merge a
maines un deploy. Cada ejecución lee la rama predeterminada en el momento en que empieza. No hay build, release ni canario: unmainroto rompe todas las tareas de la organización al instante, y el rollback esgit revert. - El Playbook manda en la tarea. Todo campo declarado en el bloque
task:sobrescribe lo que haya en la consola en cada sincronización. Cambia el archivo, no la consola. - Ningún valor de secret entra al Playbook. El Playbook declara solo
los nombres de las credenciales. Los valores viven en la bóveda de Kadu
(producción) o en un
.envlocal fuera de git (desarrollo).
El plugin kadu
Además de los plugins de la organización, toda ejecución carga el plugin
kadu, mantenido por Kobana. Trae la instrumentación de la consola
(eventos, logs, pendientes, resultado), el wrapper que corre la tarea
(/kadu:agent-run-task) y utilidades como /kadu:minhareceita-buscar-cnpj.
Fuera de la ejecución de Kadu, el plugin corre en modo de simulación (dry-run):
la instrumentación solo se imprime en la terminal. Ver
Desarrollo local.
Por eso ningún plugin de la organización puede llamarse kadu: el nombre
ya pertenece al plugin de instrumentación, y es por el prefijo del skill_slug
que Kadu encuentra el plugin correcto.
El formato del Playbook se inspiró en el formato de plugins de Claude Code, y por eso los nombres de algunos archivos (
.claude-plugin/,
SKILL.md) vienen de allí.