Audit Agent Consolidation Command

Audit Agent Consolidation Command

Analyze agents for consolidation opportunities and track refactoring progress.

Initialization

Before auditing, initialize the environment:

1. Get the current UTC date for audit timestamps.
2. Capture the project root path for subagent communication.
3. Ensure the temp directory (.claude/​temp/) exists.
4. Load the ecosystem-health skill for consolidation criteria access.

What Gets Analyzed

• Configuration fields: tools, model, permissionMode, skills, color
• Grouping: Agents grouped by tools + model + permissionMode
• Reference tracking: Commands, skills, memory, agents that reference each agent
• Consolidation scoring: Based on configuration similarity and reference impact
• Skills analysis: Different skills = different purpose (auto-load guarantee)

Command Arguments

Modes of Operation

Analyze Mode (Default)

Discovers agents, groups by configuration, calculates consolidation scores.

Steps:

1. Discover all agent files based on scope
2. Parse YAML frontmatter for each agent
3. Group agents by tools + model + permissionMode
4. Calculate consolidation scores using criteria from ecosystem-health skill
5. Generate recommendations
6. Display summary

References Mode (--references)

Shows all components that reference each agent.

Searches:

• Skills: skills/​*/​SKILL.md for delegation patterns and Task invocations
• Memory: .claude/​memory/​*.md for agent references
• Agents: agents/​*.md for chaining patterns

Impact Mode (--impact <group>)

Shows detailed analysis of what would break if a group is consolidated.

Reports:

• All references to agents in the group
• Estimated refactoring effort
• Risk assessment
• Suggested migration path

Track Mode (--track)

Persists analysis to .claude/​temp/​agent-consolidation-{timestamp}.json for:

• Multi-session consolidation efforts
• Progress tracking
• Historical comparison

Execute Mode (--execute <plan>)

Interactive mode to apply a consolidation plan.

REQUIRES explicit user confirmation for each step.

Step 1: Parse Arguments

Check for mode flags:

• --force: Set force_reanalyze = true
• --plugin-only: Set scope = "plugin"
• --project-only: Set scope = "project"
• --references: Set mode = "references"
• --impact <group>: Set mode = "impact", capture group ID
• --track: Set track = true
• --execute <plan>: Set mode = "execute", capture plan path

Default: mode = "analyze", scope = "all"

Step 2: Discover Agents

Search for agent files based on scope:

Plugin agents:

• plugins/​*/​agents/​*.md

Project agents:

• .claude/​agents/​*.md

User agents (if scope = all):

• ~/​.claude/​agents/​*.md (note: may not be accessible)

Build list of discovered agents with:

• Full path
• Scope (plugin:<name>, project, user)
• Last modified date

Step 3: Present Discovery Summary

## Agent Discovery

**Scope**: [ALL | PLUGIN | PROJECT]
**Agents Found**: [N]

| Scope | Count | Location |
| ----- | ----- | -------- |
| plugin:claude-ecosystem | 17 | plugins/​claude-ecosystem/​agents/ |
| plugin:code-quality | 3 | plugins/​code-quality/​agents/ |
| project | 2 | .claude/​agents/ |

Step 4: Execute Analysis

For Analyze mode, spawn agent-consolidation-analyst subagent with context:

• Scope (plugin:name, project, all)
• List of agent file paths
• Project root for output files
• Current UTC timestamp

For large agent counts (>10), batch into groups of 5 for parallel analysis.

The subagent will:

1. Parse all agent YAML frontmatter
2. Group by configuration
3. Search for references
4. Calculate scores
5. Write dual output (JSON + Markdown) to .claude/​temp/

Step 5: Aggregate Results

After subagent(s) complete:

1. Read JSON output file(s) from .claude/​temp/
2. Aggregate groups and recommendations
3. Calculate totals

Step 6: Display Results

Analyze Mode Output

Agent Consolidation Analysis
============================

Scope: [scope]
Agents Analyzed: [N]
Groups Found: [N]

Configuration Groups:
---------------------

Group 1: auditor-opus-plan ([N] agents)
  Config: tools=[standard+MCP], model=opus, permissionMode=plan
  Members:
    - skill-auditor (skills: skill-development) [2 refs]
    - skill-auditor (skills: skill-development) [2 refs, handles both skills and commands]
    - agent-auditor (skills: subagent-development) [2 refs]
    - hook-auditor (skills: hook-management) [2 refs]
    ... ([N] more)

  Consolidation: NO
  Score: 45/​100
  Reason: Each agent's `skills:` field provides domain-specific
          knowledge via auto-load guarantee. Cannot replicate via
          Task tool prompt injection.

Group 2: researcher-haiku ([N] agents)
  Config: tools=[Read,Grep,WebFetch], model=haiku
  Members:
    - docs-researcher (skills: none) [1 ref]
    - issue-researcher (skills: none) [3 refs]

  Consolidation: REVIEW
  Score: 78/​100
  Reason: Similar purpose, no skills field. Could potentially merge
          with query-based specialization in prompt.

Recommendations:
----------------
1. [NO ACTION] auditor-opus-plan - skills: auto-load justifies separation
2. [REVIEW] researcher-haiku - Consider meta-skill approach

Total Reference Count: [N]
Highest Impact Agent: [agent-name] ([N] references)

References Mode Output

Agent References Analysis
=========================

skill-auditor:
  Commands: 1
    - audit-skills.md:87 "spawn skill-auditor agent"
  Skills: 0
  Memory: 1
    - audit-protocol.md:45 "uses skill-auditor for validation"
  Total: 2 references

skill-auditor (commands):
  Commands: 1
    - audit-skills.md:66 "spawn skill-auditor agent"
  Skills: 0
  Memory: 1
    - audit-protocol.md:48 "uses skill-auditor for validation"
  Total: 2 references

...

Track Mode

After analysis, if --track flag:

Analysis persisted to:
  .claude/​temp/​agent-consolidation-2026-01-10T193000Z.json

Use --execute to apply consolidation plan.

Important Notes

The skills: Auto-Load Guarantee

CRITICAL: The skills: field provides an auto-load guarantee:

• Skill loads AUTOMATICALLY when agent starts
• No prompt required, no Claude decision needed
• Consistent, reliable domain knowledge

Task tool CANNOT replicate this:

• Cannot specify skills: parameter in Task tool
• Must describe skill content in prompt (token bloat)
• Claude must decide to invoke Skill tool (not guaranteed)

Therefore: Agents with different skills: fields should NOT be consolidated unless their skills can be merged into one meta-skill.

Configuration Field Weights

Scoring Thresholds

Plugin Isolation Constraint

CRITICAL: Plugins cannot reference resources outside their individual plugin directory.

This means:

• Agents in plugin-a/​agents/ cannot consolidate with agents in plugin-b/​agents/
• Cross-plugin consolidation is architecturally impossible
• Only agents within the SAME plugin can be consolidated
• When analyzing consolidation candidates, group only by plugin scope

When the analysis identifies similar agents across different plugins (e.g., *-docs-researcher agents), these should be noted as following a common pattern but are NOT consolidation candidates.

Scope filtering recommendation:

• Use --plugin-only and analyze each plugin separately
• Group recommendations by plugin, not globally
• Cross-plugin patterns inform template standardization, not consolidation

Example Usage

Example 1: Analyze All Agents

User: /​audit-agent-consolidation

Claude: Discovering agents...

## Agent Discovery
Scope: ALL
Agents Found: 22

[Analysis proceeds...]

Agent Consolidation Analysis
============================
...

Example 2: Plugin-Only Analysis

User: /​audit-agent-consolidation --plugin-only

Claude: Discovering plugin agents only...

## Agent Discovery
Scope: PLUGIN
Agents Found: 20
...

Example 3: Show References

User: /​audit-agent-consolidation --references

Claude: Analyzing agent references...

Agent References Analysis
=========================
...

Example 4: Track for Multi-Session

User: /​audit-agent-consolidation --track

Claude: [Analysis...]

Analysis persisted to:
  .claude/​temp/​agent-consolidation-2026-01-10T193000Z.json

Example 5: Impact Analysis

User: /​audit-agent-consolidation --impact auditor-opus-plan

Claude: Analyzing impact for group: auditor-opus-plan

Impact Analysis: auditor-opus-plan
==================================

Agents in Group: 13
Total References: 26

If consolidated, would need to update:
  - 13 command files (Task invocations)
  - 13 memory references

Risk Assessment: HIGH
Reason: skills: field provides domain-specific knowledge

Recommendation: Do NOT consolidate. The auto-load guarantee
cannot be replicated via Task tool.

Ecosystem Health Integration

This command integrates with the ecosystem-health skill:

• Uses references/​consolidation-criteria.md for scoring rubric
• Contributes to component coverage tracking
• Supports the audit orchestration workflow

Run /​ecosystem-health --status to see overall audit coverage including agent consolidation.