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