# Migrate

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-hellotern-sextant-migrate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hellotern](https://agentstack.voostack.com/s/hellotern)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hellotern](https://github.com/hellotern)
- **Source:** https://github.com/hellotern/Sextant/tree/main/skills/migrate

## Install

```sh
agentstack add skill-hellotern-sextant-migrate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

!../principles/SKILL_BODY.md

!../tool-gitnexus/SKILL_BODY.md

---

# Migration Workflow

## Core Principle

Migrations are multi-module, stateful, and partially irreversible. The core strategy is **migrate in dependency order, validate at every checkpoint, and keep rollback options open until all modules are confirmed working.**

> **Distinct from sextant:modify-feature:** Modify-feature changes one module's behavior. Migration coordinates changes across many modules in a defined sequence, with compatibility shims and a rollback plan at each phase boundary.

---

## Complete Execution Workflow

> **Progress tracking:** At the start of each step, output an updated progress block so the user knows where the migration stands.
>
> ```
> Migration Progress
> ✓ Step 1: Scope Scan         — 
> ✓ Step 2: Compatibility      — 
> → Step 3: Migration Plan     — in progress
> ○ Step 4: Per-Module Migration + Validation
> ○ Step 5: Cleanup
> ```
>
> Replace `○` with `→` for the current step, and `✓` once complete.

---

### Step 1: Migration Scope Scan

Enumerate all affected files and produce a migration inventory:

- List every file that references the old API, type, pattern, or version
- Score the total impact using the Impact Radius Scorecard (§3.2)
- Identify dependency relationships between affected files

```
─── Migration Inventory ─────────────────────────────
Migration:  → 
Impact radius score: N → 

File                   | Change Type             | Dependency Order
───────────────────────|─────────────────────────|──────────────────────
               |     | leaf (migrate first)
               |        | depends on A
               |            | migrate last
─────────────────────────────────────────────────────
```

🔗 When GitNexus is available, use `impact` MCP tool to enumerate all dependents automatically.

### Step 2: Compatibility Assessment

For each breaking change in the migration:

- Is there a **compatibility shim** available (e.g., an adapter, polyfill, or compatibility layer)?
- What is the **backward compatibility window** — can the old and new API coexist during migration?
- Is there **runtime coercion risk** — can old data be silently misinterpreted by the new code?

```
─── Compatibility Assessment ────────────────────────
Breaking change: 
  Shim available:         Yes () / No
  Old/new coexistence:    Yes (window: ) / No
  Runtime coercion risk:  Yes (describe) / No
  Rollback approach:      
─────────────────────────────────────────────────────
```

**If no shim is available and old/new cannot coexist:** flag as a hard-cutover migration step. Use the confirmation gate with:

- **question**: The Compatibility Assessment block for this step, plus: `"This is a hard-cutover step — old and new cannot coexist. Rollback after this point requires manual intervention. Authorize execution?"`
- **options**:
  - `"Yes, I authorize this hard-cutover step"`
  - `"No — let's find a compatibility shim or defer this step"`

Do not proceed with this step until the user selects "Yes".

### Step 3: Migration Order Planning

**Ordering rule (per §6.2 dependency direction):** migrate leaf modules first, core modules last.

```
─── Migration Sequence ──────────────────────────────
Phase 1 (no dependents): 
Phase 2 (depend on Phase 1 only): 
...
Phase N (core): 

Rollback boundary after each phase: if Phase N+1 fails, revert only Phase N.
─────────────────────────────────────────────────────
```

**Each phase should be a separate commit** — this preserves rollback granularity and makes the migration history bisectable.

### Confirmation Gate (between Step 3 and Step 4)

After completing the Migration Sequence, **before executing any module change**, use the confirmation gate with:

- **question**: The full Migration Sequence block above, plus a summary of any hard-cutover steps identified in Step 2
- **options**:
  - `"Yes, begin execution in this order"`
  - `"No — let's revise the sequence or scope"`

Do not begin Step 4 until the user selects "Yes".

**If user selects "No":** ask *"What should change — the order, scope, or approach?"*, update the Migration Sequence, and use the confirmation gate again.

---

### Step 4: Per-Module Migration + Validation

For each module, in the order established in Step 3:

1. Apply the migration to this module only
2. Run the associated tests for this module (and its direct callers)
3. **If tests pass:** continue to the next module
4. **If tests fail:** stop. Do not continue to the next module. Diagnose the failure — link `sextant:debug` if the root cause is not immediately clear.

```
─── Per-Module Migration Log ────────────────────────
Module: 
Change applied: 
Tests run: 
Result: ✅ Pass — proceed to next module / ❌ Fail — stopped (diagnosis below)
─────────────────────────────────────────────────────
```

**Forbidden:** Migrating multiple modules between test runs. Each module migration must be validated before the next begins.

### Step 5: Legacy Code Cleanup

After all modules pass validation, remove migration scaffolding in a **separate commit**:

- Delete compatibility shims and adapters
- Remove old type aliases and version-compatibility branches
- Remove `@deprecated` annotations added for this migration
- Remove feature flags introduced to gate the migration

```
─── Cleanup Checklist ───────────────────────────────
[ ] Compatibility shims removed
[ ] Old type aliases / version branches deleted
[ ] @deprecated annotations cleared
[ ] Migration feature flags removed
[ ] Tests updated to remove compatibility-mode paths
[ ] Documentation updated (README, CHANGELOG, migration guide)
─────────────────────────────────────────────────────
```

> **Why a separate commit?** Cleanup changes are low-risk and mechanical. Keeping them separate from functional migration changes makes both easier to review and easier to bisect if a regression appears later.

---

## Forbidden Actions

- Do not migrate multiple modules in a single step without validating each — this removes rollback granularity
- Do not delete the old API or shim before all consumers have been migrated and tested
- Do not make behavioral changes alongside migration changes — migration commits must be pure migrations (structure changes only, behavior preserved)

---

## Sprint State Integration

If `.sextant/state.json` exists in the project root and the current task matches a sprint task:

- **On start:** offer to update the task's `status` from `pending` → `in_progress`. Ask: *"Update sprint state to mark Task N as in_progress?"*
- **On completion** (acceptance condition met): offer to update `status` to `done`. Ask: *"Update sprint state to mark Task N as done?"*
- **On blocker** (test failure, missing dependency, unresolvable ambiguity that halts progress): surface the issue, then ask: *"Mark Task N as blocked and record the reason in flags?"* If confirmed, set `status: "blocked"` and append `{"task": N, "reason": ""}` to the top-level `flags` array. Do not proceed to the next task while a task is blocked.

Do not write the file without explicit user confirmation. If the user declines, continue without state updates.

---

## Reply Format

Migration Summary:

| # | Item | Detail |
|---|------|--------|
| [1] | Scope |  |
| [2] | Compatibility |  |
| [3] | Sequence |  |
| [4] | Current status |  (diagnosis: )> |
| [5] | Needs your input |  |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hellotern](https://github.com/hellotern)
- **Source:** [hellotern/Sextant](https://github.com/hellotern/Sextant)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hellotern-sextant-migrate
- Seller: https://agentstack.voostack.com/s/hellotern
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.