feat: add plugin integration analysis to config-analyze command

Add automatic detection of active marketplace plugins and verification that CLAUDE.md properly references them. This ensures projects using marketplace plugins will have proper documentation to guide Claude Code in using available tools. Changes: - Add claude-md-integration.md snippets to all 4 plugins (projman, cmdb-assistant, claude-config-maintainer, project-hygiene) - Update marketplace.json with MCP server mappings for plugin detection - Enhance /config-analyze to detect active plugins via MCP server names - Update maintainer agent with plugin integration workflow - Add plugin coverage percentage to analysis report - User confirmation required before adding plugin references Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 18:24:29 -05:00
parent 15e0654950
commit 113839b0d8
8 changed files with 361 additions and 18 deletions
--- a/plugins/claude-config-maintainer/agents/maintainer.md
+++ b/plugins/claude-config-maintainer/agents/maintainer.md
@@ -31,7 +31,11 @@ You are the **Maintainer Agent** - a specialist in creating and optimizing CLAUD

 ### 1. Analyze CLAUDE.md Files

-When analyzing a CLAUDE.md file, evaluate:
+When analyzing a CLAUDE.md file, perform two types of analysis:
+
+#### A. Content Analysis
+
+Evaluate:

 **Structure:**
 - Is the file well-organized?
@@ -57,6 +61,49 @@ When analyzing a CLAUDE.md file, evaluate:
 - Are there verbose explanations that could be shortened?
 - Is the file too long for effective use?

+#### B. Plugin Integration Analysis
+
+After content analysis, check for marketplace plugin integration:
+
+**Step 1: Detect Active Plugins**
+
+Read `.claude/settings.local.json` and identify enabled MCP servers:
+```json
+{
+  "mcpServers": {
+    "gitea": { ... },      // → projman plugin
+    "netbox": { ... }      // → cmdb-assistant plugin
+  }
+}
+```
+
+Use this mapping to identify active plugins:
+| MCP Server | Plugin |
+|------------|--------|
+| `gitea` | projman |
+| `netbox` | cmdb-assistant |
+
+Also check for hook-based plugins (project-hygiene uses `PostToolUse` hooks).
+
+**Step 2: Check CLAUDE.md for Plugin References**
+
+For each detected plugin, search CLAUDE.md for:
+- Plugin name mention (e.g., "projman", "cmdb-assistant")
+- Command references (e.g., `/sprint-plan`, `/cmdb-search`)
+- MCP tool mentions (e.g., `list_issues`, `dcim_list_devices`)
+
+**Step 3: Load Integration Snippets**
+
+For plugins not referenced in CLAUDE.md, load their integration snippet from:
+`plugins/{plugin-name}/claude-md-integration.md`
+
+**Step 4: Report and Offer Integration**
+
+Report plugin coverage percentage and offer to add missing integrations:
+- Show which plugins are detected but not referenced
+- Display the integration content that would be added
+- Ask user for confirmation before modifying CLAUDE.md
+
 ### 2. Optimize CLAUDE.md Structure

 **Recommended Structure:**
@@ -145,7 +192,42 @@ Suggested Actions:
 Would you like me to implement these improvements?
 ```

-### 5. Create New CLAUDE.md Files
+### 5. Insert Plugin Integrations
+
+When adding plugin integration content to CLAUDE.md:
+
+**Placement:**
+- Add plugin sections after the main project documentation
+- Group all plugin integrations together under a clear header
+- Use consistent formatting across all plugin sections
+
+**Process:**
+1. Read the plugin's `claude-md-integration.md` file
+2. Show the content to the user for review
+3. Ask for confirmation: "Add this plugin integration? [Y/n]"
+4. If confirmed, insert at appropriate location in CLAUDE.md
+5. Repeat for each missing plugin
+
+**User Confirmation Flow:**
+```
+Plugin Integration: projman
+--------------------------
+[Show content from plugins/projman/claude-md-integration.md]
+
+Add this integration to CLAUDE.md?
+  [1] Yes, add this integration
+  [2] Skip this plugin
+  [3] Add all remaining plugins
+  [4] Cancel
+```
+
+**Best Practices:**
+- Never modify CLAUDE.md without user confirmation
+- Show exactly what will be added before making changes
+- Allow users to skip specific plugins they don't want documented
+- Preserve existing CLAUDE.md structure and content
+
+### 6. Create New CLAUDE.md Files

 When creating a new CLAUDE.md:

--- a/plugins/claude-config-maintainer/claude-md-integration.md
+++ b/plugins/claude-config-maintainer/claude-md-integration.md
@@ -0,0 +1,30 @@
+## CLAUDE.md Maintenance (claude-config-maintainer)
+
+This project uses the **claude-config-maintainer** plugin to analyze and optimize CLAUDE.md configuration files.
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/config-analyze` | Analyze CLAUDE.md for optimization opportunities with 100-point scoring |
+| `/config-optimize` | Automatically optimize CLAUDE.md structure and content |
+| `/config-init` | Initialize a new CLAUDE.md file for a project |
+
+### Scoring System
+
+The analysis uses a 100-point scoring system across four categories:
+
+| Category | Points | What It Measures |
+|----------|--------|------------------|
+| Structure | 25 | Organization, headers, navigation, grouping |
+| Clarity | 25 | Instructions, examples, language, detail level |
+| Completeness | 25 | Overview, quick start, critical rules, workflows |
+| Conciseness | 25 | Efficiency, no repetition, appropriate length |
+
+### Usage Guidelines
+
+- Run `/config-analyze` periodically to assess CLAUDE.md quality
+- Target a score of **70+/100** for effective Claude Code operation
+- Address HIGH priority issues first when optimizing
+- Use `/config-init` when setting up new projects to start with best practices
+- Re-analyze after making changes to verify improvements
--- a/plugins/claude-config-maintainer/commands/analyze.md
+++ b/plugins/claude-config-maintainer/commands/analyze.md
@@ -1,10 +1,10 @@
 ---
-description: Analyze CLAUDE.md for optimization opportunities
+description: Analyze CLAUDE.md for optimization opportunities and plugin integration
 ---

 # Analyze CLAUDE.md

-This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities.
+This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities and plugin integration status.

 ## What This Command Does

@@ -12,7 +12,9 @@ This command analyzes your project's CLAUDE.md file and provides a detailed repo
 2. **Analyze Structure** - Evaluates organization, headers, and flow
 3. **Check Content** - Reviews clarity, completeness, and conciseness
 4. **Identify Issues** - Finds redundancy, verbosity, and missing sections
-5. **Generate Report** - Provides scored assessment with recommendations
+5. **Detect Active Plugins** - Identifies marketplace plugins enabled in the project
+6. **Check Plugin Integration** - Verifies CLAUDE.md references active plugins
+7. **Generate Report** - Provides scored assessment with recommendations

 ## Usage

@@ -52,6 +54,29 @@ Analyze the CLAUDE.md file in this project
 - Appropriate length for project size
 - No generic filler content

+## Plugin Integration Analysis
+
+After the content analysis, the command detects and analyzes marketplace plugin integration:
+
+### Detection Method
+
+1. **Read `.claude/settings.local.json`** - Check for enabled MCP servers
+2. **Map MCP servers to plugins** - Use marketplace registry to identify active plugins:
+   - `gitea` → projman
+   - `netbox` → cmdb-assistant
+3. **Check for hooks** - Identify hook-based plugins (project-hygiene)
+4. **Scan CLAUDE.md** - Look for plugin integration content
+
+### Plugin Coverage Scoring
+
+For each detected plugin, verify CLAUDE.md contains:
+- Plugin section header or mention
+- Available commands documentation
+- MCP tools reference (if applicable)
+- Usage guidelines
+
+Coverage is reported as percentage: `(plugins referenced / plugins detected) * 100`
+
 ## Expected Output

 ```
@@ -101,10 +126,37 @@ Recommendations:

 Estimated improvement: 15-20 points after changes

+---
+
+Plugin Integration Analysis
+===========================
+
+Detected Active Plugins:
+  ✓ projman (via gitea MCP server)
+  ✓ cmdb-assistant (via netbox MCP server)
+  ✓ project-hygiene (via PostToolUse hook)
+
+Plugin Coverage: 33% (1/3 plugins referenced)
+
+  ✓ projman - Referenced in CLAUDE.md
+  ✗ cmdb-assistant - NOT referenced
+  ✗ project-hygiene - NOT referenced
+
+Missing Integration Content:
+
+1. cmdb-assistant
+   Add infrastructure management commands and NetBox MCP tools reference.
+
+2. project-hygiene
+   Add cleanup hook documentation and configuration options.
+
+---
+
 Would you like me to:
-[1] Implement all recommended changes
-[2] Show before/after for specific section
-[3] Generate optimized version for review
+[1] Implement all content recommendations
+[2] Add missing plugin integrations to CLAUDE.md
+[3] Do both (recommended)
+[4] Show preview of changes first
 ```

 ## When to Use
@@ -115,6 +167,8 @@ Run `/config-analyze` when:
 - Claude seems to miss instructions
 - Before major project changes
 - Periodic maintenance (quarterly)
+- After installing new marketplace plugins
+- When Claude doesn't seem to use available plugin tools

 ## Follow-Up Actions

--- a/plugins/cmdb-assistant/claude-md-integration.md
+++ b/plugins/cmdb-assistant/claude-md-integration.md
@@ -0,0 +1,58 @@
+## Infrastructure Management (cmdb-assistant)
+
+This project uses the **cmdb-assistant** plugin for NetBox CMDB integration to manage network infrastructure.
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cmdb-search` | Search across all NetBox objects |
+| `/cmdb-device` | Manage devices (create, update, list) |
+| `/cmdb-ip` | Manage IP addresses and prefixes |
+| `/cmdb-site` | Manage sites and locations |
+
+### MCP Tools Available
+
+The following NetBox MCP tools are available for infrastructure management:
+
+**DCIM (Data Center Infrastructure Management):**
+- `dcim_list_devices`, `dcim_get_device`, `dcim_create_device`, `dcim_update_device` - Device management
+- `dcim_list_sites`, `dcim_get_site`, `dcim_create_site` - Site management
+- `dcim_list_racks`, `dcim_get_rack`, `dcim_create_rack` - Rack management
+- `dcim_list_interfaces`, `dcim_create_interface` - Interface management
+- `dcim_list_cables`, `dcim_create_cable` - Cable management
+- `dcim_list_device_types`, `dcim_list_device_roles`, `dcim_list_manufacturers` - Reference data
+- `dcim_list_regions`, `dcim_list_locations` - Location hierarchy
+
+**IPAM (IP Address Management):**
+- `ipam_list_ip_addresses`, `ipam_create_ip_address`, `ipam_get_ip_address` - IP address management
+- `ipam_list_prefixes`, `ipam_create_prefix`, `ipam_list_available_prefixes` - Prefix management
+- `ipam_list_vlans`, `ipam_create_vlan` - VLAN management
+- `ipam_list_vrfs`, `ipam_create_vrf` - VRF management
+- `ipam_list_available_ips`, `ipam_create_available_ip` - IP allocation
+
+**Virtualization:**
+- `virtualization_list_virtual_machines`, `virtualization_create_virtual_machine` - VM management
+- `virtualization_list_clusters`, `virtualization_create_cluster` - Cluster management
+- `virtualization_list_vm_interfaces` - VM interface management
+
+**Circuits:**
+- `circuits_list_circuits`, `circuits_create_circuit` - Circuit management
+- `circuits_list_providers`, `circuits_create_provider` - Provider management
+
+**Tenancy:**
+- `tenancy_list_tenants`, `tenancy_create_tenant` - Tenant management
+- `tenancy_list_contacts`, `tenancy_create_contact` - Contact management
+
+**Extras:**
+- `extras_list_tags`, `extras_create_tag` - Tag management
+- `extras_list_journal_entries`, `extras_create_journal_entry` - Audit journal
+- `extras_list_object_changes` - Change tracking
+
+### Usage Guidelines
+
+- Use NetBox MCP tools for all infrastructure queries and modifications
+- Always verify device/IP existence before creating duplicates
+- Use tags for categorization and filtering
+- Create journal entries for significant changes to maintain audit trail
+- Check available IPs in a prefix before manual allocation
--- a/plugins/project-hygiene/claude-md-integration.md
+++ b/plugins/project-hygiene/claude-md-integration.md
@@ -0,0 +1,36 @@
+## Project Cleanup (project-hygiene)
+
+This project uses the **project-hygiene** plugin for automated post-task cleanup.
+
+### How It Works
+
+The plugin automatically runs after file Write or Edit operations to:
+
+1. **Delete temporary files** - Removes `*.tmp`, `*.bak`, `__pycache__/`, `.pytest_cache/`, etc.
+2. **Warn about unexpected root files** - Alerts when files are created outside expected locations
+3. **Identify orphaned files** - Detects supporting files that may no longer be needed
+
+### Configuration
+
+The plugin can be configured via `.hygiene.json` in the project root:
+
+```json
+{
+  "temp_patterns": ["*.tmp", "*.bak", "*.swp"],
+  "ignore_dirs": ["node_modules", ".git", ".venv"],
+  "allowed_root_files": ["CLAUDE.md", "README.md", "LICENSE"],
+  "warn_on_root_files": true
+}
+```
+
+### Hook Events
+
+The plugin registers on the following events:
+- `PostToolUse` (matcher: `Write|Edit`) - Runs cleanup after file modifications
+
+### Usage Guidelines
+
+- Let the hook run automatically - no manual intervention needed
+- Review warnings about unexpected root files
+- Configure `.hygiene.json` to customize cleanup behavior for your project
+- Check cleanup output if files seem to disappear unexpectedly
--- a/plugins/projman/claude-md-integration.md
+++ b/plugins/projman/claude-md-integration.md
@@ -0,0 +1,56 @@
+## Sprint Management (projman)
+
+This project uses the **projman** plugin for sprint planning and project management with Gitea integration.
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/sprint-plan` | Start sprint planning with AI-guided architecture analysis |
+| `/sprint-start` | Begin sprint execution with relevant lessons learned |
+| `/sprint-status` | Check current sprint progress and identify blockers |
+| `/sprint-close` | Complete sprint and capture lessons learned to Gitea Wiki |
+| `/labels-sync` | Synchronize label taxonomy from Gitea |
+| `/initial-setup` | Run initial setup for projman plugin |
+
+### MCP Tools Available
+
+The following Gitea MCP tools are available for issue and project management:
+
+**Issue Management:**
+- `list_issues` - Query issues with filters (state, labels)
+- `get_issue` - Fetch single issue details
+- `create_issue` - Create new issue with labels
+- `update_issue` - Modify existing issue
+- `add_comment` - Add comments to issues
+
+**Labels:**
+- `get_labels` - Fetch org + repo label taxonomy
+- `suggest_labels` - Analyze context and suggest appropriate labels
+- `create_label` - Create missing required labels
+
+**Milestones:**
+- `list_milestones` - List sprint milestones
+- `get_milestone` - Get milestone details
+- `create_milestone` - Create sprint milestone
+- `update_milestone` - Update/close milestone
+
+**Dependencies:**
+- `list_issue_dependencies` - Get issue dependencies
+- `create_issue_dependency` - Create dependency between issues
+- `get_execution_order` - Get parallel execution batches
+
+**Wiki (Lessons Learned):**
+- `list_wiki_pages` - List wiki pages
+- `get_wiki_page` - Fetch specific page content
+- `create_wiki_page` - Create new wiki page
+- `create_lesson` - Create lessons learned document
+- `search_lessons` - Search past lessons by tags
+
+### Usage Guidelines
+
+- **Always use `/sprint-plan`** when starting new development work
+- **Check `/sprint-status`** regularly during active sprints
+- **Run `/sprint-close`** at the end of each sprint to capture lessons learned
+- Use `suggest_labels` when creating issues to ensure proper categorization
+- Search lessons learned with `search_lessons` before implementing features to avoid repeated mistakes