Do merge ao console

Dois caminhos leem o mesmo repositório, em ritmos diferentes:

	Código da skill	Catálogo e tarefas
Quem lê	cada execução	a sincronização da organização
Quando	toda execução clona o branch padrão	a cada push, de hora em hora, ou pelo botão Sincronizar
O que consome	o SKILL.md inteiro e os arquivos ao lado	só o frontmatter e o kadu.yaml
Efeito de um merge	imediato, no disparo seguinte	na próxima sincronização

Um merge que muda o corpo de uma skill vale no disparo seguinte. Um merge que muda o frontmatter vale na próxima sincronização.

Merge em main é deploy

Cada execução clona o branch padrão, com --depth 1, sem tag nem commit fixo. Então:

• o que roda é o HEAD do branch padrão no momento do disparo;
• um merge entra em produção na próxima execução de qualquer tarefa da organização, sem build, release nem janela de deploy;
• main quebrado quebra todas as tarefas da organização na hora;
• rollback é git revert e push. O console não tem "voltar para a versão anterior".

Trabalhe em branch, valide com o sandbox de CI e trate o merge com o cuidado de um deploy.

Quando a sincronização roda

Gatilho	Quando
Push no branch padrão	aviso do GitHub App (ou do webhook do repositório, sem o App). Push em outro branch é ignorado.
Verificação de hora em hora	compara o HEAD remoto com o último commit lido e sincroniza se mudou. Cobre um aviso perdido.
Manual	Sincronizar em Configurações → Deployment (ou POST /v1/repository/sync).

Na prática, o push em main já sincroniza. O botão serve para ver o resultado na hora.

O que a sincronização faz, em ordem

1. Grava o catálogo: o frontmatter de todo SKILL.md com bloco task:. Skill sem o bloco não entra.
2. Garante a estrutura: um workspace por plugin e as atividades declaradas. Só cria: nunca renomeia nem apaga.
3. Atualiza as tarefas existentes, casadas pelo skill_slug (<plugin>:<pasta-da-skill>).
4. Cria as tarefas que faltam para skills com task: sem tarefa na organização.
5. Aplica os ambientes do kadu.yaml (cria e atualiza).
6. Aplica os agendamentos de cada tarefa (task.schedules).
7. Aplica o metadata de workspaces e atividades e os webhooks do kadu.yaml.
8. Apaga os ambientes do repositório que saíram do kadu.yaml, por último, para que um agendamento que mudou de ambiente já tenha saído do antigo.

Não é preciso cadastrar a tarefa à mão: o merge cria a tarefa.

O Playbook é a fonte de verdade

No passo 3, todo campo declarado no bloco task: que diverge do Kadu é sobrescrito. A comparação de parameters_schema e metadata ignora a ordem das chaves, então reformatar o YAML não gera atualização.

Campo no frontmatter	O que a sincronização faz com a tarefa existente
label, description	sobrescreve
model	troca o nível (preço, executor e modelo). Valor que não é nível: não aplica e avisa
parameters_schema	sobrescreve; null limpa
parameters_sensitive, accepts_input_files, generates_output_files	sobrescreve
systems, features, required_secrets	sobrescreve a lista inteira
activity	move a tarefa para a atividade com esse nome; cria a atividade se não existir
workspace	ignorado: a tarefa fica no workspace do plugin
endpoint	concilia; nunca troca o tipo de autenticação nem liga sem credencial
schedules	cria, atualiza e apaga os agendamentos do repositório
executor	grava o override de executor e modelo; inherit limpa
metadata	sobrescreve o objeto inteiro

Regras que decorrem disso:

• Campo ausente quer dizer "não mexa". Apagar uma linha do frontmatter não volta o campo ao padrão. Para limpar, declare vazio: required_secrets: [], features: [], parameters_schema: null, description: "".
• Edição feita no console em campo declarado é desfeita no próximo push ou na próxima hora. Mude no frontmatter.
• Agendamento e ambiente editados no console voltam ao declarado no próximo push. A pausa feita no console é a exceção, enquanto o item não declarar paused.
• Tarefa apagada não volta. A sincronização conta a tarefa apagada como existente: não a recria nem a atualiza. E o contrário: remover o bloco task: não apaga a tarefa, só para de atualizá-la. Para aposentar uma tarefa, peça a remoção à Kobana e remova o bloco.
• Renomear a pasta da skill cria outra tarefa, sem histórico, sem credencial de endpoint e só com os agendamentos declarados, e deixa a antiga órfã. Para mudar o nome no console, mude label:.
• Mover a skill para outro plugin muda o prefixo do slug: também cria outra tarefa.

Onde ver o resultado

A sincronização pelo botão mostra o que mudou:

• workspaces e atividades criados;
• tarefas atualizadas, com os campos alterados (Baixar pagamentos (label, model));
• tarefas criadas e tarefas puladas, com o motivo;
• Configuração do repositório: ambientes, agendamentos, webhooks e metadados aplicados (Agendamento Baixar @ Produção criado (0 9 * * 1-5));
• Avisos: nível inválido, endpoint sem credencial, kadu.yaml inválido, secret declarado sem valor, agendamento não aplicado.

A sincronização disparada por push ou pela verificação de hora em hora não mostra o resultado a ninguém. Se uma mudança não apareceu no console, sincronize pelo botão e leia os avisos.

Tarefa pulada com o motivo	Causa
<slug> (sem task.activity no frontmatter)	falta activity:: sem atividade não há onde criar a tarefa
<slug> (nenhum tier de preço ativo)	model ausente ou inválido e nenhum nível ativo cadastrado

Sequência para uma tarefa nova

1. Escreva a skill com o bloco task: (com activity: e model: tier-N).
2. Valide localmente (/kadu:agent-run-task <plugin>:<skill>) e no sandbox de CI (Desenvolvimento local).
3. Faça o merge em main: o código já vale, e a sincronização cria a tarefa.
4. Sincronize pelo botão e confira a tarefa em "Tarefas criadas", sem avisos.
5. Cadastre os valores dos secrets (e peça a credencial do endpoint, se houver). Se a tarefa tem schedules, faça isso antes do primeiro horário: o agendamento vale desde o passo 3.
6. Dispare uma vez e confira histórico, logs, pendências e resultado.

O passo 6 não é formalidade: é onde aparecem evento sem message, resultado com status em vez de Markdown e pergunta que trava a execução.

Sequência para mudar uma tarefa

1. Mude o frontmatter, nunca o nome da pasta.
2. Faça o merge em main.
3. Confira em "Tarefas atualizadas" que o campo entrou. Se não aparece: o campo está com tipo errado (descartado em silêncio), é workspace: (ignorado) ou o valor já era igual.