Del merge a la consola

Dos caminos leen el mismo repositorio, a ritmos diferentes:

	Código de la skill	Catálogo y tareas
Quién lee	cada ejecución	la sincronización de la organización
Cuándo	toda ejecución clona la rama predeterminada	en cada push, cada hora, o con el botón Sincronizar
Qué consume	el SKILL.md completo y los archivos junto a él	solo el frontmatter y el kadu.yaml
Efecto de un merge	inmediato, en el lanzamiento siguiente	en la próxima sincronización

Un merge que cambia el cuerpo de una skill vale en el lanzamiento siguiente. Un merge que cambia el frontmatter vale en la próxima sincronización.

El merge a main es un deploy

Cada ejecución clona la rama predeterminada, con --depth 1, sin tag ni commit fijo. Entonces:

• lo que corre es el HEAD de la rama predeterminada en el momento del lanzamiento;
• un merge entra a producción en la próxima ejecución de cualquier tarea de la organización, sin build, release ni ventana de deploy;
• un main roto rompe todas las tareas de la organización al instante;
• el rollback es git revert y push. La consola no tiene "volver a la versión anterior".

Trabaja en una rama, valida con el sandbox de CI y trata el merge con el cuidado de un deploy.

Cuándo corre la sincronización

Disparador	Cuándo
Push a la rama predeterminada	aviso de la GitHub App (o del webhook del repositorio, sin la App). Un push a otra rama se ignora.
Verificación cada hora	compara el HEAD remoto con el último commit leído y sincroniza si cambió. Cubre un aviso perdido.
Manual	Sincronizar en Configuración → Deployment (o POST /v1/repository/sync).

En la práctica, el push a main ya sincroniza. El botón sirve para ver el resultado al instante.

Qué hace la sincronización, en orden

1. Guarda el catálogo: el frontmatter de todo SKILL.md con bloque task:. Una skill sin el bloque no entra.
2. Garantiza la estructura: un workspace por plugin y las actividades declaradas. Solo crea: nunca renombra ni borra.
3. Actualiza las tareas existentes, emparejadas por el skill_slug (<plugin>:<carpeta-de-la-skill>).
4. Crea las tareas que faltan para skills con task: sin tarea en la organización.
5. Aplica los entornos del kadu.yaml (crea y actualiza).
6. Aplica las programaciones de cada tarea (task.schedules).
7. Aplica el metadata de workspaces y actividades y los webhooks del kadu.yaml.
8. Borra los entornos del repositorio que salieron del kadu.yaml, al final, para que una programación que cambió de entorno ya haya salido del anterior.

No es necesario registrar la tarea a mano: el merge crea la tarea.

El repositorio es la fuente de verdad

En el paso 3, todo campo declarado en el bloque task: que difiere de Kadu se sobrescribe. La comparación de parameters_schema y metadata ignora el orden de las claves, así que reformatear el YAML no genera una actualización.

Campo en el frontmatter	Qué hace la sincronización con la tarea existente
label, description	sobrescribe
model	cambia el nivel (precio, ejecutor y modelo). Un valor que no es un nivel: no se aplica y avisa
parameters_schema	sobrescribe; null limpia
parameters_sensitive, accepts_input_files, generates_output_files	sobrescribe
systems, features, required_secrets	sobrescribe la lista completa
activity	mueve la tarea a la actividad con ese nombre; crea la actividad si no existe
workspace	ignorado: la tarea queda en el workspace del plugin
endpoint	concilia; nunca cambia el tipo de autenticación ni activa sin credencial
schedules	crea, actualiza y borra las programaciones del repositorio
executor	guarda el override de ejecutor y modelo; inherit limpia
metadata	sobrescribe el objeto completo

Reglas que se desprenden de esto:

• Un campo ausente significa "no tocar". Borrar una línea del frontmatter no devuelve el campo a su valor predeterminado. Para limpiar, declara vacío: required_secrets: [], features: [], parameters_schema: null, description: "".
• Una edición hecha en la consola en un campo declarado se deshace en el próximo push o en la próxima hora. Cambia el frontmatter.
• La programación y el entorno editados en la consola vuelven a lo declarado en el próximo push. La pausa hecha en la consola es la excepción, mientras el elemento no declare paused.
• Una tarea borrada no vuelve. La sincronización cuenta la tarea borrada como existente: no la recrea ni la actualiza. Y al revés: quitar el bloque task: no borra la tarea, solo deja de actualizarla. Para retirar una tarea, pide su eliminación a Kobana y quita el bloque.
• Renombrar la carpeta de la skill crea otra tarea, sin historial, sin credencial de endpoint y solo con las programaciones declaradas, y deja la antigua huérfana. Para cambiar el nombre en la consola, cambia label:.
• Mover la skill a otro plugin cambia el prefijo del slug: también crea otra tarea.

Dónde ver el resultado

La sincronización con el botón muestra qué cambió:

• workspaces y actividades creados;
• tareas actualizadas, con los campos modificados (Baixar pagamentos (label, model));
• tareas creadas y tareas omitidas, con el motivo;
• Configuración del repositorio: entornos, programaciones, webhooks y metadatos aplicados (Agendamento Baixar @ Produção criado (0 9 * * 1-5));
• Avisos: nivel inválido, endpoint sin credencial, kadu.yaml inválido, secret declarado sin valor, programación no aplicada.

La sincronización disparada por un push o por la verificación cada hora no muestra el resultado a nadie. Si un cambio no apareció en la consola, sincroniza con el botón y lee los avisos.

Tarea omitida con el motivo	Causa
<slug> (sem task.activity no frontmatter)	falta activity:: sin actividad no hay dónde crear la tarea
<slug> (nenhum tier de preço ativo)	model ausente o inválido y ningún nivel activo registrado

Secuencia para una tarea nueva

1. Escribe la skill con el bloque task: (con activity: y model: tier-N).
2. Valida localmente (/kadu:agent-run-task <plugin>:<skill>) y en el sandbox de CI (Desarrollo local).
3. Haz el merge a main: el código ya vale, y la sincronización crea la tarea.
4. Sincroniza con el botón y verifica la tarea en "Tareas creadas", sin avisos.
5. Registra los valores de los secrets (y pide la credencial del endpoint, si la hay). Si la tarea tiene schedules, hazlo antes del primer horario: la programación vale desde el paso 3.
6. Lánzala una vez y revisa historial, logs, pendientes y resultado.

El paso 6 no es una formalidad: es donde aparecen un evento sin message, un resultado con estado en lugar de Markdown y una pregunta que bloquea la ejecución.

Secuencia para cambiar una tarea

1. Cambia el frontmatter, nunca el nombre de la carpeta.
2. Haz el merge a main.
3. Verifica en "Tareas actualizadas" que el campo entró. Si no aparece: el campo tiene un tipo incorrecto (descartado en silencio), es workspace: (ignorado) o el valor ya era igual.