Add "lessons/patterns/agent-model-field-not-supported-by-claude-code"

lessons%2Fpatterns%2Fagent-model-field-not-supported-by-claude-code.-.md

@@ -0,0 +1,53 @@
+# Agent `model:` Field Not Supported by Claude Code
+
+## Date
+2026-02-02
+
+## Summary
+
+Claude Code does NOT support the `model:` field in agent YAML frontmatter. Adding this field causes plugins to fail loading with "1 error".
+
+## What Happened
+
+1. Sprint 7 (v5.4.0) on 2026-01-28: Added `model:` field to agent frontmatter and `defaultModel` to plugin.json
+2. 2026-01-30: Reverted in v5.4.1 because Claude Code rejected these as "Unrecognized key"
+3. 2026-02-02: **STUPIDLY re-added** `model: sonnet/haiku` to all 25 agents claiming it was "now supported"
+4. Result: projman and other plugins failed to load
+
+## Root Cause
+
+Claude Code's plugin schema does NOT recognize `model:` in agent frontmatter. The validation error is silent in the UI - it just shows "failed to load · 1 error" without explaining why.
+
+## The Fix
+
+Remove ALL `model:` fields from agent frontmatter:
+
+```bash
+for f in plugins/*/agents/*.md; do
+  sed -i '/^model:/d' "$f"
+done
+```
+
+## Lesson
+
+**DO NOT add fields to plugin manifests or agent frontmatter without VERIFYING they are supported by Claude Code's schema.**
+
+The revert commit from January 30th (`11d77eb`) explicitly documented this limitation. I ignored my own lesson and wasted hours debugging.
+
+## Valid Agent Frontmatter Fields
+
+Only these are supported:
+- `name:` (required)
+- `description:` (required)
+
+That's it. Nothing else.
+
+## Prevention
+
+Before adding ANY new field to plugin.json or agent frontmatter:
+1. Check Claude Code documentation
+2. Test with a minimal plugin first
+3. If it was reverted before, DON'T ADD IT BACK without explicit confirmation it's now supported
+
+---
+**Tags:** agents, frontmatter, plugin-loading, schema-validation