fix: migrate specs/ to .documentation/specs/ and defer migration until after template install

- Migration script now moves specs/ -> .documentation/specs/ (root and .specify/specs/)
- Migration step in upgrade() deferred until after init() installs templates, so
  migration scripts are available when needed
- needs_migration() now detects root-level specs/ as requiring migration
- Fix Next Steps text: ls specs/ -> ls .documentation/specs/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: markhazleton

.documentation/scripts/migrate-to-documentation.ps1

@@ -191,10 +191,16 @@ if ((Test-Path "templates") -and -not (Test-Path ".documentation\templates")) {
     $oldStructuresFound = $true
 }
 
+if ((Test-Path "specs") -and -not (Test-Path ".documentation\specs")) {
+    Print-Status "Found specs/ directory"
+    $structuresToMigrate += "specs"
+    $oldStructuresFound = $true
+}
+
 if (-not $oldStructuresFound) {
     Write-Host ""
     Print-Error "No old structure found to migrate."
-    Write-Host "Looking for: .specify/, memory/, scripts/, or templates/"
+    Write-Host "Looking for: .specify/, memory/, scripts/, templates/, or specs/"
     Write-Host ""
     exit 0
 }
@@ -219,7 +225,7 @@ foreach ($struct in $structuresToMigrate) {
 }
 Write-Host "  5. Update .gitignore if needed"
 Write-Host ""
-Write-ColorOutput "Your specs/ directory will NOT be touched - it's completely safe!" "Green"
+Write-ColorOutput "Your specs/ directory will be moved to .documentation/specs/" "Green"
 Write-Host ""
 
 if (-not $DryRun) {
@@ -247,6 +253,9 @@ if ($DryRun) {
 
     New-Item -ItemType Directory -Path ".documentation\templates" -Force | Out-Null
     Print-Status "Created .documentation\templates\"
+
+    New-Item -ItemType Directory -Path ".documentation\specs" -Force | Out-Null
+    Print-Status "Created .documentation\specs\"
 }
 
 Write-Host ""
@@ -341,6 +350,20 @@ if (Test-Path ".specify") {
             Print-Status "Copied .specify\templates\ to .documentation\templates\"
         }
 
+        if (Test-Path ".specify\specs") {
+            Get-ChildItem ".specify\specs" -Recurse | ForEach-Object {
+                $target = $_.FullName.Replace(".specify\specs", ".documentation\specs")
+                if ($_.PSIsContainer -eq $false) {
+                    $targetDir = Split-Path $target -Parent
+                    if (-not (Test-Path $targetDir)) {
+                        New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+                    }
+                    Copy-Item $_.FullName -Destination $target -Force
+                }
+            }
+            Print-Status "Copied .specify\specs\ to .documentation\specs\"
+        }
+
         # Copy any other files in .specify root
         Get-ChildItem ".specify" -File | ForEach-Object {
             Copy-Item $_.FullName -Destination ".documentation\" -Force
@@ -357,6 +380,7 @@ if (Test-Path ".specify") {
 Copy-Directory "memory" ".documentation\memory" "memory\"
 Copy-Directory "scripts" ".documentation\scripts" "scripts\"
 Copy-Directory "templates" ".documentation\templates" "templates\"
+Copy-Directory "specs" ".documentation\specs" "specs\"
 
 Write-Host ""
 Write-ColorOutput "Step 3: Updating path references in files" "Blue"

.documentation/scripts/migrate-to-documentation.sh

@@ -199,10 +199,16 @@ if [ -d "templates" ] && [ ! -d ".documentation/templates" ]; then
     OLD_STRUCTURES_FOUND=true
 fi
 
+if [ -d "specs" ] && [ ! -d ".documentation/specs" ]; then
+    print_status "Found specs/ directory"
+    STRUCTURES_TO_MIGRATE+=("specs")
+    OLD_STRUCTURES_FOUND=true
+fi
+
 if [ "$OLD_STRUCTURES_FOUND" = false ]; then
     echo ""
     print_error "No old structure found to migrate."
-    echo "Looking for: .specify/, memory/, scripts/, or templates/"
+    echo "Looking for: .specify/, memory/, scripts/, templates/, or specs/"
     echo ""
     exit 0
 fi
@@ -227,7 +233,7 @@ for struct in "${STRUCTURES_TO_MIGRATE[@]}"; do
 done
 echo "  5. Update .gitignore if needed"
 echo ""
-echo -e "${GREEN}Your specs/ directory will NOT be touched - it's completely safe!${NC}"
+echo -e "${GREEN}Your specs/ directory will be moved to .documentation/specs/${NC}"
 echo ""
 
 if [ "$DRY_RUN" = false ]; then
@@ -307,6 +313,11 @@ if [ -d ".specify" ]; then
             cp -r .specify/templates/* .documentation/templates/ 2>/dev/null || true
             print_status "Copied .specify/templates/ to .documentation/templates/"
         fi
+        if [ -d ".specify/specs" ]; then
+            mkdir -p .documentation/specs
+            cp -r .specify/specs/* .documentation/specs/ 2>/dev/null || true
+            print_status "Copied .specify/specs/ to .documentation/specs/"
+        fi
         # Copy any other files in .specify root
         find .specify -maxdepth 1 -type f -exec cp {} .documentation/ \; 2>/dev/null || true
         print_status "Copied .specify/ root files to .documentation/"
@@ -321,6 +332,7 @@ fi
 copy_dir "memory" ".documentation/memory" "memory/"
 copy_dir "scripts" ".documentation/scripts" "scripts/"
 copy_dir "templates" ".documentation/templates" "templates/"
+copy_dir "specs" ".documentation/specs" "specs/"
 
 echo ""
 echo -e "${BLUE}Step 3: Updating path references in files${NC}"

src/specify_cli/__init__.py

@@ -1309,6 +1309,7 @@ def needs_migration() -> bool:
         Path("memory") if not Path(".documentation/memory").exists() else None,
         Path("scripts") if not Path(".documentation/scripts").exists() else None,
         Path("templates") if not Path(".documentation/templates").exists() else None,
+        Path("specs") if not Path(".documentation/specs").exists() else None,
     ]
     # Filter out None values
     old_paths = [p for p in old_paths if p is not None]
@@ -1527,29 +1528,24 @@ def upgrade(
         agent_name = AGENT_CONFIG[ai_assistant]["name"]
         console.print(f"[green]✓[/green] Using AI assistant: [cyan]{agent_name}[/cyan] ({ai_assistant})\n")
 
-    # Step 4: Check for old structure migration
+    # Step 4: Check for old structure migration (deferred — runs after templates are installed)
+    migration_needed = False
+    migration_confirmed = False
     if not skip_migration:
         console.print("[cyan]→[/cyan] Checking for old structure...")
         if needs_migration():
+            migration_needed = True
             console.print("[yellow]⚠[/yellow] Old structure detected (.specify/, memory/, scripts/, or templates/)")
-            console.print("[dim]Migration to .documentation/ structure is recommended[/dim]")
+            console.print("[dim]Migration to .documentation/ structure will run after templates are installed[/dim]")
 
             if dry_run:
-                console.print("[cyan]Would run migration script in actual upgrade[/cyan]\n")
+                console.print("[cyan]Would run migration after templates are installed[/cyan]\n")
+            elif force:
+                console.print("[cyan]Migration will run automatically after templates are installed (--force)...[/cyan]\n")
+                migration_confirmed = True
             else:
-                if force:
-                    console.print("[cyan]Running migration automatically (--force specified)...[/cyan]")
-                    run_migration = True
-                else:
-                    run_migration = typer.confirm("Run migration now?", default=True)
-
-                if run_migration:
-                    success = run_migration_script()
-                    if success:
-                        console.print("[green]✓[/green] Migration completed\n")
-                    else:
-                        console.print("[yellow]⚠[/yellow] Migration had issues, but continuing...\n")
-                else:
+                migration_confirmed = typer.confirm("Run migration after templates are installed?", default=True)
+                if not migration_confirmed:
                     console.print("[yellow]Skipping migration - you can run it later[/yellow]")
                     console.print("[dim]See .documentation/migration-guide.md for manual steps[/dim]\n")
         else:
@@ -1606,6 +1602,15 @@ def upgrade(
         console.print(f"\n[red]✗ Upgrade failed:[/red] {e}")
         raise typer.Exit(1)
 
+    # Step 7.5: Run migration now that templates (including migration scripts) are installed
+    if migration_needed and migration_confirmed:
+        console.print("[cyan]→[/cyan] Running migration to .documentation/ structure...")
+        success = run_migration_script()
+        if success:
+            console.print("[green]✓[/green] Migration completed\n")
+        else:
+            console.print("[yellow]⚠[/yellow] Migration had issues. See .documentation/migration-guide.md for manual steps.\n")
+
     # Step 8: Post-upgrade guidance
     console.print("\n" + "="*60)
     console.print("[bold green]✓ Upgrade Complete![/bold green]")
@@ -1620,7 +1625,7 @@ def upgrade(
     console.print("[bold]Next steps:[/bold]")
     console.print("  1. Review changes: [cyan]git status[/cyan] and [cyan]git diff[/cyan]")
     console.print("  2. Test slash commands in your AI assistant (e.g., [cyan]/speckit.constitution[/cyan])")
-    console.print("  3. Verify your specs are intact: [cyan]ls specs/[/cyan]")
+    console.print("  3. Verify your specs are intact: [cyan]ls .documentation/specs/[/cyan]")
     console.print("  4. If everything looks good, commit:")
     console.print("     [cyan]git add -A[/cyan]")
     console.print("     [cyan]git commit -m 'chore: upgrade to latest spec-kit version'[/cyan]")