Migrate Workspace

---
name: migrate-workspace
description: >
  Adopt a v2.x ai-sdlc-harness workspace into v3.0 — config carries over,
  run history stays archived in place. USER-ENTRY and HUMAN-ONLY — invoke
  only when the user explicitly runs /migrate-workspace; never autonomously,
  never from a subagent (guard-enforced).
---

# migrate-workspace — adopt a v2.x workspace

**The fork seam:** this file and `harness/migrate.py` are the replaceable
unit — forks ship different adoption logic by swapping them and nothing
else. Everything that WRITES goes through the same owned path as
`/init-workspace` (`init-section` → `init-verify` → `init-finalize`);
migrate verbs are read-only proposals.

Human-only, same invocation rules as every skill here: always the full
`${CLAUDE_PLUGIN_ROOT}/bin/harness <verb>` path. First run
`/init-workspace`'s **step 0 environment bootstrap** exactly as written
there (that file owns the procedure — don't re-derive it).

## 1 · Detect (stop conditions first)

```
${CLAUDE_PLUGIN_ROOT}/bin/harness migrate-detect
```

- Surface `warnings` verbatim whenever present — e.g. an unreadable
  `overrides.yaml` reports as bootstrapped *fail-closed*, and the
  remediation lives in the warning, not here.
- `already_bootstrapped: true` → this workspace already runs v3.0. If
  `inventory.legacy_context_files` is non-empty, a prior migration stopped
  before archiving — offer the **archive-only finish** (steps 5–6; the
  report on this path records `inventory` only, since `migrate-extract`
  rightly refuses post-bootstrap — the carried-config record lives in the
  earlier attempt's confirmations); otherwise **stop** and point the user
  at `/workspace-config`.
- `legacy: null` → **stop**: nothing to adopt; point at `/init-workspace`.
- Otherwise show the `evidence` list (why this looks like v2.x), then the
  `inventory`:
  - **`in_flight` runs get a hard boundary, stated plainly:** run history
    is never converted — v3.0 state is sealed evidence (red-proofs,
    ledgers) that v2.x never produced, so migrating a half-done run would
    fabricate its audit trail. **Recommend finishing or abandoning those
    stories on v2.x before migrating**: step 5 archives the very config
    files v2.x resumes from, so proceeding now means a later v2.x session
    must first hand-restore them from `legacy-2.1/`. Proceeding anyway is
    the user's call — record the choice in the step-5 report.
  - Old `ai/` run dirs and `aborted` leftovers stay exactly where they are
    as readable archives; v3.0 run discovery ignores them.

## 2 · Extract & confirm (propose-only)

```
${CLAUDE_PLUGIN_ROOT}/bin/harness migrate-extract
```

Present the proposal per section — `provider`, `repos`, `language` — next
to every `notes` entry (missing repo paths, unverifiable stories_dir) and
the `unmapped` list (what v2.x config has no v3.0 home, and why). The user
confirms or corrects **each section**; anything extract could not fill
falls through to the matching `/init-workspace` interview question — never
guess a value extraction didn't find.

**Re-entry:** if a target section file already exists under
`.claude/context/` (a prior attempt got that far), read it and present its
current value next to the legacy-derived proposal — never silently
re-propose stale legacy data over a correction the user already confirmed.

`optional_overrides.naming` is **opt-in, default NO**: translated v2.1
naming templates are usually the v2.1 defaults the user never chose, and
v3.0's `{type}/{id}-{slug}` handles change-types better than a frozen
`feature/` prefix. Offer it only as "did you deliberately customize
naming in v2.x?".

## 3 · Apply through the owned init path

Write each confirmed section with `init-section` exactly as
`/init-workspace` step 1 documents (self-nested payloads; `overrides`
flat). Then fill the gaps the same way that interview does:

- No `language` proposal for a repo → `discover --repo <path>` and confirm
  (its dirty-repo/default-branch cautions live in `/init-workspace` step 2).
  **`discover` switches a clean repo back to its default branch** — if
  `inventory.in_flight` names a story whose v2.x feature branch may be
  checked out in that repo, say so and get explicit confirmation first.
- MCP-transport providers (`jira`, `zoho`, `ado-mcp`) → the
  model-in-the-loop MCP checklist from the interview applies unchanged.

## 4 · Verify + finalize (the same real gate)

`/init-workspace` step 4, verbatim: `init-verify` must pass (fix failures,
re-run), then `init-finalize`. A migrated workspace ends in exactly the
state a freshly-interviewed one does — there is no "migrated" flavor to
special-case later.

## 5 · Archive the legacy config

List the v2.x context files (`inventory.legacy_context_files`), confirm
with the user, then move them aside so nobody mistakes them for live
config:

```
mkdir -p .claude/context/legacy-2.1 && mv .claude/context/*.md .claude/context/legacy-2.1/
```

Write `.claude/context/legacy-2.1/migration-report.md`: what carried over
(per section), the full `unmapped` and `notes` lists, and any in-flight
v2.x stories with the finish-on-v2.x guidance. The old `ai/` dirs are the
run archive; this report is the config-decision record.

## 6 · Hand over

- `local-markdown` users: existing story files work in place — v2.1
  `> Status:` blockquotes are read tolerantly and upgrade to the v3.0
  `Status:` form on first write-back.
- Remote-provider users: work items live server-side; nothing moved.
- Offer repo-map generation (`/repo-map-refresh` owns the procedure),
  then: `/dev-workflow <work-item-id>` is ready.