---
name: compatibility-layer-generator
description: |
  Use this skill when the user needs glue code between legacy and new
  systems during migration. Triggers on: "generate adapter", "create
  shim", "build proxy", "bridge old to new", "translate between [legacy
  format] and [new format]", "wrap the legacy [API/service/database]".

  Generates: API adapters, format translators, auth shims, data
  reconciliation jobs, request proxies.

  Do NOT use for: greenfield code (use spec-driven-builder), simple format
  conversion in one direction (just a function), or end-state architecture
  (this is for the migration period only).
---

# Compatibility Layer Generator

You generate compatibility code that bridges legacy and new systems during
migration. Your code is explicit about being temporary — the migration
should kill it. You always include a clear path to deprecating the
compatibility layer.

## Categories of compatibility code

### Category 1: API adapters

The new system needs to call the legacy API (or vice versa). The adapter
translates request/response formats and hides the legacy from the new
codebase.

**When new calls legacy:**
- New system needs data the new DB doesn't have yet
- New system invokes a legacy operation (e.g., legacy still owns auth)
- New system reads from a legacy reporting table

**When legacy calls new:**
- Legacy needs a new capability that's been migrated
- Legacy delegates a function to new (incrementally moving ownership)

### Category 2: Format translators

Pure transformation code. Old format → new format, or vice versa.

Examples:
- SOAP envelope → REST JSON body
- Legacy DateTime format → ISO 8601
- Legacy error codes → new HTTP status + error envelope
- Legacy XML → JSON Schema-validated DTO

### Category 3: Authentication shims

The hardest. Make legacy auth tickets work with new system, or vice versa.

Examples:
- Legacy Forms Auth ticket → JWT
- Legacy session cookie → modern session
- AD group membership → JWT claims

### Category 4: Data reconciliation jobs

Background jobs that keep two systems in sync during migration.

Examples:
- Dual-write reconciliation (catches drift between two DBs)
- CDC consumer (legacy DB → new DB stream)
- Periodic full diff and repair

### Category 5: Request proxies

Routing layer that decides whether a request goes to new or legacy.

Examples:
- Path-based: `/api/v2/*` → new, `/api/*` → legacy
- Header-based: requests with `X-Use-New: true` → new
- Feature flag: per-user routing

## Process when activated

### Step 1: Identify category

Match the user's request to one of the 5 categories above. If unclear, ask:

> "I can build:
> 1. API adapter (new calls legacy or vice versa)
> 2. Format translator (XML → JSON, etc.)
> 3. Auth shim (legacy ticket ↔ JWT)
> 4. Data reconciliation job (sync between DBs)
> 5. Request proxy (route between old and new)
>
> Which fits your need?"

### Step 2: Get specifics

For each category, ask for the specifics needed:

**API adapter:**
- Legacy API: URL, auth method, request/response format
- New code consuming it: language/framework
- Operations needed (subset of legacy or all)

**Format translator:**
- Source format with example
- Target format with example
- Tolerance for missing fields, default values

**Auth shim:**
- Legacy auth: format, signing method, claims
- New auth: format, expected claims
- Bidirectional or one-way

**Data reconciliation:**
- Source DB connection
- Target DB connection
- Tables in scope
- Schedule (real-time, batch, periodic)
- What to do on conflict (source wins / target wins / alert)

**Request proxy:**
- Routing rule
- Source URL pattern
- Old destination
- New destination
- Auth handling (forward token, replace, strip)

### Step 3: Generate the code

Generate complete, idiomatic code in the target language/framework:

#### API adapter (C# / .NET example)

```csharp
// Adapters/Legacy/LegacyCustomerAdapter.cs
public interface ILegacyCustomerAdapter
{
    Task<Customer?> GetCustomerAsync(Guid id, CancellationToken ct);
    Task<IReadOnlyList<Customer>> SearchAsync(CustomerSearchCriteria criteria, CancellationToken ct);
}

public class LegacyCustomerAdapter : ILegacyCustomerAdapter
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<LegacyCustomerAdapter> _logger;

    public LegacyCustomerAdapter(HttpClient httpClient, ILogger<LegacyCustomerAdapter> logger)
    {
        _httpClient = httpClient;
        _logger = logger;
    }

    public async Task<Customer?> GetCustomerAsync(Guid id, CancellationToken ct)
    {
        // Legacy uses int IDs, not GUIDs - this conversion is part of the adapter
        var legacyId = await _idTranslator.GetLegacyIdAsync(id, ct);
        if (legacyId == null) return null;

        var response = await _httpClient.GetAsync(
            $"/api/customer.ashx?action=get&id={legacyId}",
            ct);

        if (response.StatusCode == HttpStatusCode.NotFound) return null;
        response.EnsureSuccessStatusCode();

        var legacy = await response.Content.ReadFromJsonAsync<LegacyCustomerDto>(ct);

        // Translation happens here, in the adapter
        return new Customer
        {
            Id = id,
            Name = legacy.CustName.Trim(),  // Legacy stores trailing whitespace
            Email = legacy.EmailAddr.ToLowerInvariant(),  // Legacy is case-sensitive
            CreatedAt = ParseLegacyDateTime(legacy.CreatedDt),  // "MM/dd/yyyy HH:mm" format
            // Legacy uses 0/1 for active flag
            IsActive = legacy.ActiveFlag == 1
        };
    }
}

// Critical: every adapter has a "deprecation marker"
// When new system has its own customer data, this adapter goes away.
// Tracking how to know:
//
// DEPRECATION CRITERIA:
// - When the customers table in the new DB has all customers from legacy
// - When no callers reference ILegacyCustomerAdapter for >7 days
// - Then: delete this file, the registration in DI, and the legacy HTTP client config

// Adapters/Translators/LegacyOrderTranslator.cs
public static class LegacyOrderTranslator
{
    public static Order FromLegacyXml(XDocument legacyXml)
    {
        var root = legacyXml.Root!;

        return new Order
        {
            Id = Guid.Parse(root.Element("OrderGuid")!.Value),
            // Legacy stores money as string with "$" prefix - clean it
            Amount = decimal.Parse(
                root.Element("Total")!.Value
                    .Replace("$", "")
                    .Replace(",", ""),
                CultureInfo.InvariantCulture),
            // Legacy date format: 6/4/2024 - parse as US format
            OrderedAt = DateTimeOffset.ParseExact(
                root.Element("OrderDate")!.Value,
                "M/d/yyyy",
                CultureInfo.InvariantCulture),
            Status = MapLegacyStatus(root.Element("Status")!.Value),
            Items = root.Elements("Item")
                .Select(MapLegacyItem)
                .ToList()
        };
    }

    private static OrderStatus MapLegacyStatus(string legacy) => legacy switch
    {
        "P" => OrderStatus.Pending,
        "S" => OrderStatus.Shipped,
        "C" => OrderStatus.Cancelled,
        "X" => OrderStatus.Refunded,  // Legacy uses X for refunded
        _ => throw new InvalidOperationException($"Unknown legacy status: {legacy}")
    };
}

// Adapters/Auth/LegacyTicketToJwtShim.cs
public class LegacyTicketToJwtShim
{
    private readonly byte[] _legacyMachineKey;
    private readonly IJwtTokenIssuer _jwtIssuer;

    // Validates a legacy Forms Auth ticket and issues a modern JWT
    public string? ConvertLegacyTicket(string formsAuthTicket)
    {
        try
        {
            // Decrypt + verify using legacy machineKey
            var ticket = FormsAuthentication.Decrypt(formsAuthTicket);
            if (ticket == null || ticket.Expired) return null;

            // Extract user info from legacy ticket
            var legacyClaims = JsonConvert.DeserializeObject<LegacyUserData>(ticket.UserData);

            // Issue modern JWT with mapped claims
            return _jwtIssuer.Issue(new ClaimsPrincipal(new ClaimsIdentity(new[]
            {
                new Claim(ClaimTypes.NameIdentifier, legacyClaims.UserId),
                new Claim(ClaimTypes.Email, legacyClaims.Email),
                new Claim(ClaimTypes.Role, string.Join(",", legacyClaims.Roles))
            })));
        }
        catch
        {
            // Don't leak details about why ticket failed
            return null;
        }
    }
}

// ============================================================================
// COMPATIBILITY LAYER - TEMPORARY CODE
// ============================================================================
// This code exists to bridge legacy and new systems during migration.
//
// DEPRECATION CRITERIA:
// - [Specific condition 1]
// - [Specific condition 2]
//
// REMOVAL CHECKLIST when criteria met:
// 1. Verify zero callers (search for [type name])
// 2. Remove DI registration in [file]
// 3. Delete this file
// 4. Remove tests for this adapter
// 5. Remove [legacy HTTP client config / connection string / etc.]
//
// Owner: [team]
// Created: [date]
// Last reviewed: [date - update when revisited]
// ============================================================================

// Program.cs / Startup.cs
services.AddHttpClient<ILegacyCustomerAdapter, LegacyCustomerAdapter>(client =>
{
    client.BaseAddress = new Uri(configuration["Legacy:CustomerApi"]!);
    client.DefaultRequestHeaders.Add("X-Internal-Token",
        configuration["Legacy:InternalToken"]);
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddPolicyHandler(GetRetryPolicy())   // Polly retry
.AddPolicyHandler(GetCircuitBreakerPolicy());

## Pairing with other skills

- **Migration Planner Skill** identifies what compatibility code is needed
- **Coexistence Architecture ADR** template documents which adapters exist
- **Test Generator Skill** can extend test coverage on adapters

## Tips

- Compatibility code is meant to die. Mark it visibly so it's removed when no longer needed.
- Resist the temptation to "improve" the legacy system through the adapter. Translate, don't improve.
- Add observability heavily — you'll thank yourself when debugging.
- Treat adapters as a separate package / project / namespace so they're clearly demarcated from new code.

## Limitations

- Best for .NET (where the patterns are encoded). For other stacks, the patterns generalize but the syntax differs.
- Cannot infer legacy quirks from descriptions — needs concrete examples or access to legacy responses.
- For very complex legacy logic embedded in stored procedures, the Stored Procedure to Service template is more appropriate.
- Real-time bidirectional sync (CDC, dual-write) is complex enough to warrant dedicated tooling — this skill scaffolds, but expect to extend.