From 0938d61f2ab9ee02f0980cfba0d4071e5abc3029 Mon Sep 17 00:00:00 2001 From: forkadarshp Date: Fri, 29 May 2026 04:48:48 +0530 Subject: [PATCH] docs: polish README for Opus 4.8 launch Add launch hero sections to the top of the README: - "Now shipping: Claude Opus 4.8" callout linking the model guide and summarizing the 4.7 -> 4.8 drop-in path and required 4.6 -> 4.7 fixes - "Our approach to migration" with an ASCII pipeline diagram showing the Opus 4.7 -> ModelPort -> Opus 4.8 behavior-preserving flow and all 7 phases - "Outcomes: with vs. without ModelPort" split-column comparison Also refresh stale docs: list references/models/ and output-style.md in the repository structure block, and update the roadmap to reflect that the Claude/GPT-5.5 model guides already ship. ASCII art uses width-safe glyphs only so box borders stay aligned on GitHub. --- README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index eb88021..f250dd6 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,68 @@ An AI agent skill for safe, production-grade LLM model migrations. Automate beha **The Problem:** Most model migrations fail after you change the model ID because search-and-replace breaks tool calling, parser behavior, and orchestration. **The Solution:** ModelPort treats migration as a behavior-preservation problem: it maps callers, separates required compatibility fixes from optional tuning, and mandates validation before finishing. +## Now shipping: Claude Opus 4.8 (released 2026-05-28) + +Opus 4.8 is live, and ModelPort already ships a dedicated migration guide for it: +[`references/models/claude-opus-4-8.md`](references/models/claude-opus-4-8.md). +It covers the **4.7 → 4.8 drop-in path**, the **4.6 → 4.7 breaking changes you +must apply first** (non-default sampling params now 400, manual extended +thinking → `{type: "adaptive"}` + `effort`, new tokenizer, removed assistant +prefills), and **effort re-baselining**. Point the skill at your repo: + +```text +Use $modelport-skill to migrate this codebase to claude-opus-4-8. +Apply required compatibility fixes first, keep tool + output behavior stable, +and return validation evidence plus rollback notes. +``` + +## Our approach to migration + +ModelPort treats a model swap as a **behavior-preservation problem**, not a +search-and-replace. The model ID is one line; the behavior around it — tool +calls, parsers, output contracts, prompts, orchestration — is everything else. +The skill drives a strict, phase-gated pipeline that maps every caller, +classifies each hit before editing, keeps required fixes apart from optional +tuning, and refuses to claim "done" without proof. + +```text +╭──────────────────────────────────────────────────────────────────────╮ +│ │ +│ [ Opus 4.7 ] ═══> ( ModelPort ) ═══> [ Opus 4.8 ] │ +│ drop-in upgrade behavior-preserving GA · 2026-05-28 │ +│ │ +│ » phase 0 lock scope, read current state ················· [ OK ]│ +│ » phase 1 discover callers, prompts, agents, tools ······· [ OK ]│ +│ » phase 2 classify every hit before editing ·············· [ OK ]│ +│ » phase 3 design: required fixes vs optional tuning ······ [ OK ]│ +│ » phase 4 surgical patches, no blind search/replace ······ [ OK ]│ +│ » phase 5 validate: tests + live smoke + contract ········ [ OK ]│ +│ » phase 6 report: proof evidence + rollback notes ········ [ OK ]│ +│ │ +╰──────────────────────────────────────────────────────────────────────╯ +``` + +## Outcomes: with vs. without ModelPort + +Skipping the discipline is exactly where migrations look fine in review and +then silently regress in production — broken tool calls, drifted output +contracts, no proof, and no way back. + +```text +╭───────────────────────────────────┬───────────────────────────────────╮ +│ WITHOUT ModelPort │ WITH ModelPort │ +├───────────────────────────────────┼───────────────────────────────────┤ +│ x find/replace the model ID │ ✓ scope-locked discovery │ +│ x tool calls break silently │ ✓ callers mapped, not guessed │ +│ x parser / output drift │ ✓ output contract preserved │ +│ x prompt hacks carry over │ ✓ fixes vs tuning kept apart │ +│ x "looks fine" — no proof │ ✓ tests + live smoke evidence │ +│ x no way back on breakage │ ✓ rollback notes included │ +├───────────────────────────────────┼───────────────────────────────────┤ +│ → silent prod regressions │ → behavior-preserving upgrade │ +╰───────────────────────────────────┴───────────────────────────────────╯ +``` + ## Why teams use it - Replace deprecated model IDs without breaking runtime calls. @@ -146,9 +208,15 @@ See [examples/example-output.md](examples/example-output.md) for a sample report ├── references/ │ ├── migration-patterns.md │ ├── migration-playbook.md +│ ├── output-style.md │ ├── prompt-template-research.md │ ├── provider-checklists.md -│ └── validation-proof.md +│ ├── validation-proof.md +│ └── models/ +│ ├── claude-opus-4-8.md +│ ├── claude-opus-4-6.md +│ ├── claude-sonnet-4-5.md +│ └── gpt-5-5.md ├── examples/ │ ├── example-prompts.md │ └── example-output.md @@ -180,8 +248,8 @@ npx markdownlint-cli2 "**/*.md" ## Roadmap -- Add provider-specific deep dives for OpenAI, Anthropic, Gemini, and - self-hosted models. +- Per-model migration guides for Claude Opus 4.8 / 4.6, Sonnet 4.5, and GPT-5.5 + ship today in `references/models/`. Next: Gemini and self-hosted models. - Add regression fixtures for prompt, tool, and structured-output migrations. - Add benchmark examples for latency, token usage, and output contract drift. - Add real-world before/after migration case studies.