Template

Files

lmiranda f082b78c0b fix: address critical issues from codebase analysis

- Add hooks declarations to 9 plugins missing them in marketplace.json
- Change .mcp.json to use relative paths (portable across users)
- Fix pr-review hook schema to use standard nested hooks structure
- Fix token exposure in cmdb-assistant startup-check.sh (use curl -K)
- Update version to 5.4.1 in marketplace.json, README.md
- Fix CANONICAL-PATHS.md version (was incorrectly showing 5.5.0)

All 12 plugins now have hooks properly registered.
All validations pass.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-30 18:06:04 -05:00

11 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: 2026-01-30 (v5.4.1)

Repository Root Structure

leo-claude-mktplace/
├── .claude/                    # Claude Code local settings
├── .claude-plugin/             # Marketplace manifest
│   └── marketplace.json
├── .scratch/                   # Transient work (auto-cleaned)
├── docs/                       # All documentation
│   ├── architecture/           # Draw.io diagrams and specs
│   ├── CANONICAL-PATHS.md      # This file - single source of truth
│   ├── COMMANDS-CHEATSHEET.md  # All commands quick reference
│   ├── CONFIGURATION.md        # Centralized configuration guide
│   ├── DEBUGGING-CHECKLIST.md  # Systematic troubleshooting guide
│   └── UPDATING.md             # Update guide
├── hooks/                      # Shared hooks (if any)
├── mcp-servers/                # SHARED MCP servers (v3.0.0+)
│   ├── gitea/                  # Gitea MCP server
│   │   ├── mcp_server/
│   │   │   ├── server.py
│   │   │   ├── gitea_client.py
│   │   │   ├── config.py
│   │   │   └── tools/
│   │   │       ├── issues.py
│   │   │       ├── labels.py
│   │   │       ├── wiki.py
│   │   │       ├── milestones.py
│   │   │       ├── dependencies.py
│   │   │       └── pull_requests.py  # NEW in v3.0.0
│   │   ├── requirements.txt
│   │   └── .venv/
│   ├── netbox/                 # NetBox MCP server
│   │   ├── mcp_server/
│   │   ├── requirements.txt
│   │   └── .venv/
│   ├── data-platform/          # Data engineering MCP (NEW v4.0.0)
│   │   ├── mcp_server/
│   │   │   ├── server.py
│   │   │   ├── pandas_tools.py
│   │   │   ├── postgres_tools.py
│   │   │   └── dbt_tools.py
│   │   ├── requirements.txt
│   │   └── .venv/
│   ├── contract-validator/     # Contract validation MCP (NEW v5.0.0)
│   │   ├── mcp_server/
│   │   │   ├── server.py
│   │   │   ├── parse_tools.py
│   │   │   ├── validation_tools.py
│   │   │   └── report_tools.py
│   │   ├── tests/
│   │   ├── requirements.txt
│   │   └── .venv/
│   └── viz-platform/           # Visualization MCP (NEW v4.1.0)
│       ├── mcp_server/
│       │   ├── server.py
│       │   ├── config.py
│       │   ├── component_registry.py
│       │   ├── dmc_tools.py
│       │   ├── chart_tools.py
│       │   ├── layout_tools.py
│       │   ├── theme_tools.py
│       │   ├── theme_store.py
│       │   └── page_tools.py
│       ├── registry/           # DMC component JSON registries
│       ├── tests/              # 94 tests
│       ├── requirements.txt
│       └── .venv/
├── plugins/                    # ALL plugins
│   ├── projman/                # Sprint management
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── doc-guardian/           # Documentation drift detection
│   │   ├── .claude-plugin/
│   │   ├── hooks/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── code-sentinel/          # Security scanning & refactoring
│   │   ├── .claude-plugin/
│   │   ├── hooks/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── cmdb-assistant/         # NetBox CMDB integration
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   └── claude-md-integration.md
│   ├── claude-config-maintainer/
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   └── claude-md-integration.md
│   ├── project-hygiene/
│   │   ├── .claude-plugin/
│   │   ├── hooks/
│   │   └── claude-md-integration.md
│   ├── clarity-assist/
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── git-flow/
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── pr-review/
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── skills/
│   │   └── claude-md-integration.md
│   ├── data-platform/
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   ├── hooks/
│   │   └── claude-md-integration.md
│   ├── contract-validator/
│   │   ├── .claude-plugin/
│   │   ├── commands/
│   │   ├── agents/
│   │   └── claude-md-integration.md
│   └── viz-platform/
│       ├── .claude-plugin/
│       ├── commands/
│       ├── agents/
│       ├── hooks/
│       └── claude-md-integration.md
├── scripts/                    # Setup and maintenance scripts
│   ├── setup.sh                # Initial setup (create venvs, config templates)
│   ├── post-update.sh          # Post-update (clear cache, show changelog)
│   ├── check-venv.sh           # Check if venvs exist (read-only)
│   ├── validate-marketplace.sh # Marketplace compliance validation
│   ├── verify-hooks.sh         # Verify all hooks use correct event types
│   ├── setup-venvs.sh          # Setup MCP server venvs (create only, never delete)
│   └── release.sh              # Release automation with version bumping
├── 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 skills	`plugins/{plugin-name}/skills/`	`plugins/projman/skills/`
Plugin integration snippet	`plugins/{plugin-name}/claude-md-integration.md`	`plugins/projman/claude-md-integration.md`

MCP Server Paths

MCP servers are shared at repository root and configured in .mcp.json.

Context	Pattern	Example
MCP configuration	`.mcp.json`	`.mcp.json` (at repo root)
Shared MCP server	`mcp-servers/{server}/`	`mcp-servers/gitea/`
MCP server code	`mcp-servers/{server}/mcp_server/`	`mcp-servers/gitea/mcp_server/`
MCP venv	`mcp-servers/{server}/.venv/`	`mcp-servers/gitea/.venv/`

Note: Plugins do NOT have their own mcp-servers/ directories. All MCP servers are shared at root and configured via .mcp.json.

Documentation Paths

Type	Location
Architecture diagrams	`docs/architecture/`
This file	`docs/CANONICAL-PATHS.md`
Update guide	`docs/UPDATING.md`
Configuration guide	`docs/CONFIGURATION.md`
Commands cheat sheet	`docs/COMMANDS-CHEATSHEET.md`
Debugging checklist	`docs/DEBUGGING-CHECKLIST.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 .mcp.json (at root) to mcp-servers/gitea/:

.mcp.json (at repository root)
  → Uses absolute installed path: ~/.claude/plugins/marketplaces/.../mcp-servers/gitea/run.sh

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/` inside plugins	MCP servers are shared at root	Use root `mcp-servers/`
Plugin-level `.mcp.json`	MCP config is at root	Use root `.mcp.json`
Hardcoding absolute paths in source	Breaks portability	Use relative paths or `${CLAUDE_PLUGIN_ROOT}`

Architecture Note

MCP servers are shared at repository root and configured in a single .mcp.json file.

Benefits:

Single source of truth for each MCP server
Updates apply to all plugins automatically
No duplication - clean plugin structure
Simple configuration in one place

Configuration: All MCP servers are defined in .mcp.json at repository root:

{
  "mcpServers": {
    "gitea": { "command": ".../mcp-servers/gitea/run.sh" },
    "netbox": { "command": ".../mcp-servers/netbox/run.sh" },
    "data-platform": { "command": ".../mcp-servers/data-platform/run.sh" },
    "viz-platform": { "command": ".../mcp-servers/viz-platform/run.sh" },
    "contract-validator": { "command": ".../mcp-servers/contract-validator/run.sh" }
  }
}

Change Log

Date	Change	By
2026-01-30	v5.5.0: Removed plugin-level mcp-servers symlinks - all MCP config now in root .mcp.json	Claude Code
2026-01-26	v5.0.0: Added contract-validator plugin and MCP server	Claude Code
2026-01-26	v4.1.0: Added viz-platform plugin and MCP server	Claude Code
2026-01-25	v4.0.0: Added data-platform plugin and MCP server	Claude Code
2026-01-20	v3.0.0: MCP servers moved to root with symlinks	Claude Code
2026-01-20	v3.0.0: Added clarity-assist, git-flow, pr-review plugins	Claude Code
2026-01-20	v3.0.0: Added docs/CONFIGURATION.md	Claude Code
2026-01-20	v3.0.0: Renamed marketplace to leo-claude-mktplace	Claude Code
2026-01-20	Removed docs/references/ (obsolete planning docs)	Claude Code
2026-01-19	Added claude-md-integration.md path pattern	Claude Code
2025-12-15	Restructured: MCP servers bundled in plugins	Claude Code
2025-12-12	Initial creation	Claude Code

11 KiB Raw Blame History