Merge pull request 'feat: add plugin integration analysis to config-analyze command' (#30) from development into main

Reviewed-on: personal-projects/support-claude-mktplace#30
2026-01-19 23:27:15 +00:00
parent a12665c22d 113839b0d8
commit 5fc18f28e9
8 changed files with 361 additions and 18 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,25 +11,43 @@
      "name": "projman",
      "version": "2.0.0",
      "description": "Sprint planning and project management with Gitea integration",
-      "source": "./plugins/projman"
+      "source": "./plugins/projman",
+      "mcpServers": ["gitea"],
+      "integrationFile": "claude-md-integration.md"
    },
    {
      "name": "project-hygiene",
      "version": "0.1.0",
      "description": "Post-task cleanup hook that removes temp files and manages orphaned files",
-      "source": "./plugins/project-hygiene"
+      "source": "./plugins/project-hygiene",
+      "mcpServers": [],
+      "integrationFile": "claude-md-integration.md",
+      "hooks": ["PostToolUse"]
    },
    {
      "name": "cmdb-assistant",
      "version": "1.0.0",
      "description": "NetBox CMDB integration for infrastructure management",
-      "source": "./plugins/cmdb-assistant"
+      "source": "./plugins/cmdb-assistant",
+      "mcpServers": ["netbox"],
+      "integrationFile": "claude-md-integration.md"
    },
    {
      "name": "claude-config-maintainer",
      "version": "1.0.0",
      "description": "CLAUDE.md optimization and maintenance for Claude Code projects",
-      "source": "./plugins/claude-config-maintainer"
+      "source": "./plugins/claude-config-maintainer",
+      "mcpServers": [],
+      "integrationFile": "claude-md-integration.md"
    }
-  ]
+  ],
+  "pluginDetection": {
+    "mcpServerMapping": {
+      "gitea": "projman",
+      "netbox": "cmdb-assistant"
+    },
+    "hookMapping": {
+      "PostToolUse:Write|Edit": "project-hygiene"
+    }
+  }
 }
--- a/docs/CANONICAL-PATHS.md
+++ b/docs/CANONICAL-PATHS.md
@@ -26,7 +26,8 @@ support-claude-mktplace/
 │   │   │   └── gitea/          # Gitea + Wiki tools
 │   │   ├── commands/
 │   │   ├── agents/
-│   │   └── skills/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
 │   ├── projman-pmo/
 │   ├── project-hygiene/
 │   ├── cmdb-assistant/
@@ -34,11 +35,17 @@ support-claude-mktplace/
 │   │   ├── mcp-servers/        # MCP servers bundled IN plugin
 │   │   │   └── netbox/
 │   │   ├── commands/
-│   │   └── agents/
-│   └── claude-config-maintainer/
+│   │   ├── agents/
+│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
+│   ├── claude-config-maintainer/
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
+│   └── project-hygiene/
 │       ├── .claude-plugin/
-│       ├── commands/
-│       └── agents/
+│       ├── hooks/
+│       └── claude-md-integration.md  # CLAUDE.md integration snippet
 ├── scripts/                    # Setup and maintenance scripts
 ├── CLAUDE.md
 ├── README.md
@@ -60,6 +67,7 @@ support-claude-mktplace/
 | Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
 | Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
 | Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
+| Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |

 ### MCP Server Paths (Bundled in Plugins)

@@ -149,5 +157,6 @@ MCP servers are bundled inside each plugin (not shared at root) because:

 | Date | Change | By |
 |------|--------|-----|
+| 2026-01-19 | Added claude-md-integration.md path pattern for plugin integration snippets | Claude Code |
 | 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
 | 2025-12-12 | Initial creation | Claude Code |
--- 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