---
name: step-02-create
description: Create migration with MCP naming
next_step: step-03-validate.md
---

# Step 2: Create Migration

## YOUR TASK:

Get migration description from user, call MCP for compliant name, and create migration.

**MANDATORY:** Use MCP `suggest_migration` for naming. NEVER hardcode.

**Previous step:** `step-01-check.md`

---

## EXECUTION SEQUENCE:

### 1. Get Description from User

**If NOT force mode with predefined description:**

```yaml
AskUserQuestion:
  header: "Description"
  question: "Short description for the migration (e.g., 'Add User Roles'):"
  options:
    - label: "Add..."
      description: "Adding tables/columns"
    - label: "Update..."
      description: "Modifying structure"
    - label: "Fix..."
      description: "Schema correction"
    - label: "Remove..."
      description: "Deleting elements"
  multiSelect: false
```

**User can also provide free text (Other option).**

```bash
# DESCRIPTION = user response or predefined value
# Examples: "Add User Roles", "Update Tenant Schema", "Fix Foreign Keys"

echo ""
echo "Description: $DESCRIPTION"
```

### 2. Verify MCP Availability

```bash
# Check MCP cache before calling suggest_migration
MCP_STATUS_FILE=".claude/mcp-status.json"

if [ -f "$MCP_STATUS_FILE" ]; then
  MCP_STATUS=$(cat "$MCP_STATUS_FILE" | grep -o '"status":"[^"]*"' | head -1 | cut -d'"' -f4)
  if [ "$MCP_STATUS" = "error" ]; then
    echo "ERROR: MCP server is unavailable (status: error)"
    echo "Run: /mcp healthcheck to diagnose"
    exit 1
  fi
fi
```

### 3. Call MCP for Migration Name (MANDATORY)

```javascript
// DESCRIPTION = from user input (e.g., "Add User Roles")
// DBCONTEXT_TYPE = "core" or "extensions" (from detect_dbcontext)

const result = await mcp__smartstack__suggest_migration({
  description: DESCRIPTION,
  context: DBCONTEXT_TYPE    // NEVER hardcode!
});

// Result example: core_v1.8.0_001_AddUserRoles
MIGRATION_NAME = result.migrationName;
```

**FORBIDDEN:**
- Calculating name manually
- Hardcoding context as "core"
- Using wrong version format

### 4. Display Migration Name

```bash
echo ""
echo "Migration name: $MIGRATION_NAME"
echo "Context: $DBCONTEXT"
echo ""
```

### 5. Create Migration

```bash
echo "Creating migration..."
echo ""

dotnet ef migrations add "$MIGRATION_NAME" \
  --context "$DBCONTEXT" \
  --project "$INFRA_PROJECT" \
  --startup-project "$STARTUP_PROJECT" \
  -o Persistence/Migrations \
  --verbose
```

### 6. Cleanup EF Core Design-Time Artifacts

```bash
# EF Core's Roslyn BuildHost creates corrupted bin folders on Windows (U+F05C instead of backslash)
# Clean up any bin*Debug folders that are NOT the normal bin/Debug path
for d in src/*/bin?Debug; do
  if [ -d "$d" ]; then
    echo "Removing corrupted EF Core artifact: $d"
    rm -rf "$d"
  fi
done
```

### 7. Verify Creation

```bash
# Check files were created
MIGRATION_FILE="$MIGRATIONS_DIR/${MIGRATION_NAME}.cs"
DESIGNER_FILE="$MIGRATIONS_DIR/${MIGRATION_NAME}.Designer.cs"

if [ ! -f "$MIGRATION_FILE" ]; then
  echo ""
  echo "ERROR: Migration file not created"
  echo "Expected: $MIGRATION_FILE"
  exit 1
fi

echo ""
echo "Migration created:"
echo "  $MIGRATION_FILE"
echo "  $DESIGNER_FILE"
```

---

## STATE OUTPUT:

| Variable | Description |
|----------|-------------|
| `{description}` | User-provided description |
| `{migration_name}` | Name from MCP |
| `{migration_file}` | Path to .cs file |

---

## ERROR HANDLING:

| Error | Resolution |
|-------|------------|
| MCP unavailable | Check connection, retry |
| Creation fails | Check dotnet ef output |
| File not created | Verify paths and permissions |

---

## SUCCESS CRITERIA:

- Description captured
- MCP called successfully
- Migration files created

## NEXT STEP:

→ `step-03-validate.md`
