docs/migration-guide.md
Task Master v0.16.0 introduces a new .taskmaster/ directory structure to keep your project directories clean and organized. This guide explains the benefits of the new structure and how to migrate existing projects.
your-project/
├── tasks/ # Task files
│ ├── tasks.json
│ ├── task-1.txt
│ └── task-2.txt
├── scripts/ # PRD and reports
│ ├── prd.txt
│ ├── example_prd.txt
│ └── task-complexity-report.json
├── .taskmasterconfig # Configuration
└── ... (your project files)
your-project/
├── .taskmaster/ # Consolidated Task Master files
│ ├── config.json # Configuration (was .taskmasterconfig)
│ ├── tasks/ # Task files
│ │ ├── tasks.json
│ │ ├── task-1.txt
│ │ └── task-2.txt
│ ├── docs/ # Project documentation
│ │ └── prd.txt
│ ├── reports/ # Generated reports
│ │ └── task-complexity-report.json
│ └── templates/ # Example/template files
│ └── example_prd.txt
└── ... (your project files)
✅ Cleaner Project Root: No more scattered Task Master files
✅ Better Organization: Logical separation of tasks, docs, reports, and templates
✅ Hidden by Default: .taskmaster/ directory is hidden from most file browsers
✅ Future-Proof: Centralized location for Task Master extensions
✅ Backward Compatible: Existing projects continue to work until migrated
Task Master provides a built-in migration command that handles everything automatically:
# Dry run to see what would be migrated
task-master migrate --dry-run
# Perform the migration with backup
task-master migrate --backup
# Force migration (overwrites existing files)
task-master migrate --force
# Clean up legacy files after migration
task-master migrate --cleanup
Ask your AI assistant:
Please migrate my Task Master project to the new .taskmaster directory structure
If you prefer to migrate manually:
Create the new directory structure:
mkdir -p .taskmaster/{tasks,docs,reports,templates}
Move your files:
# Move tasks
mv tasks/* .taskmaster/tasks/
# Move configuration
mv .taskmasterconfig .taskmaster/config.json
# Move PRD and documentation
mv scripts/prd.txt .taskmaster/docs/
mv scripts/example_prd.txt .taskmaster/templates/
# Move reports (if they exist)
mv scripts/task-complexity-report.json .taskmaster/reports/ 2>/dev/null || true
Clean up empty directories:
rmdir tasks scripts 2>/dev/null || true
The migration process handles these file types:
.taskmaster/tasks/tasks.json.txt).taskmaster/docs/
prd.txt, requirements.txt, etc..taskmaster/templates/
example_prd.txt, template files.taskmaster/reports/
task-complexity-report.json.taskmasterconfig → .taskmaster/config.jsonOnce migrated, Task Master will:
✅ Automatically use the new directory structure
✅ Show deprecation warnings when legacy files are detected
✅ Create new files in the proper locations
✅ Fall back gracefully to legacy locations if new ones don't exist
After migration, verify everything works:
List your tasks:
task-master list
Check your configuration:
task-master models
Generate new task files:
task-master generate
Q: Migration says "no files to migrate"
A: Your project may already be using the new structure or have no Task Master files to migrate.
Q: Migration fails with permission errors
A: Ensure you have write permissions in your project directory.
Q: Some files weren't migrated
A: Check the migration output - some files may not match the expected patterns. You can migrate these manually.
If you're working with an older project that hasn't been migrated:
New projects automatically use the new structure:
task-master init # Creates .taskmaster/ structure
If you're developing tools or scripts that interact with Task Master files:
.taskmasterconfig.taskmaster/config.jsontasks/tasks.json.taskmaster/tasks/tasks.jsonscripts/task-complexity-report.json.taskmaster/reports/task-complexity-report.jsonscripts/prd.txt.taskmaster/docs/prd.txtIf you encounter issues during migration:
--debug flag for detailed output--backup option for safety--dry-run to preview changesThis migration guide applies to Task Master v0.15.x and later. For older versions, please upgrade to the latest version first.