Enhance device-migration skill with sub-agent architecture and phase safety guards

docs/skills/c2000-idea/SKILL.md

@@ -13,15 +13,24 @@ the MCP* for a given migration task; the MCP supplies the analysis.
 
 ## Prerequisite
 
-These workflows require the IDEA MCP server to be running. It is hosted by the C2000-IDEA
-extension over HTTP. If the IDEA MCP tools are not available in your session, tell the user
-to enable it (Command Palette → "C2000-IDEA: Enable IDEA MCP") and register it with their
-agent, then retry.
+These workflows require the IDEA MCP server, CCS Project MCP, and (for TRM register
+lookups) TI ASM MCP to be running. They are hosted by the C2000-IDEA VS Code extension
+over HTTP. If any required MCP tools are not available in your session, tell the user
+to enable them (Command Palette → `C2000-IDEA: Enable IDEA MCP` / `Enable TI ASM MCP`, or click **MCP Servers** in the VS Code status bar)
+and register them with their agent, then retry.
 
+**Before starting any device migration task, run the Phase 0 pre-flight check:**
 
-**Before starting any task, verify the IDEA MCP server is live:**
+- Reference file: [`references/device-migration/phase-0-preflight.md`](references/device-migration/phase-0-preflight.md)
+- Phase 0 probes all three MCPs, verifies Git state, and records pre-flight results as session context for Phase 1.
+- Do not start Phase 1 until Phase 0 completes without a hard stop.
 
-1. Attempt `list_migration_devices()` as a probe call.
+For non-migration tasks (e.g., bitfield-to-driverlib conversion), run the minimal probe
+below instead of full Phase 0:
+
+**Minimal MCP probe (non-migration tasks):**
+
+1. Attempt `get_projects()` as a probe call.
    - If it succeeds → server is running. Proceed.
    - If it fails or is unreachable → server is not running. **Stop here.**
 2. Tell the user: *"The IDEA MCP server is not running. Please enable it:"*

docs/skills/c2000-idea/references/device-migration.md

@@ -31,9 +31,11 @@ explicitly:
 Call `list_migration_devices()` from IDEA MCP immediately after collecting inputs.
 - Confirm every **target device** the user provided is in the supported list.
 - If any target device is not supported, notify the user which device(s) are unsupported
-  and **terminate** — do not proceed.
+  and **exclude those targets** — remove them from the target list and continue with the
+  remaining supported targets. If **all** targets are unsupported, stop and tell the user.
 - The source device is validated later (Phase 1, step 1.2) once discovered from the
-  project, but if it is not in the supported list, also notify the user and terminate.
+  project. If the source device is not in the supported list, notify the user and
+  **stop** — migration cannot proceed without a supported source.
 
 ## Dependencies
 
@@ -99,6 +101,10 @@ to recover your position and progress.**
 
 ## Resuming a paused migration
 
+> ⛔ **If you are resuming:** Read `c2000-migration.md` FIRST — before reading the Phase
+> sequence below. Identify where you left off, then jump directly to the correct phase file.
+> **Do not start from Phase 1 unless Phase 1 is explicitly recorded as incomplete.**
+
 If you are resuming a migration that was started in a previous session:
 
 1. Locate the target project's `c2000-migration.md`. The `get_projects()` result also
@@ -113,16 +119,22 @@ If you are resuming a migration that was started in a previous session:
 
 ## How to run this workflow
 
-This workflow is split into five phases. **Execute them in strict order.** Read one phase
-file at a time, complete all steps in it, then return here and read the next phase file.
-Do not read ahead — only load the next phase when the current one is done.
+> ⛔ **Do not read ahead.** Read one phase file at a time. Complete every step in it.
+> Return here. Only then read the next phase file. Do not open the next phase file early.
+
+This workflow is split into six phases. **Execute them in strict order.**
 
 > **Per-target:** When migrating to multiple target devices, migrate **one device at a
 > time** — run Phases 2, 3, 4, and 5 fully for one target before starting the next. Do not
 > interleave or batch phases across targets. Phase 1 covers all targets at once.
 
 ### Phase sequence
 
+0. **Read `device-migration/phase-0-preflight.md`** — Run the pre-flight check: probe all
+   MCP servers (IDEA MCP, CCS Project MCP, TI ASM MCP), verify Git state, and initialize
+   the session context. **This phase runs once before Phase 1 and is mandatory.**
+   → When complete, return here.
+
 1. **Read `device-migration/phase-1-import.md`** — Discover the source project, identify
    the SDK, import and validate the target project(s).
    → When complete, return here.
@@ -150,12 +162,24 @@ Do not read ahead — only load the next phase when the current one is done.
 
 These rules apply across all phases:
 
+### Universal project invariants (absolute — never override)
+
+- Do keep the target project in the **universal project style**: it must always retain a
+  `.syscfg` with the `device_support` module as the non-negotiable baseline — regardless
+  of whether the source project used SysConfig at all. Never remove the target's `.syscfg`.
+- Do treat `device_support` as the **absolute minimum** in the target syscfg. It generates
+  `device.c`/`device.h` (clocking/init), `.opt` (compiler options), and `.cmd.genlibs`
+  (linker libs), and provides pinmux data essential for the target device — even if the
+  user does not configure any peripheral in SysConfig right now.
+- Do layer all other syscfg content (peripheral configs, CMD module, etc.) **on top of** the
+  `device_support` baseline if the source used them — but the baseline is always preserved.
+
+### General rules
+
 - Do keep the source project unchanged — it is the golden reference.
 - Do cross-check CCS MCP and IDEA MCP results for consistency.
-- Do terminate early if devices are not in the supported migration list.
+- Do exclude unsupported target devices (notify user); stop only if the source device is unsupported.
 - Do apply settings automatically unless the difference is a legitimate device delta.
-- Do ensure the target always has a `.syscfg` with the device-support module present — it
-  regenerates `device.c`/`device.h`, `.opt`, and `.cmd.genlibs`.
 - Do mirror the source's linker style: a CMD module in the target syscfg if the source used
   one, a plain `.cmd` (CMD module removed) if the source used a plain file.
 - Do read AGENTS.md from SDK roots if present.

docs/skills/c2000-idea/references/device-migration/phase-0-preflight.md

@@ -0,0 +1,156 @@
+# Phase 0 — Pre-flight Check
+
+> **Run Phase 0 once before starting Phase 1.** This phase verifies that all required
+> MCP servers are live and the workspace Git state is clean. If any check fails, stop
+> and resolve it before proceeding. Do not skip this phase — a silent MCP failure mid-
+> migration is far harder to diagnose than a failure caught here.
+
+---
+
+## Step 0.1 — Probe IDEA MCP
+
+Call `get_projects()` with no arguments.
+
+- **Success** → IDEA MCP is live. Note the list of C2000 projects returned.
+- **Failure / unreachable** → IDEA MCP is not running. **Stop.**
+  Tell the user:
+  > *"The IDEA MCP server is not running. Please enable it:"*
+  > - Command Palette → `C2000-IDEA: Enable IDEA MCP`  (or click **MCP Servers** in the VS Code status bar)
+  > - After enabling, re-register the MCP with your agent tool, then tell me to retry.
+
+Do not proceed past Step 0.1 until `get_projects()` succeeds.
+
+---
+
+## Step 0.2 — Probe CCS Project MCP
+
+Call `getToolOptions` (ccs-project MCP). This is the lightest read-only introspection
+call — it returns the list of available build tool options without modifying anything.
+
+- **Success** → CCS Project MCP is live.
+- **Tool not found / error** → CCS Project MCP is not registered or not running.
+  Tell the user:
+  > *"The CCS Project MCP is not available. This is required for project import, build,
+  > and settings management during migration. Please register it with your agent tool."*
+  > **Stop** — do not proceed to Phase 1 without CCS Project MCP.
+
+> **If `getToolOptions` returns an error that looks like a usage error** (e.g., "required
+> parameter missing") rather than "tool not found", the MCP is live — the tool requires
+> arguments. In that case, treat it as a successful probe.
+
+---
+
+## Step 0.3 — Probe TI ASM MCP
+
+Attempt any TI ASM MCP tool call. The exact tool name depends on which tools the TI ASM
+MCP exposes — try the first tool listed in the MCP's tool manifest (any lightweight
+introspection or info call). The default port is `55000`.
+
+> **If you cannot determine any tool name** from the MCP manifest, try a minimal call to
+> any tool you know the TI ASM MCP provides (e.g., a device-lookup or TRM-query tool).
+> If no tool is callable, treat TI ASM MCP as unavailable (soft warning — see below).
+
+- **Success** → TI ASM MCP is live.
+- **Failure / tool not found** → TI ASM MCP is not available. This is a **soft warning**
+  (not a hard stop), because TI ASM MCP is only required when a migration report issue
+  has no `Suggested fix` and you need to look up the register in the TRM. Tell the user:
+  > *"TI ASM MCP is not available (port 55000). Migration can proceed, but if any Phase 4
+  > issue requires TRM register lookup, you will need to enable it:*
+  > *Command Palette → `C2000-IDEA: Enable TI ASM MCP`*"
+
+  Record the warning in `c2000-migration.md` (see Step 0.5). Continue to Step 0.4.
+
+---
+
+## Step 0.4 — Verify Git state
+
+Check the Git status of the workspace (use a read-only Git status check — do not commit
+or stage anything here).
+
+### 0.4a — Confirm clean working tree
+
+Verify there are no uncommitted modifications to the **source project** directory.
+
+- **Clean** → proceed.
+- **Dirty (uncommitted changes)** → warn the user:
+  > *"Your source project has uncommitted changes. It is strongly recommended to commit
+  > or stash these before starting migration so the pre-migration state is recoverable."*
+
+  Ask: *"Do you want to commit/stash first, or proceed anyway?"*
+  - If the user says proceed → note `Git state: dirty (user acknowledged)` in the
+    migration log and continue.
+  - If the user wants to commit first → wait for them to do so, then re-check.
+
+### 0.4b — Confirm migration branch exists or offer to create one
+
+Check whether the current branch name suggests a migration branch (e.g., contains
+`migration`, `migrate`, or `mig`).
+
+- If on a dedicated migration branch → good, note the branch name.
+- If on `main`, `master`, `dev`, or any non-migration branch → recommend:
+  > *"You are on branch `<branch>`. It is recommended to create a dedicated migration
+  > branch (e.g., `migration-to-<target device>`) before proceeding so you can roll
+  > back cleanly."*
+
+  Ask: *"Create a migration branch now, or proceed on the current branch?"*
+  - If user wants a new branch → help them create it (e.g., `git checkout -b
+    migration-to-<targetDevice>`), then confirm the switch.
+  - If user says proceed on current branch → note in the migration log and continue.
+
+---
+
+## Step 0.5 — Record pre-flight results for Phase 1
+
+> **Do NOT create `c2000-migration.md` in Phase 0.** The migration log lives inside
+> each target project's directory, which does not exist until Phase 1 imports and
+> renames the target project (step 1.9). Creating the log here would put it in the
+> wrong location (workspace root instead of the target project directory), and Phase 1
+> would then create a second log — violating the append-only rule.
+>
+> Phase 0's results are recorded as **session context** that Phase 1 embeds into the
+> log when it creates it in step 1.9.
+
+Keep the following pre-flight results in your **session context** (conversation memory)
+so Phase 1 can reference them when creating `c2000-migration.md`:
+
+```
+Pre-flight results (to embed in c2000-migration.md at Phase 1 step 1.9):
+  IDEA MCP:         live
+  CCS Project MCP:  live
+  TI ASM MCP:       <live | not available (warned)>
+  Git branch:       <branch name>
+  Git state:        <clean | dirty — user acknowledged>
+```
+
+Phase 1 step 1.9 will seed `c2000-migration.md` with these values under the session
+header. The Phase status table (Phase 0 through Phase 5) is created by Phase 1, not here.
+
+---
+
+## Step 0.6 — Phase 0 complete
+
+Confirm to the user:
+
+```
+Pre-flight check complete.
+✅ IDEA MCP: live
+✅ CCS Project MCP: live
+<✅ or ⚠> TI ASM MCP: <live | not available>
+<✅ or ⚠> Git state: <clean | dirty — acknowledged>
+Migration log: will be created in Phase 1 step 1.9 (once target project is imported)
+
+Ready to start Phase 1 (project import).
+```
+
+Then **re-read `device-migration.md`** to find Phase 1 and proceed.
+
+---
+
+## Failure reference
+
+| Failure | Action |
+|---------|--------|
+| `get_projects()` fails | Hard stop — IDEA MCP required |
+| CCS Project MCP not found | Hard stop — required for all build operations |
+| TI ASM MCP not found | Soft warning — record and continue |
+| Git working tree dirty | User decision — record outcome and continue |