migrate-workspace

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.