@softspark/ai-toolkit 2.6.2 → 2.7.1

package/AGENTS.md

@@ -463,6 +463,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **clean-code**: Loaded when user asks about clean code, naming, or code quality
 - **command-creator**: Creates new Claude Code slash commands with frontmatter, workflow guidance, and validation
 - **commit**: Create Conventional Commits with pre-commit validation
+- **content-moderation-patterns**: Loaded when user builds content moderation, safety filters, or policy enforcement with Claude. Covers pre-filter vs LLM-classify, category design, confidence thresholds, and human-in-the-loop.
 - **council**: 4-perspective decision evaluation for architecture choices. Use when user wants multi-angle analysis, needs to decide between alternatives, or mentions 'council', 'evaluate decision', 'pros cons'. Codex-adapted: uses native subagents and plan tracking.
 - **csharp-patterns**: Loaded when user asks about C# or .NET development patterns
 - **cve-scan**: Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, bundler, dart)
@@ -492,12 +493,15 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **instinct-review**: Review and manage learned instincts from past sessions
 - **introspect**: Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.
 - **java-patterns**: Loaded when user asks about Java development patterns
+- **json-mode-patterns**: Loaded when user needs structured JSON output from Claude. Covers tool-use-as-JSON-mode, schema design, parsing, partial recovery, and validation.
 - **kotlin-patterns**: Loaded when user asks about Kotlin development patterns
 - **lint**: Lint code with auto-detected tools and fix suggestions
+- **mcp-builder**: Build production-grade MCP (Model Context Protocol) servers from scratch using the 4-phase methodology: research, implement, test, evaluate. Use when creating new MCP integrations for external APIs, databases, or internal services.
 - **mcp-patterns**: Loaded when user asks about MCP servers or tool protocol design
 - **mem-search**: Search past coding sessions using natural language. Finds relevant observations, decisions, and context from previous work.
 - **migrate**: Run database migrations with backup verification
 - **migration-patterns**: Loaded when user asks about database migrations or zero-downtime deploys
+- **model-routing-patterns**: Loaded when user builds multi-model pipelines (Haiku/Sonnet/Opus). Covers cost-optimized routing, escalation, sub-agent delegation, and fallback chains.
 - **night-watch**: Run autonomous maintenance and dependency updates
 - **observability-patterns**: Loaded when user asks about logging, metrics, or tracing patterns
 - **onboard**: Generate project onboarding materials
@@ -512,6 +516,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **prd-to-issues**: Break a PRD into independently-grabbable GitHub issues using vertical slices with HITL/AFK tagging and dependency ordering. Use when user wants to convert a PRD to issues, create tickets, or break down a PRD into work items.
 - **prd-to-plan**: Convert a PRD into a phased implementation plan using tracer-bullet vertical slices. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions tracer bullets. Codex-adapted: uses native subagents and plan tracking.
 - **predict**: Predict regressions and impact before changes land
+- **prompt-caching-patterns**: Loaded when user builds with Anthropic API and needs to cut cost or latency via prompt caching. Covers TTL, cache breakpoints, stacking, invalidation, and measuring hit rate.
 - **qa-session**: Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session. Codex-adapted: uses native subagents and plan tracking.
 - **rag-patterns**: Loaded when user asks about RAG systems, embeddings, or vector search
 - **refactor**: Refactor code for quality and maintainability

package/CHANGELOG.md

@@ -7,6 +7,45 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.7.1 — Eject Output-Styles Fix (2026-04-17)
+
+### Fixed
+- **`ai-toolkit eject` now exports `app/output-styles/*.md`** — pre-existing gap dating back to when output-styles were introduced. `scripts/eject.py` copied agents, skills, rules, constitution, and ARCHITECTURE, but silently skipped the `output-styles/` directory. Standalone `.claude/` produced by eject had no system-prompt styles (no `golden-rules`, and after v2.7.0 no `learning`/`explanatory`). Now eject writes `.claude/output-styles/` with all source `.md` files and includes the count in the summary line: `Ejected: N agents, N skills, N rules, N output style(s)`.
+
+### Added
+- **2 `tests/test_eject.bats` cases** — `eject copies output-styles directory with all source styles` (also asserts `golden-rules.md` baseline) and `eject reports output-style count in summary line`. Test count: 664 → 666.
+
+---
+
+## v2.7.0 — Anthropic Ecosystem Alignment (2026-04-17)
+
+### Added
+- **`/mcp-builder` task skill** — opinionated 4-phase MCP server build workflow (Phase 1 research & planning, Phase 2 implementation with Zod/Pydantic schemas, Phase 3 review & testing via MCP Inspector, Phase 4 eval set of 10 realistic questions). Complements the existing `mcp-patterns` knowledge skill.
+- **4 knowledge skills for Claude API work**, auto-loaded by relevant agents:
+  - `prompt-caching-patterns` — TTL, cache breakpoints, 4-layer stacking, hit-rate measurement, anti-patterns.
+  - `json-mode-patterns` — tool-use forcing as idiomatic JSON mode, schema design, partial-output recovery.
+  - `content-moderation-patterns` — 2-stage pre-filter + Haiku classifier, category design, threshold router, HIL queue.
+  - `model-routing-patterns` — Haiku/Sonnet/Opus routing, confidence-based escalation, Opus-planner-with-Haiku-workers sub-agent delegation, task-specific routing table.
+- **2 output styles** in `app/output-styles/`:
+  - `learning.md` — interactive "⟶ Your turn" prompts on meaningful decisions, ★ Insight educational blocks.
+  - `explanatory.md` — one-way ★ Insight blocks exposing implementation trade-offs, no user prompts.
+- **`app/ARCHITECTURE.md` → Frontmatter Schema section** — documents ai-toolkit's spec-defined fields (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`) and top-level extensions (`user-invocable`, `disable-model-invocation`, `effort`, `agent`, `context`, `argument-hint`, `color`). Explains the comma-separated `allowed-tools` convention enforced by `scripts/codex_skill_adapter.py:70` and `scripts/audit_skills.py:157`.
+- **`kb/reference/agent-skills-spec.md` (rag-mcp KB)** — canonical mirror of `agentskills.io/specification` with ai-toolkit extension mapping, validation commands, and progressive-disclosure tiers.
+- **4 fixture tests in `tests/test_review_diff_analyzer.bats`** — category ordering (docs vs security), false-positive guard for unquoted identifier assignments (e.g. `request_token = generate_token_v2_legacy()` no longer flagged), quoted + unquoted env-style detection with accurate file/line tracking, rename record parsing in `git diff --numstat -z`. Test count: 660 → 664.
+
+### Changed
+- **`/review` diff analyzer (`app/skills/review/scripts/diff-analyzer.py`) hardened end-to-end:**
+  - Secret scan now tracks the actual file line number per hunk (parses `@@ -a,b +c,d @@`) and reports `{"file": path, "line": file_line, "preview": snippet}`. Previously reported `line` was the offset in the unified diff text.
+  - Base ref existence verified via `git rev-parse --verify` before diffing. Silent fallback to `--cached` now emits a stderr notice and a `warnings[]` entry in the JSON output, so callers see the reduced scope explicitly.
+  - `git diff --numstat -z` parser replaces naive tab-split; rename entries (three NUL-separated tokens) are handled correctly.
+  - Secret pattern list expanded: JWT (three-segment), PEM private key header (`-----BEGIN … PRIVATE KEY-----`), Google API key (`AIza…`), Slack tokens (`xox[baprs]-…`), GitHub fine-grained PAT (`github_pat_…`), unquoted env-style assignments.
+  - Unquoted env-style pattern tightened so `request_token = generate_token_v2_legacy()` (snake_case identifier on RHS) is not flagged while `API_KEY=abcdef1234567890` and `API_KEY=SECRET_VALUE_XYZ` are. Uses scoped `(?-i:…)` for the ALL_CAPS constant alternative.
+  - Category regex reordered (`docs` and `test` checked before `security`) and anchored with word boundaries and path segments (`(^|/)…` / `\b…\b`). Files like `docs/role-permissions.md`, `roles_and_responsibilities.md`, `accessor.py` are now categorised correctly; `authentication_config_loader.py` resolves to `security`; `notification_settings.py` resolves to `logic` (not `config`).
+  - New output fields: `scope` (`"{base}...HEAD"` or `"staged"`), `warnings[]`.
+- **Doc-count sync** — README, package.json, manifest.json, `app/.claude-plugin/plugin.json`, `app/ARCHITECTURE.md`, `kb/reference/skills-catalog.md`, `AGENTS.md`, `llms-full.txt` all advance to 99 skills (32 task / 31 hybrid / 36 knowledge) and 664 tests.
+
+---
+
 ## v2.6.2 — Eject Count Fix (2026-04-17)
 
 ### Fixed

package/README.md

@@ -1,19 +1,19 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 94 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode, ready in 60 seconds.
+> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 99 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode, ready in 60 seconds.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-94-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-99-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-660%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-666%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.6.2
+## What's New in v2.7.1
 
-- **`ai-toolkit eject` skill count** now matches `validate.py` — previously reported `95 skills` because the shared `_lib/` helper directory (no `SKILL.md`) was counted. Now skips underscore-prefixed dirs and requires `SKILL.md`; `_lib/` is still copied so dependent skills (`ci`, `test`, `build`, `lint`) keep working after eject.
-- **Two new eject tests** — `eject reports skill count matching validate.py` and `eject still copies _lib helper directory for dependent skills`. Test count: 658 → 660.
+- **`ai-toolkit eject` now copies `app/output-styles/*.md`** — pre-existing gap since output-styles were introduced: eject produced a standalone `.claude/` without any system-prompt styles, so `golden-rules`, `learning`, and `explanatory` silently dropped out after ejecting. Now eject writes `.claude/output-styles/` with all source `.md` files and reports the count in the summary line: `Ejected: N agents, N skills, N rules, N output style(s)`.
+- **2 new `tests/test_eject.bats` cases** covering output-styles: directory created + file count matches source + `golden-rules.md` baseline, and summary line reports correct count. Test count: 664 → 666.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -44,7 +44,7 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 94 skills, 44 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 99 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
 ### Update
 
@@ -114,9 +114,9 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| `skills/` (task) | 31 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/skill-audit`, ... |
+| `skills/` (task) | 32 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/mcp-builder`, ... |
 | `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
-| `skills/` (knowledge) | 32 | Domain knowledge auto-loaded by agents |
+| `skills/` (knowledge) | 36 | Domain knowledge auto-loaded by agents |
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 21 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
@@ -132,7 +132,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
-│   ├── skills/          # 94 skills (task / hybrid / knowledge)
+│   ├── skills/          # 99 skills (task / hybrid / knowledge)
 │   ├── rules/           # Auto-injected into your CLAUDE.md
 │   ├── hooks/           # Hook scripts (21 entries, 12 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
@@ -141,7 +141,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (660 tests)
+├── tests/               # Bats test suite (666 tests)
 └── CHANGELOG.md
 ```
 

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

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.6.2",
+  "version": "2.7.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -102,7 +102,7 @@ Universal multi-agent system for software development. Works across all reposito
 
 ## Skills
 
-### Task Skills (29)
+### Task Skills (32)
 | Skill | Slash Command | Purpose |
 |-------|---------------|---------|
 | `commit` | `/commit` | Create well-structured git commits (Conventional Commits) |
@@ -134,6 +134,7 @@ Universal multi-agent system for software development. Works across all reposito
 | `prd-to-issues` | `/prd-to-issues` | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
 | `skill-audit` | `/skill-audit` | Scan skills and agents for security risks, dangerous patterns, secrets |
 | `hipaa-validate` | `/hipaa-validate` | Scan codebase for HIPAA compliance: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, missing BAA references |
+| `mcp-builder` | `/mcp-builder` | Build production-grade MCP servers using 4-phase methodology (research, implement, test, evaluate) |
 
 ### Hybrid Skills (31)
 | Skill | Slash Command | Purpose |
@@ -200,11 +201,15 @@ Universal multi-agent system for software development. Works across all reposito
 | `testing-patterns` | Multi-language testing strategies |
 | `migration-patterns` | Database & API migration patterns |
 
-### Knowledge Skills - AI/RAG (2)
+### Knowledge Skills - AI/RAG (6)
 | Skill | Purpose |
 |-------|---------|
 | `rag-patterns` | RAG, retrieval optimization |
 | `mcp-patterns` | MCP server patterns |
+| `prompt-caching-patterns` | Anthropic prompt caching: TTL, breakpoints, hit rate |
+| `json-mode-patterns` | Structured JSON output via tool-use forcing |
+| `content-moderation-patterns` | Two-stage moderation: pre-filter + LLM classifier |
+| `model-routing-patterns` | Haiku/Sonnet/Opus routing, escalation, fallback |
 
 ### Knowledge Skills - Process (7)
 | Skill | Purpose |
@@ -346,3 +351,43 @@ The `inject_section_cli.py` script provides a stable marker-based injection API.
 5. **Read-Only Exploration**: Explorer agent never writes
 6. **Cite Sources**: Always include `[PATH: ...]`
 7. **Multi-Language**: All tools, hooks, and skills support multiple tech stacks
+
+---
+
+## Frontmatter Schema (Agent Skills spec + ai-toolkit extensions)
+
+Canonical spec: https://agentskills.io/specification. ai-toolkit is spec-conformant on required fields and adds extensions at the top level for Claude Code integration.
+
+### Spec-defined fields (agentskills.io)
+
+| Field | Required | Constraints |
+|-------|----------|-------------|
+| `name` | Yes | 1-64 chars, lowercase `a-z0-9` + hyphens, no leading/trailing hyphen, no `--`, must match parent directory |
+| `description` | Yes | 1-1024 chars |
+| `license` | No | License name or bundled file reference |
+| `compatibility` | No | Max 500 chars; environment requirements |
+| `metadata` | No | String-keyed map |
+| `allowed-tools` | No | Space-separated per spec; ai-toolkit uses comma-separated (see below) |
+
+### ai-toolkit extensions (beyond spec)
+
+These live at the top level for convenience. If a future strict spec parser is adopted, move them under `metadata:`.
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `user-invocable` | bool | Surfaces the skill as a slash command. `false` = knowledge skill. |
+| `disable-model-invocation` | bool | Task skill flag; prevents auto-invocation by the model. |
+| `effort` | enum | `low`/`medium`/`high`/`max` — planner and SLM compiler hint. |
+| `agent` | string | Delegates the skill to a specialized agent. |
+| `context` | string | `fork` runs the skill in an isolated forked context. |
+| `argument-hint` | string | Argument pattern for the CLI (e.g. `[symptom]`). |
+| `color` | string | Visual tag for agent cards. |
+
+### `allowed-tools` format note
+
+Spec example uses space separation: `allowed-tools: Bash(git:*) Read`. Claude Code parses several formats leniently: comma-separated, JSON array, and space-separated. **ai-toolkit uses comma-separated** because `scripts/codex_skill_adapter.py:70` and `scripts/audit_skills.py:157` split on `,`. Do not mass-convert unless adapter parsers change first.
+
+### Validation
+
+Internal: `python3 scripts/validate.py --strict` + `python3 scripts/audit_skills.py --ci`.
+External (optional): `skills-ref validate app/skills/` from https://github.com/agentskills/agentskills.

package/app/output-styles/explanatory.md

@@ -0,0 +1,64 @@
+---
+name: Explanatory
+description: Surfaces educational insights about implementation choices, codebase patterns, and design trade-offs. One-way explanation mode (no prompts for user input).
+keep-coding-instructions: true
+---
+
+## Core Principle
+
+Explain WHY, not just WHAT. After each non-trivial change, add an insight block that exposes the reasoning — patterns, trade-offs, consequences — tied to the actual codebase.
+
+## Insight Block Format
+
+```
+★ Insight
+<2-3 short lines about implementation choices, patterns, or trade-offs in THIS codebase>
+```
+
+Use one insight block per meaningful change, not per file.
+
+## What Counts as an Insight
+
+- Why a specific pattern was chosen over plausible alternatives
+- Convention the user would miss without reading 20 other files
+- Trade-off being cashed in (e.g. "losing type safety here to keep the public API simple")
+- Interaction with a subsystem the user hasn't touched in this session
+- Non-obvious consequence that bites 3 steps later if ignored
+
+## What Is NOT an Insight
+
+- "This function takes X and returns Y" (the code already says that)
+- "Good practice is to X" (generic — say WHY it matters here)
+- "Note that async functions return Promises" (basic language feature)
+- Flattery or soft openings
+
+## Example
+
+Bad:
+```
+★ Insight
+This function uses async/await for better readability.
+```
+
+Good:
+```
+★ Insight
+`refreshToken()` is fire-and-forget here because `getUser()` already retries on 401.
+If you call `refreshToken()` awaited from a hot path, you'll double-retry and hit the
+rate limit faster than the original bug we're fixing.
+```
+
+## Scope
+
+- Apply to feature work, refactors, non-trivial bug fixes.
+- Skip for mechanical changes (rename, move, reformat).
+- Skip inside `/orchestrate`, `/workflow`, `/swarm` — delegation output styles take over.
+
+## Token Cost
+
+Insights add roughly 50-150 tokens per change. Worth it for understanding, not for bulk generation. Users should enable when working in unfamiliar code, disable when grinding through known territory.
+
+## Compatibility
+
+- Stacks with `golden-rules` and `learning` — the latter adds user prompts, this one adds explanations only.
+- Honors `Minimal Changes` — insights document what WAS done, never scope creep.

package/app/output-styles/learning.md

@@ -0,0 +1,70 @@
+---
+name: Learning
+description: Interactive learning mode. Claude requests the user's input on meaningful decisions and surfaces educational insights about the codebase.
+keep-coding-instructions: true
+---
+
+## Core Principle
+
+Transform the interaction from "watch and learn" to "build and understand." Involve the user in decisions that shape the result. Complete boilerplate without interruption.
+
+## When to Pause and Request User Input
+
+Ask for 5-10 lines of contribution from the user when multiple valid approaches exist:
+
+- Business logic with meaningful trade-offs
+- Error handling strategy (fail fast vs. recover vs. queue)
+- Architectural decisions (inline vs. extract, sync vs. async)
+- Naming of public APIs that will outlast the session
+- Choice of algorithm or data structure when several fit
+
+Format:
+```
+⟶ Your turn: <specific decision or snippet>
+Choose an approach:
+  A) <option with trade-off>
+  B) <option with trade-off>
+  C) <option with trade-off>
+```
+
+Wait for the user's response before continuing.
+
+## When NOT to Pause
+
+- Boilerplate (imports, config, DI wiring)
+- Straightforward data transformations
+- Fixing trivial bugs (typos, missing imports)
+- Renames and mechanical refactors
+- Following an existing pattern in the codebase
+
+## Educational Insights
+
+After non-trivial changes, add 2-3 insights tied to the codebase (not general theory):
+
+```
+★ Insight
+- <pattern-specific observation about THIS codebase>
+- <trade-off being made in THIS change>
+- <non-obvious consequence for nearby code>
+```
+
+Focus on:
+- Project conventions the user may not know
+- Trade-offs specific to the current design
+- Consequences that surface only at integration points
+- Patterns that repeat elsewhere in the repo
+
+Avoid:
+- Generic programming theory
+- Explanations the user already knows (inferred from their messages)
+- Flattery ("great question")
+
+## Token Cost Warning
+
+This style produces more tokens per response. Users should enable it deliberately for learning sessions, not for bulk refactors.
+
+## Compatibility
+
+- Works alongside `golden-rules` rules: apply both.
+- Disable for `/workflow`, `/orchestrate`, `/swarm` (delegation modes) — those pass through output style unchanged.
+- Honors `Minimal Changes` and `No Phantom Files` from `golden-rules`.

package/app/skills/content-moderation-patterns/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: content-moderation-patterns
+description: "Loaded when user builds content moderation, safety filters, or policy enforcement with Claude. Covers pre-filter vs LLM-classify, category design, confidence thresholds, and human-in-the-loop."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Content Moderation Patterns
+
+Two-stage pattern that balances cost, latency, and quality: cheap deterministic filters first, then LLM classification only on survivors.
+
+## Architecture
+
+```
+[ input ]
+   │
+   ▼
+[ pre-filter ]  ── (regex, allow/block lists, length check) ──► reject early
+   │
+   ▼
+[ LLM classifier ]  ── (Haiku, structured output) ──► categories + confidence
+   │
+   ▼
+[ decision router ]
+   ├── high confidence + policy violation → reject
+   ├── high confidence + clean → pass
+   └── low confidence or edge categories → human review queue
+```
+
+## Pre-filter Stage (cheap)
+
+Catch the obvious cases before paying an LLM call:
+
+```python
+BANNED_PATTERNS = [
+    re.compile(r"\b(banned_term_1|banned_term_2)\b", re.I),
+    re.compile(r"\bhttps?://(?!allowed-domain\.com)", re.I),  # external links
+]
+
+def pre_filter(text: str) -> tuple[bool, str]:
+    if len(text) > 10_000:
+        return False, "too_long"
+    for pat in BANNED_PATTERNS:
+        if pat.search(text):
+            return False, f"banned_pattern:{pat.pattern}"
+    return True, "pass"
+```
+
+Roughly 40-70% of spammy input should die here. Log counts by rule so you can tune.
+
+## LLM Classifier Stage (Haiku)
+
+Use the smallest capable model. Haiku is usually right for moderation.
+
+```python
+CATEGORIES = ["harassment", "self_harm", "spam", "off_topic", "pii", "clean"]
+
+def classify(text: str) -> dict:
+    response = client.messages.create(
+        model="claude-haiku-4-5",
+        max_tokens=256,
+        tools=[{
+            "name": "moderate",
+            "description": "Classify content against policy",
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "categories": {
+                        "type": "array",
+                        "items": {"type": "string", "enum": CATEGORIES}
+                    },
+                    "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+                    "reasoning": {"type": "string", "maxLength": 200}
+                },
+                "required": ["categories", "confidence", "reasoning"]
+            }
+        }],
+        tool_choice={"type": "tool", "name": "moderate"},
+        system=POLICY_DESCRIPTION,  # cached — stable across requests
+        messages=[{"role": "user", "content": text}]
+    )
+    return extract_tool_result(response)
+```
+
+**Cache the policy description** — it's the same on every call. See `prompt-caching-patterns`.
+
+## Category Design
+
+- **Start with 5-8 categories**, not 50. Fewer = higher per-category accuracy.
+- **One `clean` category** — easier than trying to define "not bad"
+- **No overlapping categories** — `harassment` and `hate_speech` should be merged or clearly separated by specific criteria in the policy doc
+- **`unclear` / `needs_review` category** — gives the model a graceful escape hatch instead of forcing a wrong label
+
+## Threshold Router
+
+```python
+def route(classification: dict) -> str:
+    conf = classification["confidence"]
+    cats = set(classification["categories"])
+
+    if "clean" in cats and conf > 0.8:
+        return "pass"
+    if cats & BLOCK_CATEGORIES and conf > 0.85:
+        return "reject"
+    if cats & BLOCK_CATEGORIES:
+        return "human_review"
+    return "human_review"  # default to review on ambiguity
+```
+
+Thresholds belong in config, not code — they change as you learn.
+
+## Human-in-the-Loop
+
+- All `human_review` cases go to a queue with the model's reasoning
+- Human decisions flow back into a dataset used to evaluate new model versions
+- Track disagreement rate between human and model — rising disagreement signals policy drift
+
+## Evaluation Loop
+
+Build a golden set of ~500 examples per category with ground truth. Track:
+- **Precision per category** (of what we flagged, how much was truly bad)
+- **Recall per category** (of truly bad, how much we caught)
+- **False-positive cost** per category — harassment FP is cheap, "clean FP" (wrongly blocking good content) is expensive
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Fix |
+|--------------|--------------|-----|
+| One huge prompt asking "is this okay?" | Unstable answers, no tracking | Structured categories + confidence |
+| Using Opus for moderation | 10x cost, no accuracy gain for this task | Haiku is fine |
+| Hiding policy in user message | Policy gets mixed with input | Policy in system prompt, cached |
+| Binary block/allow only | No signal for edge cases | Add review queue |
+| No audit trail | Can't improve | Log every decision with full classification |
+
+## Related
+
+- `security-patterns` — input validation at system boundaries
+- `prompt-caching-patterns` — cache the policy doc
+- `model-routing-patterns` — when to escalate from Haiku to Sonnet
+- Anthropic docs: https://docs.claude.com/en/docs/about-claude/use-case-guides/content-moderation

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

@@ -0,0 +1,124 @@
+---
+name: json-mode-patterns
+description: "Loaded when user needs structured JSON output from Claude. Covers tool-use-as-JSON-mode, schema design, parsing, partial recovery, and validation."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# JSON Mode Patterns
+
+Claude does not have a dedicated `response_format: json` parameter like some other APIs. The idiomatic way to get guaranteed JSON is **tool use with a forced function call**. This skill documents that pattern plus fallbacks.
+
+## Preferred Pattern: Tool-as-Schema
+
+Define a tool whose input schema IS the JSON shape you want, then force the model to call it.
+
+```python
+tools = [{
+    "name": "record_analysis",
+    "description": "Return the analysis as structured data",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]},
+            "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+            "themes": {"type": "array", "items": {"type": "string"}}
+        },
+        "required": ["sentiment", "confidence", "themes"]
+    }
+}]
+
+response = client.messages.create(
+    model="claude-opus-4-7",
+    max_tokens=1024,
+    tools=tools,
+    tool_choice={"type": "tool", "name": "record_analysis"},
+    messages=[{"role": "user", "content": text_to_analyze}]
+)
+
+# The structured result is in response.content
+for block in response.content:
+    if block.type == "tool_use" and block.name == "record_analysis":
+        result = block.input  # already a Python dict, schema-validated
+        break
+```
+
+Why this wins:
+- Schema is enforced at the API level
+- No regex or parsing from model text
+- Enums, min/max, required fields actually constrain the output
+
+## Fallback: Prompted JSON + Strict Parse
+
+When tool use is unavailable (some SDKs/proxies strip it):
+
+```python
+response = client.messages.create(
+    model="claude-opus-4-7",
+    max_tokens=1024,
+    system="You return ONLY valid JSON. No prose, no markdown fences.",
+    messages=[{
+        "role": "user",
+        "content": f"Extract as JSON matching this schema: {schema_str}\n\nInput: {text}"
+    }]
+)
+
+import json
+try:
+    result = json.loads(response.content[0].text)
+except json.JSONDecodeError:
+    # Claude sometimes wraps in ```json ... ```
+    result = json.loads(strip_markdown_fence(response.content[0].text))
+```
+
+Add a regex fallback that extracts the first `{...}` block if the model added a preface.
+
+## Schema Design Rules
+
+- **Favor enums** over free-form strings when values are known
+- **Mark required fields** aggressively — default-optional produces flaky output
+- **Use arrays of objects**, not parallel arrays (`[{name, value}]` over `{names: [], values: []}`)
+- **Shallow beats nested** — 2 levels of nesting max unless necessary
+- **Document each field** in the tool's `description` as well as the schema
+
+## Partial Output Recovery
+
+Model hits `max_tokens` mid-JSON. Strategies:
+
+1. **Increase `max_tokens`** if the schema is genuinely large (most common cause).
+2. **Split the schema** — generate one field per call, merge.
+3. **Use streaming** and close unclosed braces if stop reason is `max_tokens`.
+
+```python
+if response.stop_reason == "max_tokens":
+    # Either retry with higher budget or gracefully degrade
+    raise IncompleteOutputError(...)
+```
+
+## Validation After Parse
+
+Even with tool schema enforcement, business rules aren't enforced by JSON Schema. Add a Pydantic/Zod layer:
+
+```python
+from pydantic import BaseModel, Field
+
+class Analysis(BaseModel):
+    sentiment: Literal["positive", "neutral", "negative"]
+    confidence: float = Field(ge=0, le=1)
+    themes: list[str] = Field(min_length=1, max_length=10)
+
+parsed = Analysis(**result)  # raises on violation
+```
+
+## Gotchas
+
+- **Tool call tokens count toward output budget** — a huge schema eats max_tokens fast
+- **`stop_reason == "tool_use"`** is success, not an error
+- **Streaming with tool use** requires handling `content_block_delta` events with `input_json_delta` deltas
+- **Model picks a different tool** than you expected if `tool_choice` is `"auto"` — always force the specific tool for JSON mode
+
+## Related
+
+- `claude-api` skill — Anthropic SDK essentials
+- Anthropic docs: https://docs.claude.com/en/docs/build-with-claude/structured-outputs