feat: current-generation model guides, freshness checks, and repositioning

.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "modelport",
+  "description": "ModelPort: upgrade LLM code to newer models without breaking prod",
+  "owner": {
+    "name": "Kumar Adarsh Pandita",
+    "url": "https://github.com/forkadarshp"
+  },
+  "plugins": [
+    {
+      "name": "modelport",
+      "source": "./",
+      "description": "Migrate prompts, tools, API calls, and tests to a newer LLM, with per-model breaking-change guides and proof that the upgrade worked."
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "modelport",
+  "displayName": "ModelPort",
+  "version": "0.2.0",
+  "description": "Upgrade LLM code to newer models (Claude 5.x, GPT-6, Gemini 3.8) without breaking prod. Applies each model's breaking-change fixes, then proves the upgrade with tests and evals.",
+  "author": {
+    "name": "Kumar Adarsh Pandita",
+    "url": "https://github.com/forkadarshp"
+  },
+  "homepage": "https://github.com/forkadarshp/MPort",
+  "repository": "https://github.com/forkadarshp/MPort",
+  "license": "MIT",
+  "keywords": ["model-migration", "llm-migration", "prompt-migration", "model-upgrade", "breaking-changes", "evals"]
+}

.github/workflows/freshness.yml

@@ -0,0 +1,38 @@
+name: Model guide freshness
+
+on:
+  schedule:
+    - cron: "0 9 * * 1" # Mondays 09:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check guide ages
+        id: check
+        continue-on-error: true
+        run: python3 scripts/check_freshness.py . | tee freshness-report.txt
+      - name: Open or update the freshness issue
+        if: steps.check.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          title="Model guides need re-verification"
+          body="$(cat freshness-report.txt)"
+          existing="$(gh issue list --state open --search "$title in:title" --json number --jq '.[0].number')"
+          if [ -n "$existing" ]; then
+            gh issue comment "$existing" --body "$body"
+          else
+            gh issue create --title "$title" --body "$body"
+          fi

CONTRIBUTING.md

@@ -34,6 +34,23 @@ python3 scripts/validate_skill.py .
 npx markdownlint-cli2 "**/*.md"
 ```
 
+## Adding or updating a model guide
+
+New models are the most valuable contribution. A guide needs:
+
+- A header with `Model ID:`, pricing, `Last verified: YYYY-MM-DD`, and
+  `Source:` (the provider page you used). Mark facts from blogs or other
+  secondary sources as such.
+- Required changes (will error), silent changes (behavior differs), upgrade
+  paths from older models, and optional tuning, kept separate.
+- An entry in `references/models/INDEX.md`, and in
+  `references/breaking-changes.md` if the model adds new errors.
+- Superseded guides get `Status: legacy` and `Last verified: legacy, ...`
+  instead of being deleted.
+
+`python3 scripts/validate_skill.py .` checks the header and the index entry.
+`python3 scripts/check_freshness.py .` lists guides older than 30 days.
+
 ## Reporting bugs
 
 Use the bug template and include:

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modelport-skill
-description: Use when the user asks to migrate, upgrade, or port prompts, agents, tools, or codebases from one LLM model or provider version to another. Also use when auditing or continuing migration work started by another agent. Covers API calls, prompt assets, agent configs, tool definitions, tests, docs, runtime settings, rollout plans, and handoff coordination. Can also benchmark pre/post migration systems (old model and prompts vs new model and enhanced system) and report the stats as evidence.
+description: Use when the user asks to migrate, upgrade, or port prompts, agents, tools, or code to a newer LLM or a different provider, including Claude Opus 5.5 / Sonnet 5.5 / Haiku 5.5 / Fable 5.1, GPT-6, and Gemini 3.8, or replace a deprecated or retired model. Also use when a model swap returns 400s (thinking disabled, budget_tokens, forced tool_choice, temperature/top_p, prefill, computer_20251124), truncates replies, or breaks parsers and tool calls, and when auditing migration work another agent started. Fixes API calls, prompts, tool definitions, tests, and configs, then proves it with tests, a live smoke check, and an optional old-vs-new benchmark.
 ---
 
 # ModelPort Skill
@@ -89,10 +89,19 @@ Collect before editing:
   report (baseline old/old vs new/enhanced, plus the raw-swap control)? Opt-in.
   Ask once, up front — capturing the baseline later is impossible.
 
-If source or target matches a model with a dedicated guide in
-`references/models/`, read that guide before proceeding. Model guides contain
+Look up source and target in `references/models/INDEX.md`. If either has a
+dedicated guide, read it before proceeding, and follow the upgrade path in the
+index (older guides are layered under newer ones). Model guides contain
 changelogs, breaking changes, migration steps, and version-specific quirks.
 
+Freshness check, before trusting any guide:
+
+- `Last verified:` older than 30 days, or the target is not in the index →
+  fetch the provider's official migration page first. Never guess model IDs,
+  parameters, prices, or limits.
+- Record the source and date used in the migration report.
+- Facts marked as secondary-source in a guide → confirm on the provider page.
+
 If benchmarking is requested, read `references/benchmarking.md` and capture the
 baseline (Arm A) in Phase 0 before any edit — it cannot be reconstructed later.
 
@@ -126,9 +135,12 @@ Read:
 
 - `references/migration-playbook.md`
 - `references/provider-checklists.md`
+- `references/models/INDEX.md` — registry, upgrade paths, freshness rules
+- `references/breaking-changes.md` — error/symptom → cause → fix lookup across
+  providers; read first when a swap returns 400s or behaves differently
 - `references/models/<model>.md` — when source or target matches a model with
-  a dedicated guide (e.g. `claude-opus-4-8.md`, `claude-opus-4-6.md`,
-  `claude-sonnet-4-5.md`, `gpt-5-5.md`)
+  a dedicated guide (Claude Fable 5.1 / Opus 5.5 / Sonnet 5.5 / Haiku 5.5,
+  GPT-6, Gemini 3.8 Flash, plus legacy Claude and GPT-5.5 guides)
 - `references/prompt-template-research.md` — when creating or improving a
   migration prompt or reusable migration request
 - `references/migration-patterns.md` — when choosing rollout strategy,
@@ -249,7 +261,7 @@ Format per `examples/example-output.md`.
 - Migration strategy: `references/migration-playbook.md`
 - Provider checklists: `references/provider-checklists.md`
 - Model-specific guides: `references/models/` (per-version changelogs, quirks,
-  migration steps)
+  migration steps). Start at `references/models/INDEX.md`.
 - Prompt design research: `references/prompt-template-research.md`
 - Migration patterns: `references/migration-patterns.md`
 - Validation proof gates: `references/validation-proof.md`

_config.yml

@@ -0,0 +1,21 @@
+# GitHub Pages site config. The repo root is the site source, so every guide
+# becomes an indexable page. The skill itself does not read this file.
+title: ModelPort
+description: >-
+  Upgrade LLM code to Claude Opus 5.5, GPT-6, or Gemini 3.8 without breaking
+  prod. Breaking changes, fixes, and an agent skill that applies them.
+url: https://forkadarshp.github.io
+baseurl: /MPort
+theme: jekyll-theme-primer
+plugins:
+  - jekyll-seo-tag
+  - jekyll-sitemap
+exclude:
+  - harness/
+  - scripts/
+  - templates/
+  - agents/
+  - docs/PUBLISHING.md
+  - CODE_OF_CONDUCT.md
+  - SECURITY.md
+  - LICENSE

agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ModelPort"
-  short_description: "Migrate prompts, agents, and LLM code safely"
-  default_prompt: "Use $modelport-skill and the starter prompt template to migrate this codebase from the current model to the newer target model with validation evidence and rollback notes."
+  short_description: "Upgrade to newer LLMs (Claude 5.x, GPT-6, Gemini 3.8) without breaking prod"
+  default_prompt: "Use $modelport-skill to migrate this codebase to the target model. Read references/models/INDEX.md, apply required compatibility fixes before optional tuning, and return validation evidence plus rollback notes."