# Cuga Migrator

> Migrate a source agent system to CUGA SDK. Triggers on requests like "migrate <source> to CUGA", "convert this agent system to CUGA SDK", "run the CUGA migration pipeline for <source> as <target>".

- Skill: `cuga-project/cuga-migrator` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add cuga-project/cuga-migrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cuga-project/cuga-migrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: cuga-project (https://skillmd.com/u/cuga-project)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cuga-project/cuga-migrator

---


# CUGA Migrator — Orchestrator

You are the orchestrator of a 5-stage pipeline that converts a source agent system into a CUGA
SDK implementation: **analyst → implementer → test_writer → evaluator → debugger (loop)**.

Each stage's full agent instructions live in their own file under `agents/` — read the
relevant one in full immediately before spawning that stage's subagent, rather than trying to
hold all five in your own context at once. This keeps this file itself as pipeline logic only,
and mirrors the original Claude Code project's one-file-per-agent layout
(`cuga-migrator/.claude/agents/<name>.md`), just accessed via `Read` instead of a named
`agent_name=` parameter, since Bob has no built-in custom sub-agent definitions.

| Stage | Agent file |
|---|---|
| 1. Analyst | `agents/analyst.md` |
| 3. Implementer | `agents/implementer.md` |
| 4. Test writer | `agents/test_writer.md` |
| 6a. Evaluator | `agents/evaluator.md` |
| 6b. Debugger | `agents/debugger.md` |

**Execution model — read this before starting.** Every stage spawns exactly **one** subagent
and waits for it to fully return before moving on. Bob subagents run strictly sequentially with
real per-spawn overhead — no concurrent fan-out. Every "for each X" below (test cases, failure
categories, etc.) means one subagent call after another, never several at once.

## Global rules (apply to every stage)

Each agent file already ends with these; they're restated here for your own reference too:

1. Never modify `migration_to/cuga-agent/` — read-only SDK runtime.
2. Never modify `migration_from/` — read-only source reference.
3. Never modify `migration_to/data/ground_truth/` — read-only evaluation source of truth.
4. Minimum change principle — make the smallest change that achieves the goal.

## Arguments

Parse the user's request as `<source-name>`, `<target-name>`, and an optional ordered list of
stages:
- **source_name** — subfolder under `migration_from/`
- **target_name** — subfolder under `migration_to/`
- **stages** (optional) — if the request asks to run only specific stage(s) (e.g. "just run the
  analyst stage", "re-run implementer then evaluator for cp4i-cuga"), extract which one(s), in the
  order the user wants them run: `analyst`, `implementer`, `test_writer`, `evaluator`, or
  `debugger`. See "Stage-only mode (--stages)" below.

If source_name or target_name is missing, ask the user for it before proceeding.

## Paths (relative to this project's root)

| Variable | Path |
|----------|------|
| Source repo | `migration_from/<source_name>/` |
| Output dir | `migration_to/<target_name>/` |
| Ground truth | `migration_to/data/ground_truth/` |
| CUGA SDK | `migration_to/cuga-agent/` |
| Templates | `cuga-templates/` |
| SDK reference (supervisor) | `migration_to/cuga-agent/docs/examples/travel_agent/` |
| SDK reference (one_agent) | `migration_to/cuga-agent/docs/examples/cuga_with_runtime_tools/` |
| Spec output | `.cuga-migrator/migration_spec.md` |
| Prediction dir | `migration_to/data/prediction/` |
| State file | `.cuga-migrator/state.json` |

Create `.cuga-migrator/` and `migration_to/<target_name>/` if they don't exist.

## User request

Before doing anything else, check if `.cuga-migrator/user_request.md` exists. If it does, read it
— its full contents go into the analyst subagent's prompt below as the "User request" input,
verbatim, whether it's empty or not. The analyst is responsible for folding it into
`migration_spec.md` (architecture choice in `## Architecture`, everything else in `## Notes`) —
every downstream stage reads the spec, not this file directly, so what the analyst writes there is
the request's only path into the rest of the pipeline.

## Resuming

If `.cuga-migrator/state.json` exists, read it and skip stages already listed in
`completed_stages`.

<Steps>

<Step title="Stage 1 — Analyst: produce migration_spec.md">

**Stage 1a — Spawn the analyst subagent:** Read `agents/analyst.md` in full. Spawn one subagent
whose prompt is that file's content verbatim, with the bracketed paths and the user request (from
above) filled in. This subagent writes `.cuga-migrator/migration_spec.md` itself, as
its own last action — you do not save anything on its behalf.

**After it returns**, read `.cuga-migrator/migration_spec.md` yourself and assess:
- How many agents, MCP servers, policies?
- Any ambiguities in `## Notes`?
- **Capability coverage check** — for every agent, verify every external-call step resolves to a
  named MCP server, a named CUGA config field, or a `## Capability Gaps` entry; flag any hedging
  language ("may require", "unclear", "the platform handles") without a concrete resolution.

If the file is missing, check `migration_to/` for a similarly-named file the subagent may have
misplaced (e.g. `MIGRATION_SPEC.md`, `MIGRATION_PLAN.md`) and move it to the correct path yourself
rather than redoing the analysis.

**Pause here.** Summarize the spec for the user — including flagged gaps — and ask if it looks
correct before continuing. If they want changes, edit the spec markdown directly, then continue.

Update `.cuga-migrator/state.json` (create if absent):
```json
{"source_name": "<source_name>", "target_name": "<target_name>", "completed_stages": ["analyst"], "debug_iterations": 0, "overall_score": null}
```

</Step>

<Step title="Stage 2 — Copy templates">

Read the spec to determine the chosen architecture, then:

```bash
cp -r cuga-templates/<architecture>/* migration_to/<target_name>/
cp -r cuga-templates/tests/* migration_to/<target_name>/
```

</Step>

<Step title="Stage 3 — Implementer: generate the CUGA implementation">

Read `agents/implementer.md` in full. Spawn one subagent whose prompt is that file's content
verbatim, with the bracketed paths filled in.

**Adapt to complexity:**
- Simple spec (≤2 agents): single pass
- Complex spec (5+ agents or multiple MCP servers): tell the implementer to do a phased approach

Update `state.json`: append `"implementer"` to `completed_stages`.

</Step>

<Step title="Stage 4 — Test writer: produce test_cases.json">

If `migration_to/<target_name>/test_cases.json` already exists, skip this stage.

Check if ground truth files exist at `migration_to/data/ground_truth/`. If none exist, ask the
user to provide them before continuing — do not invent test cases.

Otherwise read `agents/test_writer.md` in full and spawn one subagent whose prompt is
that file's content verbatim, with the bracketed paths filled in.

Update `state.json`: append `"test_writer"` to `completed_stages`.

</Step>

<Step title="Stage 5 — Human review gate">

Show the user a summary of files generated in `migration_to/<target_name>/`. Ask them to review
before running tests. Wait for confirmation before continuing to Stage 6.

</Step>

<Step title="Stage 6 — Eval-debug loop">

Set `iteration = 0`. Repeat the following up to 3 times:

**Evaluator.** Read `agents/evaluator.md` in full. Spawn one subagent whose prompt is that
file's content verbatim, with the bracketed paths and the current `iteration` filled in.

**After the subagent returns:** read `migration_to/data/prediction/eval_report.json` and check
`overall_score`:

- **≥ 0.8** → done. Report success to the user with the score and passing test count. Update
  `state.json`: `"completed_stages"` includes `"evaluator"`, `"overall_score"` set. Stop the loop.
- **< 0.8** and `iteration < 3` → read `agents/debugger.md` in full and spawn one subagent
  whose prompt is that file's content verbatim, filled in with the specific failures
  from this report (test ID, category, failure reason for each — never a generic prompt repeated
  across cycles). Increment `iteration`, re-run the evaluator subagent above, and re-check the
  score. Repeat.
- **< 0.8** after 3 cycles → summarize remaining failures for the user and ask how to proceed.
  Update `state.json` with the final `debug_iterations` and `overall_score`.

Never spawn the evaluator and debugger subagents in parallel with each other, or with themselves
across cycles — one at a time, one cycle fully finished before the next starts.

</Step>

</Steps>

## Stage-only mode (--stages)

If one or more stages were extracted per "## Arguments" above, do **only** the following instead
of the `<Steps>` pipeline, then stop — no human review gate, no automatic eval-debug looping (each
listed stage runs exactly once, in the order given — if the user wants the up-to-3-cycle loop,
that's what the full `<Steps>` pipeline is for), and do **not** write/update `state.json`
(stage-only runs are ad-hoc and shouldn't perturb full-pipeline resumability).

1. **Validate** every extracted stage is one of `analyst`, `implementer`, `test_writer`,
   `evaluator`, `debugger`. If any isn't, tell the user which one and stop before running anything.

2. **Process the stages in the order the user asked for them.** For each one:

   a. **Check its prerequisite** — if missing, stop and tell the user exactly what to run first
      instead of guessing or improvising. (An earlier stage in the *same* request can satisfy a
      later one's prerequisite — e.g. "run analyst then implementer" is fine with no
      `migration_spec.md` yet, since analyst produces it before implementer's turn comes up.)

      | Stage | Required input(s) already on disk | If missing, tell the user to run |
      |---|---|---|
      | `analyst` | `migration_from/<source_name>/` exists | add the source repo there |
      | `implementer` | `.cuga-migrator/migration_spec.md` exists | the analyst stage first |
      | `test_writer` | at least one `.txt` file under `migration_to/data/ground_truth/` | add ground truth files |
      | `evaluator` | `migration_to/<target_name>/test_cases.json` **and** `migration_spec.md` both exist | the implementer and/or test_writer stage first |
      | `debugger` | `migration_to/data/prediction/eval_report.json` exists | the evaluator stage first |

   b. **For `implementer` only** — also ensure templates are copied first (Stage 2 above), but
      only if `migration_to/<target_name>/` doesn't already look scaffolded (no
      `supervisor_config.yaml` / `agent_config.yaml` present yet). If it's already scaffolded,
      leave it alone — don't re-copy raw templates over an implementation already in progress.

   c. **Spawn only that stage's subagent** — read `agents/<stage>.md` in full and spawn one
      subagent whose prompt is that file's content verbatim, filled in with the same
      inputs the matching `<Step>` above uses (Stage 1/3/4/6a/6b respectively). For `debugger`
      specifically, read `eval_report.json` yourself first to pull out the specific failures and
      iteration number to pass it, same as Stage 6 does. For `evaluator`, after it returns just
      report the score — do not spawn `debugger` automatically unless `debugger` is itself the
      next stage in the list.

   d. Move to the next stage, if any.

3. **After the last stage finishes**, report the combined results and stop.

## State persistence

After each stage, write `.cuga-migrator/state.json`:

```json
{
  "source_name": "<source_name>",
  "target_name": "<target_name>",
  "completed_stages": ["analyst", "implementer"],
  "debug_iterations": 0,
  "overall_score": null
}
```

On resume, read it and skip already-completed stages.