Migration from v1

If you have projects with .planning directories from the original Get Shit Done (v1), you can migrate them to GSD-2's .gsd format.

Running the Migration

# From within the project directory
/gsd migrate

# Or specify a path
/gsd migrate ~/projects/my-old-project

What Gets Migrated

The migration tool:

Parses your old PROJECT.md, ROADMAP.md, REQUIREMENTS.md, phase directories, plans, summaries, and research
Maps phases → slices, plans → tasks, milestones → milestones
Treats an explicit path as the target project root, so /gsd migrate ~/projects/my-old-project writes to ~/projects/my-old-project/.gsd
Blocks zero-slice migrations and refuses to run while active, paused, or worktree session state exists
Backs up any existing .gsd/ to .gsd-backups/migrate-YYYYMMDD-HHMMSS/, deletes the old .gsd/, and restores the backup if migration fails
Writes the imported hierarchy into the GSD database, then renders markdown projections from that database
Preserves completion state ([x] phases stay done, summaries carry over)
Consolidates research files into the new structure and archives the full legacy .planning source under .gsd/migration/legacy/
Records .gsd/migration/MIGRATION.md and .gsd/migration/manifest.json audit artifacts
Shows a preview before writing anything
Optionally runs a read-only review of the output for quality assurance

Supported Formats

The migration handles various v1 format variations:

Milestone-sectioned roadmaps with <details> blocks
Bold phase entries
Bullet-format requirements
Decimal phase numbering
Duplicate phase numbers across milestones

Requirements

Migration works best with a ROADMAP.md file for milestone structure. Without one, milestones are inferred from the phases/ directory.

Post-Migration

After migrating, verify the output with:

/gsd doctor

This checks database and projection integrity and flags any structural issues. Use /gsd inspect when you need database diagnostics.

If an existing project has markdown artifacts but a missing or damaged database, start GSD once so the database opens, then run:

/gsd recover

/gsd recover clears the persisted hierarchy plus validation-related state, including quality-gate rows and skipped-validation assessments, then reconstructs the milestone, slice, and task hierarchy from the rendered markdown on disk. It is an explicit destructive recovery/import operation; normal runtime does not silently derive state from markdown.