diff --git a/.gitignore b/.gitignore index eb4b8da..77984e3 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,9 @@ __pycache__/ *.egg-info/ .env .gemini/ + +# Internal AI-agent coordination scratchpad (not part of the published skill) +transcript.md + +# Internal launch/growth notes (not part of the published skill) +LAUNCH_PREP.md diff --git a/README.md b/README.md index ca3aedc..e164cdf 100644 --- a/README.md +++ b/README.md @@ -12,18 +12,20 @@ An AI agent skill for safe, production-grade LLM model migrations. Automate behavior-preserving upgrades across prompts, agents, API callers, and tests. Universal and plug-and-play across Codex, Claude Code, Cursor, and more. +> **Install in one line:** `npx skills add forkadarshp/MPort` — then tell your agent to migrate. See [Quick start](#quick-start). + **The model ID is one line. The behavior around it is everything else.** Most migrations break because search-and-replace silently shatters tool calling, parsers, and orchestration. ModelPort treats a swap as behavior preservation: ```text - # the naive migration ┄ what a find/replace does + # the naive migration ┄ what a find/replace does $ grep -rl 'opus-4-7' . | xargs sed -i 's/4-7/4-8/g' - x tool calls break x parser drift x silent prod regressions + x tool calls break x parser drift x silent prod regressions - # the ModelPort migration ┄ behavior-preserving + # the ModelPort migration ┄ behavior-preserving > migrate this repo to claude-opus-4-8, keep behavior, prove it - ✓ callers mapped ✓ contract held ✓ tests + rollback evidence + ✓ callers mapped ✓ contract held ✓ tests + rollback evidence ``` ## Now shipping: Claude Opus 4.8 (released 2026-05-28) @@ -307,6 +309,49 @@ npx markdownlint-cli2 "**/*.md" (the methodology lands today in `references/benchmarking.md`). - Add real-world before/after migration case studies. +## FAQ + +### How do I migrate to Claude Opus 4.8? + +Install ModelPort, then ask your agent: *"migrate this repo to +`claude-opus-4-8`."* It reads the +[Opus 4.8 guide](references/models/claude-opus-4-8.md), applies the required +compatibility fixes, preserves tool calling and output contracts, and returns +validation evidence plus rollback notes. + +### How do I migrate from Claude Opus 4.7 to 4.8? + +4.7 → 4.8 is a drop-in upgrade with no breaking API changes — the main task is +re-baselining any tuned `effort` settings. ModelPort makes the model-ID change, +flags the settings to retest, and validates that behavior is unchanged. Coming +from 4.6 or earlier, it applies the 4.7 breaking changes first (sampling params, +adaptive thinking, tokenizer, removed prefills). + +### Will changing the model ID break my tool calling or output format? + +Often, yes — and that's the problem ModelPort exists to solve. Newer models +follow instructions more literally and re-tokenize differently, so a raw +find/replace can silently break tool calls and parsers. ModelPort treats the +swap as behavior preservation and validates the contract before finishing. + +### How do I benchmark Opus 4.8 against my current model? + +Opt into benchmarking at the start and ModelPort runs a three-arm comparison — +baseline, naive swap, and the enhanced system — on the same eval set, then +reports a leaderboard with quality, latency, cost, and contract metrics. See +[references/benchmarking.md](references/benchmarking.md). + +### Does it work with Claude Code, Codex, and Cursor? + +Yes. It's a universal agent skill — install it once and invoke it from Claude +Code, Codex, Cursor, or any compatible agent. + +### Which models and providers does it support? + +Any model or provider swap (Anthropic, OpenAI, and others). It ships dedicated +migration guides for Claude Opus 4.8 / 4.6, Claude Sonnet 4.5, and GPT-5.5, and +a generic playbook for everything else. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/assets/social-preview.png b/assets/social-preview.png new file mode 100644 index 0000000..c9ea9ef Binary files /dev/null and b/assets/social-preview.png differ diff --git a/transcript.md b/transcript.md deleted file mode 100644 index 1817421..0000000 --- a/transcript.md +++ /dev/null @@ -1,33 +0,0 @@ -# ModelPort - AI Agent Activity Transcript - -> **Agent Instructions:** -> This document acts as the centralized handoff and state-management timeline for all AI agents working on the ModelPort project. -> -> 1. **Read First**: Always read this transcript upon joining to understand the current state and recent history. -> 2. **Plan Here First**: Always document your planned changes in the "Planned Changes" section before implementing them. -> 3. **Update Execution State**: Move tasks to "Currently Executing" when actively working on them. -> 4. **Log Completion**: Once finished, move the task to the "Completed Events Log" with a timestamp and a brief summary of what was done. - -## 📋 Planned Changes - -*List all upcoming tasks, features, and fixes here.* - -- [ ] (Example) Implement core migration engine for ModelPort. - ---- - -## ⏳ Currently Executing - -*List the tasks that are actively being worked on by an agent right now.* - -- [ ] (Example) Setting up initial project scaffolding. - ---- - -## ✅ Completed Events Log - -*Log all finished tasks here. Include timestamps, agent IDs if applicable, and short summaries.* - -- **2026-05-29** - Initialized git repository locally and pushed initial commit to `https://github.com/forkadarshp/MPort`. -- **2026-05-29** - Created the `transcript.md` file to initialize state management for ModelPort agents. -- **2026-05-29** - Completed rebranding from ModelLift to ModelPort across all documentation files (`SKILL.md`, `CONTRIBUTING.md`, `examples/`), and resolved all markdownlint errors.