Agent({
description: "API migrate: <from> → <to>",
subagent_type: "api-expert:api-expert",
// model omitted — inherits the session model (always the strongest available Claude)
prompt: "<see briefing below>"
})
ORIGINAL USER REQUEST: <verbatim>
WORKFLOW: migration
SOURCE: <version / protocol / framework / repo>
TARGET: <version / protocol / framework / repo>
AFFECTED ENDPOINTS: <list or estimate>
KNOWN CONSUMERS: <internal services + external clients>
SLA: <uptime target>
DEADLINE: <if any>
Read ${CLAUDE_PLUGIN_ROOT}/references/schema-design.md and documentation-lifecycle.md FIRST, plus the target-protocol reference file (architecture-patterns.md or inter-service.md depending).
DELIVERABLES:
1. Catalog current state
- List every affected endpoint with its contract shape
- Identify shared types / models
- Identify shared middleware (auth, rate limit, logging)
- Identify consumers (grep external repos, check SDK download counts); tag each consumer with
its evidence source — `grep:<path>` (show the command) or `assumed` — and list any repo you
could not access
2. Design target state
- Explicit mapping: current endpoint → target endpoint (or deprecation)
- Field-level mapping for payload changes
- Breaking vs non-breaking classification per endpoint
- Cutover sequence (bottom-up: shared code → individual services → external surface)
3. Migration pattern selection (pick the right one):
- **Stripe evolutionary**: version-rewriting middleware translates new canonical shape → old client's pinned version. Zero breaking for external clients, complex internally.
- **URL versioning (v1/ → v2/)**: simplest, explicit, but fragments codebase and consumer SDKs
- **Header versioning (Accept-Version)**: transparent to URLs, allows gradual migration
- **Parallel services**: new service alongside old, gradual traffic shift via gateway/mesh
- **Dual-read**: new code reads from v1 AND v2 data paths, compares results, reports mismatches (validation phase before cutover)
- **Shadow traffic**: mirror prod traffic to new version, measure correctness/performance without user impact
- **Blue-green**: atomic cutover at gateway layer after full validation
- **Strangler fig**: new service proxies unhandled requests to old; grows coverage over time
4. Incremental migration plan (ordered steps):
- Step 1: <what, verification, rollback>
- Step 2: ...
- Each step must be independently reversible
- Each step must have explicit verification before proceeding
5. Compatibility layer (if needed):
- Write request-rewriting middleware OR translator service
- Cover all breaking changes in this layer
- Fixed maintenance cost via tight encapsulation (Stripe's pattern)
6. Consumer communication plan:
- Who to notify (internal + external)
- Channels (email, dashboard, changelog, blog post)
- Timeline (12-24 month external deprecation windows typical)
- Migration guide
- Sunset date
7. Rollback procedures:
- Per-step rollback instructions
- Emergency rollback plan (full revert in <15 min)
- Data rollback if schema changed
- Traffic rollback at gateway
8. Testing strategy:
- Contract tests pinned to source state before migration
- Add contract tests for target state during migration
- Dual-test both APIs during overlap period
- Load test target state before cutover
- Security audit target state
9. Observability during migration:
- Extra metrics: old-endpoint call rate, new-endpoint call rate, mismatch rate (if dual-read)
- Error rate alert thresholds tightened during migration
- Dashboards comparing old vs new
10. Timeline with gates:
- Gate 1: Target state deployed, shadow traffic for N days
- Gate 2: Dual-read validation passes
- Gate 3: X% traffic on new path for N days
- Gate 4: 100% traffic, old path standby
- Gate 5: Old path removed (after grace period)
CONSTRAINTS:
- NEVER break behavioral contracts without explicit deprecation + sunset headers (RFC 9745 + RFC 8594)
- NEVER change error strings, status codes, log field names, metric names without propagating to callers
- GREP all external consumers before changing anything — surprise breakages destroy trust
- PRESERVE operationIds, GraphQL field names, Protobuf field numbers even when renaming conceptually (add deprecation instead)
- PREFER adding new alongside existing over replacing
PROCEED. Read the reference files above, query goodmem for prior migration learnings if configured, then produce the plan.
Before presenting, verify the returned plan: the pattern selection states why it beats the
alternatives for THIS migration; every incremental step has its own verification and rollback; the
consumer catalog is grounded in grep evidence, not assumption. Missing pieces → re-query the agent
before relaying.
The dispatched agent inherits the session model — always the strongest available Claude, never a pinned or dated model. If the session model is already the strongest tier and the task is important or complicated, this skill may run the migration workflow inline in the main context instead of dispatching a separate agent. Never block on, or wait for, a model that isn't the session model.
