Desarrollo local

Las tareas de un Playbook corren en tu máquina, en Claude Code, con el mismo plugin de instrumentación de producción. Fuera de Kadu ese plugin entra solo en modo de simulación (dry-run): todo lo que iría a la consola se imprime únicamente en la terminal.

Preparar

Prerrequisitos: Claude Code, jq y curl en el PATH, y credenciales de prueba de los sistemas externos.

1. Secrets de prueba. Copia la plantilla versionada y complétala:

   cp sandbox/.env.example sandbox/.env    # sandbox/.env queda fuera de git
   set -a; source sandbox/.env; set +a

   No exportes GITHUB_ACTIONS: su ausencia es lo que mantiene la simulación activada.

2. Plugins, en Claude Code. Instala el kadu (instrumentación) y los plugins de tu Playbook:

   /plugin marketplace add Kadu-Kobs/kadu-kobs-core
   /plugin install kadu@kadu-kobs-core
   
   /plugin marketplace add <dueño>/<tu-repositorio>
   /plugin install finance@<nombre-del-marketplace>

   El kadu-kobs-core es un repositorio de Kobana. Si el marketplace add no lo encuentra, pide acceso al soporte de Kobana. Lo que va después de la @ es el name del marketplace.json, y no el nombre del repositorio. Para iterar sobre el código local, agrega el marketplace por la ruta (/plugin marketplace add ./ en la raíz del repositorio).

Ejecutar una tarea

Lánzala por el wrapper, como en producción:

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

O llama a la skill directamente (/finance:pagarme-atualizar-cadastro).

Qué observar:

• Instrumentación simulada: cada evento, log, pendiente y el resultado aparecen en el stderr con el prefijo [dry-run POST ...] y se acumulan en $AGENT_MOCK_LOG (predeterminado /tmp/kadu_dryrun.ndjson), una línea JSON por llamada:

  jq . /tmp/kadu_dryrun.ndjson

• Las llamadas externas son reales. ERP, gateway, emisor de facturas: nada de eso pasa por la simulación. Usa credenciales de prueba.

:::note Una skill nueva no aparece en la sesión en que se escribió Claude Code lee el catálogo de plugins al inicio de la sesión. Una skill recién creada responde Unknown skill aunque el SKILL.md esté en disco. Reinicia la sesión, o sigue el cuerpo del SKILL.md a mano, que es el mismo contenido. :::

Probar como CI

La simulación ejercita el razonamiento de la skill. No ejercita la tubería de una ejecución de verdad: el runner, la resolución del plugin por el skill_slug, la entrega de los secrets de la lista de permitidos, el envío HTTP de la instrumentación y el enmascaramiento.

El repositorio de Kobana tiene un sandbox de CI para esto (sandbox/ci/), que vale la pena copiar: corre el workflow de ejecución localmente con act y apunta la instrumentación a un mock de la API de ingesta dentro del propio job.

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

	smoke	live
Llama al modelo de IA	no	sí (gasta tokens)
Ejecuta la skill	no (un cuerpo de prueba fijo)	sí
Efecto externo	ninguno	real
Prueba	runner, plugin, lista de permitidos, envío HTTP, enmascaramiento	la skill de punta a punta

:::danger El mock es obligatorio El plugin kadu decide entre simulación y envío real por la variable GITHUB_ACTIONS, y act la define. Un act ingenuo, apuntado a la consola de producción, graba ejecución, eventos y pendientes de verdad a partir de una prueba local. El sandbox aborta si la URL de la consola no es localhost. :::

El smoke reprueba el job cuando llega una llamada a una ruta que la ingesta no tiene, cuando falta autenticación, cuando no llega ningún evento, y cuando un valor de secret aparece en lo que recibió el mock (el canario del enmascaramiento).

El ciclo hasta producción

#	Etapa	Dónde	Comando	Qué prueba
1	Escribir la skill	rama local	—	—
2	Simulación	Claude Code	/kadu:agent-run-task <plugin>:<skill>	el cuerpo de la skill
3	Lint del workflow	terminal	actionlint	el shell de los bloques run:
4	Smoke de CI	terminal	./sandbox/ci/run.sh smoke <plugin>:<skill>	runner, plugin, secrets, envío, enmascaramiento
5	Live de CI	terminal	./sandbox/ci/run.sh live <plugin>:<skill>	la skill de punta a punta, con efectos externos reales
6	Merge a main	GitHub	—	deploy del código
7	Sincronización	automática, o Sincronizar	—	tarea creada o actualizada por el frontmatter
8	Secrets	Configuración → Secrets	—	la ejecución recibe las variables de required_secrets
9	Primer lanzamiento	consola	Ejecutar ahora	historial, logs, pendientes y resultado aparecen como se espera

Los pasos 2 y 4 se complementan, y ninguno sustituye al otro: la simulación ejercita la skill sin red hacia la consola; el smoke ejercita la tubería sin modelo de IA.