/opus-4-7-migration

name: opus-4-7-migration
description: 'Scan a repository for Opus-4.6-era patterns that break or degrade on Opus 4.7 — fixed-budget Extended Thinking parameters, retired model ID aliases, and prompts that assumed verbose default output or eager sub-agent delegation. Produces a categorized report with file:line references and migration actions. Triggers on: "opus 4.7 migration", "migrate to opus 4.7", "audit for opus 4.7", "opus 4.6 to 4.7", "scan for budget_tokens", "find retired model IDs", "adapt repo to opus 4.7". NOT for implementing migrations — this skill identifies candidates.'
metadata:
  version: 1.0.0
  category: review
  tags: [opus-4-7, migration, audit, model-refresh, budget-tokens]
  difficulty: intermediate
  phase: review

Opus 4.7 Migration Scanner

Identify patterns in a repository that break or silently degrade when the Anthropic platform routes to Opus 4.7. Produces a categorized report with file:line references so a maintainer can plan a scoped migration PR rather than chasing symptoms after the fact.

Reference Files

| File | Contents | Load When | | ----------------------------- | ------------------------------------------------------------- | ---------------------------------- | | `scripts/scan.py` | Repo scanner producing a categorized findings report | Always | | `references/migration-map.md` | Per-category migration actions with before/after code samples | When a category returns findings |

When to Run

• Before upgrading a service or agent stack to Opus 4.7
• When an existing Anthropic SDK integration starts returning errors after the platform rolled out 4.7
• Periodically in a CI or weekly audit to prevent drift as the repo grows
• Before publishing a package that downstream users will run against 4.7

Scope — What the Scanner Flags

The scanner is intentionally narrow. It reports three categories of **deterministic** patterns plus two **heuristic** categories that require manual review.

Category A — Fixed-budget Extended Thinking (deterministic)

Opus 4.7 does not support Extended Thinking with a fixed `budget_tokens` value. Code that still passes `thinking={"type": "enabled", "budget_tokens": N}` fails or is ignored depending on SDK version.

Patterns flagged:

• Literal `budget_tokens=` in Python source
• `"budget_tokens"` keys inside `thinking={...}` dict literals
• `.thinking.budget_tokens` attribute references

Category B — Retired model ID aliases (deterministic)

Dated or superseded Claude model aliases that no longer map to the current model. Using them is not broken but defeats the platform's model routing.

Patterns flagged:

• `claude-opus-4-5`, `claude-opus-4-4`, `claude-opus-4-3`, `claude-opus-4-2`, `claude-opus-4-1`, `claude-opus-4-0`
• `claude-sonnet-4-5`, `claude-sonnet-4-4`, `claude-sonnet-4-3`, `claude-sonnet-4-2`, `claude-sonnet-4-1`, `claude-sonnet-4-0`
• Dated format aliases: `claude-*-20250514`, `claude-*-20241022`, etc.
• `claude-3-*` family (superseded)

Category C — Hardcoded model references outside config (deterministic)

Per the armory convention "model refs in config files only," any `claude-*` literal in `.py` / `.ts` / `.js` source code outside of `config.toml`, `.env`, or test-only sentinel strings is a candidate for extraction.

Category D — Opus-4.6-verbosity-assuming prompts (heuristic)

Opus 4.7 is less default-verbose than 4.6. Prompts that relied on Opus 4.6's eager output or never needed a depth cue may produce shorter-than-expected responses on 4.7.

Patterns flagged (review required):

• Prompts requesting "detailed" or "comprehensive" output without matching length directive
• Prompts that exceeded Opus 4.6's defaults by relying on implicit verbosity
• Absence of first-turn specification completeness in agent prompts

Category E — Non-explicit parallel sub-agent dispatch (heuristic)

Opus 4.7 delegates more judiciously than 4.6. Agent prompts instructing "spawn in parallel" without the phrase "in a single message" or stating sub-task independence often serialize on 4.7.

Patterns flagged (review required):

• `Spawn` + `parallel` language in agent prompts without "single message" or "independent"
• `subagent_type` dispatches in loops or sequential blocks where parallelism was intended

Workflow

Phase 1: Run the Scanner

Execute:

python3 scripts/scan.py /path/to/repo

Optional flags:

• `--categories A,B,C` — run only deterministic categories (skip heuristics)
• `--exclude tests/,vendor/,node_modules/` — path exclusion
• `--format json` — machine-readable output for CI integration
• `--exit-code` — exit 1 if any findings (useful for pre-commit hooks)

Phase 2: Triage Findings

Group findings by category and sort by severity. Deterministic categories (A, B, C) are always actionable. Heuristic categories (D, E) require reading the surrounding prompt context before editing.

Priority order for a migration PR:

1. **Category A** first — these either error out or silently do the wrong thing on 4.7 2. **Category B** — rename to current logical aliases (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`) or to the platform's auto-routing name 3. **Category C** — extract to `config.toml` per repo convention 4. **Category D, E** — manual review; fix those that materially change behavior

Phase 3: Write the Migration PR

For each category with findings, apply the actions documented in `references/migration-map.md`. Prefer small PRs grouped by category over one large PR.

Pair the migration with:

• Unit tests or integration tests that exercise the updated code paths on Opus 4.7
• A short CHANGELOG entry noting "Opus 4.7 compatibility: removed `budget_tokens` from …"
• A rollout plan if the service is production-critical (`high`/`xhigh` effort level on the targeted agents)

Output Format

The scan