# dot-ai-migrate

> Migrate workspace from old dot-ai convention version to current

- Author: Jonathan Gelin
- Repository: jogelin/dot-ai
- Version: 20260207120425
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/jogelin/dot-ai
- Web: https://mule.run/skillshub/@@jogelin/dot-ai~dot-ai-migrate:20260207120425

---

---
name: dot-ai-migrate
description: Migrate workspace from old dot-ai convention version to current
triggers: [manual]
internal: true
parent: dot-ai
---

# dot-ai-migrate — Convention Version Migration

Migrates a workspace from an older version of the `.ai/` convention to the current version.

## When to Use

- After pulling updates to `dot-ai` skill with breaking changes
- When `.ai/VERSION` is outdated compared to `dot-ai` skill version
- Manual trigger: "migrate dot-ai to latest", "upgrade .ai convention"

## Version Detection

```bash
# Current workspace version
WORKSPACE_VERSION=$(cat .ai/VERSION 2>/dev/null || echo "0.0.0")

# dot-ai skill version
SKILL_VERSION=$(grep "^version:" .ai/skills/dot-ai/SKILL.md | cut -d' ' -f2)

if [[ "$WORKSPACE_VERSION" != "$SKILL_VERSION" ]]; then
  echo "Migration needed: $WORKSPACE_VERSION → $SKILL_VERSION"
fi
```

## Migration Paths

### 0.1.0 → 0.2.0

**Changes:**
1. `projects-index.md` now auto-generated by `workspace-scan`
2. New sub-skills: `project-init`, `skill-sync`, `backlog-sync`, `migrate`, `export`
3. Memory conventions clarified (no temporary vs permanent distinction)
4. Sync sub-skills pattern introduced (`*-sync` for each file type)

**Migration steps:**
```bash
# 1. Backup current projects-index.md
cp .ai/memory/projects-index.md .ai/memory/projects-index.md.backup

# 2. Run workspace-scan to regenerate with markers
# (workspace-scan will preserve manual content outside markers)

# 3. Update .ai/VERSION
echo "0.2.0" > .ai/VERSION

# 4. Run audit to validate new structure
# dot-ai-audit will use new sync sub-skills
```

### Future Migrations

Template for future version migrations:

```markdown
### X.Y.Z → X.Y+1.Z

**Breaking changes:**
- Change 1
- Change 2

**Migration steps:**
1. Step 1
2. Step 2
3. Update VERSION

**Rollback (if needed):**
1. Restore from backup
2. Revert VERSION
```

## Migration Process

### Step 1 — Backup

```bash
# Create migration backup
BACKUP_DIR=".ai/backups/migration-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Backup critical files
cp -r .ai/memory/projects-index.md "$BACKUP_DIR/"
cp .ai/VERSION "$BACKUP_DIR/"
cp -r .ai/skills/dot-ai "$BACKUP_DIR/"
```

### Step 2 — Detect Changes

```bash
# Compare old vs new convention
OLD_VERSION=$(cat .ai/VERSION)
NEW_VERSION=$(grep "^version:" .ai/skills/dot-ai/SKILL.md | cut -d' ' -f2)

# Show changelog
echo "Migrating: $OLD_VERSION → $NEW_VERSION"
# (Display relevant migration path from above)
```

### Step 3 — Apply Migration

Execute migration steps for detected version path.

### Step 4 — Validate

```bash
# Run full audit with new convention
dot-ai-audit

# Verify no critical errors
if [[ $? -eq 0 ]]; then
  echo "✅ Migration successful"
  echo "$NEW_VERSION" > .ai/VERSION
else
  echo "❌ Migration failed, check errors above"
  echo "Backup available at: $BACKUP_DIR"
fi
```

### Step 5 — Update Workspace

```bash
# Regenerate auto-managed files with new convention
dot-ai-workspace-scan
dot-ai-agent-sync --all
```

## Rollback

If migration fails:

```bash
# Restore from backup
LATEST_BACKUP=$(ls -t .ai/backups/migration-* | head -1)
cp "$LATEST_BACKUP/VERSION" .ai/VERSION
cp "$LATEST_BACKUP/projects-index.md" .ai/memory/
# etc.
```

## Safety Rules

1. **Always backup before migration**
2. **Validate after migration** (run audit)
3. **Never delete backups** (keep in `.ai/backups/`)
4. **Test in branch first** if possible
5. **Rollback if validation fails**

## Commands

| Command | Action |
|---------|--------|
| "migrate dot-ai" | Detect version and migrate |
| "migrate to version X.Y.Z" | Force migration to specific version |
| "check migration needed" | Compare versions, show if update needed |
| "rollback migration" | Restore from latest backup |

## Output

**Success:**
```
🔄 Migrating .ai/ convention: 0.1.0 → 0.2.0

Backup created: .ai/backups/migration-20260206-1430/

Applying migration steps:
  ✅ Regenerated projects-index.md with markers
  ✅ Created new sub-skills directories
  ✅ Updated VERSION to 0.2.0

Running validation...
  ✅ Audit passed

Migration complete! 🎉
```

**Failure:**
```
❌ Migration failed

Errors during migration:
  - YAML parse error in projects/pro/.ai/AGENT.md
  - Missing required field in .ai/skills/backlog/SKILL.md

Backup available at: .ai/backups/migration-20260206-1430/
Run `rollback migration` to restore.
```