Merge pull request 'fix(plugins): remove broken mcpServers references that broke plugin loading' (#325) from fix/remove-broken-mcp-references into development

Reviewed-on: #325

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "5.3.0"
+    "version": "5.4.0"
   },
   "plugins": [
     {
@@ -20,7 +20,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/projman/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["./.mcp.json"],
       "category": "development",
       "tags": ["sprint", "agile", "gitea", "project-management"],
       "license": "MIT"
@@ -84,7 +83,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["./.mcp.json"],
       "category": "infrastructure",
       "tags": ["cmdb", "netbox", "dcim", "ipam", "data-quality", "validation"],
       "license": "MIT"
@@ -145,7 +143,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/pr-review/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["./.mcp.json"],
       "category": "development",
       "tags": ["code-review", "pull-requests", "security", "quality"],
       "license": "MIT"
@@ -161,7 +158,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/data-platform/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["./.mcp.json"],
       "category": "data",
       "tags": ["pandas", "postgresql", "postgis", "dbt", "data-engineering", "etl"],
       "license": "MIT"
@@ -177,7 +173,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/viz-platform/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["./.mcp.json"],
       "category": "visualization",
       "tags": ["dash", "plotly", "mantine", "charts", "dashboards", "theming", "dmc"],
       "license": "MIT"
@@ -193,7 +188,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/contract-validator/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["./.mcp.json"],
       "category": "development",
       "tags": ["validation", "contracts", "compatibility", "agents", "interfaces", "cross-plugin"],
       "license": "MIT"

.mcp.json

@@ -0,0 +1,24 @@
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "/home/lmiranda/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/gitea/run.sh",
+      "args": []
+    },
+    "netbox": {
+      "command": "/home/lmiranda/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/netbox/run.sh",
+      "args": []
+    },
+    "viz-platform": {
+      "command": "/home/lmiranda/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/viz-platform/run.sh",
+      "args": []
+    },
+    "data-platform": {
+      "command": "/home/lmiranda/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/data-platform/run.sh",
+      "args": []
+    },
+    "contract-validator": {
+      "command": "/home/lmiranda/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator/run.sh",
+      "args": []
+    }
+  }
+}

CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [5.4.0] - 2026-01-28
+
+### Added
+
+#### Sprint 7: Multi-Model Agent Support
+Configurable model selection for agents with inheritance chain.
+
+**Model Configuration:**
+- Agent-level `model` field in YAML frontmatter (opus|sonnet|haiku)
+- Plugin-level `defaultModel` in plugin.json
+- Inheritance: Agent → Plugin → System default (sonnet)
+
+**Recommended Model Assignments:**
+| Model | Use Case | Agents |
+|-------|----------|--------|
+| **Opus** | Complex reasoning, security analysis | planner, code-reviewer, security-reviewer, data-analysis |
+| **Sonnet** | Implementation, coordination | orchestrator, executor, layout-builder, data-ingestion |
+| **Haiku** | Quick validation | component-check, agent-check |
+
+**Documentation:**
+- `docs/MODEL-RECOMMENDATIONS.md` - Central model selection guide
+- `docs/CONFIGURATION.md` - Added agent model configuration section
+- `CLAUDE.md` - Added model config quick reference
+
+**Agent Updates (7 files):**
+- Opus: planner, code-reviewer (projman), security-reviewer (pr-review, code-sentinel), data-analysis
+- Haiku: component-check (viz-platform), agent-check (contract-validator)
+
+**Plugin Manifest Updates (6 files):**
+- All plugins with agents now have `defaultModel: sonnet`
+- Version bumps: projman 3.3.0, pr-review 1.1.0, data-platform 1.1.0, viz-platform 1.1.0, code-sentinel 1.0.1, contract-validator 1.1.0
+
+**Validation:**
+- `scripts/validate-marketplace.sh` - Added model field validation (v5.4.0+)
+
+**Sprint Completed:**
+- Milestone: Sprint 7 - Multi-Model Agent Support
+- Issues: #302, #303, #304, #305, #306
+- PRs: #307, #308
+- Wiki: [Change V5.4.0: Multi-Model Support (Sprint 7 Implementation)](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.4.0%3A-Multi-Model-Support-%28Sprint-7-Implementation%29)
+
+---
+
 ## [5.3.0] - 2026-01-28
 
 ### Added

CLAUDE.md

@@ -1,48 +1,44 @@
 # CLAUDE.md
 
 This file provides guidance to Claude Code when working with code in this repository.
-## ⛔ MANDATORY BEHAVIOR RULES - READ FIRST
 
-**These rules are NON-NEGOTIABLE. Violating them wastes the user's time and money.**
+## ⛔ RULES - READ FIRST
 
-### 1. WHEN USER ASKS YOU TO CHECK SOMETHING - CHECK EVERYTHING
-- Search ALL locations, not just where you think it is
-- Check cache directories: `~/.claude/plugins/cache/`
-- Check installed: `~/.claude/plugins/marketplaces/`
-- Check source: `~/claude-plugins-work/`
-- **NEVER say "no" or "that's not the issue" without exhaustive verification**
+### Behavioral Rules
 
-### 2. WHEN USER SAYS SOMETHING IS WRONG - BELIEVE THEM
-- The user knows their system better than you
-- Investigate thoroughly before disagreeing
-- If user suspects cache, CHECK THE CACHE
-- If user suspects a file, READ THE FILE
-- **Your confidence is often wrong. User's instincts are often right.**
+| Rule | Summary |
+|------|---------|
+| **Check everything** | Search cache (`~/.claude/plugins/cache/`), installed (`~/.claude/plugins/marketplaces/`), and source (`~/claude-plugins-work/`) |
+| **Believe the user** | User knows their system. Investigate before disagreeing. |
+| **Verify before "done"** | Run commands, show output, check all locations. "Done" = verified working. |
+| **Show what's asked** | Don't interpret or summarize unless asked. |
 
-### 3. NEVER SAY "DONE" WITHOUT VERIFICATION
-- Run the actual command/script to verify
-- Show the output to the user
-- Check ALL affected locations
-- **"Done" means VERIFIED WORKING, not "I made changes"**
+### After Plugin Updates
 
-### 4. SHOW EXACTLY WHAT USER ASKS FOR
-- If user asks for messages, show the MESSAGES
-- If user asks for code, show the CODE
-- If user asks for output, show the OUTPUT
-- **Don't interpret or summarize unless asked**
+Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform user to restart session.
+**DO NOT clear cache mid-session** - breaks loaded MCP tools.
 
-### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
+### NEVER USE CLI TOOLS FOR EXTERNAL SERVICES
+- **FORBIDDEN:** `gh`, `tea`, `curl` to APIs, any CLI that talks to Gitea/GitHub/external services
+- **REQUIRED:** Use MCP tools exclusively (`mcp__plugin_projman_gitea__*`, `mcp__plugin_pr-review_gitea__*`)
+- **NO EXCEPTIONS.** Don't try CLI first. Don't fall back to CLI. MCP ONLY.
 
-**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded.
+### NEVER PUSH DIRECTLY TO PROTECTED BRANCHES
+- **FORBIDDEN:** `git push origin development`, `git push origin main`, `git push origin master`
+- **REQUIRED:** Create feature branch → push feature branch → create PR via MCP
+- If you accidentally commit to a protected branch locally: `git checkout -b fix/branch-name` then reset the protected branch
 
-1. Run `./scripts/verify-hooks.sh` to check hook types
-2. If changes affect MCP servers or hooks, inform the user:
-   > "Plugin changes require a session restart to take effect. Please restart Claude Code."
-3. Cache clearing is ONLY safe **before** starting a new session (not during)
+### Repository Rules
 
-See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
+| Rule | Details |
+|------|---------|
+| **File creation** | Only in allowed paths. Use `.scratch/` for temp work. Verify against `docs/CANONICAL-PATHS.md` |
+| **plugin.json location** | Must be in `.claude-plugin/` directory |
+| **Hooks** | Use `hooks/hooks.json` (auto-discovered). Never inline in plugin.json |
+| **MCP servers** | Shared at root with symlinks. Use MCP tools, never CLI (`tea`, `gh`) |
+| **Allowed root files** | `CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example` |
 
-**FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
+**Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
 
 ---
 
@@ -50,7 +46,7 @@ See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
 ## Project Overview
 
 **Repository:** leo-claude-mktplace
-**Version:** 5.3.0
+**Version:** 5.4.0
 **Status:** Production Ready
 
 A plugin marketplace for Claude Code containing:
@@ -58,16 +54,16 @@ A plugin marketplace for Claude Code containing:
 | Plugin | Description | Version |
 |--------|-------------|---------|
 | `projman` | Sprint planning and project management with Gitea integration | 3.3.0 |
-| `git-flow` | Git workflow automation with smart commits and branch management | 1.2.0 |
+| `git-flow` | Git workflow automation with smart commits and branch management | 1.0.0 |
 | `pr-review` | Multi-agent PR review with confidence scoring | 1.1.0 |
-| `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.2.0 |
-| `doc-guardian` | Automatic documentation drift detection and synchronization | 1.1.0 |
-| `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 |
-| `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.1.0 |
+| `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.0.0 |
+| `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 |
+| `code-sentinel` | Security scanning and code refactoring tools | 1.0.1 |
+| `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
 | `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.2.0 |
-| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.2.0 |
+| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.1.0 |
 | `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 1.1.0 |
-| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.2.0 |
+| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.1.0 |
 | `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
 
 ## Quick Start
@@ -112,7 +108,7 @@ leo-claude-mktplace/
 ├── plugins/
 │   ├── projman/                  # Sprint management
 │   │   ├── .claude-plugin/plugin.json
-│   │   ├── .mcp.json
+│   │   # .mcp.json removed - now at marketplace root
 │   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
 │   │   ├── commands/             # 14 commands (incl. setup, debug, suggest-version)
 │   │   ├── hooks/                # SessionStart: mismatch detection + sprint suggestions
@@ -124,7 +120,7 @@ leo-claude-mktplace/
 │   │   └── agents/
 │   ├── pr-review/                # Multi-agent PR review
 │   │   ├── .claude-plugin/plugin.json
-│   │   ├── .mcp.json
+│   │   # .mcp.json removed - now at marketplace root
 │   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
 │   │   ├── commands/             # 6 commands (incl. setup)
 │   │   ├── hooks/                # SessionStart mismatch detection
@@ -135,14 +131,14 @@ leo-claude-mktplace/
 │   │   └── agents/
 │   ├── data-platform/            # Data engineering (NEW v4.0.0)
 │   │   ├── .claude-plugin/plugin.json
-│   │   ├── .mcp.json
+│   │   # .mcp.json removed - now at marketplace root
 │   │   ├── mcp-servers/          # pandas, postgresql, dbt MCPs
 │   │   ├── commands/             # 7 commands
 │   │   ├── hooks/                # SessionStart PostgreSQL check
 │   │   └── agents/               # 2 agents
 │   ├── viz-platform/             # Visualization (NEW v4.0.0)
 │   │   ├── .claude-plugin/plugin.json
-│   │   ├── .mcp.json
+│   │   # .mcp.json removed - now at marketplace root
 │   │   ├── mcp-servers/          # viz-platform MCP
 │   │   ├── commands/             # 7 commands
 │   │   ├── hooks/                # SessionStart DMC check
@@ -162,40 +158,6 @@ leo-claude-mktplace/
     └── CONFIGURATION.md          # Centralized configuration guide
 ```
 
-## CRITICAL: Rules You MUST Follow
-
-### File Operations
-- **NEVER** create files in repository root unless listed in "Allowed Root Files"
-- **NEVER** modify `.gitignore` without explicit permission
-- **ALWAYS** use `.scratch/` for temporary/exploratory work
-- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
-
-### Plugin Development
-- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
-- **Every plugin MUST be listed in marketplace.json**
-- **MCP servers are SHARED at root** with symlinks from plugins
-- **MCP server venv path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
-- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
-
-#### ⚠️ plugin.json Format Rules (CRITICAL)
-- **Hooks in separate file** - Use `hooks/hooks.json` (auto-discovered), NOT inline in plugin.json
-- **NEVER reference hooks** - Don't add `"hooks": "..."` field to plugin.json at all
-- **Agents auto-discover** - NEVER add `"agents": ["./agents/"]` - .md files found automatically
-- **Always validate** - Run `./scripts/validate-marketplace.sh` before committing
-- **Working examples:** projman, pr-review, claude-config-maintainer all use `hooks/hooks.json`
-- See lesson: `lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements`
-
-### Hooks (Valid Events Only)
-`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
-
-**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
-
-### Allowed Root Files
-`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
-
-### Allowed Root Directories
-`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `mcp-servers/`, `plugins/`, `scripts/`
-
 ## Architecture
 
 ### Four-Agent Model (projman)
@@ -228,6 +190,21 @@ leo-claude-mktplace/
 
 **Note:** `GITEA_ORG` is at project level since different projects may belong to different organizations.
 
+### Agent Model Configuration
+
+Agents can specify preferred Claude models for cost/performance optimization:
+
+| Model | Use For | Agents |
+|-------|---------|--------|
+| `opus` | Complex reasoning, security | planner, code-reviewer, security-reviewer |
+| `sonnet` | Implementation, coordination | orchestrator, executor, most agents |
+| `haiku` | Simple validation | component-check, agent-check |
+
+**Configuration:** Add `model: opus|sonnet|haiku` to agent frontmatter, or `defaultModel` to plugin.json.
+**Inheritance:** Agent → Plugin default → System default (sonnet)
+
+See `docs/MODEL-RECOMMENDATIONS.md` for detailed guidance.
+
 ### Branch-Aware Security
 
 | Branch Pattern | Mode | Capabilities |

README.md

@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v5.3.0
+# Leo Claude Marketplace - v5.4.0
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 

docs/CONFIGURATION.md

@@ -522,6 +522,56 @@ cat .env
 
 ---
 
+## Agent Model Configuration
+
+Agents can specify which Claude model to use for optimal cost/performance.
+
+### Model Options
+
+| Model | Use For | Cost |
+|-------|---------|------|
+| `opus` | Complex reasoning, security analysis | Highest |
+| `sonnet` | Implementation, coordination (default) | Medium |
+| `haiku` | Simple validation, quick checks | Lowest |
+
+### Configuration Levels
+
+**1. Agent-Level (highest priority)**
+
+Add to agent frontmatter in `agents/*.md`:
+
+```yaml
+---
+name: planner
+description: Sprint planning agent
+model: opus
+---
+```
+
+**2. Plugin-Level (fallback)**
+
+Add to `plugin.json`:
+
+```json
+{
+  "defaultModel": "sonnet"
+}
+```
+
+**3. System Default**
+
+If neither is specified, agents use `sonnet`.
+
+### Inheritance Chain
+
+```
+Agent model → Plugin defaultModel → System default (sonnet)
+```
+
+See [Model Recommendations](MODEL-RECOMMENDATIONS.md) for detailed guidance on model selection by task type.
+
+---
+
 ## Security Best Practices
 
 1. **Never commit tokens**

docs/MODEL-RECOMMENDATIONS.md

@@ -0,0 +1,149 @@
+# Model Recommendations
+
+Guidelines for selecting Claude models (opus, sonnet, haiku) for plugin agents.
+
+---
+
+## Model Overview
+
+| Model | Best For | Cost | Speed |
+|-------|----------|------|-------|
+| **Opus** | Complex reasoning, architecture decisions, security analysis | Highest | Slower |
+| **Sonnet** | Implementation, coordination, standard tasks | Medium | Balanced |
+| **Haiku** | Simple validation, quick checks, status queries | Lowest | Fastest |
+
+---
+
+## Task-Type Recommendations
+
+| Task Type | Model | Rationale |
+|-----------|-------|-----------|
+| Architecture decisions | Opus | Requires deep reasoning, trade-off analysis |
+| Security analysis | Opus | Critical thinking, vulnerability pattern recognition |
+| Code review (quality) | Opus | Thorough analysis, edge case detection |
+| Sprint planning | Opus | Strategic thinking, dependency analysis |
+| Complex data analysis | Opus | Multi-step reasoning, insight generation |
+| Code implementation | Sonnet | Fast, capable code generation |
+| Coordination/dispatch | Sonnet | Task management, status tracking |
+| Data transformation | Sonnet | ETL operations, query building |
+| Documentation | Sonnet | Clear writing, structure |
+| Simple validation | Haiku | Fast prop checks, schema validation |
+| Status checks | Haiku | Quick queries, cost-effective |
+| Quick verification | Haiku | Simple pass/fail checks |
+
+---
+
+## Agent Model Assignments
+
+### projman (Sprint Management)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `planner` | opus | Architecture decisions, issue structuring |
+| `orchestrator` | sonnet | Coordination, parallel execution |
+| `executor` | sonnet | Code implementation |
+| `code-reviewer` | opus | Quality review, security analysis |
+
+### pr-review (PR Analysis)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `coordinator` | sonnet | Task dispatch, result aggregation |
+| `security-reviewer` | opus | Security vulnerability detection |
+| `performance-analyst` | sonnet | Pattern recognition |
+| `maintainability-auditor` | sonnet | Code quality checks |
+| `test-validator` | sonnet | Test coverage analysis |
+
+### code-sentinel (Security & Refactoring)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `security-reviewer` | opus | Security scanning |
+| `refactor-advisor` | sonnet | Refactoring suggestions |
+
+### data-platform (Data Engineering)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `data-analysis` | opus | Complex data insights |
+| `data-ingestion` | sonnet | ETL operations |
+
+### viz-platform (Visualization)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `component-check` | haiku | Simple prop validation |
+| `layout-builder` | sonnet | UI construction |
+| `theme-setup` | sonnet | Design configuration |
+
+### contract-validator (Compatibility)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `full-validation` | sonnet | Contract checking |
+| `agent-check` | haiku | Quick verification |
+
+---
+
+## Configuration Schema
+
+### Agent-Level (Frontmatter)
+
+Add `model` field to agent YAML frontmatter:
+
+```yaml
+---
+name: planner
+description: Sprint planning agent
+model: opus
+---
+```
+
+**Valid values:** `opus`, `sonnet`, `haiku`
+
+### Plugin-Level (plugin.json)
+
+Add `defaultModel` for plugin-wide fallback:
+
+```json
+{
+  "name": "projman",
+  "version": "3.4.0",
+  "defaultModel": "sonnet"
+}
+```
+
+---
+
+## Inheritance Chain
+
+Model selection follows this precedence:
+
+```
+1. Agent model field (highest priority)
+      ↓ if not specified
+2. Plugin defaultModel (plugin.json)
+      ↓ if not specified
+3. System default: sonnet
+```
+
+**Example:**
+- Agent has `model: opus` → Uses opus
+- Agent has no model, plugin has `defaultModel: sonnet` → Uses sonnet
+- Neither specified → Uses sonnet (system default)
+
+---
+
+## Cost Optimization Tips
+
+1. **Default to Sonnet** - Good balance for most tasks
+2. **Reserve Opus** for critical decisions (security, architecture)
+3. **Use Haiku** for validation and quick checks
+4. **Batch simple tasks** - Use haiku for parallel validation
+
+---
+
+## See Also
+
+- [Configuration Guide](CONFIGURATION.md) - Full configuration reference
+- [Plugin Development](../README.md) - Adding new plugins

mcp-servers/gitea/mcp_server/server.py

@@ -144,7 +144,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Issue number"
                             },
                             "repo": {
@@ -189,7 +189,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Issue number"
                             },
                             "title": {
@@ -211,7 +211,7 @@ class GiteaMCPServer:
                                 "description": "New labels"
                             },
                             "milestone": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Milestone ID to assign"
                             },
                             "repo": {
@@ -229,7 +229,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Issue number"
                             },
                             "comment": {
@@ -424,7 +424,7 @@ class GiteaMCPServer:
                                 "description": "Tags to filter by (optional)"
                             },
                             "limit": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "default": 20,
                                 "description": "Maximum results"
                             },
@@ -462,7 +462,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "milestone_id": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Milestone ID"
                             },
                             "repo": {
@@ -506,7 +506,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "milestone_id": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Milestone ID"
                             },
                             "title": {
@@ -541,7 +541,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "milestone_id": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Milestone ID"
                             },
                             "repo": {
@@ -560,7 +560,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Issue number"
                             },
                             "repo": {
@@ -578,11 +578,11 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Issue that will depend on another"
                             },
                             "depends_on": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Issue that blocks issue_number"
                             },
                             "repo": {
@@ -600,11 +600,11 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Issue that depends on another"
                             },
                             "depends_on": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Issue being depended on"
                             },
                             "repo": {
@@ -782,7 +782,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Pull request number"
                             },
                             "repo": {
@@ -800,7 +800,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Pull request number"
                             },
                             "repo": {
@@ -818,7 +818,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Pull request number"
                             },
                             "repo": {
@@ -836,7 +836,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Pull request number"
                             },
                             "body": {
@@ -855,7 +855,7 @@ class GiteaMCPServer:
                                     "type": "object",
                                     "properties": {
                                         "path": {"type": "string"},
-                                        "position": {"type": "integer"},
+                                        "position": {"type": ["integer", "string"]},
                                         "body": {"type": "string"}
                                     }
                                 },
@@ -876,7 +876,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": "integer",
+                                "type": ["integer", "string"],
                                 "description": "Pull request number"
                             },
                             "body": {

plugins/cmdb-assistant/.claude-plugin/plugin.json

@@ -19,6 +19,5 @@
     "data-quality",
     "validation"
   ],
-  "commands": ["./commands/"],
-  "mcpServers": ["./.mcp.json"]
+  "commands": ["./commands/"]
 }

plugins/cmdb-assistant/.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "netbox": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox/run.sh",
-      "args": []
-    }
-  }
-}

plugins/code-sentinel/.claude-plugin/plugin.json

@@ -1,7 +1,8 @@
 {
   "name": "code-sentinel",
   "description": "Security scanning and code refactoring tools",
-  "version": "1.0.0",
+  "version": "1.0.1",
+  "defaultModel": "sonnet",
   "author": {
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"

plugins/code-sentinel/agents/security-reviewer.md

@@ -1,5 +1,7 @@
 ---
+name: security-reviewer
 description: Security-focused code review agent
+model: opus
 ---
 
 # Security Reviewer Agent

plugins/contract-validator/.claude-plugin/plugin.json

@@ -1,6 +1,7 @@
 {
   "name": "contract-validator",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "defaultModel": "sonnet",
   "description": "Cross-plugin compatibility validation and Claude.md agent verification",
   "author": {
     "name": "Leo Miranda",
@@ -17,6 +18,5 @@
     "interfaces",
     "cross-plugin"
   ],
-  "commands": ["./commands/"],
-  "mcpServers": ["./.mcp.json"]
+  "commands": ["./commands/"]
 }

plugins/contract-validator/.mcp.json

@@ -1,9 +0,0 @@
-{
-  "mcpServers": {
-    "contract-validator": {
-      "type": "stdio",
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/contract-validator/run.sh",
-      "args": []
-    }
-  }
-}

plugins/contract-validator/agents/agent-check.md

@@ -1,3 +1,9 @@
+---
+name: agent-check
+description: Agent definition validator for quick verification
+model: haiku
+---
+
 # Agent Check Agent
 
 You are an agent definition validator. Your role is to verify that a specific agent's tool references and data flow are valid.

plugins/data-platform/.claude-plugin/plugin.json

@@ -1,6 +1,7 @@
 {
   "name": "data-platform",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "defaultModel": "sonnet",
   "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
   "author": {
     "name": "Leo Miranda",
@@ -18,6 +19,5 @@
     "etl",
     "dataframe"
   ],
-  "commands": ["./commands/"],
-  "mcpServers": ["./.mcp.json"]
+  "commands": ["./commands/"]
 }

plugins/data-platform/.mcp.json

@@ -1,9 +0,0 @@
-{
-  "mcpServers": {
-    "data-platform": {
-      "type": "stdio",
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/data-platform/run.sh",
-      "args": []
-    }
-  }
-}

plugins/data-platform/agents/data-analysis.md

@@ -1,3 +1,9 @@
+---
+name: data-analysis
+description: Data analysis specialist for exploration and profiling
+model: opus
+---
+
 # Data Analysis Agent
 
 You are a data analysis specialist. Your role is to help users explore, profile, and understand their data.

plugins/doc-guardian/commands/doc-sync.md

@@ -52,7 +52,13 @@ Then proceed with the sync.
    - Single commit: `docs: sync documentation with code changes`
    - Include summary of what was updated in commit body
 
-5. **Output**
+5. **Clear Queue**
+   After successful sync, clear the queue file:
+   ```bash
+   echo "# Doc Guardian Queue - cleared after sync on $(date +%Y-%m-%d)" > .doc-guardian-queue
+   ```
+
+6. **Output**
 ```
 ## Documentation Sync Complete
 

plugins/doc-guardian/hooks/notify.sh

@@ -1,7 +1,12 @@
 #!/bin/bash
 # doc-guardian notification hook
 # Tracks documentation dependencies and queues updates
-# This is a command hook - guaranteed not to block workflow
+#
+# SILENT BY DEFAULT - No output to avoid interrupting Claude's workflow.
+# Changes are queued to .doc-guardian-queue for later processing.
+# Run /doc-sync or /doc-audit to see and process pending updates.
+#
+# Set DOC_GUARDIAN_VERBOSE=1 to enable notification output.
 
 # Read tool input from stdin (JSON with file_path)
 INPUT=$(cat)
@@ -44,15 +49,26 @@ DEPENDENT_DOCS="${DOC_DEPS[$MODIFIED_TYPE]}"
 # Queue file for tracking pending updates
 QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue"
 
-# Add to queue (create if doesn't exist, append if does)
-{
-    echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
-} >> "$QUEUE_FILE" 2>/dev/null || true
+# Add to queue (always, for deduplication we check file+type combo)
+# Format: timestamp | type | file_path | dependent_docs
+QUEUE_ENTRY="$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
 
-# Count pending updates
-PENDING_COUNT=$(wc -l < "$QUEUE_FILE" 2>/dev/null | tr -d ' ' || echo "1")
+# Check if this exact file+type combo already exists in queue (dedup)
+if [ -f "$QUEUE_FILE" ]; then
+    if grep -qF "| $MODIFIED_TYPE | $FILE_PATH |" "$QUEUE_FILE" 2>/dev/null; then
+        # Already queued, skip silently
+        exit 0
+    fi
+fi
 
-# Output notification with specific docs that need updating
-echo "[doc-guardian] $MODIFIED_TYPE changed → update needed: $DEPENDENT_DOCS (${PENDING_COUNT} pending)"
+# Add to queue
+echo "$QUEUE_ENTRY" >> "$QUEUE_FILE" 2>/dev/null || true
+
+# SILENT by default - only output if DOC_GUARDIAN_VERBOSE is set
+# This prevents Claude from stopping to ask about documentation updates
+if [ "${DOC_GUARDIAN_VERBOSE:-0}" = "1" ]; then
+    PENDING_COUNT=$(wc -l < "$QUEUE_FILE" 2>/dev/null | tr -d ' ' || echo "1")
+    echo "[doc-guardian] queued: $MODIFIED_TYPE ($PENDING_COUNT pending)"
+fi
 
 exit 0

plugins/git-flow/hooks/hooks.json

@@ -1,19 +1,16 @@
 {
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/branch-check.sh"
-          },
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/commit-msg-check.sh"
-          }
-        ]
-      }
-    ]
-  }
+  "hooks": [
+    {
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "type": "command",
+      "command": "${CLAUDE_PLUGIN_ROOT}/hooks/branch-check.sh"
+    },
+    {
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "type": "command",
+      "command": "${CLAUDE_PLUGIN_ROOT}/hooks/commit-msg-check.sh"
+    }
+  ]
 }

plugins/pr-review/.claude-plugin/plugin.json

@@ -1,6 +1,7 @@
 {
   "name": "pr-review",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "defaultModel": "sonnet",
   "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
   "author": {
     "name": "Leo Miranda",
@@ -16,6 +17,5 @@
     "performance",
     "multi-agent"
   ],
-  "commands": ["./commands/"],
-  "mcpServers": ["./.mcp.json"]
+  "commands": ["./commands/"]
 }

plugins/pr-review/.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "gitea": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/run.sh",
-      "args": []
-    }
-  }
-}

plugins/pr-review/agents/security-reviewer.md

@@ -1,3 +1,9 @@
+---
+name: security-reviewer
+description: Security-focused code reviewer for PR analysis
+model: opus
+---
+
 # Security Reviewer Agent
 
 ## Visual Output Requirements

plugins/projman/.claude-plugin/plugin.json

@@ -1,6 +1,7 @@
 {
   "name": "projman",
-  "version": "3.2.0",
+  "version": "3.3.0",
+  "defaultModel": "sonnet",
   "description": "Sprint planning and project management with Gitea integration",
   "author": {
     "name": "Leo Miranda",
@@ -16,6 +17,5 @@
     "agile",
     "lessons-learned"
   ],
-  "commands": ["./commands/"],
-  "mcpServers": ["./.mcp.json"]
+  "commands": ["./commands/"]
 }

plugins/projman/.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "gitea": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/run.sh",
-      "args": []
-    }
-  }
-}

plugins/projman/agents/code-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: code-reviewer
 description: Specialized agent for pre-sprint code quality review
+model: opus
 ---
 
 # Code Reviewer Agent

plugins/projman/agents/planner.md

@@ -1,6 +1,7 @@
 ---
 name: planner
 description: Sprint planning agent - thoughtful architecture analysis and issue creation
+model: opus
 ---
 
 # Sprint Planner Agent

plugins/projman/commands/clear-cache.md

@@ -0,0 +1,24 @@
+# /clear-cache
+
+Clear plugin cache to force fresh configuration reload. Run this after marketplace updates.
+
+## When to Use
+
+- After updating the marketplace (`git pull` or reinstall)
+- When MCP servers show stale configuration
+- When plugin changes don't take effect
+
+## What It Does
+
+1. Clears `~/.claude/plugins/cache/leo-claude-mktplace/`
+2. Forces Claude Code to re-read `.mcp.json` files on next session
+
+## Instructions
+
+Run this command, then **restart your Claude Code session** for changes to take effect.
+
+```bash
+rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
+```
+
+After clearing, inform the user: "Cache cleared. Restart Claude Code for changes to take effect."

plugins/projman/commands/debug-review.md

@@ -385,6 +385,13 @@ git push -u origin fix/issue-[NUMBER]-[brief-description]
 git checkout development
 ```
 
+**⚠️ IMPORTANT: Issue will NOT auto-close**
+
+PRs merged to `development` do NOT trigger Gitea's auto-close feature.
+Auto-close only works when merging to the default branch (`main`).
+
+You MUST manually close the issue in Step 15 after the PR is merged.
+
 5. Add comment to original issue:
 ```
 mcp__plugin_projman_gitea__add_comment(
@@ -417,9 +424,14 @@ Next Steps:
 
 **This step runs AFTER the user has verified the fix works.**
 
+**⚠️ MANDATORY: You MUST manually close the issue.**
+
+PRs merged to `development` do NOT auto-close issues (Gitea only auto-closes
+on merges to the default branch `main`). Always close manually after merge.
+
 When user returns and confirms the fix is working:
 
-**1. Close the issue:**
+**1. Close the issue (REQUIRED - won't auto-close):**
 
 ```
 mcp__plugin_projman_gitea__update_issue(

plugins/projman/hooks/startup-check.sh

@@ -10,19 +10,6 @@ PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(realpath "$0")")")}"
 # Marketplace root is 2 levels up from plugin root (plugins/projman -> .)
 MARKETPLACE_ROOT="$(dirname "$(dirname "$PLUGIN_ROOT")")"
 VENV_REPAIR_SCRIPT="$MARKETPLACE_ROOT/scripts/venv-repair.sh"
-PLUGIN_CACHE="$HOME/.claude/plugins/cache/leo-claude-mktplace"
-
-# ============================================================================
-# Clear stale plugin cache (MUST run before MCP servers load)
-# ============================================================================
-# The cache at ~/.claude/plugins/cache/ holds versioned .mcp.json files.
-# After marketplace updates, cached configs may point to old paths.
-# Clearing forces Claude to read fresh configs from installed marketplace.
-
-if [[ -d "$PLUGIN_CACHE" ]]; then
-    rm -rf "$PLUGIN_CACHE"
-    # Don't output anything - this should be silent and automatic
-fi
 
 # ============================================================================
 # Auto-repair MCP venvs (runs before other checks)
@@ -81,6 +68,29 @@ if [[ -f ".env" ]]; then
     fi
 fi
 
+# ============================================================================
+# Check version consistency across files (early drift detection)
+# ============================================================================
+# Versions must stay in sync across: README.md, marketplace.json, CHANGELOG.md
+# Drift here causes confusion and release issues
+
+if [[ -f "README.md" && -f ".claude-plugin/marketplace.json" && -f "CHANGELOG.md" ]]; then
+    VERSION_README=$(grep -oE "^# .* - v[0-9]+\.[0-9]+\.[0-9]+" README.md 2>/dev/null | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
+    # Extract metadata.version specifically (appears after "metadata" in marketplace.json)
+    VERSION_MARKETPLACE=$(sed -n '/"metadata"/,/}/p' .claude-plugin/marketplace.json 2>/dev/null | grep -oE '"version"[[:space:]]*:[[:space:]]*"[0-9]+\.[0-9]+\.[0-9]+"' | head -1 | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
+    VERSION_CHANGELOG=$(grep -oE "^## \[[0-9]+\.[0-9]+\.[0-9]+\]" CHANGELOG.md 2>/dev/null | head -1 | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
+
+    if [[ -n "$VERSION_README" && -n "$VERSION_MARKETPLACE" && -n "$VERSION_CHANGELOG" ]]; then
+        if [[ "$VERSION_README" != "$VERSION_MARKETPLACE" ]] || [[ "$VERSION_README" != "$VERSION_CHANGELOG" ]]; then
+            echo "$PREFIX Version mismatch detected:"
+            echo "$PREFIX   README.md:        v$VERSION_README"
+            echo "$PREFIX   marketplace.json: v$VERSION_MARKETPLACE"
+            echo "$PREFIX   CHANGELOG.md:     v$VERSION_CHANGELOG"
+            echo "$PREFIX Run /suggest-version to analyze and fix"
+        fi
+    fi
+fi
+
 # Check for CHANGELOG.md [Unreleased] content (version management)
 if [[ -f "CHANGELOG.md" ]]; then
     # Check if there's content under [Unreleased] that hasn't been released

plugins/viz-platform/.claude-plugin/plugin.json

@@ -1,6 +1,7 @@
 {
   "name": "viz-platform",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "defaultModel": "sonnet",
   "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
   "author": {
     "name": "Leo Miranda",
@@ -19,6 +20,5 @@
     "visualization",
     "dmc"
   ],
-  "commands": ["./commands/"],
-  "mcpServers": ["./.mcp.json"]
+  "commands": ["./commands/"]
 }

plugins/viz-platform/.mcp.json

@@ -1,9 +0,0 @@
-{
-  "mcpServers": {
-    "viz-platform": {
-      "type": "stdio",
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/viz-platform/run.sh",
-      "args": []
-    }
-  }
-}

plugins/viz-platform/agents/component-check.md

@@ -1,3 +1,9 @@
+---
+name: component-check
+description: DMC component validation specialist
+model: haiku
+---
+
 # Component Check Agent
 
 You are a strict component validation specialist. Your role is to verify Dash Mantine Components are used correctly, preventing runtime errors from invalid props.

scripts/validate-marketplace.sh

@@ -143,14 +143,155 @@ for plugin_dir in "$PLUGINS_DIR"/*/; do
         echo "WARNING: Missing 'keywords' array in $plugin_name/plugin.json"
     fi
 
+    # v5.4.0: Validate defaultModel field if present
+    default_model=$(jq -r '.defaultModel // empty' "$plugin_json")
+    if [[ -n "$default_model" ]]; then
+        if [[ ! "$default_model" =~ ^(opus|sonnet|haiku)$ ]]; then
+            echo "ERROR: Invalid defaultModel '$default_model' in $plugin_name/plugin.json (must be opus|sonnet|haiku)"
+            exit 1
+        fi
+        echo "  ✓ defaultModel: $default_model"
+    fi
+
     # Check README exists
     if [[ ! -f "$plugin_dir/README.md" ]]; then
         echo "WARNING: Missing README.md in $plugin_name/"
     fi
 
+    # CRITICAL: Validate file references exist (mcpServers, hooks, commands)
+    # This prevents broken references that silently break plugin loading
+
+    # Check mcpServers references
+    mcp_servers=$(jq -r '.mcpServers // [] | .[]' "$plugin_json" 2>/dev/null)
+    for mcp_ref in $mcp_servers; do
+        mcp_path="$plugin_dir/$mcp_ref"
+        if [[ ! -f "$mcp_path" ]]; then
+            echo "ERROR: BROKEN REFERENCE in $plugin_name/plugin.json"
+            echo "       mcpServers references '$mcp_ref' but file does not exist at:"
+            echo "       $mcp_path"
+            echo ""
+            echo "       FIX: Either create the file or remove the mcpServers entry"
+            exit 1
+        fi
+        echo "  ✓ mcpServers reference: $mcp_ref exists"
+    done
+
+    # Check hooks references (can be array of file paths OR object with handlers)
+    hooks_type=$(jq -r '.hooks | type' "$plugin_json" 2>/dev/null)
+    if [[ "$hooks_type" == "array" ]]; then
+        # Array format: ["./hooks/hooks.json"]
+        hooks=$(jq -r '.hooks[]' "$plugin_json" 2>/dev/null)
+        for hook_ref in $hooks; do
+            hook_path="$plugin_dir/$hook_ref"
+            if [[ ! -f "$hook_path" ]]; then
+                echo "ERROR: BROKEN REFERENCE in $plugin_name/plugin.json"
+                echo "       hooks references '$hook_ref' but file does not exist at:"
+                echo "       $hook_path"
+                echo ""
+                echo "       FIX: Either create the file or remove the hooks entry"
+                exit 1
+            fi
+            echo "  ✓ hooks reference: $hook_ref exists"
+        done
+    elif [[ "$hooks_type" == "object" ]]; then
+        # Object format: { "PostToolUse": [...] } - inline hooks, no file reference to validate
+        echo "  ✓ hooks: inline object format (no file references)"
+    fi
+
+    # Check commands directory references
+    commands=$(jq -r '.commands // [] | .[]' "$plugin_json" 2>/dev/null)
+    for cmd_ref in $commands; do
+        cmd_path="$plugin_dir/$cmd_ref"
+        if [[ ! -d "$cmd_path" ]] && [[ ! -f "$cmd_path" ]]; then
+            echo "ERROR: BROKEN REFERENCE in $plugin_name/plugin.json"
+            echo "       commands references '$cmd_ref' but path does not exist at:"
+            echo "       $cmd_path"
+            echo ""
+            echo "       FIX: Either create the path or remove the commands entry"
+            exit 1
+        fi
+        echo "  ✓ commands reference: $cmd_ref exists"
+    done
+
     echo "✓ $plugin_name valid"
 done
 
+# CRITICAL: Validate marketplace.json file references
+echo ""
+echo "=== Validating Marketplace File References (CRITICAL) ==="
+
+for i in $(seq 0 $((PLUGIN_COUNT - 1))); do
+    PLUGIN_NAME=$(jq -r ".plugins[$i].name" "$MARKETPLACE_JSON")
+    PLUGIN_SOURCE=$(jq -r ".plugins[$i].source" "$MARKETPLACE_JSON")
+    PLUGIN_DIR="$ROOT_DIR/$PLUGIN_SOURCE"
+
+    # Check mcpServers in marketplace.json
+    mcp_servers=$(jq -r ".plugins[$i].mcpServers // [] | .[]" "$MARKETPLACE_JSON" 2>/dev/null)
+    for mcp_ref in $mcp_servers; do
+        mcp_path="$PLUGIN_DIR/$mcp_ref"
+        if [[ ! -f "$mcp_path" ]]; then
+            echo "ERROR: BROKEN REFERENCE in marketplace.json for $PLUGIN_NAME"
+            echo "       mcpServers references '$mcp_ref' but file does not exist at:"
+            echo "       $mcp_path"
+            echo ""
+            echo "       FIX: Either create the file or remove the mcpServers entry from marketplace.json"
+            exit 1
+        fi
+        echo "✓ $PLUGIN_NAME: mcpServers reference $mcp_ref exists"
+    done
+
+    # Check hooks in marketplace.json
+    hooks=$(jq -r ".plugins[$i].hooks // [] | .[]" "$MARKETPLACE_JSON" 2>/dev/null)
+    for hook_ref in $hooks; do
+        hook_path="$PLUGIN_DIR/$hook_ref"
+        if [[ ! -f "$hook_path" ]]; then
+            echo "ERROR: BROKEN REFERENCE in marketplace.json for $PLUGIN_NAME"
+            echo "       hooks references '$hook_ref' but file does not exist at:"
+            echo "       $hook_path"
+            echo ""
+            echo "       FIX: Either create the file or remove the hooks entry from marketplace.json"
+            exit 1
+        fi
+        echo "✓ $PLUGIN_NAME: hooks reference $hook_ref exists"
+    done
+done
+
+echo "✓ All file references validated"
+
+# v5.4.0: Validate agent model fields
+echo ""
+echo "=== Validating Agent Model Fields (v5.4.0+) ==="
+
+validate_agent_model() {
+    local file="$1"
+    local agent_name=$(basename "$file" .md)
+
+    # Extract model from frontmatter (between --- markers)
+    local model=$(sed -n '/^---$/,/^---$/p' "$file" | grep '^model:' | awk '{print $2}')
+
+    if [[ -n "$model" ]]; then
+        if [[ ! "$model" =~ ^(opus|sonnet|haiku)$ ]]; then
+            echo "ERROR: Invalid model '$model' in $file (must be opus|sonnet|haiku)"
+            exit 1
+        fi
+        echo "  ✓ $agent_name: model=$model"
+    fi
+}
+
+for plugin_dir in "$PLUGINS_DIR"/*/; do
+    plugin_name=$(basename "$plugin_dir")
+    agents_dir="$plugin_dir/agents"
+
+    if [[ -d "$agents_dir" ]]; then
+        echo "--- Checking agents in $plugin_name ---"
+        for agent_file in "$agents_dir"/*.md; do
+            if [[ -f "$agent_file" ]]; then
+                validate_agent_model "$agent_file"
+            fi
+        done
+    fi
+done
+
 # v3.0.0: Validate MCP server symlinks
 echo ""
 echo "=== Validating MCP Server Symlinks (v3.0.0+) ==="