@softspark/ai-toolkit 4.12.0 → 4.14.0

package/app/claude-app/skills/ai-toolkit-rules/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: ai-toolkit-rules
+description: "Mandatory engineering, security, testing, git, performance, quality, and response rules. Claude MUST load this skill for every technical, coding, debugging, review, architecture, DevOps, data, or file-editing task in Chat or Cowork."
+user-invocable: true
+---
+
+# AI Toolkit Rules
+
+Apply every relevant rule below before acting. Treat MUST/NEVER language as mandatory.
+
+## Source: `app/rules/claude-toolkit-rules.md`
+
+# Claude Toolkit
+
+Shared AI development toolkit — lifecycle hooks, safety constitution, multi-platform support.
+
+## Skill Tiers
+
+- **Tier 1** — single-agent: `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/triage-issue`
+- **Tier 1.5** — planning: `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues`; design: `/design-an-interface`, `/architecture-audit`, `/refactor-plan`
+- **Tier 2** — multi-agent: `/workflow <type>` (feature-development, backend-feature, frontend-feature, api-design, database-evolution, test-coverage, security-audit, debugging, incident-response, spike, codebase-onboarding, performance-optimization, infrastructure-change, application-deploy, proactive-troubleshooting)
+- **Tier 3** — custom: `/orchestrate <desc>` (3–6 agents) | `/swarm <mode> <desc>` (map-reduce | consensus | relay)
+
+## Path Safety
+- NEVER guess or hallucinate user home directory paths
+- Use `~` or `$HOME` instead of hardcoded `/Users/<username>/` or `/home/<username>/`
+- When an absolute path is needed, run `echo $HOME` first to get the correct value
+
+## User Preferences
+
+- **Style:** Direct & efficient. No pleasantries. Measurable results.
+- **Methodology:** Provide >=3 alternatives. Use Socratic questioning.
+- **Review:** Apply "Devil's Advocate" critique to decisions.
+
+## Source: `app/rules/git-conventions.md`
+
+# Git Conventions
+
+- Do NOT add `Co-Authored-By: Claude` or any AI co-authorship to commits
+- Do NOT add Claude signatures or attribution to commit messages
+- Conventional commits format: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+
+## Source: `app/rules/output-mode.md`
+
+# Output Mode
+
+`output-mode: concise`
+
+Default response mode for this project is **concise**. The `brand-voice` skill (when present in ai-toolkit) auto-loads its `concise` rules; assistants without that skill should still apply the directives below.
+
+## Concise Mode Directives
+
+- **No preamble.** Skip "I'll now...", "Sure, let me...", "Great question!" and similar warm-ups. Start with the answer.
+- **Lead with the result.** Conclusion or output first; explanation only if asked or non-obvious.
+- **Max 3 sentences per closed question.** Yes/no, single-fact, or "where is X" answers stay under three sentences.
+- **Tables and lists over prose** when comparing options, listing steps, or showing values.
+- **No trailing summaries.** If the diff or output already shows what changed, do not restate it.
+- **Drop filler adjectives.** No "nice", "great", "powerful", "robust" unless the user asked for evaluation.
+- **Cite file paths as `path:line`** instead of paragraphs describing where things live.
+- **Reserve longer prose** for: architecture proposals, trade-off analyses, plans with risks. Everything else: terse.
+
+## When to escalate to verbose
+
+- User explicitly asks: "explain in detail", "walk me through", "give me the full picture".
+- Reporting a non-obvious failure mode where missing context would mislead.
+- Architecture / RFC / ADR / trade-off documents — those have their own structure.
+
+## How to override
+
+- Per-session: `/brand-voice default` (or `/brand-voice strict` for even tighter)
+- Per-project: change this rule's `output-mode:` value in the project's `CLAUDE.md`
+- Permanent removal: re-run `ai-toolkit install --skip rules` or strip the `<!-- TOOLKIT:output-mode -->` block manually
+
+## Source: `app/rules/quality-gates.md`
+
+# Quality Gates & Mandatory Practices
+
+## MANDATORY PRACTICES
+1.  **Plan First:** Tasks >1h require Plan, Success Criteria, and Pre-Mortem.
+2.  **Quality Gates:**
+    *   `ruff check .` (0 errors)
+    *   `mypy --strict src/` (0 errors)
+    *   `pytest --cov=src` (>70% coverage)
+    *   **Type Safety:** 100% public APIs, >60% internal.
+3.  **Security:** No secrets in code, sanitization, auth z/n.
+
+## Source: `app/rules/common/coding-style.md`
+
+# Universal Coding Style
+
+## Principles
+- KISS: simplest solution that works. Clever code is a liability. If 200 lines could be 50, rewrite.
+- DRY: extract when you repeat 3+ times, not before.
+- YAGNI: do not build features "just in case." No abstractions for single-use code.
+- Prefer immutability: use `const`, `final`, `val`, `let` by default.
+- Fail fast: validate inputs at boundaries, return early on errors.
+- State assumptions before coding. If uncertain or multiple interpretations exist, ask — don't pick silently.
+
+## Naming
+- Use descriptive names that reveal intent (`remainingRetries`, not `r`).
+- Boolean variables/functions: prefix with `is`, `has`, `can`, `should`.
+- Functions: verb + noun (`fetchUser`, `calculateTotal`, `validateInput`).
+- Avoid abbreviations unless universally understood (`id`, `url`, `http`).
+- Collections use plural nouns (`users`, `orderItems`).
+
+## Functions
+- Max 20-30 lines per function. If longer, extract.
+- Max 3 parameters. Beyond that, use an options/config object.
+- Single responsibility: one function does one thing.
+- Pure functions preferred: same input, same output, no side effects.
+- Avoid boolean parameters: use separate functions or enums.
+
+## File Organization
+- One primary concept per file (class, module, component).
+- Group imports: stdlib, external, internal, relative.
+- Constants at top, public API before private helpers.
+- Keep files under 300 lines. Split when they grow.
+
+## Comments
+- Code should be self-documenting. Comment *why*, not *what*.
+- Delete commented-out code. That is what version control is for.
+- Use TODO/FIXME with ticket references: `// TODO(PROJ-123): migrate to v2`.
+- Document public APIs with doc comments (JSDoc, docstrings, etc.).
+
+## Formatting
+- Use project formatter (Prettier, Black, gofmt, rustfmt). No manual formatting debates.
+- Consistent indentation: follow project convention (spaces vs tabs, width).
+- Max line length: 80-120 characters depending on language convention.
+- Trailing commas in multi-line structures (where language supports).
+
+## Surgical Changes
+- Touch only what the task requires. Every changed line should trace to the request.
+- Match existing style, even if you would do it differently.
+- Do not "improve" adjacent code, comments, or formatting unprompted.
+- Orphan cleanup: remove imports/variables/functions that YOUR changes made unused.
+
+## No Dead Code (Constitution Art. VI.1)
+- When a refactor leaves a file, class, function, import, l10n key, or variable unused, DELETE it in the same change. Verify via grep that zero references remain in the repo.
+- This applies to pre-existing code too, if your work makes its unusedness verifiable. "Legacy", "separate refactor", "out of scope", or "świadome pominięcie" are NOT valid excuses.
+- Before claiming the task done: grep for every symbol you removed or renamed; fix orphaned references.
+
+## Fix Every Found Bug (Constitution Art. VI.2)
+- A bug, missing test for changed behavior, or stale doc discovered while working on a task MUST be fixed in the same change — not deferred to "second step", "separate PR", or "świadome pominięcie".
+- When behavior changes, update integration AND unit tests AND the affected docs alongside. A unit test on a new helper is not sufficient when the behavior is exposed over an API — add the integration test too.
+- Legitimate deferral exists ONLY when: (a) the fix requires a user decision — in that case, surface it explicitly and ask, don't bury in a summary; or (b) the issue is genuinely unrelated to the current change surface.
+- Before marking done: re-read the diff and confirm no orphaned references, no missing test coverage for changed paths, no stale docs. If any are present, keep working.
+
+## Goal-Driven Execution
+- Transform vague tasks into verifiable goals before starting.
+- For multi-step work, state a brief plan with verification per step:
+  `1. [Step] → verify: [check]`
+- Strong success criteria enable independent looping. Weak criteria ("make it work") require clarification — ask first.
+
+## JSON Wire Format Conventions
+- Field names (keys): `camelCase`. Aligns with JSON:API spec, Google JSON Style Guide, and framework defaults (Symfony Serializer, Spring Jackson, `json_serializable` for Dart). No public major API uses `snake_case` keys in modern designs except ecosystem-bound cases (Rails/Django APIs defaulting to ecosystem convention).
+- Enum / status / permission / domain values: `UPPER_SNAKE_CASE`. Community consensus: [Protocol Buffers style guide](https://protobuf.dev/programming-guides/style/) (mandatory), [Google AIP-126 / api-linter](https://linter.aip.dev/126/upper-snake-values) (enforced), [Zalando Rule #240](https://opensource.zalando.com/restful-api-guidelines/), Java/Kotlin/C++/Python enum convention. `lowercase snake_case` (Stripe-style) is a legitimate outlier but not consensus.
+- Avoid `camelCase` for enum values — no major public API uses it, loses visual distinction between keys and values.
+- Pick one convention per project and enforce it with a CI grep gate. Mixing conventions inside a single API surface is the worst outcome.
+- External contracts (Stripe, GitHub, webhooks you receive) follow their own convention — map to your project convention at the adapter boundary, do not leak their keys past it.
+
+## Anti-Patterns to Avoid
+- God classes/modules with 500+ lines and multiple responsibilities.
+- Deep nesting (>3 levels): use early returns and extract functions.
+- Magic numbers/strings: use named constants.
+- Mutable global state: use dependency injection instead.
+
+## Source: `app/rules/common/git-workflow.md`
+
+# Git Workflow Rules
+
+## Commit Messages
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
+- First line: imperative mood, max 72 chars (`feat: add user registration endpoint`).
+- Body (optional): explain *why*, not *what*. The diff shows what.
+- Reference tickets: `fix: prevent duplicate orders (PROJ-456)`.
+
+## Commit Practices
+- Commit small, atomic changes. One commit = one logical change.
+- Never commit: secrets, `.env` files, build artifacts, large binaries.
+- Never commit broken code to `main`. Use feature branches.
+- Squash fixup commits before merging to keep history clean.
+
+## Branching
+- `main` is always deployable. Protect it with required reviews and CI.
+- Feature branches: `feat/user-registration`, `fix/order-total-calc`.
+- Delete branches after merge. Stale branches are clutter.
+- Rebase feature branches on main before PR to keep linear history.
+
+## Pull Requests
+- Keep PRs small: <400 lines changed. Split large features into stacked PRs.
+- PR title follows conventional commit format.
+- Include: summary, test plan, and screenshots/recordings for UI changes.
+- Require at least one approval before merge.
+
+## Code Review
+- Review for: correctness, security, performance, readability.
+- Approve with comments if nits only. Block for: bugs, security, missing tests.
+- Respond to reviews within 24 hours. Do not let PRs rot.
+
+## Tags and Releases
+- Use semantic versioning: MAJOR.MINOR.PATCH.
+- Tag releases: `git tag v1.2.3`. Automate changelog from commits.
+
+## Recovery
+- Use `git stash` for WIP, not unfinished commits.
+- Prefer `git revert` over `git reset --hard` on shared branches.
+- Never force-push to `main` or shared branches.
+
+## Source: `app/rules/common/performance.md`
+
+# Universal Performance Rules
+
+## Mindset
+- Profile before optimizing. Measure, do not guess.
+- Premature optimization is the root of all evil. Ship correct first, fast second.
+- Set performance budgets and test against them in CI.
+
+## Database
+- Fix N+1 queries: use JOINs, eager loading, or batch fetching.
+- Add indexes for columns used in WHERE, ORDER BY, and JOIN clauses.
+- Use EXPLAIN/ANALYZE to verify query plans. Avoid full table scans.
+- Paginate all list endpoints. Never return unbounded result sets.
+- Use connection pooling. Never open a new connection per request.
+
+## Caching
+- Cache at the right layer: CDN > reverse proxy > application > database.
+- Set explicit TTLs. Stale cache is worse than no cache.
+- Cache immutable or slowly-changing data. Avoid caching user-specific mutable data.
+- Use cache-aside pattern: check cache, fetch on miss, populate cache.
+- Include cache invalidation strategy before adding any cache.
+
+## I/O and Network
+- Async/non-blocking for I/O-bound work. Thread pools for CPU-bound work.
+- Batch operations where possible: bulk inserts, batch API calls.
+- Set timeouts on all external calls: HTTP, database, message queues.
+- Use streaming for large payloads instead of loading everything into memory.
+
+## Memory
+- Preallocate collections when size is known.
+- Use streaming/iterators for large datasets instead of loading all into memory.
+- Watch for memory leaks: unclosed connections, growing caches, event listener accumulation.
+- Avoid unnecessary copies/clones of large data structures.
+
+## API Performance
+- Compress responses (gzip/brotli). Return only requested fields.
+- Use HTTP/2 or HTTP/3 where supported.
+- Implement request deduplication for identical concurrent requests.
+- Return 202 Accepted for long-running operations, process async.
+
+## Monitoring
+- Track p50, p95, p99 latencies, not just averages.
+- Alert on latency regressions, not just errors.
+- Log slow queries (>100ms) and slow endpoints (>500ms).
+
+## Source: `app/rules/common/security.md`
+
+# Universal Security Rules
+
+## Input Validation
+- Validate ALL input at API boundaries. Trust nothing from clients.
+- Use allowlists over denylists: define what IS valid, reject everything else.
+- Validate type, length, format, and range for every input field.
+- Sanitize output for the target context (HTML, SQL, shell, URL).
+
+## Authentication
+- Hash passwords with bcrypt, scrypt, or argon2. Never MD5/SHA for passwords.
+- Use constant-time comparison for tokens and secrets.
+- Implement rate limiting on auth endpoints (login, register, password reset).
+- Enforce MFA for admin and sensitive operations.
+
+## Authorization
+- Check permissions on every request, not just at the UI level.
+- Use principle of least privilege: default deny, explicitly grant.
+- Validate resource ownership: user can only access their own data.
+- Never rely on client-side authorization checks.
+
+## Secrets Management
+- Never hardcode secrets in source code. Use environment variables or vaults.
+- Rotate secrets regularly. Automate rotation where possible.
+- Use different secrets per environment (dev/staging/prod).
+- Add `.env` to `.gitignore`. Use `.env.example` as a template.
+
+## SQL Injection Prevention
+- Always use parameterized queries or ORM query builders.
+- Never concatenate user input into SQL strings.
+- Validate and cast types before using in queries.
+
+## XSS Prevention
+- Escape all dynamic content rendered in HTML.
+- Use Content Security Policy (CSP) headers.
+- Set `HttpOnly` and `Secure` flags on authentication cookies.
+- Avoid `innerHTML`, `eval()`, and `dangerouslySetInnerHTML`.
+
+## API Security
+- Use HTTPS everywhere. No exceptions.
+- Implement rate limiting and request throttling.
+- Set CORS headers explicitly. Never use `*` in production.
+- Return generic error messages to clients. Log details server-side.
+- Use security headers: HSTS, X-Content-Type-Options, X-Frame-Options.
+
+## Dependencies
+- Audit dependencies regularly (`npm audit`, `pip-audit`, `cargo audit`).
+- Pin dependency versions. Use lockfiles.
+- Remove unused dependencies. Each dependency is an attack surface.
+
+## Logging
+- Never log passwords, tokens, credit cards, or PII.
+- Log security events: failed logins, permission denials, input validation failures.
+- Use structured logging with correlation IDs for traceability.
+
+## Source: `app/rules/common/testing.md`
+
+# Universal Testing Rules
+
+## Test Structure
+- Use Arrange-Act-Assert (AAA) pattern in every test.
+- One logical assertion per test. Multiple `assert` calls are fine if testing one behavior.
+- Test names describe behavior: `test_returns_404_when_user_not_found`.
+- Keep tests independent: no shared mutable state between tests.
+
+## Test Organization
+- Mirror source structure: `src/auth/login.ts` -> `tests/auth/login.test.ts`.
+- Separate unit, integration, and e2e tests into distinct directories or markers.
+- Shared fixtures go in `conftest.py`, `test-utils.ts`, or equivalent.
+
+## What to Test
+- Test behavior, not implementation. Tests should survive refactors.
+- Cover: happy path, error cases, edge cases, boundary values.
+- New code: 100% coverage. Overall project: >70%.
+- Critical paths (auth, payments, data mutations): always tested.
+
+## What NOT to Test
+- Framework internals (ORM save, HTTP library send).
+- Trivial getters/setters with no logic.
+- Third-party library correctness.
+- Private methods directly: test through public API.
+
+## Mocking
+- Mock at boundaries: HTTP clients, databases, file systems, clocks.
+- Prefer fakes over mocks when logic is complex.
+- Never mock the thing you are testing.
+- Reset mocks between tests to prevent leakage.
+
+## Test Quality
+- Tests must be deterministic: no flaky tests allowed.
+- Tests must be fast: unit tests <100ms each, test suite <60s.
+- Avoid `sleep` in tests: use polling, events, or test clocks.
+- Do not test implementation details (private methods, internal state).
+
+## Coverage
+- Measure coverage but do not chase 100%: focus on critical paths.
+- Coverage gaps in error handling and edge cases are worse than gaps in happy paths.
+- New PRs must not decrease overall coverage.
+
+## Test Data
+- Use factories/builders to create test data, not raw constructors.
+- Keep test data minimal: only set fields relevant to the test.
+- Do not share mutable test data across tests.
+- Use realistic but not real data (no production data in tests).

package/app/hooks/config-desync-guard.sh

@@ -25,39 +25,79 @@ SOURCE="$TOOLKIT_DIR/app/hooks.json"
 [ -f "$SETTINGS" ] || exit 0
 [ -f "$SOURCE" ] || exit 0
 
-# Compare the set of ai-toolkit-tagged commands in each file.
+# Compare canonical behavior, accepting older/current settings where Claude has
+# rewritten the JSON without preserving the private `_source` marker.
+DIFF_STATUS=0
 DIFF=$(python3 - "$SETTINGS" "$SOURCE" <<'PY'
 import json
 import sys
 
 
-def toolkit_commands(path):
+def without_source(value):
+    if isinstance(value, dict):
+        return {
+            key: without_source(item)
+            for key, item in value.items()
+            if key != "_source"
+        }
+    if isinstance(value, list):
+        return [without_source(item) for item in value]
+    return value
+
+
+def signature(entry):
+    return json.dumps(without_source(entry), sort_keys=True, separators=(",", ":"))
+
+
+def load_hooks(path):
     try:
         data = json.load(open(path))
     except Exception:
-        return set()
-    hooks = data.get("hooks", {}) if isinstance(data, dict) else {}
+        return {}
+    return data.get("hooks", {}) if isinstance(data, dict) else {}
+
+
+def entry_commands(event, entry):
     out = set()
-    for event, entries in hooks.items():
-        if not isinstance(entries, list):
-            continue
-        for entry in entries:
-            if not isinstance(entry, dict):
-                continue
-            tagged_top = entry.get("_source") == "ai-toolkit"
-            for hook in entry.get("hooks", []):
-                if not isinstance(hook, dict):
-                    continue
-                tagged_inner = hook.get("_source") == "ai-toolkit"
-                if not (tagged_top or tagged_inner):
-                    continue
-                cmd = hook.get("command", "")
-                out.add((event, entry.get("matcher", ""), cmd))
+    for hook in entry.get("hooks", []):
+        if isinstance(hook, dict):
+            out.add((event, entry.get("matcher", ""), hook.get("command", "")))
     return out
 
 
-installed = toolkit_commands(sys.argv[1])
-source = toolkit_commands(sys.argv[2])
+installed_hooks = load_hooks(sys.argv[1])
+source_hooks = load_hooks(sys.argv[2])
+source_signatures = {
+    event: {
+        signature(entry)
+        for entry in entries
+        if isinstance(entry, dict)
+    }
+    for event, entries in source_hooks.items()
+    if isinstance(entries, list)
+}
+
+source = set()
+for event, entries in source_hooks.items():
+    if not isinstance(entries, list):
+        continue
+    for entry in entries:
+        if isinstance(entry, dict):
+            source.update(entry_commands(event, entry))
+
+installed = set()
+for event, entries in installed_hooks.items():
+    if not isinstance(entries, list):
+        continue
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        tagged = entry.get("_source") == "ai-toolkit" or any(
+            isinstance(hook, dict) and hook.get("_source") == "ai-toolkit"
+            for hook in entry.get("hooks", [])
+        )
+        if tagged or signature(entry) in source_signatures.get(event, set()):
+            installed.update(entry_commands(event, entry))
 
 missing = source - installed  # in source, not installed (toolkit got new hooks)
 extra = installed - source    # in installed, not source (stale toolkit hook)
@@ -75,9 +115,9 @@ if extra:
         print(f"    - [{event}] {cmd}")
 sys.exit(1)
 PY
-)
+) || DIFF_STATUS=$?
 
-if [ $? -ne 0 ] && [ -n "$DIFF" ]; then
+if [ "$DIFF_STATUS" -ne 0 ] && [ -n "$DIFF" ]; then
     cat >&2 <<EOF
 config-desync-guard: ai-toolkit hooks drifted from source manifest.
 

package/app/plugins/README.md

@@ -10,10 +10,13 @@ They serve three purposes:
 3. give `plugin-creator` a concrete scaffold to follow.
 
 Plugin packs can target:
-- Claude global runtime via `ai-toolkit plugin install --editor claude <name>`
+- Claude Code global runtime via `ai-toolkit plugin install --editor claude <name>`
 - Codex global plugin layer via `ai-toolkit plugin install --editor codex <name>`
 - both runtimes via `ai-toolkit plugin install --editor all <name>`
 
+These packs are not directly uploadable Claude app plugins. For Claude Chat,
+Desktop, and Cowork use `ai-toolkit claude-app export`.
+
 Current packs:
 - `security-pack`
 - `research-pack`

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 |