From d4293193929b308288fe4ae3509a8ad997323d47 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 21:48:17 -0500 Subject: [PATCH 1/4] docs: add model recommendations documentation - Create docs/MODEL-RECOMMENDATIONS.md with task-type guidance - Update docs/CONFIGURATION.md with model configuration section - Update CLAUDE.md with agent model configuration overview Fixes #302 Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 15 ++++ docs/CONFIGURATION.md | 50 ++++++++++++ docs/MODEL-RECOMMENDATIONS.md | 149 ++++++++++++++++++++++++++++++++++ 3 files changed, 214 insertions(+) create mode 100644 docs/MODEL-RECOMMENDATIONS.md diff --git a/CLAUDE.md b/CLAUDE.md index edda684..68c4bba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -190,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 | diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index b1662bb..c278838 100644 --- a/docs/CONFIGURATION.md +++ b/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** diff --git a/docs/MODEL-RECOMMENDATIONS.md b/docs/MODEL-RECOMMENDATIONS.md new file mode 100644 index 0000000..fb701c9 --- /dev/null +++ b/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 From 5aff53972e7231447de46036baad10a373b26d2b Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 21:51:20 -0500 Subject: [PATCH 2/4] feat: add model:opus to critical reasoning agents - projman/planner.md - architecture decisions - projman/code-reviewer.md - quality review - pr-review/security-reviewer.md - security analysis - code-sentinel/security-reviewer.md - security scanning - data-platform/data-analysis.md - complex data insights Fixes #303 Co-Authored-By: Claude Opus 4.5 --- plugins/code-sentinel/agents/security-reviewer.md | 2 ++ plugins/data-platform/agents/data-analysis.md | 6 ++++++ plugins/pr-review/agents/security-reviewer.md | 6 ++++++ plugins/projman/agents/code-reviewer.md | 1 + plugins/projman/agents/planner.md | 1 + 5 files changed, 16 insertions(+) diff --git a/plugins/code-sentinel/agents/security-reviewer.md b/plugins/code-sentinel/agents/security-reviewer.md index 1d62908..a4e7624 100644 --- a/plugins/code-sentinel/agents/security-reviewer.md +++ b/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 diff --git a/plugins/data-platform/agents/data-analysis.md b/plugins/data-platform/agents/data-analysis.md index ffbe615..aad9972 100644 --- a/plugins/data-platform/agents/data-analysis.md +++ b/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. diff --git a/plugins/pr-review/agents/security-reviewer.md b/plugins/pr-review/agents/security-reviewer.md index 52d47d2..23c5dff 100644 --- a/plugins/pr-review/agents/security-reviewer.md +++ b/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 diff --git a/plugins/projman/agents/code-reviewer.md b/plugins/projman/agents/code-reviewer.md index d5d454e..4a5cf57 100644 --- a/plugins/projman/agents/code-reviewer.md +++ b/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 diff --git a/plugins/projman/agents/planner.md b/plugins/projman/agents/planner.md index e5ffe5e..8587891 100644 --- a/plugins/projman/agents/planner.md +++ b/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 From cf4d1b595c9a4bd6fee8ae0eb6965ad84971f035 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 21:52:02 -0500 Subject: [PATCH 3/4] feat: add model:haiku to validation agents - viz-platform/component-check.md - simple prop validation - contract-validator/agent-check.md - quick verification Fixes #304 Co-Authored-By: Claude Opus 4.5 --- plugins/contract-validator/agents/agent-check.md | 6 ++++++ plugins/viz-platform/agents/component-check.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/plugins/contract-validator/agents/agent-check.md b/plugins/contract-validator/agents/agent-check.md index 09f9723..39c5a51 100644 --- a/plugins/contract-validator/agents/agent-check.md +++ b/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. diff --git a/plugins/viz-platform/agents/component-check.md b/plugins/viz-platform/agents/component-check.md index 1c34eb8..3483e00 100644 --- a/plugins/viz-platform/agents/component-check.md +++ b/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. From 4983cc9feb26160d0ddbb4dc86c1b6564fd505d0 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 21:53:36 -0500 Subject: [PATCH 4/4] feat: add defaultModel to plugin manifests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add defaultModel: sonnet to all plugin manifests that have agents, establishing the plugin-level default in the model inheritance chain. Version bumps: - projman: 3.2.0 → 3.3.0 (minor: new feature) - pr-review: 1.0.0 → 1.1.0 (minor: new feature) - data-platform: 1.0.0 → 1.1.0 (minor: new feature) - viz-platform: 1.0.0 → 1.1.0 (minor: new feature) - code-sentinel: 1.0.0 → 1.0.1 (patch: config addition) - contract-validator: 1.0.0 → 1.1.0 (minor: new feature) Fixes #305 Co-Authored-By: Claude Opus 4.5 --- plugins/code-sentinel/.claude-plugin/plugin.json | 3 ++- plugins/contract-validator/.claude-plugin/plugin.json | 3 ++- plugins/data-platform/.claude-plugin/plugin.json | 3 ++- plugins/pr-review/.claude-plugin/plugin.json | 3 ++- plugins/projman/.claude-plugin/plugin.json | 3 ++- plugins/viz-platform/.claude-plugin/plugin.json | 3 ++- 6 files changed, 12 insertions(+), 6 deletions(-) diff --git a/plugins/code-sentinel/.claude-plugin/plugin.json b/plugins/code-sentinel/.claude-plugin/plugin.json index bf57dfa..351dd8c 100644 --- a/plugins/code-sentinel/.claude-plugin/plugin.json +++ b/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" diff --git a/plugins/contract-validator/.claude-plugin/plugin.json b/plugins/contract-validator/.claude-plugin/plugin.json index 394de21..d859b8e 100644 --- a/plugins/contract-validator/.claude-plugin/plugin.json +++ b/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", diff --git a/plugins/data-platform/.claude-plugin/plugin.json b/plugins/data-platform/.claude-plugin/plugin.json index 489fcee..2d1f223 100644 --- a/plugins/data-platform/.claude-plugin/plugin.json +++ b/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", diff --git a/plugins/pr-review/.claude-plugin/plugin.json b/plugins/pr-review/.claude-plugin/plugin.json index de6417a..3339a3c 100644 --- a/plugins/pr-review/.claude-plugin/plugin.json +++ b/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", diff --git a/plugins/projman/.claude-plugin/plugin.json b/plugins/projman/.claude-plugin/plugin.json index 80acba0..31ab203 100644 --- a/plugins/projman/.claude-plugin/plugin.json +++ b/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", diff --git a/plugins/viz-platform/.claude-plugin/plugin.json b/plugins/viz-platform/.claude-plugin/plugin.json index c25d1d6..c08b6e0 100644 --- a/plugins/viz-platform/.claude-plugin/plugin.json +++ b/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",