From merge to console

Two paths read the same repository, at different paces:

	Skill code	Catalog and tasks
Who reads	each execution	the organization's sync
When	every execution clones the default branch	on each push, hourly, or through the Sync button
What it consumes	the whole SKILL.md and the files next to it	only the frontmatter and kadu.yaml
Effect of a merge	immediate, on the next run	on the next sync

A merge that changes a skill's body takes effect on the next run. A merge that changes the frontmatter takes effect on the next sync.

Merging to main is a deploy

Each execution clones the default branch, with --depth 1, with no pinned tag or commit. So:

• what runs is the HEAD of the default branch at the moment of the run;
• a merge reaches production on the next execution of any task in the organization, with no build, release or deploy window;
• a broken main breaks all the organization's tasks immediately;
• rollback is git revert and push. The console has no "go back to the previous version".

Work on a branch, validate with the CI sandbox and treat the merge with the care of a deploy.

When the sync runs

Trigger	When
Push to the default branch	notice from the GitHub App (or from the repository webhook, without the App). A push to another branch is ignored.
Hourly check	compares the remote HEAD with the last commit read and syncs if it changed. Covers a missed notice.
Manual	Sync in Settings → Deployment (or POST /v1/repository/sync).

In practice, the push to main already syncs. The button is for seeing the result right away.

What the sync does, in order

1. Stores the catalog: the frontmatter of every SKILL.md with a task: block. A skill without the block is left out.
2. Ensures the structure: one workspace per plugin and the declared activities. It only creates: it never renames or deletes.
3. Updates the existing tasks, matched by skill_slug (<plugin>:<skill-folder>).
4. Creates the missing tasks for skills with task: that have no task in the organization.
5. Applies the environments from kadu.yaml (creates and updates).
6. Applies each task's schedules (task.schedules).
7. Applies the metadata of workspaces and activities and the kadu.yaml webhooks.
8. Deletes the repository's environments that left kadu.yaml, last, so that a schedule that moved environments has already left the old one.

You do not need to register the task by hand: the merge creates the task.

The Playbook is the source of truth

In step 3, every declared field in the task: block that differs from Kadu is overwritten. The comparison of parameters_schema and metadata ignores key order, so reformatting the YAML does not generate an update.

Frontmatter field	What the sync does to the existing task
label, description	overwrites
model	switches the tier (price, executor and model). A value that is not a tier: not applied, with a warning
parameters_schema	overwrites; null clears
parameters_sensitive, accepts_input_files, generates_output_files	overwrites
systems, features, required_secrets	overwrites the whole list
activity	moves the task to the activity with that name; creates the activity if it does not exist
workspace	ignored: the task stays in the plugin's workspace
endpoint	reconciles; never changes the authentication type or turns on without a credential
schedules	creates, updates and deletes the repository's schedules
executor	stores the executor and model override; inherit clears
metadata	overwrites the whole object

Rules that follow from this:

• A missing field means "do not touch". Deleting a frontmatter line does not return the field to the default. To clear, declare it empty: required_secrets: [], features: [], parameters_schema: null, description: "".
• An edit made in the console to a declared field is undone on the next push or the next hour. Change it in the frontmatter.
• A schedule and environment edited in the console revert to what was declared on the next push. A pause made in the console is the exception, as long as the item does not declare paused.
• A deleted task does not come back. The sync counts the deleted task as existing: it neither recreates nor updates it. And the reverse: removing the task: block does not delete the task, it only stops updating it. To retire a task, ask Kobana to remove it and remove the block.
• Renaming the skill folder creates another task, without history, without endpoint credential and with only the declared schedules, and leaves the old one orphaned. To change the name in the console, change label:.
• Moving the skill to another plugin changes the slug prefix: it also creates another task.

Where to see the result

The sync through the button shows what changed:

• workspaces and activities created;
• tasks updated, with the changed fields (Baixar pagamentos (label, model));
• tasks created and tasks skipped, with the reason;
• Repository configuration: environments, schedules, webhooks and metadata applied (Agendamento Baixar @ Produção criado (0 9 * * 1-5));
• Warnings: invalid tier, endpoint without credential, invalid kadu.yaml, secret declared without a value, schedule not applied.

A sync triggered by a push or by the hourly check shows the result to nobody. If a change did not appear in the console, sync through the button and read the warnings.

Task skipped with the reason	Cause
<slug> (sem task.activity no frontmatter)	activity: missing: without an activity there is nowhere to create the task
<slug> (nenhum tier de preço ativo)	model missing or invalid and no active tier registered

Sequence for a new task

1. Write the skill with the task: block (with activity: and model: tier-N).
2. Validate locally (/kadu:agent-run-task <plugin>:<skill>) and in the CI sandbox (Local development).
3. Merge to main: the code is already in effect, and the sync creates the task.
4. Sync through the button and check the task under "Tasks created", with no warnings.
5. Register the secret values (and ask for the endpoint credential, if any). If the task has schedules, do this before the first run time: the schedule is in effect from step 3.
6. Run it once and check the timeline, logs, pending items and result.

Step 6 is not a formality: it is where an event without message, a result with a status instead of Markdown and a question that blocks the execution show up.

Sequence for changing a task

1. Change the frontmatter, never the folder name.
2. Merge to main.
3. Check under "Tasks updated" that the field went in. If it does not appear: the field has the wrong type (silently discarded), it is workspace: (ignored) or the value was already the same.