| 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.
