Template

Files

lmiranda 113839b0d8 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

5.7 KiB

Raw Blame History

Canonical Paths - SINGLE SOURCE OF TRUTH

This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.

Last Updated: 2025-12-15

Repository Root Structure

support-claude-mktplace/
├── .claude/                    # Claude Code local settings
├── .claude-plugin/             # Marketplace manifest (claude-code-marketplace)
│   └── marketplace.json
├── .scratch/                   # Transient work (auto-cleaned)
├── docs/                       # All documentation
│   ├── architecture/           # Draw.io diagrams and specs
│   ├── references/             # Reference specifications
│   └── workflows/              # Workflow documentation
├── hooks/                      # Shared hooks (if any)
├── plugins/                    # ALL plugins with bundled MCP servers
│   ├── projman/
│   │   ├── .claude-plugin/
│   │   ├── mcp-servers/        # MCP servers bundled IN plugin
│   │   │   └── gitea/          # Gitea + Wiki tools
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
│   ├── projman-pmo/
│   ├── project-hygiene/
│   ├── cmdb-assistant/
│   │   ├── .claude-plugin/
│   │   ├── mcp-servers/        # MCP servers bundled IN plugin
│   │   │   └── netbox/
│   │   ├── commands/
│   │   ├── 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/
│       ├── hooks/
│       └── claude-md-integration.md  # CLAUDE.md integration snippet
├── scripts/                    # Setup and maintenance scripts
├── CLAUDE.md
├── README.md
├── LICENSE
├── CHANGELOG.md
└── .gitignore

Path Patterns (MANDATORY)

Plugin Paths

Context	Pattern	Example
Plugin location	`plugins/{plugin-name}/`	`plugins/projman/`
Plugin manifest	`plugins/{plugin-name}/.claude-plugin/plugin.json`	`plugins/projman/.claude-plugin/plugin.json`
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)

MCP servers are now bundled inside each plugin to ensure they work when plugins are cached.

Context	Pattern	Example
MCP server location	`plugins/{plugin}/mcp-servers/{server}/`	`plugins/projman/mcp-servers/gitea/`
MCP server code	`plugins/{plugin}/mcp-servers/{server}/mcp_server/`	`plugins/projman/mcp-servers/gitea/mcp_server/`
MCP venv	`plugins/{plugin}/mcp-servers/{server}/.venv/`	`plugins/projman/mcp-servers/gitea/.venv/`

Relative Path Patterns (CRITICAL)

From	To	Pattern
Plugin .mcp.json	Bundled MCP server	`${CLAUDE_PLUGIN_ROOT}/mcp-servers/{server}`
marketplace.json	Plugin	`./plugins/{plugin-name}`

Documentation Paths

Type	Location
Reference specs	`docs/references/`
Architecture diagrams	`docs/architecture/`
Workflow docs	`docs/workflows/`
This file	`docs/CANONICAL-PATHS.md`

Validation Rules

Before Creating Any File

Check this file for the correct path pattern
Verify the parent directory exists in the structure above
If path not listed here, STOP AND ASK

Before Generating Any Prompt

List all file paths the prompt will create/modify
Verify each path against patterns in this file
Show verification to user before proceeding

Relative Path Calculation

From plugins/projman/.mcp.json to bundled mcp-servers/gitea/:

plugins/projman/.mcp.json
  → MCP servers are IN the plugin at mcp-servers/

Result: mcp-servers/gitea/
With variable: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/

From .claude-plugin/marketplace.json to plugins/projman/:

.claude-plugin/marketplace.json
  ↑ marketplace.json is at repo root level
  → go down to plugins/projman/           (./plugins/projman/)

Result: ./plugins/projman

Anti-Patterns (NEVER DO THIS)

Wrong	Why	Correct
`projman/` at root	Plugins go in `plugins/`	`plugins/projman/`
`mcp-servers/` at root	MCP servers are bundled in plugins	`plugins/{plugin}/mcp-servers/`
`../../mcp-servers/` from plugin	Old pattern, doesn't work with caching	`${CLAUDE_PLUGIN_ROOT}/mcp-servers/`
`./../../../plugins/projman` in marketplace	Wrong (old nested structure)	`./plugins/projman`

Architecture Note

MCP servers are bundled inside each plugin (not shared at root) because:

Claude Code caches only the plugin directory when installed
Relative paths to parent directories break in the cache
Each plugin must be self-contained to work properly

Change Log

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

5.7 KiB Raw Blame History