agentleFS
MostAshrafMostAshraf/ai-sdlc-harness/skills/migrate-workspace/SKILL.md

migrate-workspace

Skill20 starsChanged 3 months agoMITView on GitHub

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

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. tymrtn/tomorrowkit-for-minds★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    in_flight runs get a hard boundary, stated plainly: run history is never converted — v3.0 state is sealed evidence (red-proofs, ledgers) …

    line 42
  2. Very specific:

    Re-entry: if a target section file already exists under .claude/context/ (a prior attempt got that far), read it and present its current …

    line 66
  3. Very specific:

    Write each confirmed section with init-section exactly as /init-workspace step 1 documents (self-nested payloads.

    line 79
  4. Very specific:

    Write .claude/context/legacy-2.1/migration-report.md: what carried over (per section), the full unmapped and notes lists, and any in-flight …

    line 108

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.