Local development

A Playbook's tasks run on your machine, in Claude Code, with the same instrumentation plugin as production. Outside Kadu this plugin switches to simulation mode (dry-run) on its own: everything that would go to the console is just printed in the terminal.

Prepare

Prerequisites: Claude Code, jq and curl on the PATH, and test credentials for the external systems.

1. Test secrets. Copy the versioned template and fill it in:

   cp sandbox/.env.example sandbox/.env    # sandbox/.env stays out of git
   set -a; source sandbox/.env; set +a

   Do not export GITHUB_ACTIONS: its absence is what keeps the simulation on.

2. Plugins, in Claude Code. Install kadu (instrumentation) and your Playbook's plugins:

   /plugin marketplace add Kadu-Kobs/kadu-kobs-core
   /plugin install kadu@kadu-kobs-core
   
   /plugin marketplace add <owner>/<your-repository>
   /plugin install finance@<marketplace-name>

   kadu-kobs-core is a Kobana repository. If marketplace add cannot find it, ask Kobana support for access. What comes after the @ is the name in marketplace.json, not the repository name. To iterate on local code, add the marketplace by path (/plugin marketplace add ./ at the repository root).

Run a task

Trigger it through the wrapper, as in production:

/kadu:agent-run-task finance:task-baixar-pagamentos

Or call the skill directly (/finance:pagarme-atualizar-cadastro).

What to watch for:

• Simulated instrumentation: each event, log, pending item and the result appear on stderr with the [dry-run POST ...] prefix and are accumulated in $AGENT_MOCK_LOG (default /tmp/kadu_dryrun.ndjson), one JSON line per call:

  jq . /tmp/kadu_dryrun.ndjson

• External calls are real. ERP, gateway, invoice issuer: none of that goes through the simulation. Use test credentials.

:::note A new skill does not show up in the session where it was written Claude Code reads the plugin catalog at the start of the session. A newly created skill answers Unknown skill even with the SKILL.md on disk. Restart the session, or follow the SKILL.md body by hand, which is the same content. :::

Test as CI

The simulation exercises the skill's reasoning. It does not exercise the plumbing of a real execution: the runner, plugin resolution by skill_slug, delivery of the allowlist secrets, the instrumentation's HTTP sending and masking.

Kobana's repository has a CI sandbox for this (sandbox/ci/), worth copying: it runs the execution workflow locally with act and points the instrumentation at an ingestion API mock inside the job itself.

./sandbox/ci/run.sh smoke finance:task-baixar-pagamentos
./sandbox/ci/run.sh live  finance:task-baixar-pagamentos

	smoke	live
Calls the AI model	no	yes (spends tokens)
Runs the skill	no (a fixed test body)	yes
External effect	none	real
Proves	runner, plugin, allowlist, HTTP sending, masking	the skill end to end

:::danger The mock is mandatory The kadu plugin chooses between simulation and real sending through the GITHUB_ACTIONS variable, and act sets it. A naive act, pointed at the production console, writes an execution, events and pending items for real from a local test. The sandbox aborts if the console URL is not localhost. :::

The smoke fails the job when a call arrives for a route the ingestion does not have, when authentication is missing, when no event arrives, and when a secret value appears in what the mock received (the masking canary).

The cycle up to production

#	Step	Where	Command	What it proves
1	Write the skill	local branch	—	—
2	Simulation	Claude Code	/kadu:agent-run-task <plugin>:<skill>	the skill body
3	Workflow lint	terminal	actionlint	the shell in the run: blocks
4	CI smoke	terminal	./sandbox/ci/run.sh smoke <plugin>:<skill>	runner, plugin, secrets, sending, masking
5	CI live	terminal	./sandbox/ci/run.sh live <plugin>:<skill>	the skill end to end, with real external effects
6	Merge to main	GitHub	—	code deploy
7	Sync	automatic, or Sync	—	task created or updated from the frontmatter
8	Secrets	Settings → Secrets	—	the execution receives the required_secrets variables
9	First run	console	Run now	timeline, logs, pending items and result appear as expected

Steps 2 and 4 complement each other, and neither replaces the other: the simulation exercises the skill with no network to the console; the smoke exercises the plumbing with no AI model.