/migrate-workspace

namespace: aiwg
name: migrate-workspace
platforms: [all]
description: Migrate the .aiwg/ directory from single-framework layout to the multi-framework layout with an automatic backup

Migrate Workspace

You upgrade the `.aiwg/` directory from the old single-framework layout to the new multi-framework layout, moving artifacts into framework-scoped subdirectories. A backup is always created before any changes are applied.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "upgrade my aiwg structure" → run migration
• "move to multi-framework layout" → run migration
• "preview workspace migration" → dry-run only
• "what would migrate?" → dry-run only

Trigger Patterns Reference

| Pattern | Example | Action | |---------|---------|--------| | Full migration | "migrate my workspace" | Run `aiwg migrate-workspace` | | Dry run | "preview the workspace migration" | Run `aiwg migrate-workspace --dry-run` | | Forced | "migrate workspace, skip confirmation" | Run `aiwg migrate-workspace --yes` | | Check needed | "do I need to migrate?" | Run `aiwg migrate-workspace --dry-run` |

Behavior

When triggered:

1. **Always dry-run first** unless the user explicitly confirms or passes `--yes`:

• Run `aiwg migrate-workspace --dry-run` to show what would move.
• Report the planned changes to the user.
• Ask for confirmation before proceeding.

2. **Extract arguments**:

• Is `--dry-run` requested? Report only, no changes.
• Has the user already confirmed? Use `--yes` to skip the interactive prompt.
• Is there a specific backup path? (optional)

3. **Run the appropriate command**:

   # Preview only — no changes
   aiwg migrate-workspace --dry-run

   # Full migration (prompts for confirmation)
   aiwg migrate-workspace

   # Full migration, skip prompt
   aiwg migrate-workspace --yes

4. **What the migration does**:

• Creates a timestamped backup at `.aiwg/.backup-<timestamp>/`
• Creates framework-scoped subdirectories under `.aiwg/frameworks/<name>/`
• Moves existing flat artifacts into the appropriate scoped location
• Updates `.aiwg/frameworks/registry.json`
• Leaves a `MIGRATION.md` log at `.aiwg/` root

5. **Safety guarantee**: The backup is created before any file is moved. If migration fails partway through, `aiwg rollback-workspace` can restore from the backup.

6. **Report the result** — show what was moved, backup location, and how to rollback if needed.

Examples

Example 1: Dry run first (default approach)

**User**: "Migrate my workspace"

**Extraction**: Migration requested — dry-run before applying

**Action** (step 1):

aiwg migrate-workspace --dry-run

**Response**:

Workspace Migration Preview
━━━━━━━━━━━━━━━━━━━━━━━━━━━
Would move:
  .aiwg/requirements/ → .aiwg/frameworks/sdlc-complete/requirements/
  .aiwg/architecture/ → .aiwg/frameworks/sdlc-complete/architecture/
  .aiwg/testing/      → .aiwg/frameworks/sdlc-complete/testing/
  (+ 5 more directories)

Would create backup: .aiwg/.backup-20260401-1423/
No files would be deleted.

Proceed with migration? [y/N]

After user confirms → run `aiwg migrate-workspace --yes`.

Example 2: Dry run only

**User**: "What would the workspace migration do?"

**Extraction**: Preview-only, no confirmation needed

**Action**:

aiwg migrate-workspace --dry-run

**Response**: Shows the planned moves table (as above) and stops. Does not prompt for confirmation.

Example 3: Already on new layout

**User**: "Do I need to migrate my workspace?"

**Extraction**: Check whether migration is needed

**Action**:

aiwg migrate-workspace --dry-run

**Response**: "Your workspace is already on the multi-framework layout. No migration needed."

Example 4: Migration with confirmation

**User**: "Go ahead and migrate the workspace"

**Extraction**: User has already seen dry-run output and is confirming

**Action**:

aiwg migrate-workspace --yes

**Response**:

Backup created: .aiwg/.backup-20260401-1423/
Migrating 8 directories...
  requirements/  moved
  architecture/  moved
  testing/       moved
  (+ 5 more)
registry.json updated.
Migration complete. To undo: aiwg rollback-workspace

Clarification Prompts

If the user's intent is ambiguous:

• "Would you like me to preview the migration first, or go ahead and apply it?"
• "Have you already reviewed the dry-run output, or should I run it first?"

References

• @$AIWG_ROOT/src/cli/handlers/workspace.ts — `migrate-workspace` command handler
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/rollback-workspace/SKILL.md — Undoing a migration