feat(agents): add permissionMode, disallowedTools, skills frontmatter to all 25 agents #409

Merged
lmiranda merged 1 commits from feat/agent-frontmatter-hardening-v3 into development 2026-02-03 16:10:25 +00:00
28 changed files with 201 additions and 87 deletions
Showing only changes of commit 19ba80191f - Show all commits

View File

@@ -87,6 +87,36 @@ Per-agent model selection using Claude Code's now-supported `model` frontmatter
- Added missing frontmatter to 13 agents across pr-review, viz-platform, contract-validator, clarity-assist, git-flow, doc-guardian, code-sentinel, cmdb-assistant, and data-platform
- All 25 agents now have consistent `name`, `description`, and `model` fields
### Changed
#### Agent Frontmatter Hardening v3
Comprehensive agent-level configuration using Claude Code's supported frontmatter fields.
**permissionMode added to all 25 agents:**
- `bypassPermissions` (1): Executor — full autonomy with code-sentinel + Code Reviewer safety nets
- `acceptEdits` (7): Orchestrator, Data Ingestion, Theme Setup, Refactor Advisor, Doc Analyzer, Git Assistant, Maintainer
- `default` (7): Planner, Code Reviewer, Data Advisor, Layout Builder, Full Validation, Clarity Coach, CMDB Assistant
- `plan` (10): All pr-review agents (5), Data Analysis, Design Reviewer, Component Check, Agent Check, Security Reviewer (code-sentinel)
**disallowedTools added to 12 agents:**
- All `plan`-mode agents (10) + Code Reviewer + Clarity Coach receive `disallowedTools: Write, Edit, MultiEdit`
- Enforces read-only contracts at platform level (defense-in-depth with `permissionMode`)
**Model promotions:**
- Planner: `sonnet``opus` (architectural reasoning benefits from deeper analysis)
- Code Reviewer: `sonnet``opus` (quality gate benefits from thorough review)
**skills frontmatter on 3 agents:**
- Executor: 7 safety-critical skills auto-injected (branch-security, runaway-detection, etc.)
- Code Reviewer: 4 review skills auto-injected
- Maintainer: 2 config skills auto-injected
- Body text `## Skills to Load` removed for these agents to avoid duplication
**Documentation:**
- `CLAUDE.md` and `docs/CONFIGURATION.md` updated with complete agent configuration matrix
- New subsections: permissionMode Guide, disallowedTools Guide, skills Frontmatter Guide
---
## [5.8.0] - 2026-02-02

View File

@@ -271,39 +271,60 @@ leo-claude-mktplace/
| **Executor** | Implementation-focused | Code implementation, branch management, MR creation |
| **Code Reviewer** | Thorough, practical | Pre-close quality review, security scan, test verification |
### Agent Model Selection
### Agent Frontmatter Configuration
Agents specify their model in frontmatter using Claude Code's `model` field. Supported values: `sonnet` (default), `opus`, `haiku`, `inherit`.
Agents specify their configuration in frontmatter using Claude Code's supported fields. Reference: https://code.claude.com/docs/en/sub-agents
| Plugin | Agent | Model | Rationale |
|--------|-------|-------|-----------|
| projman | Planner | sonnet | Architectural analysis, sprint planning |
| projman | Orchestrator | sonnet | Coordination and tool dispatch |
| projman | Executor | sonnet | Code generation and implementation |
| projman | Code Reviewer | sonnet | Quality gate, pattern detection |
| pr-review | Coordinator | sonnet | Orchestrates sub-agents, aggregates findings |
| pr-review | Security Reviewer | sonnet | Security analysis |
| pr-review | Performance Analyst | sonnet | Performance pattern detection |
| pr-review | Maintainability Auditor | haiku | Pattern matching (complexity, duplication) |
| pr-review | Test Validator | haiku | Coverage gap detection |
| data-platform | Data Advisor | sonnet | Schema validation, dbt orchestration |
| data-platform | Data Analysis | sonnet | Data exploration and profiling |
| data-platform | Data Ingestion | haiku | Data loading operations |
| viz-platform | Design Reviewer | sonnet | DMC validation + accessibility |
| viz-platform | Layout Builder | sonnet | Dashboard design guidance |
| viz-platform | Component Check | haiku | Quick component validation |
| viz-platform | Theme Setup | haiku | Theme configuration |
| contract-validator | Agent Check | haiku | Reference checking |
| contract-validator | Full Validation | sonnet | Marketplace sweep |
| code-sentinel | Security Reviewer | sonnet | Security analysis |
| code-sentinel | Refactor Advisor | sonnet | Code refactoring advice |
| doc-guardian | Doc Analyzer | sonnet | Documentation drift detection |
| clarity-assist | Clarity Coach | sonnet | Conversational coaching |
| git-flow | Git Assistant | haiku | Git operations |
| claude-config-maintainer | Maintainer | sonnet | CLAUDE.md optimization |
| cmdb-assistant | CMDB Assistant | sonnet | NetBox operations |
**Supported frontmatter fields:**
Override by editing the `model:` field in `plugins/{plugin}/agents/{agent}.md`.
| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `name` | Yes | — | Unique identifier, lowercase + hyphens |
| `description` | Yes | — | When Claude should delegate to this subagent |
| `model` | No | `inherit` | `sonnet`, `opus`, `haiku`, or `inherit` |
| `permissionMode` | No | `default` | Controls permission prompts: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
| `disallowedTools` | No | none | Comma-separated tools to remove from agent's toolset |
| `skills` | No | none | Comma-separated skills auto-injected into context at startup |
| `hooks` | No | none | Lifecycle hooks scoped to this subagent |
**Complete agent matrix:**
| Plugin | Agent | `model` | `permissionMode` | `disallowedTools` | `skills` |
|--------|-------|---------|-------------------|--------------------|----------|
| projman | planner | opus | default | — | body text (14) |
| projman | orchestrator | sonnet | acceptEdits | — | body text (12) |
| projman | executor | sonnet | bypassPermissions | — | frontmatter (7) |
| projman | code-reviewer | opus | default | Write, Edit, MultiEdit | frontmatter (4) |
| pr-review | coordinator | sonnet | plan | Write, Edit, MultiEdit | — |
| pr-review | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
| pr-review | performance-analyst | sonnet | plan | Write, Edit, MultiEdit | — |
| pr-review | maintainability-auditor | haiku | plan | Write, Edit, MultiEdit | — |
| pr-review | test-validator | haiku | plan | Write, Edit, MultiEdit | — |
| data-platform | data-advisor | sonnet | default | — | — |
| data-platform | data-analysis | sonnet | plan | Write, Edit, MultiEdit | — |
| data-platform | data-ingestion | haiku | acceptEdits | — | — |
| viz-platform | design-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
| viz-platform | layout-builder | sonnet | default | — | — |
| viz-platform | component-check | haiku | plan | Write, Edit, MultiEdit | — |
| viz-platform | theme-setup | haiku | acceptEdits | — | — |
| contract-validator | full-validation | sonnet | default | — | — |
| contract-validator | agent-check | haiku | plan | Write, Edit, MultiEdit | — |
| code-sentinel | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
| code-sentinel | refactor-advisor | sonnet | acceptEdits | — | — |
| doc-guardian | doc-analyzer | sonnet | acceptEdits | — | — |
| clarity-assist | clarity-coach | sonnet | default | Write, Edit, MultiEdit | — |
| git-flow | git-assistant | haiku | acceptEdits | — | — |
| claude-config-maintainer | maintainer | sonnet | acceptEdits | — | frontmatter (2) |
| cmdb-assistant | cmdb-assistant | sonnet | default | — | — |
**Design principles:**
- `bypassPermissions` is granted to exactly ONE agent (Executor) which has code-sentinel PreToolUse hook + Code Reviewer downstream as safety nets.
- `plan` mode is assigned to all pure analysis agents (pr-review, read-only validators).
- `disallowedTools: Write, Edit, MultiEdit` provides defense-in-depth on agents that should never write files.
- `skills` frontmatter is used for agents with ≤7 skills where guaranteed loading is safety-critical. Agents with 8+ skills use body text `## Skills to Load` for selective loading.
- `hooks` (agent-scoped) is reserved for future use (v6.0+).
Override any field by editing the agent's `.md` file in `plugins/{plugin}/agents/`.
### MCP Server Tools (Gitea)

View File

@@ -496,60 +496,100 @@ Not all plugins have MCP servers. The install script handles this automatically:
---
## Agent Model Selection
## Agent Frontmatter Configuration
Marketplace agents specify their preferred model using Claude Code's `model` frontmatter field. This allows cost/performance optimization per agent.
Agents specify their configuration in frontmatter using Claude Code's supported fields. Reference: https://code.claude.com/docs/en/sub-agents
### Supported Values
### Supported Frontmatter Fields
| Value | Description |
|-------|-------------|
| `sonnet` | Default. Balanced performance and cost. |
| `opus` | Higher reasoning depth. Use for complex analysis. |
| `haiku` | Faster, lower cost. Use for mechanical tasks. |
| `inherit` | Use session's current model setting. |
| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `name` | Yes | — | Unique identifier, lowercase + hyphens |
| `description` | Yes | — | When Claude should delegate to this subagent |
| `model` | No | `inherit` | `sonnet`, `opus`, `haiku`, or `inherit` |
| `permissionMode` | No | `default` | Controls permission prompts: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
| `disallowedTools` | No | none | Comma-separated tools to remove from agent's toolset |
| `skills` | No | none | Comma-separated skills auto-injected into context at startup |
| `hooks` | No | none | Lifecycle hooks scoped to this subagent |
### How It Works
### Complete Agent Matrix
Each agent in `plugins/{plugin}/agents/{agent}.md` has frontmatter like:
| Plugin | Agent | `model` | `permissionMode` | `disallowedTools` | `skills` |
|--------|-------|---------|-------------------|--------------------|----------|
| projman | planner | opus | default | — | body text (14) |
| projman | orchestrator | sonnet | acceptEdits | — | body text (12) |
| projman | executor | sonnet | bypassPermissions | — | frontmatter (7) |
| projman | code-reviewer | opus | default | Write, Edit, MultiEdit | frontmatter (4) |
| pr-review | coordinator | sonnet | plan | Write, Edit, MultiEdit | — |
| pr-review | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
| pr-review | performance-analyst | sonnet | plan | Write, Edit, MultiEdit | — |
| pr-review | maintainability-auditor | haiku | plan | Write, Edit, MultiEdit | — |
| pr-review | test-validator | haiku | plan | Write, Edit, MultiEdit | — |
| data-platform | data-advisor | sonnet | default | — | — |
| data-platform | data-analysis | sonnet | plan | Write, Edit, MultiEdit | — |
| data-platform | data-ingestion | haiku | acceptEdits | — | — |
| viz-platform | design-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
| viz-platform | layout-builder | sonnet | default | — | — |
| viz-platform | component-check | haiku | plan | Write, Edit, MultiEdit | — |
| viz-platform | theme-setup | haiku | acceptEdits | — | — |
| contract-validator | full-validation | sonnet | default | — | — |
| contract-validator | agent-check | haiku | plan | Write, Edit, MultiEdit | — |
| code-sentinel | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
| code-sentinel | refactor-advisor | sonnet | acceptEdits | — | — |
| doc-guardian | doc-analyzer | sonnet | acceptEdits | — | — |
| clarity-assist | clarity-coach | sonnet | default | Write, Edit, MultiEdit | — |
| git-flow | git-assistant | haiku | acceptEdits | — | — |
| claude-config-maintainer | maintainer | sonnet | acceptEdits | — | frontmatter (2) |
| cmdb-assistant | cmdb-assistant | sonnet | default | — | — |
```yaml
---
name: planner
description: Sprint planning agent - thoughtful architecture analysis
model: sonnet
---
```
### Design Principles
Claude Code reads this field when invoking the agent as a subagent.
- `bypassPermissions` is granted to exactly ONE agent (Executor) which has code-sentinel PreToolUse hook + Code Reviewer downstream as safety nets.
- `plan` mode is assigned to all pure analysis agents (pr-review, read-only validators).
- `disallowedTools: Write, Edit, MultiEdit` provides defense-in-depth on agents that should never write files.
- `skills` frontmatter is used for agents with ≤7 skills where guaranteed loading is safety-critical. Agents with 8+ skills use body text `## Skills to Load` for selective loading.
- `hooks` (agent-scoped) is reserved for future use (v6.0+).
### Model Assignments
Override any field by editing the agent's `.md` file in `plugins/{plugin}/agents/`.
Agents are assigned models based on their task complexity:
### permissionMode Guide
| Model | Agents | Rationale |
|-------|--------|-----------|
| **sonnet** | Planner, Orchestrator, Executor, Code Reviewer, Coordinator, Security Reviewers, Performance Analyst, Data Advisor, Data Analysis, Design Reviewer, Layout Builder, Full Validation, Doc Analyzer, Clarity Coach, Maintainer, CMDB Assistant, Refactor Advisor | Standard reasoning, tool orchestration, code generation |
| **haiku** | Maintainability Auditor, Test Validator, Component Check, Theme Setup, Agent Check, Data Ingestion, Git Assistant | Pattern matching, quick validation, mechanical tasks |
| Value | Prompts for file ops? | Prompts for Bash? | Prompts for MCP? | Use when |
|-------|-----------------------|-------------------|-------------------|----------|
| `default` | Yes | Yes | No (MCP bypasses permissions) | You want full visibility |
| `acceptEdits` | No | Yes | No | Core job is file read/write, Bash visibility useful |
| `dontAsk` | No | No (most) | No | Even Bash prompts are friction |
| `bypassPermissions` | No | No | No | Agent has downstream safety layers |
| `plan` | N/A (read-only) | N/A (read-only) | No | Pure analysis, no modifications |
### Overriding Model Selection
### disallowedTools Guide
**Per-agent override:** Edit the `model:` field in the agent file:
Use `disallowedTools` to remove specific tools from an agent's toolset. This is a blacklist — the agent inherits all tools from the main thread, then the listed tools are removed.
```bash
# Change executor to use opus for heavy implementation work
nano plugins/projman/agents/executor.md
# Change model: sonnet to model: opus
```
Prefer `disallowedTools` over `tools` (whitelist) because:
- New MCP servers are automatically available without updating every agent.
- Less configuration to maintain.
- Easier to audit — you only list what's blocked.
**Session-level:** Users on Opus subscription can change the agent's model to `inherit` to use whatever model the session is using.
Common patterns:
- `disallowedTools: Write, Edit, MultiEdit` — read-only agent, cannot modify files.
- `disallowedTools: Bash` — no shell access (rare, most agents need at least read-only Bash).
### Best Practices
### skills Frontmatter Guide
1. **Default to sonnet** - Good balance for most tasks
2. **Use haiku for speed-sensitive agents** - Sub-agents dispatched in parallel, read-only tasks
3. **Reserve opus for heavy analysis** - Only when sonnet's reasoning isn't sufficient
4. **Use inherit sparingly** - Only when you want session-level control
The `skills` field auto-injects skill file contents into the agent's context window at startup. The agent does NOT need to read the files — they are already present.
**When to use frontmatter `skills`:**
- Agent has ≤7 skills.
- Skills are safety-critical (e.g., `branch-security`, `runaway-detection`).
- You need guaranteed loading — no risk of the agent skipping a skill.
**When to keep body text `## Skills to Load`:**
- Agent has 8+ skills (context window cost too high for full injection).
- Skills are situational — not all needed for every invocation.
- Agent benefits from selective loading based on the specific task.
Skill names in frontmatter are resolved relative to the plugin's `skills/` directory. Use the filename without the `.md` extension.
---

View File

@@ -2,6 +2,8 @@
name: clarity-coach
description: Patient, structured coach helping users articulate requirements clearly. Uses neurodivergent-friendly communication patterns.
model: sonnet
permissionMode: default
disallowedTools: Write, Edit, MultiEdit
---
# Clarity Coach Agent

View File

@@ -2,6 +2,8 @@
name: maintainer
description: CLAUDE.md optimization and maintenance agent
model: sonnet
permissionMode: acceptEdits
skills: visual-header, settings-optimization
---
# CLAUDE.md Maintainer Agent

View File

@@ -2,6 +2,7 @@
name: cmdb-assistant
description: Infrastructure management assistant specialized in NetBox CMDB operations. Use for device management, IP addressing, and infrastructure queries.
model: sonnet
permissionMode: default
---
# CMDB Assistant Agent

View File

@@ -2,6 +2,7 @@
name: refactor-advisor
description: Code structure and refactoring specialist. Use when analyzing code quality, design patterns, or planning refactoring work.
model: sonnet
permissionMode: acceptEdits
---
# Refactor Advisor Agent

View File

@@ -2,6 +2,8 @@
name: security-reviewer
description: Security-focused code review agent
model: sonnet
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Security Reviewer Agent

View File

@@ -2,6 +2,8 @@
name: agent-check
description: Agent definition validator for quick verification
model: haiku
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Agent Check Agent

View File

@@ -2,6 +2,7 @@
name: full-validation
description: Contract validation specialist for comprehensive cross-plugin compatibility validation of the entire marketplace.
model: sonnet
permissionMode: default
---
# Full Validation Agent

View File

@@ -2,6 +2,7 @@
name: data-advisor
description: Reviews code for data integrity, schema validity, and dbt compliance using data-platform MCP tools. Use when validating database operations or data pipelines.
model: sonnet
permissionMode: default
---
# Data Advisor Agent

View File

@@ -2,6 +2,8 @@
name: data-analysis
description: Data analysis specialist for exploration and profiling
model: sonnet
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Data Analysis Agent

View File

@@ -2,6 +2,7 @@
name: data-ingestion
description: Data ingestion specialist for loading, transforming, and preparing data for analysis.
model: haiku
permissionMode: acceptEdits
---
# Data Ingestion Agent

View File

@@ -2,6 +2,7 @@
name: doc-analyzer
description: Specialized agent for documentation analysis and drift detection. Use when detecting or fixing discrepancies between code and documentation.
model: sonnet
permissionMode: acceptEdits
---
# Documentation Analyzer Agent

View File

@@ -2,6 +2,7 @@
name: git-assistant
description: Git workflow assistant for complex git operations, conflict resolution, and repository history management.
model: haiku
permissionMode: acceptEdits
---
# Git Assistant Agent

View File

@@ -2,6 +2,8 @@
name: coordinator
description: Review coordinator that orchestrates the multi-agent PR review process. Dispatches to specialized reviewers, aggregates findings, and produces the final review report. Use proactively after code changes.
model: sonnet
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Coordinator Agent

View File

@@ -2,6 +2,8 @@
name: maintainability-auditor
description: Identifies code complexity, duplication, naming issues, and architecture concerns in PR changes.
model: haiku
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Maintainability Auditor Agent

View File

@@ -2,6 +2,8 @@
name: performance-analyst
description: Performance-focused code reviewer that identifies performance issues, inefficiencies, and optimization opportunities.
model: sonnet
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Performance Analyst Agent

View File

@@ -2,6 +2,8 @@
name: security-reviewer
description: Security-focused code reviewer for PR analysis
model: sonnet
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Security Reviewer Agent

View File

@@ -2,6 +2,8 @@
name: test-validator
description: Test quality reviewer that validates test coverage, test quality, and testing practices in PR changes.
model: haiku
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Test Validator Agent

View File

@@ -1,20 +1,16 @@
---
name: code-reviewer
description: Pre-sprint code quality review agent
model: sonnet
model: opus
permissionMode: default
disallowedTools: Write, Edit, MultiEdit
skills: review-checklist, test-standards, sprint-lifecycle, visual-output
---
# Code Reviewer Agent
You are the **Code Reviewer Agent** - a thorough, practical reviewer who ensures code quality before sprint close.
## Skills to Load
- skills/review-checklist.md
- skills/test-standards.md
- skills/sprint-lifecycle.md
- skills/visual-output.md
## Your Personality
**Thorough but Practical:**

View File

@@ -2,22 +2,14 @@
name: executor
description: Implementation executor agent - precise implementation guidance and code quality
model: sonnet
permissionMode: bypassPermissions
skills: mcp-tools-reference, branch-security, git-workflow, progress-tracking, runaway-detection, lessons-learned, visual-output
---
# Implementation Executor Agent
You are the **Executor Agent** - an implementation-focused specialist who writes clean code and ensures quality.
## Skills to Load
- skills/mcp-tools-reference.md
- skills/branch-security.md
- skills/git-workflow.md
- skills/progress-tracking.md
- skills/runaway-detection.md
- skills/lessons-learned.md
- skills/visual-output.md
## Your Personality
**Implementation-Focused:**

View File

@@ -2,6 +2,7 @@
name: orchestrator
description: Sprint orchestration agent - coordinates execution and tracks progress
model: sonnet
permissionMode: acceptEdits
---
# Sprint Orchestration Agent

View File

@@ -1,7 +1,8 @@
---
name: planner
description: Sprint planning agent - thoughtful architecture analysis and issue creation
model: sonnet
model: opus
permissionMode: default
---
# Sprint Planning Agent

View File

@@ -2,6 +2,8 @@
name: component-check
description: DMC component validation specialist
model: haiku
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Component Check Agent

View File

@@ -2,6 +2,8 @@
name: design-reviewer
description: Reviews code for design system compliance using viz-platform MCP tools. Use when validating DMC components, theme tokens, or accessibility standards.
model: sonnet
permissionMode: plan
disallowedTools: Write, Edit, MultiEdit
---
# Design Reviewer Agent

View File

@@ -2,6 +2,7 @@
name: layout-builder
description: Practical dashboard layout specialist for creating well-structured layouts with filtering, grid systems, and responsive design.
model: sonnet
permissionMode: default
---
# Layout Builder Agent

View File

@@ -2,6 +2,7 @@
name: theme-setup
description: Design-focused theme setup specialist for creating consistent, brand-aligned themes for Dash Mantine Components applications.
model: haiku
permissionMode: acceptEdits
---
# Theme Setup Agent