Cuga Template Sync

CUGA Template Sync

Read the current CUGA SDK source and update cuga-templates/ so future cuga-migrator runs produce accurate implementations. Run this whenever migration_to/cuga-agent/ is updated to a new SDK version — before starting a migration.

Paths

1. migration_to/cuga-agent/src/cuga/sdk.py — the authoritative source. Extract every accepted parameter (with type + docstring) of CugaSupervisor.__init__() and CugaAgent.__init__(). In particular, confirm (don't assume) whether CugaSupervisor accepts tool_provider and any policy-related kwargs (policy_system, cuga_folder, auto_load_policies, reset_policy_storage, filesystem_sync) and exposes a .policies manager property — these are easy to wrongly assume are agent-only. Find how supervisor_config.yaml / agent_config.yaml are parsed — list every YAML field actually consumed. Determine which component loads policies (cuga_folder, auto_load_policies) — note that CugaSupervisor can hold its OWN policies independently of any sub-agent; don't default to "policies always belong to sub-agents" without checking.
2. .../supervisor_utils/supervisor_config.py (or wherever load_supervisor_config lives) — confirm exactly which top-level YAML keys it consumes vs. ignores. This is the source of truth for the YAML schema.
3. .../src/cuga/settings.toml and .../src/cuga/config.py — every advanced_features.* flag affecting supervisor/agent behaviour (e.g. force_autonomous_mode, decomposition_strategy, lite_mode). These are dynaconf settings, not __init__ parameters, overridable via DYNACONF_ADVANCED_FEATURES__<NAME> env vars.
4. .../prompts/supervisor_lite_prompt.jinja2 — the supervisor's actual system prompt. Note any Jinja conditionals whose behaviour the templates' guidance comments describe.
5. docs/examples/travel_agent/ and docs/examples/cuga_with_runtime_tools/ — canonical examples. Treat as secondary references: they can lag sdk.py, cross-check before trusting.

CUGA has exactly three capability axes that templates make constraint claims about: tools, policies, and skills. Both CugaAgent and CugaSupervisor can independently support or lack each one, and which is which is a fact about the current SDK version, not a fixed rule — it can change release to release. Before checking any template file, re-read CugaAgent.__init__() and CugaSupervisor.__init__() in sdk.py and fill in this table from scratch, citing the exact __init__ line for every cell (do not carry over a previous sync's answers):

For each cell, answer only from what the constructor signature actually accepts (plus, for policies/skills, whether a .policies-style manager or loader method exists) — not from what any template currently does. A class lacking a parameter for a capability is a hard "no"; a class having the parameter but no template currently passing it is a "yes, unused by convention."

Use the finished matrix as the single source of truth for grading every constraint comment in every template file that makes an "X does/doesn't support tools/policies/skills" claim: matches → confirmed accurate; comment says impossible but matrix says supported → rewrite the comment to plainly state, in your own words based on what you verify that sync, what the template currently has configured for that capability and — if unused — which kwarg would turn it on (and check whether the entrypoint silently relies on something that no-ops, e.g. a plain env var the constructor never reads instead of the real kwarg); comment says supported but matrix says no such param → fix the comment the other direction. State only the fact you just verified from the live SDK/template that sync — never frame it as "a design choice, not an SDK limitation," and don't reference what the comment used to say; that kind of before/after narrative belongs in the sync report, not the template file. Apply this the same way to all three axes — don't special-case tools or policies over skills.

For each *_config.yaml (supervisor, a2a_supervisor_external, one_agent): enumerate every top-level and nested key, cite the exact SDK or entrypoint file:line that consumes it, or mark it DEAD and remove it (dead only if neither the SDK nor the template's own entrypoint reads it — common dead suspects: supervisor.strategy, supervisor.mode). Verify YAML ↔ entrypoint consistency both directions — a key the SDK would consume via from_yaml but the template's manual loader silently drops is a silent-drift bug; fix it. Confirm constraint comments are accurate (e.g. if special_instructions IS consumed, the comment must say so, not "DO NOT add"). Grade any tools/policies/skills capability claim against the matrix above, cell by cell.

For each *_entrypoint.py: import paths match current SDK package structure; constructor calls use only parameters that actually exist; no deprecated/removed parameters referenced; every config lookup corresponds to a key actually present in that template's YAML.

For each mcp_servers/mcp_server_template.py / a2a_agents/a2a_agent_template.py: import paths, decorator/class patterns, and entrypoint calls match current SDK/A2A package versions.

For each scripts/start.sh: startup commands (module path, env vars, ports) match the canonical example.

For each .cuga/<type>/*.md policy template: YAML frontmatter uses the field names and triggers structure the SDK actually parses for that type.

For cuga-templates/one_agent/.agents/skills/skill_template/SKILL.md: frontmatter (name, description) matches what CugaAgent reads for skills; body section structure (When to Use, Workflow, Output Format, Error Handling) reflects current best practice.

For cuga-templates/tests/runner_template.py: Agent.create() call matches the current entrypoint API; import placeholder pattern still works; parallel-execution/output-path logic matches what the evaluator stage expects.

For cuga-templates/README.md: file listing and descriptions still match what's actually on disk.

Edit only the parts that are wrong or outdated; do not rewrite entire files. When fixing a comment, replace it with one that plainly states the current, correct fact — a reader opening the template fresh should see only accurate, present-tense documentation of what it does now, not "previously this said...", "this used to be...", or "design choice vs SDK limitation" narration. Keep any before/after story in the sync report. If the SDK added a new field, add a commented-out example line with a {{PLACEHOLDER}} note. If a field was removed, remove it (with a brief inline comment explaining the removal if it prevents confusion).

First capture the SDK commit so future syncs can tell whether they're operating against the same state:

cd migration_to/cuga-agent && git rev-parse HEAD 2>/dev/null || echo "not-a-git-repo"

Write .cuga-migrator/sync_report.md:

# CUGA Sync Report

**Date**: <today>
**SDK path**: migration_to/cuga-agent/
**SDK commit**: <git SHA or "not-a-git-repo">

## Changes made
- <file>: <what was wrong> -> <what was fixed>

## No changes needed
- <file>: confirmed accurate

## Dead YAML keys removed
- `<template>/<config>.yaml`: removed `<key>` (confirmed dead against `<sdk-file>:<line>` and `<entrypoint-file>:<line>`)

## Silent YAML <-> entrypoint drift fixed
- `<template>/<entrypoint>.py`: now reads `<key>` from YAML and forwards it to `<SDK call>` (was silently ignored before)

## Key SDK facts (for cuga-migrator awareness)
- CugaSupervisor: accepts <parameters>; does NOT support <what it lacks>
- CugaAgent: accepts <key parameters>
- Policy loading: owned by <supervisor|agent|both>
- YAML fields consumed by supervisor config: <list, citing SDK file:line>
- YAML fields consumed by agent config: <list, citing SDK file:line>

## Behaviour-shaping settings (not in __init__)
- `<setting.path>` (default `<value>`): <one-line effect>

This report is read by the migration orchestrator and passed to the analyst as context. Keep it factual and terse — list every template file checked, both changed and unchanged, so coverage is visible.