Kadu Playbook

The Kadu Playbook is the git repository where an organization keeps everything Kadu runs for it: the tasks, the helper skills they use and the organization's configuration. Each organization has one Playbook, and it follows the Kadu Playbook spec, described in this section.

The Playbook is Kadu's source of truth: each push to the default branch updates the console's tasks, and each execution reads the skills from there.

This section is the guide to setting up and maintaining a Playbook. It follows what Kobana's own Playbook (kadu-kobs-kobana) learned in production.

The model

organization = Playbook (a git repository)
workspace    = plugin inside the Playbook
task         = skill with a `task:` block   →   skill_slug = <plugin>:<skill>

In Kadu	In the Playbook	Example
Kobana organization	the kadu-kobs-kobana Playbook	—
Finance workspace	the finance/ plugin	finance/.claude-plugin/plugin.json
Task "Settle payments via boleto and Pix"	the skill with a task: block	finance/skills/task-baixar-pagamentos-via-boleto-pix/SKILL.md
Helper skill	a skill without a task: block	finance/skills/fintera-listar-contas-a-receber/SKILL.md
Environments, webhooks, metadata	the root kadu.yaml	kadu.yaml

What you will do

Step	Page
Create the Playbook structure: catalog, plugins, skills	Playbook structure
Link the Playbook to the organization	Connect the Playbook
Understand how a push becomes a task in the console	Sync
Declare the task in the frontmatter	The task: block
Schedule, expose over HTTP, choose a model	Schedule, endpoint and executor
Write the task body with the console instrumentation	The task body
Declare and provision credentials	Secrets
Declare the organization's environments, webhooks and metadata	The kadu.yaml
Test locally and as CI	Local development
Write skills that work with nobody watching	Best practices
A task with tools the runner does not have	Custom workflow
Check before merging	Checklist
Diagnose what went wrong	Common errors

Three rules that apply to everything

1. Merging to main is a deploy. Each execution reads the default branch at the moment it starts. There is no build, release or canary: a broken main breaks every task in the organization immediately, and rollback is git revert.
2. The Playbook rules the task. Every field declared in the task: block overwrites what is in the console on each sync. Change the file, not the console.
3. No secret value goes into the Playbook. The Playbook declares only the credential names. The values live in Kadu's vault (production) or in a local .env outside git (development).

The kadu plugin

Besides the organization's plugins, every execution loads the kadu plugin, maintained by Kobana. It brings the console instrumentation (events, logs, pending items, result), the wrapper that runs the task (/kadu:agent-run-task) and utilities such as /kadu:minhareceita-buscar-cnpj. Outside a Kadu execution, the plugin runs in simulation mode (dry-run): the instrumentation is only printed in the terminal. See Local development.

That is why no organization plugin can be named kadu: the name already belongs to the instrumentation plugin, and Kadu finds the right plugin by the skill_slug prefix.

---

The Playbook format was inspired by the Claude Code plugin format, which is why the names of some files (.claude-plugin/, SKILL.md) come from it.