From d4293193929b308288fe4ae3509a8ad997323d47 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 21:48:17 -0500 Subject: [PATCH] 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