lmiranda
113839b0d8
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>
163 lines
5.7 KiB
Markdown
163 lines
5.7 KiB
Markdown
# 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
|
|
|
|
1. Check this file for the correct path pattern
|
|
2. Verify the parent directory exists in the structure above
|
|
3. If path not listed here, **STOP AND ASK**
|
|
|
|
### Before Generating Any Prompt
|
|
|
|
1. List all file paths the prompt will create/modify
|
|
2. Verify each path against patterns in this file
|
|
3. 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 |
|