home / skills / williamzujkowski / standards / legacy-bridge

legacy-bridge skill

safe

This skill translates legacy @load patterns to the new Skills format, enabling zero-break migration during the six month transition.

npx playbooks add skill williamzujkowski/standards --skill legacy-bridge

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

4.0 KB

---
name: legacy-bridge
description: Backward compatibility bridge that translates legacy @load patterns to new Skills format. Enables seamless migration with zero breaking changes during 6-month transition period.
---

# Legacy Bridge

> **Quick Navigation:**
> Level 1: [Quick Start](#level-1-quick-start) (5 min) → Level 2: [Implementation](#level-2-implementation) (30 min) → Level 3: [Mastery](#level-3-mastery-resources) (Extended)

---

## Level 1: Quick Start

### Overview

The legacy-bridge skill provides backward compatibility for existing `@load` patterns used in CLAUDE.md and the product-matrix system. This bridge enables a zero-breaking-change migration path from the legacy standards loader to the new Skills-based architecture.

**Migration Timeline**: 6-month transition period (deprecation warnings only, no breaking changes)

### When to Use

Use this skill when:

- You have existing code using `@load product:*` patterns
- You need to maintain backward compatibility during migration
- You want to gradually transition to the new Skills format

### Quick Reference

| Legacy Pattern | New Skill Loading |
|----------------|-------------------|
| `@load product:api` | `skill-loader.py load product:api` |
| `@load CS:python` | `skills/coding-standards/python` |
| `@load SEC:*` | `skills/security/*` + NIST baseline |

---

## Level 2: Implementation

### Pattern Translation

The legacy-bridge automatically translates old `@load` patterns to new skill loads:

#### Product Type Patterns

```bash
# Old Pattern → New Skill Loading
@load product:api         → Load: [coding-standards, testing, security, devops]
@load product:web-service → Load: [coding-standards, testing, security, frontend, devops]
@load product:frontend-web → Load: [frontend, testing, security]
```

#### Standard Code Patterns

```bash
# Coding Standards (CS)
@load CS:python       → Load: skills/coding-standards/python
@load CS:javascript   → Load: skills/coding-standards/javascript

# Testing Standards (TS)
@load TS:pytest       → Load: skills/testing/pytest
@load TS:*            → Load: skills/testing/* (all testing skills)

# Security Standards (SEC)
@load SEC:auth        → Load: skills/security/authentication
@load SEC:*           → Load: skills/security/* + NIST-IG:base
```

#### Composite Patterns

```bash
# Multiple standards combined
@load [product:api + CS:python + TS:pytest]
  → Load: product:api skills + python coding + pytest testing
```

### Wildcard Expansion

The bridge automatically expands wildcards:

```yaml
SEC:*  expands to:
  - SEC:auth
  - SEC:secrets
  - SEC:input-validation
  - NIST-IG:base  # Auto-included with security

TS:* expands to:
  - TS:unit
  - TS:integration
  - TS:e2e
```

### Auto-Inclusion Rules

**NIST Baseline Auto-Loading**:

- Any security standard (`SEC:*`) automatically includes `NIST-IG:base`
- Explicit override available with `--no-auto-nist` flag

---

## Level 3: Mastery Resources

### Migration Guide

#### Phase 1: Compatibility Mode (Current)

Both patterns work side-by-side:

```bash
# Legacy pattern (still works)
@load product:api

# New skill pattern (recommended)
skill-loader.py load product:api
```

#### Phase 2: Deprecation Warnings (Month 3-6)

Deprecation warnings will appear in logs.

#### Phase 3: Legacy Removal (Month 6+)

Legacy syntax will be removed. Migration guide available.

### Migration Tools

```bash
# Scan codebase for legacy patterns
skill-loader.py audit-legacy --path .

# Generate migration report
skill-loader.py migration-report --output migration-plan.md

# Auto-migrate files (with backup)
skill-loader.py migrate --path . --backup
```

### Related Skills

- [skill-loader](../skill-loader/SKILL.md) - New skill loading mechanism
- [coding-standards](../coding-standards/SKILL.md) - Base coding standards
- [security-practices](../security-practices/SKILL.md) - Security implementations

### External Resources

- `resources/legacy-mappings.yaml` - Complete mapping definitions
- `config/product-matrix.yaml` - Original product definitions
- `examples/legacy-patterns/` - Migration examples

Overview

This skill provides a backward compatibility bridge that translates legacy @load patterns into the new Skills loading format. It enables a zero-breaking-change migration path during a six-month transition window by auto-mapping legacy tokens to current skill names and loading rules. The bridge supports wildcard expansion, composite patterns, and configurable auto-inclusions so existing workflows continue uninterrupted.

How this skill works

The bridge inspects legacy @load directives and applies a deterministic mapping to the new skill-loader targets, expanding wildcards and composite expressions into concrete skill lists. It auto-includes contextual baselines (for example, NIST-IG:base for security loads) and supports CLI flags to override defaults such as --no-auto-nist. Tools are provided to audit, report, and optionally migrate legacy patterns across a codebase with backups.

When to use it

When you have code that still uses legacy @load product:* or CS:, TS:, SEC: patterns
While running a phased migration to the new Skills architecture during the 6-month transition
When you need zero-breaking-change compatibility to avoid interrupting CI or production workflows
When you want automated wildcard expansion and baseline inclusion for security standards
When you prefer gradual migration with audit and auto-migration tooling available

Best practices

Start by running the audit tool to inventory all legacy patterns: skill-loader.py audit-legacy --path .
Enable compatibility mode and log deprecation warnings; fix high-impact files first
Use migration-report to generate a prioritized plan before running automatic migrations
Test auto-migrated files from backups; use --backup when running migrate
Disable automatic NIST inclusion only when you have an explicit replacement using --no-auto-nist

Example use cases

A monorepo with hundreds of CLAUDE.md files scanning for @load product:* patterns and producing a migration plan
CI pipelines that must continue loading coding-standards and testing skills while teams update manifests
Security teams that need SEC:* to auto-include NIST baseline and expand into concrete security checks
Gradual replacement of @load CS:python entries with skills/coding-standards/python across multiple services
Auto-migrating combined composite patterns like [product:api + CS:python + TS:pytest] into full skill sets

FAQ

Will the bridge make breaking changes during the transition?

No. The bridge preserves behavior and emits deprecation warnings only during the six-month transition to avoid breaking changes.

Can I opt out of automatic NIST baseline inclusion?

Yes. Use the --no-auto-nist flag to prevent the bridge from auto-including NIST-IG:base with security patterns.