DFCX to CXAS Migration

Four small scripts, one persistent IR bundle:

State flows through <target>_ir.json (a Pydantic IRBundle containing the MigrationConfig, source DFCXAgentIR, target MigrationIR, stage history, and version checkpoints). Each stage loads it from disk, mutates it, and writes it back. No re-fetching or re-compiling between stages.

When to use this skill vs. the CLI directly

This skill (InquirerPy prompts + HTML pre-flight preview + Gemini model picker) is the right entry when you want to interactively drive a migration with rich pre-flight context. The same MigrationService.run_stage* methods this skill calls are also exposed via the canonical CLI for scripted / CI use:

# Same E2E plumbing, non-interactive (standard optimized profile by default):
cxas migrate dfcx --run --source-agent-id … --project-id … --target-name …

# Non-interactive Stage Checkpoint optimization runs:
cxas migrate dfcx --optimize --stage 1 --target-name my_app
cxas migrate dfcx --optimize --stage 2 --target-name my_app
cxas migrate dfcx --optimize --stage 3 --target-name my_app --architecture hub-and-spoke
cxas migrate dfcx --optimize --stage resume --target-name my_app  # interactive stage picker

The skill, the dashboard, and the E2E / Checkpoint commands all go through the same MigrationService.runstage1/runstage2/runstage3 methods — pick whichever entry point matches your workflow.

Prerequisites

# Ensure cxas_scrapi is installed editable (so this skill picks up local changes)
pip install -e .

# Auth
gcloud auth application-default login
gcloud auth list   # confirm the account has read on source + admin on target

InquirerPy is required for the interactive prompts (matches the agent-foundry skill):

pip install InquirerPy

Driving the flow interactively (from Claude)

When invoked through Claude, lead the user through one question at a time. The scripts will prompt for missing inputs via InquirerPy, but you should pre-collect:

1. GCP project ID (target — where the new CXAS app will live).
2. Location — default us. Do NOT default to global — it does not work for CXAS apps in most projects.
3. Source agent — DFCX agent ID (full resource name) or path to a local .zip export.
4. Target name — display name for the new CXAS app.

Optional follow-ups: --env (PROD/AUTOPUSH), --model (Gemini), --migration-version (1.0/2.0).

Quick Reference

# 1:1 migration (interactive — InquirerPy will prompt for project + location)
python .agents/skills/cxas-dfcx-migration/scripts/migrate.py

# Fully scripted
python .agents/skills/cxas-dfcx-migration/scripts/migrate.py \
  --source-agent-id "projects/<src_proj>/locations/us/agents/<uuid>" \
  --project-id <target_proj> --location us \
  --target-name my_cxas_app --yes

# Pre-flight HTML preview only (no migration)
python .agents/skills/cxas-dfcx-migration/scripts/migrate.py \
  --source-agent-id "<id>" --project-id <proj> --target-name preview_only \
  --preview-only --yes

# Stage 1 — variable dedup + Gemini consolidation
python .agents/skills/cxas-dfcx-migration/scripts/stage_1.py --target-name my_cxas_app

# Stage 1 — replay a saved grouping JSON
python .agents/skills/cxas-dfcx-migration/scripts/stage_1.py \
  --target-name my_cxas_app --grouping-json my_cxas_app_grouping.json --yes

# Stage 2 — instruction state machines + tool mocks + lint + report
python .agents/skills/cxas-dfcx-migration/scripts/stage_2.py --target-name my_cxas_app

# Stage 3 — rewire consolidated agent parent-child topology (idempotent)
python .agents/skills/cxas-dfcx-migration/scripts/stage_3.py --target-name my_cxas_app --architecture hub-and-spoke

What lives in the skill vs. in cxas_scrapi

The skill is a thin orchestrator. **Every migration / optimization step lives in src/cxasscrapi/migration/ and is reachable via MigrationService.runstage_* methods**, so the same logic powers all three entry points: this skill, cxas migrate dfcx (interactive TUI), and non-interactive command modes (--run / --optimize).

Skill-local helpers (UX glue only — InquirerPy prompts + thin delegations to MigrationCLI):

• _prompts.py — InquirerPy prompt library (matches agent-foundry).
• shared.py — InquirerPy variants of project/location prompts, source loader, and MigrationConfig assembly; plus pure delegations to MigrationCLI for checkauth, rundependencyanalysis, selectresources, showvisualizations.

The stage scripts now import the promoted modules directly: `from cxasscrapi.migration.datamodels import IRBundle (plus htmlpreview in migrate.py and phasetracker) and call sites use the canonical model names (IRBundle, phasetracker.PhaseTracker, htmlpreview.generatehtmlreport`) — no re-export shim layer.

The skill's stage scripts (migrate.py / stage1.py / stage2.py / stage3.py) are now ~80-200 line shells: parse args → restore service from bundle → call the matching MigrationService.runstage_* → print summary. There is no orchestration logic left in the skill — only InquirerPy prompts and the HTML preview that's specific to the skill's pre-flight UX.HTML preview that's specific to the skill's pre-flight UX.

IR bundle (<target>_ir.json)

The unit of state shared across the three scripts. Pydantic IRBundle model:

{
  "schema_version": "1",
  "created_at": "2026-05-14T15:30:00",
  "config": { /* MigrationConfig */ },
  "source_agent_data": { /* DFCXAgentIR — needed for tool-mock context */ },
  "ir": { /* MigrationIR — mutated by each stage */ },
  "stage_history": [
    {"phase": "migrate", "status": "ok", ...},
    {"phase": "stage1",  "status": "ok", ...}
  ],
  "app_url": "https://ces.cloud.google.com/...",
  "version_checkpoints": [["0.0.1", "Stage 1: ..."]],
  "grouping": { /* present if Stage 1 ran consolidation */ }
}

Killing a stage script mid-run leaves the bundle untouched (only persisted on success). Re-running picks up where the last successful stage left off.

Pre-flight HTML preview

migrate.py generates <target>treepreview.html in ~5 seconds after source loading. Open it in any browser to see:

• Source overview (resource counts, estimated migration time).
• Topology graph (graphviz SVG when dot is on PATH; Mermaid fallback otherwise).
• Per-playbook and per-flow Rich trees.

migrate.py --preview-only exits after the preview without running the migration.

Troubleshooting

• create_app returns 404 / 501 / MethodNotImplemented — your --location is wrong. CXAS apps in most projects live in us, not global. Pass --location us.
• AlreadyExists: App with same display name — pick a different --target-name. Old runs leave deployed apps behind even on partial failure.
• Stage 1 / Stage 2 fail with No IR bundle found — run migrate.py first to produce <target>_ir.json, or pass --ir-bundle <path> explicitly.
• Synthesis (Stage 1 consolidation) hangs on Gemini — fixed with per-group asyncio.waitfor(timeout=600s) in structuralconsolidator.synthesizeinstructions. Override via SYNTHESISTIMEOUT_S env var. Hung groups fall back to the concatenated instruction.
• gemini-2.5-flash-001 not found during AI augment — the Gemini call uses locations/global for the model; sometimes that endpoint is project-restricted. The migration continues with empty AI descriptions. Pick a different --model if you need them.

Detailed reference

See [references/migration-options.md](references/migration-options.md) for full parameter / flag descriptions and the IR bundle schema.