Aiwg migrate-workspace

Migrate the .aiwg/ directory from single-framework layout to the multi-framework layout with an automatic backup

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/migrate-workspace" ~/.claude/skills/jmagly-aiwg-migrate-workspace && rm -rf "$T"

manifest: .agents/skills/migrate-workspace/SKILL.md

source content

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:

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

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

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
Safety guarantee: The backup is created before any file is moved. If migration fails partway through,
```
aiwg rollback-workspace
```
can restore from the backup.
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