@softspark/ai-toolkit 4.13.0 → 4.14.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.14.1 — Keep fact-checker on Sonnet (2026-07-14)
+
+Patch release. Reverts one of the two agent model reassignments from v4.14.0: `fact-checker` goes back to `model: sonnet`. Claim verification is accuracy-sensitive and Haiku's recall on subtle claims did not justify the cost saving. `explorer-agent` (pure read/search) stays on `model: haiku`. No count change (44 agents, 108 skills, 1216 tests).
+
+### Changed
+- **`fact-checker` reverted to Sonnet** — `model: haiku → model: sonnet`. Quality over cost for claim verification / RAG-accuracy checks.
+
+## v4.14.0 — Model refresh + effort-aware routing (2026-07-14)
+
+Minor release. Refreshes Claude model IDs to the current generation across the toolkit, teaches the routing skill to route on `effort` (not just model tier), and moves two pure-retrieval agents to Haiku. No skill/agent/hook count change (44 agents, 108 skills, 1216 tests).
+
+### Changed
+- **Canonical model IDs bumped** — `scripts/_common.py` `DEFAULT_CLAUDE_MODELS` now resolves `opus → claude-opus-4-8` and `sonnet → claude-sonnet-5` (`haiku → claude-haiku-4-5` unchanged). This is the single source of truth generators emit.
+- **`model-routing-patterns` skill refreshed** — tier table updated to Haiku 4.5 / Sonnet 5 / Opus 4.8 with per-1M pricing, added a **Fable 5** row plus a "not the default best model" caveat (target for "strongest model" stays `claude-opus-4-8`), and a new **Effort routing** section (effort is the cheaper lever before swapping models — it does not invalidate the prompt cache). Fallback-chain example IDs updated.
+- **Stale example model IDs refreshed** — `json-mode-patterns`, `prompt-caching-patterns`, and `skill-creator` code samples now reference `claude-opus-4-8`.
+- **Pure-retrieval agents routed to Haiku** — `explorer-agent` (Read/Grep/Glob only) and `fact-checker` (Read only) changed from `model: sonnet` to `model: haiku`, closing the gap where the routing skill recommended Haiku workers but no agent used the tier.
+
 ## v4.13.0 — Claude app delivery + Devin sunset cleanup (2026-07-10)
 
 Minor release. Adds a validated distribution path for Claude Chat/Desktop/Cowork, fixes the core plugin contract, and removes the retired Cascade hook surface. Test count: 1208 → 1216 (seven deprecated Cascade assertions removed; six Claude app contract tests, three editor migration/propagation tests, two state-isolation/cleanup tests, two untagged-hook diagnostics, and two dry-run regressions added).

package/README.md

@@ -8,16 +8,14 @@
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
 [![Tests](https://img.shields.io/badge/tests-1216%20passing-success)](tests/)
 
-## What's New in v4.13.0
+## What's New in v4.14.1
 
-v4.13.0 makes the Claude app a first-class distribution target and completes the Devin/Cascade migration.
+v4.14.1 refreshes Claude model IDs to the current generation, makes model routing effort-aware, and tunes agent model tiers.
 
-- **Claude Chat/Desktop/Cowork export**: `ai-toolkit claude-app export --verify` creates an uploadable plugin ZIP and Cowork global-instructions file. Core and registered rules are packaged as app-native skills.
-- **Plugin contract repaired**: the official validator now accepts the manifest; app hooks use `${CLAUDE_PLUGIN_ROOT}` instead of depending on a Claude Code install.
-- **Cascade cleanup**: removed the dead `.windsurf/hooks.json` generator after the 2026-07-01 sunset; `.devin/hooks.v1.json` is the live Devin hook surface.
-- **Devin skill-path correction**: stopped emitting undocumented `.devin/skills`; the pointer remains under the currently documented `.windsurf/skills` compatibility path.
-- **Ecosystem refresh**: registry expanded to 13 targets and snapshots refreshed against current official documentation.
-- **Test count**: 1208 → 1216 (Claude app export, editor migration/propagation, state isolation, diagnostics, and dry-run accuracy covered).
+- **Current model IDs**: `scripts/_common.py` now resolves `opus → claude-opus-4-8` and `sonnet → claude-sonnet-5` (the single source of truth generators emit); stale `claude-opus-4-7` samples across skills refreshed.
+- **Effort-aware routing**: `model-routing-patterns` gains an Effort section — tuning `output_config.effort` is the cheaper lever before swapping models, and it does not invalidate the prompt cache the way a mid-session model swap does.
+- **Fable 5 tier documented**: added to the routing table with pricing and a "not the default best model" caveat — for "strongest model", the target stays `claude-opus-4-8`.
+- **Agent tiers tuned**: `explorer-agent` (pure read/search) runs on `model: haiku`; `fact-checker` stays on `model: sonnet` — accuracy over cost for claim verification.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.13.0",
+  "version": "4.14.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -55,7 +55,7 @@ The toolkit is organised as five stacked layers. Higher layers depend on lower l
 - A skill MAY trigger an agent (`agent: <name>` frontmatter) — that's Layer 2 calling Layer 4.
 - A hook MUST NOT call a skill — hooks are deterministic shell, skills are LLM-driven.
 - A plugin MAY bundle skills + agents + hooks, but never the inverse.
-- Claude Code reads CLAUDE.md across layers. Claude Chat/Cowork uses app-global/folder instructions and plugin skills instead; `claude_app.py` renders core rules into `ai-toolkit-rules` for that runtime.
+- Claude Code reads CLAUDE.md across layers. Claude Chat/Cowork uses app-global/folder instructions and plugin skills instead; `ai-toolkit claude-app export` (backed by `claude_app.py`) builds the uploadable plugin ZIP + Cowork global-instructions and renders core rules into `ai-toolkit-rules` for that runtime.
 
 ---
 

package/app/agents/explorer-agent.md

@@ -2,7 +2,7 @@
 name: explorer-agent
 description: "Codebase exploration and discovery agent. Use for mapping project structure, finding dependencies, understanding architecture, and research. Does NOT write code - only reads and analyzes."
 tools: Read, Grep, Glob
-model: sonnet
+model: haiku
 color: cyan
 skills: clean-code
 ---

package/app/skills/json-mode-patterns/SKILL.md

@@ -30,7 +30,7 @@ tools = [{
 }]
 
 response = client.messages.create(
-    model="claude-opus-4-7",
+    model="claude-opus-4-8",
     max_tokens=1024,
     tools=tools,
     tool_choice={"type": "tool", "name": "record_analysis"},
@@ -55,7 +55,7 @@ When tool use is unavailable (some SDKs/proxies strip it):
 
 ```python
 response = client.messages.create(
-    model="claude-opus-4-7",
+    model="claude-opus-4-8",
     max_tokens=1024,
     system="You return ONLY valid JSON. No prose, no markdown fences.",
     messages=[{

package/app/skills/model-routing-patterns/SKILL.md

@@ -12,13 +12,30 @@ Three Claude tiers. Using Opus for everything is 10-40x more expensive than it n
 
 ## Model Characteristics (2026)
 
-| Model | Latency | Cost (rel.) | Strengths | When |
-|-------|---------|-------------|-----------|------|
-| Haiku 4.5 | Fastest | 1x | Classification, extraction, simple tools, moderation | Bulk processing, triage, labels |
-| Sonnet 4.6 | Medium | 3-5x | General coding, reasoning, most agent tasks | Default workhorse |
-| Opus 4.7 | Slowest | 15-30x | Complex reasoning, orchestration, architecture, large context | Hard, rare, high-stakes |
+| Model | $/1M in·out | Cost (rel.) | Strengths | When |
+|-------|-------------|-------------|-----------|------|
+| Haiku 4.5 | $1 / $5 | 1x | Classification, extraction, simple tools, moderation | Bulk processing, triage, labels |
+| Sonnet 5 | $3 / $15 | ~3x | General coding, reasoning, most agent tasks | Default workhorse |
+| Opus 4.8 | $5 / $25 | ~5x | Complex reasoning, orchestration, architecture, large context | Hard, rare, high-stakes |
+| Fable 5 | $10 / $50 | ~10x | Most demanding long-horizon agentic work | Only when explicitly chosen |
 
-Ratios are approximate and shift between releases. Re-check pricing before committing a production path.
+Prices are per 1M tokens; ratios are approximate and shift between releases. Re-check pricing before committing a production path.
+
+> **Fable 5 is not the default "best model".** Its price sits above Opus-tier, and Opus 4.8 is state-of-the-art on planning/orchestration at half the input and output cost. Reach for Fable 5 only when the user explicitly asks for it or a benchmarked task genuinely needs it — for "use the strongest model", the target is `claude-opus-4-8`.
+
+## Effort — the cheaper lever before swapping models
+
+On Fable 5 / Opus 4.8 / Sonnet 5, `output_config.effort` (`low` | `medium` | `high` | `xhigh` | `max`) controls thinking depth and token spend **without changing the model** — so it does not invalidate the prompt cache the way a mid-session model swap does. Tune effort first; drop to a cheaper model only when effort alone can't hit the cost target.
+
+| Effort | Use for |
+|--------|---------|
+| `low` | Latency-sensitive, non-intelligence-sensitive: chat, simple lookups, cheap subagents |
+| `medium` | Cost-conscious step-down from the default |
+| `high` | Default for most intelligence-sensitive work (a good quality/cost balance) |
+| `xhigh` | Hardest coding and agentic tasks (Claude Code's default) |
+| `max` | Correctness matters more than cost; test for diminishing returns |
+
+In our agents, effort is set per skill/agent frontmatter (`effort:`), not swapped at runtime. Combine effort routing with model routing: e.g. `sonnet` at `high` often beats `opus` at `low` for cost-equal quality — benchmark before committing.
 
 ## Pattern 1 — Complexity Router (pre-classify)
 
@@ -69,7 +86,7 @@ When primary is rate-limited or errors, degrade gracefully:
 
 ```python
 def call_with_fallback(messages):
-    for model in ["claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5"]:
+    for model in ["claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"]:
         try:
             return client.messages.create(model=model, messages=messages, ...)
         except (RateLimitError, OverloadedError):

package/app/skills/prompt-caching-patterns/SKILL.md

@@ -24,7 +24,7 @@ from anthropic import Anthropic
 
 client = Anthropic()
 response = client.messages.create(
-    model="claude-opus-4-7",
+    model="claude-opus-4-8",
     max_tokens=1024,
     system=[
         {
@@ -90,7 +90,7 @@ Target ratio for a well-tuned loop: `cache_read / (cache_read + input) > 0.7`. B
 
 ```typescript
 const response = await anthropic.messages.create({
-  model: "claude-opus-4-7",
+  model: "claude-opus-4-8",
   max_tokens: 1024,
   system: [
     { type: "text", text: LONG_SYSTEM, cache_control: { type: "ephemeral" } }

package/app/skills/skill-creator/SKILL.md

@@ -33,7 +33,7 @@ Create a new skill following the Agent Skills standard.
 | `user-invocable` | bool | no | `false` = knowledge skill, Claude auto-loads |
 | `allowed-tools` | csv or YAML list | no | Restrict tool access for safety; YAML-style lists accepted |
 | `disallowedTools` | csv or YAML list | no | Block specific tools (plugin-shipped agents) |
-| `model` | string | no | Override default model (accepts full IDs like `claude-opus-4-7`) |
+| `model` | string | no | Override default model (accepts full IDs like `claude-opus-4-8`) |
 | `context` | string | no | `fork` to run in isolated subagent |
 | `agent` | string | no | Agent type to use when `context: fork` |
 | `skills` | csv | no | Auto-load skills for the invoked subagent |

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.13.0",
+  "version": "4.14.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.13.0",
+  "version": "4.14.1",
   "description": "AI coding toolkit: 108 skills, 44 agents, 12 developer-tool integrations plus Claude Chat/Cowork plugin export, machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/_common.py

@@ -79,8 +79,8 @@ skills_dir: Path = app_dir / "skills"
 # the client at runtime and do NOT need updating here.
 # ---------------------------------------------------------------------------
 DEFAULT_CLAUDE_MODELS: dict[str, str] = {
-    "opus": "claude-opus-4-7",
-    "sonnet": "claude-sonnet-4-6",
+    "opus": "claude-opus-4-8",
+    "sonnet": "claude-sonnet-5",
     "haiku": "claude-haiku-4-5",
 }